QBCore Frameworkqbcore.netCommunity docs
On this page

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

  1. Install qb-core, qb-target and PolyZone before qb-fuel. These are named in the upstream README; the manifest declares qb-target.
  2. Place qb-fuel in the resources directory and start it after the dependencies.
  3. Verify that existing vehicle-shop, garage and HUD scripts use compatible fuel exports. Keep only one authoritative fuel implementation active.
  4. 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:

ExportArgumentsReturn
GetFuelvehicle entity handleFuel number or nil when the entity is invalid
SetFuelvehicle, fuelSets 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
end

This 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:

KeyCurrent defaultPurpose
GlobalFuelConsumptionMultiplier4.5Vehicle handling-based consumption multiplier
SyncFuelBetweenPlayerstrueReplicate fuel state via entity state bags
FuelSyncTime10Sync interval in seconds
MoneyType'cash'Account used to pay for fuel
FuelPrice5Price per litre
JerryCanCost100Petrol-can purchase price
JerryCanLitre40Can capacity
JerryCanRefillCostCalculated from price × litresRefill price
RefillTimePerLitre0.5Refuel delay per litre
Blip, PumpModels, GasStationsTablesMap markers, pump models and locations

Example:

Config.GlobalFuelConsumptionMultiplier = 4.5
Config.SyncFuelBetweenPlayers = true
Config.FuelSyncTime = 10
Config.MoneyType = 'cash'
Config.FuelPrice = 5

Older 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, using Config.MoneyType.
  • Events qb-fuel:server:buyJerryCan, qb-fuel:server:refillJerryCan and qb-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

SymptomCheck
No such export GetFuel in resource qb-fuelEnsure code runs on the client, qb-fuel is started, and the resource is not a different fork
No such export ... in resource LegacyFuelVerify qb-fuel manifest provide and resource startup order
Fuel resets on respawnCheck vehicle-spawn/garage property persistence separately from state-bag replication
Gas pump does not respondCheck qb-target, PolyZone, pump model, distance and console errors
Fuel doesn't change or syncVerify entity is a vehicle, SyncFuelBetweenPlayers, network ownership and sync settings
Paying for fuel failsVerify the selected MoneyType balance and qb-fuel:server:refillVehicle callback

Update checklist

  1. Pin deployed qb-fuel, qb-target, garage and vehicle-shop commits together.
  2. Test GetFuel/SetFuel on the client and LegacyFuel compatibility.
  3. Test refueling, invalid purchase requests, petrol-can costs, state sync and vehicle respawn.
  4. 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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website