Bucky Fuel

#Overview

Bucky Fuel turns fuel into a player-run business. Players buy one of 26 stations, set the pump price, truck fuel in from depots by tanker, hire drivers and upgrade the station, while every driver in the city refuels with a nozzle and a retro pump terminal.

#Requirements

Works on FiveM and FiveM Enhanced.

#Installation

#1. Place the resources

resources/
└── [bucky-scripts]/
    ├── bucky-fuel/
    └── LegacyFuel/      -- the included compatibility bridge

Remove any other fuel script (including the original LegacyFuel) first.

#2. Database

Import bucky-fuel/sql/install.sql. It creates bucky_fuel_stations and bucky_fuel_employees, and is safe to re-run. Newer columns are added automatically on start.

#3. server.cfg

ensure oxmysql
ensure qb-core
ensure qb-target

ensure bucky-reserve
ensure bucky-fuel
ensure LegacyFuel

#Refuelling

At any pump (models in Config.PumpModels), players use the target menu:

1. Get Fuel Nozzle at the pump.
2. Insert Nozzle into the vehicle.
3. Put Fuel at the refuel terminal, choose the amount and pay by card or cash.
4. Remove Nozzle and Return Nozzle when done.

Fuel goes in at Config.RefillTimePerLitre (0.5 s per litre) and comes out of the station's tank. If the station's tank is empty, it can't sell fuel.

Vehicles burn fuel Config.GlobalFuelConsumptionMultiplier times faster than GTA's default (4.5×), and fuel levels sync between players every Config.FuelSyncTime seconds.

#Jerry cans

The can's fuel is stored on the weapon_petrolcan item, so it shows in the inventory and survives a relog.

Config.JerryCan = {
    Capacity = 50,          -- litres
    ContainerFee = 0,       -- extra charge for the can itself
    PourTimePerLitre = 0.4,
    FillTimePerLitre = 0.2, -- 50 L = 10 s at a pump
}

#Owning a station

Players buy a station from the attendant at the station ("Talk to Attendant"). Each station has its own price, pump count, tank size and upgrade ceiling, set in Config.Stations.

From the owner dashboard, owners:

• set the pump price
• see stock, income, sales and customers
• start a tanker resupply
• hire and pay employees (Config.EmployeePayPerDelivery, $500 per delivery)
• buy upgrades and protection
• withdraw income

Keep the tank stocked. A station that sits at 0 fuel for more than 24 hours is reset and goes back on sale. Each day of Protection adds 24 hours to that limit.

#Tanker resupply

1. Start a resupply from the dashboard (Config.TankerCost, $5,000).
2. Pick up a phantom truck and tanker trailer at one of the 5 fuel depots (Config.FuelDepots).
3. Drive to the station and unload. Unloading takes Config.TankerUnloadTime (20 s); pressing X stops it and nothing is delivered.

Each tanker carries Config.TankerCapacity litres (10,000), plus any truck upgrades. Fuel is bought at the wholesale price (Config.WholesaleFuelPrice, $2/L).

#Pricing and demand

Owners set the price per litre. Background customers compare it to the station's certified maximum price, so a higher price sells fewer litres:

litres sold × (1 − Elasticity × (price / maxPrice)²)

With the default elasticity of 0.41, profit keeps rising with price and peaks at about 92 % of the maximum. Charging the full maximum sells about 41 % fewer litres than charging almost nothing. The dashboard's profit gauge uses the same formula.

Config.PriceDemand = {
    Enabled = true,   -- false: volume ignores price
    Elasticity = 0.41,
}

#Upgrades

Upgrades are bought from the dashboard and paid into the Central Reserve. Each station caps how far it can upgrade.

#Taxes and the Reserve

Bucky Fuel never creates money. Everything owners pay goes into Bucky Reserve's Central Reserve and is written to its ledger:

#Configuration

Everything is in config.lua. It stays editable in the escrowed release.

If you change a station's price here, change the same station in Bucky Reserve's Config.FuelIntegration.Stations so its Marketplace shows the same figure.

#Commands

Admin commands need the qbcore.admin group.

#Exports

-- Client
local fuel = exports['bucky-fuel']:GetFuel(vehicle)   -- 0-100
exports['bucky-fuel']:SetFuel(vehicle, 75.0)

Scripts that use LegacyFuel's exports (exports['LegacyFuel']:GetFuel / SetFuel) keep working through the included LegacyFuel bridge, which forwards them to Bucky Fuel. That covers QBCore's jobs, the vehicle shop and cruise control.

#Troubleshooting

"Couldn't start resource bucky-fuel". Bucky Reserve must be installed and started; it's a dependency in this release.

Scripts still show fuel from the old system. Make sure the original LegacyFuel is removed and the included LegacyFuel bridge is started after bucky-fuel.

A station can't sell fuel. Its tank is empty. Run a tanker resupply, or /fulltank [id] as an admin.

An owner lost their station. It sat at 0 fuel longer than 24 hours plus any Protection days, so it was reset and put back on sale.

The pump target doesn't show. Check the pump's model is in Config.PumpModels and that qb-target is started before Bucky Fuel.