Updated 2026-10-11 · 4 min read
qb-fuel: client exports and configuration
qb-fuel handles vehicle fuel level, refueling and petrol cans. This page describes upstream commit 2e51aa3. Many third-party examples refer to a different resource or an older fuel API.
Install and start order
- Install
qb-core,qb-targetandPolyZonebeforeqb-fuel. These are named in the upstream README; the manifest declaresqb-target. - Place
qb-fuelin the resources directory and start it after the dependencies. - Verify that existing vehicle-shop, garage and HUD scripts use compatible fuel exports. Keep only one authoritative fuel implementation active.
- On a test server, check a spawned vehicle's fuel level, refueling at a pump and a petrol-can purchase.
Client exports (the supported integration surface)
Only the client-side client/exports.lua registers these two exports:
| Export | Arguments | Return |
|---|---|---|
GetFuel | vehicle entity handle | Fuel number or nil when the entity is invalid |
SetFuel | vehicle, fuel | Sets fuel clamped to 0–100; no useful return |
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
if vehicle ~= 0 then
local fuel = exports['qb-fuel']:GetFuel(vehicle)
if fuel then
print(('Fuel: %.1f'):format(fuel))
exports['qb-fuel']:SetFuel(vehicle, math.min(100.0, fuel + 10.0))
end
endThis example belongs in a client resource. The reviewed server/main.lua does not register server-side GetFuel or SetFuel exports. Do not call them from server.lua or present them as shared functions.
LegacyFuel compatibility
The manifest includes provide 'LegacyFuel' and the client registers the legacy export handlers. Existing client resources that use exports['LegacyFuel']:SetFuel(vehicle, value) can work with qb-fuel, provided load order and installed resource versions are compatible. Verify both fuel reads and writes after swapping implementations.
Real configuration keys
The current Config.lua uses these settings:
| Key | Current default | Purpose |
|---|---|---|
GlobalFuelConsumptionMultiplier | 4.5 | Vehicle handling-based consumption multiplier |
SyncFuelBetweenPlayers | true | Replicate fuel state via entity state bags |
FuelSyncTime | 10 | Sync interval in seconds |
MoneyType | 'cash' | Account used to pay for fuel |
FuelPrice | 5 | Price per litre |
JerryCanCost | 100 | Petrol-can purchase price |
JerryCanLitre | 40 | Can capacity |
JerryCanRefillCost | Calculated from price × litres | Refill price |
RefillTimePerLitre | 0.5 | Refuel delay per litre |
Blip, PumpModels, GasStations | Tables | Map markers, pump models and locations |
Example:
Config.GlobalFuelConsumptionMultiplier = 4.5
Config.SyncFuelBetweenPlayers = true
Config.FuelSyncTime = 10
Config.MoneyType = 'cash'
Config.FuelPrice = 5Older snippets mentioning Config.FuelDecor, Config.FuelUsage, Config.FuelTickRate or Config.ExcludedModels do not describe this revision.
Server-side purchase flow
The bundled server/main.lua registers:
- QBCore callback
qb-fuel:server:refillVehicle— charges litres ×Config.FuelPrice, usingConfig.MoneyType. - Events
qb-fuel:server:buyJerryCan,qb-fuel:server:refillJerryCanandqb-fuel:server:setCanFuel.
These are internal flows, not qb-fuel:server:buyFuel, qb-fuel:client:fuelChanged or qb-fuel:client:vehicleOutOfFuel API contracts. A custom integration that charges money must validate the request server-side. In particular, review client-supplied litre amounts and can-fuel values before exposing the handlers to untrusted callers.
Fuel synchronizes using an entity state key named qb-fuel when Config.SyncFuelBetweenPlayers is enabled. Persisting fuel across vehicle deletion/recreation remains the responsibility of the owning vehicle/garage integration.
Troubleshooting
| Symptom | Check |
|---|---|
No such export GetFuel in resource qb-fuel | Ensure code runs on the client, qb-fuel is started, and the resource is not a different fork |
No such export ... in resource LegacyFuel | Verify qb-fuel manifest provide and resource startup order |
| Fuel resets on respawn | Check vehicle-spawn/garage property persistence separately from state-bag replication |
| Gas pump does not respond | Check qb-target, PolyZone, pump model, distance and console errors |
| Fuel doesn't change or sync | Verify entity is a vehicle, SyncFuelBetweenPlayers, network ownership and sync settings |
| Paying for fuel fails | Verify the selected MoneyType balance and qb-fuel:server:refillVehicle callback |
Update checklist
- Pin deployed
qb-fuel,qb-target, garage and vehicle-shop commits together. - Test
GetFuel/SetFuelon the client andLegacyFuelcompatibility. - Test refueling, invalid purchase requests, petrol-can costs, state sync and vehicle respawn.
- Revisit vehicle-state troubleshooting before changing persistence.
Sources
Repository · Client exports · Server purchase logic · Manifest
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
qb-streetraces
Review QBCore street-race commands, stake limits, event handlers and legacy player-method compatibility before installing or enabling wagers.
qb-garages
Source-backed qb-garages guide covering current public, house, gang, job and depot garages, AutoRespawn, SharedGarages, vehicle classes and house-garage integration.
