Install & Configure

Requirements

• FS-Lib for the default prompts and notifications.
• OneSync enabled on your FiveM server.
• A supported money system: FS-Money, Qbox, QB-Core, or ESX. Developers can connect another system with the custom integration.

FS-Fuel does not need an SQL import. Your money system may have its own database requirements.

Installation

ensure FS-Lib
ensure FS-Money
ensure FS-Fuel

Where to change things

Most server options live in config.lua. Locations are managed through /fueladmin and saved in the two placement JSON files. Only custom model displays need data/pump_screens.lua; built-in model geometry and hose slack are internal.

Payments

Leave Config.Integrations.money = 'auto' to detect your money system. If several are running, choose one: 'fs-money', 'qbox', 'qb', or 'esx'. Automatic detection checks them in that order.

Config.Money.Account selects 'bank' or 'cash'. By default, the final bill is collected when the nozzle is returned or dropped. Unpaid bills are retained for another collection attempt.

PreAuth means a temporary payment hold. It is off by default. If enabled, the script reserves Amount (default 100) as one shared hold across the player's concurrent nozzle sales, then refunds the unused amount after settlement. AllowOverage = false stops spending at that reserved budget; true allows further spending from available funds.

Without a hold, each nozzle's bill is collected when that nozzle is returned or dropped. Concurrent sales share a spending limit, while each pump face shows its own nozzle's sale. Fractional credit carries during a sale; whole-dollar money integrations can round the final debit up.

Gas prices

Edit these two tables inside Config.FuelPrices:

GasPerGallon = {
    LosSantos = 6.40,
    SandyShores = 6.07,
    PaletoBay = 6.20,
},
DieselPerGallon = {
    LosSantos = 8.36,
    SandyShores = 8.12,
    PaletoBay = 8.16,
},

These are configured starting prices per US gallon, not a live real-world price feed. They always end in 9/10 cent: entering 6.40 or 6.409 charges $6.409. A different third decimal is replaced with 9 in billing, signs, and pump displays; the fractional digit is not configurable.

• UseRegionalPrices = true: each pump uses its region's price.
• UseRegionalPrices = false: every pump uses the Los Santos price.
• A sale keeps its price once dispensing begins, even if prices later change.

The pump's position chooses the region. By default, map Y below 2000 uses Los Santos, Y from 2000 to below 5500 uses Sandy/Blaine County, and Y 5500 or higher uses Paleto. Edit RegionBoundaries only if you want different coverage.

Automatic changes

Leave AutomaticChanges.Enabled = false for fixed prices. Turn it on to simulate changes; it does not fetch real-world prices.

All regions and both liquid-fuel grades move by the same amount and keep the 9/10-cent ending. The current adjustment survives resource restarts. There is currently no EIA or other live fuel-price API integration and no API key to enter.

Diesel vehicles

Diesel vehicles use the same liquid-fuel pumps, tank capacities, and driving-consumption settings. The connected vehicle selects its grade; return the nozzle before changing grades. This does not add wrong-fuel damage or separate diesel nozzle models.

Config.DieselVehicles accepts spawn names or hashes. Set a model to true to force diesel or false to exclude it from diesel selection. A true diesel override also takes precedence over electric detection; false still allows the vehicle to be detected as electric.

-- Add these entries inside the existing Config.DieselVehicles table:
my_diesel_truck = true,
my_gas_truck = false,

By default, Config.DieselVehicleClasses includes industrial (10), utility (11), service (17), military (19), and commercial (20), with individual exceptions already listed in the config. Known electric vehicles are excluded from class-based diesel selection. Set the class table to {} for model-only selection.

For add-on or reclassified models, a direct DieselVehicles entry is simplest. Alternatively, set a shared class in Config.DieselClassOverrides, such as my_custom_truck = 20, so the client and server agree.

Tank sizes and fuel use

Config.TankCapacity.ByClass sets how many gallons each automobile class holds. For example, a compact holds 12 gallons and an SUV holds 24. ByType covers motorcycles, boats, aircraft, and other vehicle types. Default is used when no matching size is available.

To give one vehicle its own tank size, add its spawn name inside ByModel:

ByModel = {
    ['my_vehicle'] = 20.0,
},

That vehicle now holds 20 gallons, regardless of its class. Setting a capacity to 0 prevents refueling. Model hashes are also accepted in place of spawn names.

Tank size is separate from driving consumption. Config.Fuel.BaseDrainPerTick controls the base drain, and ClassRates adjusts it by class. Lower numbers use less fuel.

Refueling with the engine running

Gasoline vehicles can refuel with the engine on. By default, this has a 0.1% explosion chance per minute while gasoline is flowing: about 1 in 1,000 for a full minute. Starting the engine during a fill also creates this risk. Turning it off removes the risk.

To disable the feature, set Config.EngineRunningExplosion.Enabled = false. Gasoline refueling still works with the engine running. Change ChancePerMinute to adjust the percentage; 0 also disables the chance.

Electric charging and fuel poured onto the ground do not trigger this feature. If an explosion happens, dispensing stops and the fuel already delivered is billed normally. Any unused payment hold is refunded.

Other common settings

If you select target interactions, start the target resource first. FS-Lib is still required. If no supported target is running, the script falls back to its default prompts.

Vehicle fuel gauge

Config.FuelGauge.Enabled turns the built-in vehicle gauge on or off. It is enabled by default and switches to a battery display for EVs. Disable it when using another HUD's gauge.

The gauge hides on foot, on bicycles, when dead, and in the pause menu. It can remain visible with the engine off. This is separate from the pump's optional 2D meter (Config.ShowPumpUI).

Electric settings

Under Config.Electric, PricePerKWh is the electricity price (default $0.35) and ChargeKWhPerMinute is the charging speed (default 20 kWh per minute). Liquid-fuel region prices do not change electricity prices. Keep Enabled = true to allow charging; the charger and connector models are included.

Charging allows the engine on or off, including occupied vehicles. Electric charging does not use the gasoline engine-running explosion feature.

Slowdown.Enabled makes charging gradually slower after Slowdown.StartPercent (80% by default). Turn it off for a constant charging speed. The display shows battery percentage, estimated time remaining, energy added, and session cost.

Battery capacity uses kWh, not gallons. Add a vehicle to BatteryCapacityKWh.ByModel to change its capacity:

ByModel = {
    ['my_electric_car'] = 100.0,
},

If an addon vehicle is detected incorrectly, add it to VehicleOverrides:

VehicleOverrides = {
    ['my_electric_car'] = true,
    ['my_gas_car'] = false,
},

true means electric; false means non-electric, with gasoline/diesel selection handled by the diesel settings. An explicit DieselVehicles entry set to true takes precedence.

Driving.DrivingMinutes is the main EV range setting: default 25 minutes for the baseline 75 kWh vehicle; higher values last longer. RegenBraking.Enabled controls battery recovery and extra slowing when the accelerator is released. Regen tapers near a full battery and near a stop; use the brake pedal to stop completely.