# qb-fuel: client exports and configuration

`qb-fuel` handles vehicle fuel level, refueling and petrol cans. This page describes [upstream commit 2e51aa3](https://github.com/qbcore-fivem/qb-fuel/tree/2e51aa319af37ae3d8d9d36c8b1c298125262c61). 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](https://github.com/qbcore-fivem/qb-fuel/blob/2e51aa319af37ae3d8d9d36c8b1c298125262c61/README.md); 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`](https://github.com/qbcore-fivem/qb-fuel/blob/2e51aa319af37ae3d8d9d36c8b1c298125262c61/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 |

~~~lua filename="client.lua"
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`](https://github.com/qbcore-fivem/qb-fuel/blob/2e51aa319af37ae3d8d9d36c8b1c298125262c61/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:

~~~lua filename="Config.lua"
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`](https://github.com/qbcore-fivem/qb-fuel/blob/2e51aa319af37ae3d8d9d36c8b1c298125262c61/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

| 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

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](/docs/troubleshooting/vehicle-state) before changing persistence.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-fuel/tree/2e51aa319af37ae3d8d9d36c8b1c298125262c61) · [Client exports](https://github.com/qbcore-fivem/qb-fuel/blob/2e51aa319af37ae3d8d9d36c8b1c298125262c61/client/exports.lua) · [Server purchase logic](https://github.com/qbcore-fivem/qb-fuel/blob/2e51aa319af37ae3d8d9d36c8b1c298125262c61/server/main.lua) · [Manifest](https://github.com/qbcore-fivem/qb-fuel/blob/2e51aa319af37ae3d8d9d36c8b1c298125262c61/fxmanifest.lua)
