The main idea was to stop relying on the usual hacky fuel scripts and instead build everything on top of FiveM’s native fuel-consumption feature. The whole fuel state - level, max volume and fuel type - is stored on StateBags, so it stays properly network-synced for every player on the server, no matter who is nearby.
Built on top of the native fuel consumption feature.
What it does
Fuel types
There are four fuel types you can assign per vehicle model:
- Gas (
gas) - the default for most cars - Diesel (
diesel) - trucks, vans and similar - Kerosin (
kerosin) - planes and helicopters - Electric (
electric) - electric vehicles
Each model is mapped to its fuel type in config.vehicles.lua. If a model isn’t mapped, the type is figured out automatically and then cached on the vehicle’s state so it doesn’t have to be recalculated.
Realistic refueling
Refueling isn’t just a progress bar. You grab the nozzle from the pump, which gets attached to your character with an actual physical rope. Then you walk over to the vehicle and attach the nozzle to the fuel cap - the correct bone is detected automatically (petrolcap, petroltank, etc.), with extra handling for bikes, helis and planes. When you’re done, you take the nozzle back and return it to the pump.
There’s also a distance watchdog: if the player, the vehicle or the pump get too far apart, the refueling cancels on its own. The allowed range is larger for helicopters and planes so the bigger aircraft still work properly.
Petrolcan (jerry can)
- Buy a petrolcan at any fuel station.
- Refill an empty one at the station.
- Use it to refuel vehicles anywhere - the can’s durability/ammo is consumed while fueling.
Wrong fuel & engine damage
You can optionally let players fill up with the wrong fuel type. If more than a configurable amount (default 15 L) of the wrong fuel ends up in the tank, the engine starts failing progressively - stuttering, stalling and dropping engine health over time. Electric vehicles can’t be filled with liquid fuel and the other way around.
A damaged engine can be fixed again with the /repairVehicle command. There’s also optional integration with msk_enginetoggle, which flags the engine as damaged.
Fuel consumption
- Fuel is only used while the engine is actually running.
- The global consumption rate is configurable via
Config.FuelConsumptionRateMultiplier. - A damaged fuel tank (petrol tank health below 700) causes additional fuel loss / leaking.
- You can override the tank volume per model in
config.tankvolume.lua.
Fuel stations
- The default fuel pumps on the map work out of the box through
ox_target. - You can spawn custom fuel stations at any coordinates (
Config.CustomFuelStations). - Vehicles and trailers can act as mobile fuel stations - tankers (
tanker,armytanker), the utility truck, generators for electricity, kerosin tanks for airfields, and so on. - Blips for all station locations (configurable, can be turned off).
Performance
The script idles at around 0.00 - 0.01 ms and stays at roughly 0.02 ms during refueling.
Frameworks
Works with ESX and QBCore out of the box through the msk_core bridge.
Dependencies
Optional
- msk_enginetoggle - engine on/off & damage integration
Exports
-- Client
exports.msk_fuel:GetVehicleFuel(vehicle)
exports.msk_fuel:SetVehicleFuel(vehicle, fuel)
exports.msk_fuel:GetVehicleMaxFuel(vehicle)
exports.msk_fuel:SetVehicleMaxFuel(vehicle, maxFuel)
exports.msk_fuel:GetVehicleFuelType(vehicle)
exports.msk_fuel:SetVehicleFuelType(vehicle, fuelType)
exports.msk_fuel:SetEngineFailure(vehicle)
exports.msk_fuel:SetEngineRepaired(vehicle)
-- Server
exports.msk_fuel:GetVehicleFuel(netId)
exports.msk_fuel:SetVehicleFuel(netId, fuel)
Admin commands
| Command | Description |
|---|---|
/setFuel [amount] |
Set the fuel of the vehicle you’re sitting in |
/repairVehicle |
Repair a vehicle damaged by wrong fuel |
Documentation & Download
- Website: https://www.msk-scripts.de
- Docs: MSK Fuel | MSK Scripts - Documentation
- GitHub: GitHub - MSK-Scripts/msk_fuel: Advanced & Realistic Fuel System for FiveM Vehicles · GitHub
Feedback and suggestions are very welcome - if you run into anything or have an idea for a feature, just let me know here or open an issue on GitHub.
| Code is accessible | Yes |
| Subscription-based | No |
| Lines (approximately) | ~1500 |
| Requirements | msk_core, ox_target, ox_inventory |
| Support | Yes |