Documentación de Combustible y gasolineras

Otra Vida Combustible (ov_combustible)

Que hace

ov_combustible agrega un sistema completo de combustible a servidores FiveM con qb-core: consumo realista, gasolineras, cargadores para vehiculos electricos, bidon de emergencia, HUD y un panel de administracion para controlar precios y existencias.

Lo mas importante:

Consumo realista segun las revoluciones del motor, la clase del vehiculo y el tipo de combustible. Cada clase tiene su tamano de tanque (por ejemplo 45 L en un compacto, 15 L en una moto, 150 L en un industrial).
Cuatro tipos de combustible (regular, plus, premium y diesel) con distinto consumo y precio, mas carga electrica normal y rapida.
Interfaz de surtidor para elegir combustible, litros y cuenta de pago (efectivo o banco), con total visible antes de comprar.
Manguera con cuerda y reposte interactivo; si sobra combustible pagado, se devuelve el dinero proporcional.
Bidon (item de ox_inventory) que guarda los litros en su metadata.
Descuentos por trabajo (por defecto policia y ambulancia en servicio).
Combustible equivocado: los vehiculos diesel solo aceptan diesel, y un tipo incorrecto averia el motor (segun la lista Config.DieselVehicles).
Panel de administracion para ajustar precio y disponibilidad por estacion o de forma global.
Compatibilidad: el recurso declara provide para LegacyFuel, lc_fuel, ps-fuel y cdn-fuel, y expone GetFuel/SetFuel con los nombres habituales.

Requisitos

Requisito	Detalle
Framework	`qb-core`
Dependencias declaradas en el fxmanifest	`ox_lib`, `oxmysql`, `ox_inventory`, `qb-core`
Interaccion con surtidores y vehiculos	El codigo del cliente usa los exports `exports.ox_target:addModel` y `addGlobalVehicle`. Necesitas `ox_target` (o un recurso de apuntado que ofrezca ese mismo nombre de export) iniciado antes
Lua	5.4 (`lua54 'yes'`)
Base de datos	MySQL o MariaDB, mediante `oxmysql`

El recurso incluye dos props electricos propios en la carpeta stream/ (prop_electric_01 y prop_eletricpistol), que el fxmanifest registra con DLC_ITYP_REQUEST. No hace falta instalar nada mas para ellos.

Al declarar provide de LegacyFuel, lc_fuel, ps-fuel y cdn-fuel, no debes tener otro script de combustible activo a la vez.

Instalacion

Descarga el recurso desde el Portal de Cfx.re (seccion de assets comprados) con la cuenta Cfx.re con la que hiciste la compra. El recurso viene protegido con Asset Escrow de Cfx.re: solo funciona en servidores cuya clave de licencia pertenece a tu cuenta.
Copia la carpeta ov_combustible dentro de resources.
Declara el item del bidon en ox_inventory. El nombre debe coincidir con Config.JerryCan.item (por defecto petrolcan). El recurso guarda en la metadata del item los litros (litros) y el tipo (tipo).
Agrega en server.cfg, despues de ox_lib, oxmysql, qb-core, ox_inventory y tu recurso de apuntado:

   ensure ov_combustible

Da el permiso de administracion:

   add_ace group.admin command.combustibleadmin allow

Inicia el servidor. No hay archivo .sql: al arrancar el recurso crea solo las tablas ov_combustible_tipos y ov_combustible_estaciones (CREATE TABLE IF NOT EXISTS).

El codigo no lee convars de server.cfg.

Archivos editables: en el fxmanifest.lua el bloque escrow_ignore deja sin cifrar shared/config.lua y la carpeta html/ (interfaz). Los demas archivos de shared/ (vehiculos.lua, idioma.lua), client/ y server/ van cifrados por Asset Escrow.

Configuracion

Todo esta en shared/config.lua. Opciones principales:

Clave	Valor por defecto	Para que sirve
`Config.EnablePumpRope`	`true`	Activa la cuerda de la manguera
`Config.DefaultRopeLength`	`7.5`	Largo de la cuerda
`Config.RefuelTick`	`300`	Milisegundos por cada 0.5 L repostados (menos = mas rapido)
`Config.FuelTypeCommand`	`"fuel_type"`	Comando que muestra el tipo de combustible del vehiculo
`Config.SaveAllVehicleFuelTypes`	`true`	Guarda en base de datos el tipo de combustible de todos los vehiculos (o solo los de jugadores si es `false`)
`Config.ReturnNozzleRefund`	`true`	Devuelve el dinero del combustible no usado al devolver la manguera
`Config.FuelConsumptionChart`	`enabled = true`, `command = "fuel_chart"`, `focusShortcut = "F3"`, `position = "left"`	Grafico informativo de consumo
`Config.JerryCan`	`enabled = true`, `price = 300`, `requiredStock = 10`, `item = "petrolcan"`, `liters = 20`	Bidon: precio, item de ox_inventory y litros al comprarlo
`Config.Accounts`	`account1 = "cash"`, `account2 = "bank"`	Cuentas con las que se puede pagar
`Config.JobDiscounts`	`police = 90`, `ambulance = 80`	Descuento en % por trabajo (solo en servicio)
`Config.DefaultValues.fuelPrice`	`regular 2.02`, `plus 2.20`, `premium 2.57`, `diesel 1.94`	Precio por litro por defecto
`Config.DefaultValues.fuelStock`	todos `true`	Si hay existencias de cada tipo por defecto
`Config.FuelConsumptionPerFuelType`	`regular 1.0`, `plus 0.9`, `premium 0.8`, `diesel 1.0`	Multiplicador de consumo por tipo
`Config.FuelTankSize`	por clase y por vehiculo	Litros del tanque; `perVehicle` tiene prioridad sobre `perClass`
`Config.FuelConsumptionPerClass`	por clase de vehiculo	Multiplicador de consumo por clase
`Config.FuelUsage`	curva por RPM	Consumo segun revoluciones
`Config.DieselVehicles`	lista de modelos	Vehiculos que usan diesel
`Config.BlacklistedVehicles`	bicicletas	Vehiculos que no gastan combustible
`Config.GasPumpProps`	7 modelos de surtidor	Props reconocidos como surtidor y desplazamiento de la cuerda
`Config.CustomGasPumpLocations`	18 posiciones	Surtidores extra que el recurso crea en el mapa
`Config.CustomVehicleParameters`	`default` y ejemplos	Distancia y posicion de la boquilla por vehiculo
`Config.DebugNozzleOffset`	`false`	Ayuda para calibrar la posicion de la boquilla en vehiculos nuevos
`Config.Blips`	`enabled = true`, `blipId = 361`, `color = 41`, `scale = 0.6`, lista de ubicaciones	Marcas de gasolineras en el mapa
`Config.Electric`	`enabled = true`, cargadores, `chargeTypes` (rapida `price = 2.5`, `time = 0.8`; normal `price = 1.8`, `time = 2`), `vehiclesList`	Seccion de vehiculos electricos
`Config.Estaciones`	las estaciones de `Config.PlayerOwnedGasStations.gasStations` (27)	Estaciones (centro y radio) para precios por estacion
`Config.AdminAce`	`'command.combustibleadmin'`	Permiso ACE del panel
`Config.AdminCommand`	`'combustibleadmin'`	Comando del panel
`Config.HUD`	`modo = 'auto'`, `umbralBajo = 15.0`, `umbralCritico = 5.0`, `posicion = 'abajo-derecha'`	HUD: `'siempre'`, `'auto'` o `'nunca'`
`Config.MaxLitrosPorCompra`	`600`	Maximo de litros por compra (validacion del servidor)
`Config.VigenciaApertura`	`180`	Segundos que vale una apertura del panel antes de comprar

Los textos que ve el jugador estan en shared/idioma.lua, que va cifrado con el recurso. Consulta el archivo de configuracion y con el soporte de la tienda si necesitas traducciones personalizadas.

Comandos y permisos

Elemento	Detalle
`/fuel_type`	Muestra el tipo de combustible del vehiculo (nombre en `Config.FuelTypeCommand`)
`/fuel_chart`	Abre el grafico de consumo (nombre en `Config.FuelConsumptionChart.command`)
`F3`	Atajo para enfocar el grafico de consumo (`/fuel_focus`, configurable por el jugador en Teclas de FiveM)
`/combustibleadmin`	Abre el panel de administracion; exige el permiso ACE `command.combustibleadmin`
Tecla `X`	Detiene el repostaje en curso

Exports del cliente

Export	Uso
`GetFuel(vehiculo)` / `getFuel`	Nivel de combustible del vehiculo (0 a 100)
`SetFuel(vehiculo, nivel)` / `setFuel`	Fija el nivel (0 a 100)
`SetFuelType(vehiculo, tipo)` / `setFuelType`	Fija el tipo de combustible del vehiculo

Export del servidor

Export	Uso
`SetVehicleFuelType(placa, tipo)`	Guarda el tipo de combustible de una placa en base de datos

-- Cliente: llenar el tanque al sacar un vehiculo
exports.ov_combustible:SetFuel(vehiculo, 100.0)

Como se usa

Repostar

Acercate a un surtidor y usa el ojo de interaccion: Abrir menu de repostaje.
En el panel elige el combustible, los litros (deslizador o atajos) y la cuenta de pago. Ves el total antes de pagar.
Pulsa Comprar. Recibes la manguera en la mano.
Con el motor apagado, acercate al deposito del vehiculo y elige Repostar vehiculo.
Para detener antes, pulsa X o elige Detener repostaje.
Vuelve al surtidor y elige Devolver la manguera. Si sobro combustible, se devuelve el dinero.

Vehiculos electricos: se cargan en los cargadores con Abrir menu de carga, con modo normal (mas barato y lento) o rapido.

Bidon: se compra en el panel del surtidor. Con el bidon en el inventario, apunta al deposito de un vehiculo y elige Rellenar con bidon. Lleva la cuenta de los litros restantes.

HUD: con Config.HUD.modo = 'auto' aparece al repostar o cuando el combustible baja del umbral. Con poco combustible el recurso muestra un aviso.

Para administradores

Escribe /combustibleadmin (con el permiso asignado).
Elige una estacion o la opcion global.
Para cada tipo de combustible puedes cambiar el precio (de 0 a 1000), activar o apagar la disponibilidad o restablecer a los valores base.
La prioridad es: ajuste de la estacion, luego ajuste global, luego valores de shared/config.lua.
El panel permite teletransportarte a la estacion elegida.
Los cambios se guardan en ov_combustible_estaciones y la consola muestra quien los hizo.
Para agregar un surtidor, anade una linea en Config.CustomGasPumpLocations; para un cargador, en Config.Electric.chargersLocation. Para ajustar el tanque de un modelo concreto, usa Config.FuelTankSize.perVehicle.

Preguntas frecuentes

Es compatible con scripts que llaman a LegacyFuel o lc_fuel? El recurso expone GetFuel, SetFuel y SetFuelType con los nombres habituales y declara provide de esos recursos. Los scripts que usen esos exports deberian funcionar; verifica con tu script concreto.

Los surtidores no responden al apuntar. Comprueba que tu recurso de apuntado este iniciado antes y ofrezca el export ox_target, y que el modelo del surtidor este en Config.GasPumpProps.

Como cambio el precio del combustible? Desde /combustibleadmin (por estacion o global) o editando Config.DefaultValues.fuelPrice.

Como cambio el tamano del tanque? En Config.FuelTankSize: por clase en perClass y por modelo en perVehicle.

Un vehiculo diesel deja de funcionar al repostar. Revisa que el modelo este en Config.DieselVehicles y que se uso diesel. El combustible equivocado averia el motor.

Donde veo los errores? En la consola del servidor (mensajes [ov_combustible]) y en la consola F8 del cliente.

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re (en tus recursos comprados) y en la tienda. Descargalas con la misma cuenta Cfx.re de la compra y reemplaza la carpeta, conservando tus cambios en shared/config.lua. Para soporte, abre un ticket en el Discord de la tienda: [enlace de soporte]. Indica la version del recurso, el error de consola y los pasos para reproducirlo.