overview | Benzy Documentation

BenzyFuel

A realistic, standalone FiveM fuel script. Players park, grab a pump nozzle with a hose that runs back to the pump, carry it to the car's fuel cap, and watch a real gas-pump screen count up the gallons and the cost as the tank fills. Pumps and fuel caps are auto-detected (no coordinates to place), fuel drains while driving, and players can buy a jerry can to rescue a friend who has run dry. Charging, notifications, and prompts run through BenzyBridge, and it needs no framework or database.

Made by Samuel Benzy of Benzy Development.

Features

Grab-and-carry refueling — walk up to a pump, press E to pick up the nozzle (a hose connects it to the pump), carry it to the car's fuel cap, press E to start, and hang it back up when you're done to pay.
A real gas-pump screen — an on-screen LCD shows the total sale, the gallons/litres dispensed, the price per unit, and a live tank gauge, styled like an actual dispenser.
Auto-detected pumps — every stock GTA V pump is auto-detected, and you can add custom / mapped pump props in the config. No coordinates, ever.
Auto-detected fuel tanks — the nozzle seats itself at each vehicle's real fuel cap, with a sensible fallback for vehicles that don't have one.
Gallons or litres, USD or Euros — switch the measurement unit and the currency in the config; everything on the screen follows.
Fuel consumption — vehicles burn fuel while driving (per-class rates, based on throttle), and stall when the tank runs dry. Turn it off in one line if another script owns consumption.
Jerry cans — buy a can at any pump with H, select it from your weapon wheel, and pour it into any vehicle with E — including someone else's car when they've run out on the highway.
Charges through BenzyBridge — whatever money system the bridge resolves is what pays; nothing to wire up. Turn charging off entirely for free fuel.
Draw-text or targeting — clean "Press E" prompts (rendered by BenzyBridge), or switch to a targeting menu (ox_target / qb-target, whichever BenzyBridge detects) if you run one.
Runs on any stack — through BenzyBridge, BenzyFuel works the same on ESX / QBCore / QBox / standalone, with or without a database; the bridge auto-detects the framework, money, and targeting system.

How it works

Each vehicle's fuel level (0–100%) is synced across every player, so everyone sees the same fuel, and it is mirrored to the game's own fuel level so the dashboard gauge and the engine behave. It stays on the vehicle until it despawns (see Notes).
The client runs the whole hands-on flow: it finds nearby pumps and fuel caps, spawns the nozzle + hose, dispenses fuel over time, and draws the realistic pump screen. Nothing takes control away from you — the screen and prompts never grab your cursor.
The server owns the money: when the nozzle goes back on the pump it recomputes the cost from the config (it never trusts a price sent by the client), charges through BenzyBridge, and fires events other resources can listen to.
With Require funds on, the pump asks the money system (through BenzyBridge) how much you can afford and stops the fill there, so a purchase can never fail for lack of money.

Requirements

A FiveM server.
BenzyBridge — required. BenzyFuel pulls in the bridge's include (@BenzyBridge/init.lua is its first shared script) and calls the in-process Benzy.* API for money charging, notifications, prompts, and admin access, so BenzyBridge must be started before BenzyFuel.
Runs on any stack. Through the bridge, BenzyFuel works the same on ESX / QBCore / QBox / standalone — the bridge auto-detects the framework, money, and targeting system, so there is nothing framework-specific to configure here.
Optional: a money system for BenzyBridge to charge (fuel is free if none is set), and ox_target / qb-target if you'd rather use a targeting menu than the built-in prompts.

Installation

Place the BenzyFuel folder in your server's resources directory.

Add it to your server.cfg in the right order — your SQL connector first, then your framework (if any), then BenzyBridge, then any providers (money / notifications / targeting), and BenzyFuel last:

ensure oxmysql            # SQL connector (or mysql-async) — only if you use a database
ensure es_extended        # your framework, if any (or qb-core / qbx_core)
ensure BenzyBridge        # the bridge — must start before BenzyFuel
ensure BenzyMoney         # providers: money / notifications / a targeting system
ensure BenzyFuel          # last

(Optional) Set up the benzy.fuel ACE permission for the admin commands (see Permissions).
Open config.lua and set your unit, currency, and price.
Restart the server (or ensure/restart BenzyFuel).

Configuration

Everything is configured in config.lua, and every option has a comment above it explaining what it does. The highlights:

Units & currency

Option	What it does
`Config.Unit`	`'gallons'` (gal) or `'litres'` (L) — the unit shown everywhere.
`Config.Currency`	`'USD'` (`$`) or `'EUR'` (`€`) — the symbol on the pump screen.

Match your currency. Set Config.Currency to whatever your money script uses so the pump screen and its notifications always agree.

Pricing & dispensing

Option	What it does
`Config.PricePerUnit`	Cost of one gallon/litre. The LCD shows cents, but the charge is rounded to a whole number.
`Config.DisplayDecimals`	Decimal places shown for volume + cost on the LCD.
`Config.FlowRate`	Units dispensed per second — lower is slower and more realistic.
`Config.UsePetrolTankVolume`	Read each vehicle's real tank size from its handling data, so bigger tanks cost more to fill.
`Config.TankCapacity`	Fallback tank size when the above is off or a vehicle has no usable value.

Billing

Option	What it does
`Config.ChargeForFuel`	`false` = free fuel (the pump still works and still fires the purchase event).
`Config.Account`	Pay from `'cash'` or `'bank'`.
`Config.PayTo`	Optional account key fuel revenue is paid into (e.g. a gas-station business); blank = it just leaves the player.
`Config.RequireFunds`	The pump only dispenses what the player can afford, so a sale never fails.
`Config.RollbackOnFailedCharge`	Only when `RequireFunds` is off — take the fuel back if a charge fails.

Consumption

Option	What it does
`Config.Consumption.Enabled`	Master switch for draining fuel while driving (off = let another script own consumption).
`Config.Consumption.RatePerSecond`	Percent of a tank burned per second at full throttle.
`Config.Consumption.IdleRate`	Fraction (0–1) of the full-throttle burn while idling.
`Config.Consumption.ThrottleInfluence`	How strongly RPM scales the burn (`1` linear, higher = revving costs more).
`Config.Consumption.KillEngineWhenEmpty`	Cut the engine at empty until the vehicle is refueled.
`Config.Consumption.LowFuelWarning`	Warn the driver once when fuel drops to this percent (`0` = off).
`Config.Consumption.ClassMultipliers`	Per-class burn multiplier (`>1` faster, `<1` slower, `0` = that class never uses fuel).

Interaction

Option	What it does
`Config.Interaction.Style`	`'drawtext'` (BenzyFuel's own proximity prompts, rendered by BenzyBridge) or `'target'` (a targeting menu — `ox_target` / `qb-target`, whichever BenzyBridge detects; falls back to draw-text if none is running).
`Config.Interaction.Key` / `Config.Interaction.BuyKey`	Keys to use the pump/nozzle and to buy a jerry can — rebindable in FiveM settings.
`Config.Interaction.DriveOff`	If a player gets into a vehicle with the nozzle still out: `'putaway'` (stow + settle up), `'block'` (can't drive until it's back on the pump), or `'explode'` (drag it past the hose and the pump + vehicle blow up).
`Config.Interaction.PumpDistance` / `Config.Interaction.FuelDistance`	How close (meters) you must be to a pump, and to a fuel cap, to interact.
`Config.Interaction.HoseLength`	How far you can walk from the pump with the nozzle before an invisible wall stops you.
`Config.Interaction.ExtraPumpModels`	Add your custom / mapped pump models on top of the built-in GTA V pumps.
`Config.Interaction.Nozzle`	The nozzle prop + hand/tank attachment offsets (only touch if the nozzle looks off).

Jerry cans

Option	What it does
`Config.JerryCan.Enabled`	Master switch for buying + pouring jerry cans.
`Config.JerryCan.Capacity`	Fuel (in your unit) a full can holds.
`Config.JerryCan.Price`	Cost of a full can (covers the can and its fuel).
`Config.JerryCan.FlowRate`	Units poured per second from the can.
`Config.JerryCan.Refill`	`true` = buying tops an existing can back to full; `false` = empty it before buying again.

Locale

Option	What it does
`Config.Locale`	Active language code (default `'en'`).

Webhooks

Config.Webhooks holds one Discord URL per channel — Purchases (fuel + jerry-can sales) and Errors (charge failures / missing money script). Leave a field empty to disable that log.

Units & currency

Config.Unit switches every volume between US gallons (gal) and litres (L), and Config.Currency switches the symbol between $ (USD) and € (EUR). Config.PricePerUnit is always the price of one unit in the chosen currency, and a full fill costs the vehicle's tank capacity × PricePerUnit — that capacity comes from each vehicle's handling by default (Config.UsePetrolTankVolume), or falls back to Config.TankCapacity.

Billing

When Config.ChargeForFuel is on, the sale is finalized server-side the moment the nozzle goes back on the pump: the cost is recomputed from Config.PricePerUnit (never trusted from the client), rounded to a whole number, and charged through BenzyBridge — whatever money system the bridge resolves is what pays.

BenzyFuel charges Config.Account ('cash'/'bank'); if you also set Config.PayTo to a business/society account key, that same amount is credited to that account (the player still pays from cash or bank as configured).

Set Config.ChargeForFuel = false for free fuel (the pump still works and still fires BenzyFuel:FuelPurchased, so logging/analytics keep working).

Consumption

With Config.Consumption.Enabled on (default), the vehicle you're driving burns fuel based on how hard you're on the throttle, scaled by a per-class multiplier (Config.Consumption.ClassMultipliers — set a class to 0 to exempt it, like emergency vehicles by default). When the tank hits empty the engine cuts out until you refuel, and the driver gets a one-time low-fuel warning when the tank drops to Config.Consumption.LowFuelWarning percent (default 20; set it to 0 to turn the warning off). Set Config.Consumption.Enabled = false to hand consumption to another script while BenzyFuel keeps doing the pumps + payment.

Jerry cans

At a pump, press H (rebindable) to buy a full jerry can — charged through your money script just like fuel. It goes into your weapon wheel as the petrol can (the wheel gauge shows how full it is); select it, walk up to any vehicle's fuel cap, and press E to pour it in; there's no charge to pour, because the fuel was paid for when you bought the can. Because the pour uses the same synced write path as the pump, you can top up another player's car — perfect for rescuing someone stranded. Tune the can's capacity, price, and pour speed under Config.JerryCan, or turn the whole feature off with Config.JerryCan.Enabled = false.

Targeting

By default BenzyFuel uses its own proximity prompts (Config.Interaction.Style = 'drawtext') — no dependencies; the "Press E" prompts are rendered by BenzyBridge. Set Config.Interaction.Style = 'target' to use a targeting menu on pumps and vehicles instead — BenzyFuel registers the same actions through the bridge, which routes them to whichever targeting system it detects (ox_target / qb-target); the actions appear as menu options gated by what you're doing. If no targeting system is running, BenzyBridge warns once and falls back to the draw-text prompts automatically.

What needs a framework or money system

BenzyFuel runs on a bare server and does more when you add systems — all through BenzyBridge, with no framework-specific config here.

Feature	Works standalone?	Needs
Fueling, the pump screen, consumption, jerry cans	Yes	Nothing — the hands-on flow, the weapon-wheel jerry can, and its session tracking are self-contained.
Charging for fuel / jerry cans	Fails open (free)	A money provider resolved by BenzyBridge (BenzyMoney, or a framework's cash/bank). With none, a charge can't be taken, so the fuel dispenses free — that is expected, not an error.
Paying revenue into `Config.PayTo`	Skipped	BenzyMoney (society/business accounts). On a framework money provider or none it is skipped; the player still pays from `Config.Account`.
Admin commands (`/setfuel`, `/givejerrycan`)	Yes (via ACE / identifiers / Discord)	The `Framework` access method additionally needs a framework; the other three methods carry the check standalone.
`Config.Interaction.Style = 'target'`	Falls back to draw-text	`ox_target` / `qb-target`, detected by BenzyBridge; otherwise it warns once and uses the built-in prompts.

No inventory needed. The jerry can is a weapon-wheel item tracked in BenzyFuel's own session state — it never touches an inventory script, so it behaves the same with or without one (ox / qb / qs inventory or none).

Commands

Command	Argument	Who can use it	What it does
`/setfuel`	`[0-100]`	`benzy.fuel`	Sets the fuel level of the vehicle you're in (testing / admin).
`/givejerrycan`	`[id]`	`benzy.fuel`	Gives a full jerry can to a player (blank = yourself).

Debug: debugbenzyfuel (in the server console, or a player's F8 console when Config.Debug = true) prints what BenzyBridge resolved for BenzyFuel; in the F8 console it also lists whether you hold the benzy.fuel ace.

Permissions

The admin commands (/setfuel, /givejerrycan) are gated by Config.Access.admin, checked through the bridge with Benzy.HasAccess(src, Config.Access.admin, 'benzy.fuel'). Everything else (fueling, buying and pouring jerry cans) is open to all players.

Config.Access.admin is a single role rule with four methods, any one of which grants access — they're OR'd together, and a method whose prerequisite is missing (no framework, Badger_Discord_API not running) is simply skipped:

Config.Access = {
    admin = {
        -- a framework job/group name (ESX: admin/superadmin · QBCore/Qbox: god/admin)
        Framework   = { ENABLE = false, list = { 'admin', 'superadmin' } },
        -- raw identifiers
        Identifiers = { ENABLE = false, list = { 'license:xxxxxxxxxxxxxxxx', 'fivem:1234567' } },
        -- when true, the fixed ACE string 'benzy.fuel' is checked
        AcePerms    = true,
        -- Discord role ids (needs Badger_Discord_API)
        Discord     = { ENABLE = false, list = { '123456789012345678', '987654321098765432' } },
    },
}

Framework — matches the player's job or group name against list (only your active framework's list applies; skipped on standalone).
Identifiers — matches any of the player's raw identifiers (license: / fivem: / steam: / discord: …) against list.
AcePerms — a true/false toggle; when true, the fixed ACE string benzy.fuel checked against the player’s ACE permissions.
Discord — matches the player's Discord role ids against list (needs Badger_Discord_API running).

The default is the ACE route (AcePerms = true). Enable it in your server.cfg:

add_ace group.admin benzy.fuel allow
add_principal identifier.license:YOUR_LICENSE_HERE group.admin

Leave a method ENABLE = false (or AcePerms = false) to skip it. This is the same access model every Benzy resource uses.

Integrating with other resources

BenzyFuel exposes a full API — GetFuel/SetFuel use the standard fuel-export names so most HUDs read its fuel with no changes. See the docs:

docs/EXPORTS.md — every export, with examples.
docs/EVENTS.md — the events other resources can listen to.
docs/INTEGRATIONS.md — how charging works (through BenzyBridge) and how HUDs read fuel.

Notes

Fuel is stored on the vehicle and is not saved to a database. It is synced to every player and stays on the vehicle for as long as that vehicle exists. It is wiped when the vehicle despawns, respawns, or the server restarts — this is intentional and keeps BenzyFuel dependency-free. If you want fuel to persist across restarts, save/restore it from your framework using exports.BenzyFuel:GetFuel/SetFuel.
Jerry cans last for the session. A player's can (and its fuel) is tracked while they're connected and is not saved across a disconnect or restart.

Troubleshooting

Turn on debug logging first — set Config.Debug = true, restart the resource, and watch the server console + each client's F8 console (and run debugbenzyfuel). You'll get diagnostics for pumps found, tank detection, every session, and each charge.
Fuel is free / a charge notice says there's no money system — make sure BenzyBridge is started (before BenzyFuel) and has a money system resolved. Check debugbenzyfuel or BenzyBridge's boot summary.
The nozzle looks off in the hand — tune Config.Interaction.Nozzle (bone + offsets). The defaults are tuned to the standard fueling grip.
The hose doesn't appear — the hose is a cosmetic rope; if it fails to draw the fueling still works.
Targeting options don't show — set Config.Interaction.Style = 'target', and make sure a targeting system (ox_target / qb-target) is started and detected by BenzyBridge (check debugbenzyfuel / BenzyBridge's boot summary). With none running, BenzyFuel falls back to the draw-text prompts.

Support

Need help? Visit support.benzy.lol.

Credits

Made by Samuel Benzy of Benzy Development.

Website: https://benzy.lol

Features​

How it works​

Requirements​

Installation​

Configuration​

Units & currency​

Pricing & dispensing​

Billing​

Consumption​

Interaction​

Jerry cans​

Locale​

Webhooks​

Units & currency​

Billing​

Consumption​

Jerry cans​

Targeting​

What needs a framework or money system​

Commands​

Permissions​

Integrating with other resources​

Notes​

Troubleshooting​

Support​

Credits​

Features

How it works

Requirements

Installation

Configuration

Units & currency

Pricing & dispensing

Billing

Consumption

Interaction

Jerry cans

Locale

Webhooks

Units & currency

Billing

Consumption

Jerry cans

Targeting

What needs a framework or money system

Commands

Permissions

Integrating with other resources

Notes

Troubleshooting

Support

Credits