cdn-fuel — Manual

Sistema de combustível com bicos e mangueira, recarga de elétricos, jerry can, sifonagem, abastecimento de aeronaves e barcos, e postos de gasolina compráveis por jogadores.

Sumário

1. Dependências
2. Instalação
3. Itens
4. Configuração
5. Postos de gasolina
6. Veículos elétricos
7. Abastecimento de aeronaves e barcos
8. Jerry can e sifonagem
9. Consumo de combustível
10. Comandos
11. Integrações
12. Entrypoints para outros recursos
13. Localização
14. Estrutura de arquivos

Dependências

O fxmanifest.lua declara provide 'cdn-syphoning'. A sifonagem está embutida aqui — não rode o cdn-syphoning separadamente.

Instalação

1. Copie a pasta cdn-fuel para resources/.
2. Mova os sons de assets/sounds/ para interact-sound/client/html/sounds.
3. Importe o SQL assets/sql/cdn-fuel.sql. Ele cria a tabela fuel_stations e insere as 27 estações padrão.
4. Registre os itens jerrycan e syphoningkit no inventário (ver Itens) e copie as imagens de assets/images/ para a pasta de imagens do inventário.
5. Garanta que o cdn-fool esteja no server.cfg antes do cdn-fuel, para que os modelos do carregador elétrico existam:

   ensure PolyZone
   ensure interact-sound
   ensure cdn-fool
   ensure cdn-fuel
6. Ajuste shared/config.lua, principalmente Config.Core, Config.TargetResource e o bloco Config.Ox.
7. Conflitos — remova qualquer outro recurso de combustível (LegacyFuel, ps-fuel, cdn-syphoning). Vários recursos de veículo checam combustível pelo decor _FUEL_LEVEL; dois sistemas escrevendo nesse decor brigam entre si.

Aviso do autor sobre restart: reiniciar um recurso que faz stream de props pode travar clientes. Neste fork os modelos elétricos já foram separados no cdn-fool, então dar restart no cdn-fuel é seguro.

Itens

["syphoningkit"] = {name = "syphoningkit", label = "Kit Syphoning", weight = 5000, type = "item", image = "syphoningkit.png", unique = true, useable = true, shouldClose = false, description = "Um kit feito para sifonar gasolina."},
["jerrycan"] = {name = "jerrycan", label = "Jerry Can", weight = 15000, type = "item", image = "jerrycan.png", unique = true, useable = true, shouldClose = false, description = "Um Jerry Can feito para armazenar gasolina."}

Com Config.Ox.Inventory = true, a quantidade de combustível dentro do jerry can e do kit é guardada como metadata do ox_inventory. Ambos são registrados como usáveis via CreateUseableItem.

Configuração

Arquivo: shared/config.lua.

Geral

Visual

Emergência

Jerry can e sifonagem

Postos de propriedade de jogadores

Elétricos e consumo

Postos de gasolina

Config.GasStations traz 27 postos, cada um com uma PolyZone, um ped de gerência e um ponto de carregador elétrico.

O estado persistente de cada posto (dono, reserva, preço, saldo e nome) vive na tabela fuel_stations, indexada pelo mesmo índice numérico do Config.GasStations — se você adicionar um posto novo no config, precisa inserir a linha correspondente na tabela.

O que o dono pode fazer

Falando com o ped do posto que possui: comprar reservas de combustível, definir o preço do litro (limitado por MinimumFuelPrice e MaxFuelPrice), sacar e depositar no caixa do posto, renomear o posto (filtrado pela ProfanityList), desligar as bombas (se Config.EmergencyShutOff) e vender o posto de volta por GasStationSellPercentage do valor.

Com Config.OwnersPickupFuel = true, a reserva comprada não cai direto: o dono recebe um caminhão em Config.DeliveryTruckSpawns e precisa levá-lo até a PolyZone de entrega para que os litros entrem no posto.

Veículos elétricos

Com Config.ElectricVehicleCharging = true, os modelos listados em Config.ElectricVehicles consomem bateria em vez de combustível e só podem ser recarregados nos carregadores elétricos — spawnados em electricchargercoords de cada posto, usando os modelos electric_charger e electric_nozzle que vêm do recurso cdn-fool.

A recarga é cobrada por “KW” (Config.ElectricChargingPrice), com o mesmo desconto de emergência do combustível. Diferente da gasolina, o valor da recarga não é repassado ao dono do posto.

Abastecimento de aeronaves e barcos

Config.AirAndWaterVehicleFueling define 18 áreas ativas (helipontos de MRPD, Pillbox, Central LS Medical, Zancudo, Paleto PD, Sandy, aeroporto, Merryweather, Devin Weston, entre outras) e docas para embarcações.

Opções globais da seção: refuel_button (controle de interação, padrão 47 = tecla G), nozzle_length (distância máxima do bico até a bomba antes de ele voltar, padrão 20.0), air_fuel_price (padrão 10/litro) e water_fuel_price (padrão 4/litro). O desconto de emergência também vale aqui.

Jerry can e sifonagem

Jerry can — comprado na bomba por Config.JerryCanPrice (mais imposto), já vem com Config.JerryCanGas litros. Usar o item abre o menu para abastecer um veículo próximo ou reabastecer o próprio galão numa bomba, até Config.JerryCanCap.

Sifonagem — desligada por padrão (Config.UseSyphoning = false). Com o syphoningkit, o jogador drena combustível de um veículo para o kit (até Config.SyphonKitCap). Cada tentativa tem Config.SyphonPoliceCallChance% de disparar um alerta no sistema de dispatch escolhido em Config.SyphonDispatchSystem.

Consumo de combustível

O consumo por segundo é lido de Config.FuelUsage pela faixa de RPM atual e multiplicado pelo fator da classe do veículo em Config.Classes. Veículos listados em Config.NoFuelUsage e classes com fator 0.0 (por padrão, Cycles) não consomem nada.

O nível fica no decor _FUEL_LEVEL da entidade. Veículos que aparecem sem o decor recebem um nível aleatório entre 20 e 80 litros.

Com Config.VehicleShutoffOnLowFuel, o motor desliga sozinho ao atingir shutOffLevel e, se sounds.enabled, toca o alerta configurado.

Comandos

Todos os comandos só existem quando Config.FuelDebug = true.

Estes comandos não têm gate de permissão no código — eles simplesmente não são registrados com Config.FuelDebug = false. Não deixe o debug ligado em produção.

Integrações

ox_lib / ox_inventory / ox_target

Controlados pelo bloco Config.Ox e por Config.TargetResource. Com Config.Ox.Inventory = true, o combustível dentro do jerry can e do kit de sifonagem é guardado como metadata do item, em vez de depender do qb-inventory.

qb-target

Alternativa ao ox_target. Se você sofre com o bug em que a opção de abastecer aparece fora do posto, instale o export AllowRefuel no qb-target e ligue Config.FuelTargetExport. Com ox_target, esse campo precisa ficar em false, senão o recurso chama um export que não existe e gera erro.

cdn-fool

Fornece os modelos electric_charger e electric_nozzle. Necessário sempre que Config.ElectricChargerModel = true. Precisa ser iniciado antes do cdn-fuel.

qb-phone

Com Config.RenewedPhonePayment = true, o pagamento no débito vira uma notificação no celular (exports['qb-phone']:PhoneNotification), em vez de sair direto da conta.

ps-dispatch / qb-dispatch

Alertam a polícia quando alguém é pego sifonando. O sistema é escolhido em Config.SyphonDispatchSystem; a opção "qb-default" só cria um blip, e "custom" exige que você implemente a chamada no client/fuel_cl.lua.

Entrypoints para outros recursos

O recurso exporta duas funções, do lado cliente (declaradas em exports { 'GetFuel', 'SetFuel' } no fxmanifest.lua, implementadas em client/utils.lua).

-- Lê o nível de combustível do veículo (decor _FUEL_LEVEL).
local fuel = exports['cdn-fuel']:GetFuel(vehicle)
 
-- Define o nível de combustível do veículo.
exports['cdn-fuel']:SetFuel(vehicle, 100.0)

Uso típico — impedir dar partida sem combustível:

if exports['cdn-fuel']:GetFuel(veh) ~= 0 then
    SetVehicleEngineOn(veh, true, false, true)
else
    QBCore.Functions.Notify('Sem combustível..', 'error')
end

Localização

Os textos usam o sistema de locale do qb-core (Lang:t(...)), não o do ox_lib. O idioma é escolhido descomentando a linha correspondente em shared_scripts no fxmanifest.lua — não há convar:

shared_scripts {
    'shared/config.lua',
    '@qb-core/shared/locale.lua',
    '@ox_lib/init.lua',
    'locales/pt-br.lua', -- ativo
    -- 'locales/en.lua',
    -- 'locales/de.lua',
    -- 'locales/fr.lua',
    -- 'locales/es.lua',
    -- 'locales/ee.lua',
}

Idiomas disponíveis em locales/: pt-br (ativo neste fork), en, de, fr, es, ee.

Estrutura de arquivos

cdn-fuel/
├── client/
│   ├── fuel_cl.lua        — bicos, mangueira, abastecimento, jerry can, sifonagem, zonas de ar/água, comandos de debug
│   ├── electric_cl.lua    — carregadores elétricos, cabo e menus de recarga
│   ├── station_cl.lua     — menus do ped: comprar, gerenciar, precificar, sacar/depositar, entregar reservas
│   └── utils.lua          — GetFuel/SetFuel, imposto, blips, checagem de blacklist
├── server/
│   ├── fuel_sv.lua        — cobrança, itens usáveis (jerrycan, syphoningkit), dispatch da sifonagem
│   ├── station_sv.lua     — CRUD da tabela fuel_stations: dono, reservas, saldo, preço, nome
│   └── electric_sv.lua    — cobrança da recarga elétrica
├── shared/
│   └── config.lua         — toda a configuração: postos, elétricos, zonas de ar/água, consumo, profanity list
├── locales/
│   ├── pt-br.lua          — ativo no fxmanifest
│   ├── en.lua
│   ├── de.lua
│   ├── es.lua
│   ├── fr.lua
│   └── ee.lua
├── assets/
│   ├── sql/cdn-fuel.sql   — tabela fuel_stations + 27 estações padrão
│   ├── sounds/            — mover para interact-sound/client/html/sounds
│   └── images/            — imagens de jerrycan e syphoningkit para o inventário
├── version                — 2.1.9
└── fxmanifest.lua         — deps, exports GetFuel/SetFuel, provide 'cdn-syphoning'