Home / Free Scripts / NR_Fuel

NR_Fuel

A standalone fuel system with pump nozzle physics, jerry cans, free fuel for emergency services, and full backwards compatibility with ox_fuel.

⛽ ox_fuel Replacement

NR_Fuel registers itself as a provider for ox_fuel. Any script that depends on or references ox_fuel will automatically work with NR_Fuel — no changes needed. See the ox_fuel Compatibility section below for details.

Features

Dependencies

Resource Description Required
es_extended / qb-core / qbx_core Core framework (auto-detected) One of these
ox_lib UI library (context menus, progress bars, notifications, callbacks) Yes
ox_target / qb-target Target/interaction system (auto-detected) One of these
ox_inventory / qb-inventory Inventory system for jerry cans (auto-detected) One of these

Installation

Step 1: Download

Download NR_Fuel and extract it to your resources folder:

server/
  └── resources/
      └── [echo]/
          └── NR_Fuel/

Step 2: Remove or Disable ox_fuel

If you currently have ox_fuel installed, remove or comment out its ensure line in your server.cfg. NR_Fuel replaces it entirely:

# Remove or comment out this line:
# ensure ox_fuel

# Add NR_Fuel instead:
ensure NR_Fuel
⚠️ Important

Do not run both ox_fuel and NR_Fuel at the same time. Since NR_Fuel provides ox_fuel, running both will cause conflicts. Only one should be ensured in your server.cfg.

Step 3: server.cfg

Add the resource to your server configuration. Make sure it starts after your framework, ox_lib, target system, and inventory:

ensure ox_lib
ensure ox_target       # or qb-target
ensure ox_inventory    # or qb-inventory

ensure NR_Fuel

Step 4: Configure

Edit config.lua to adjust fuel pricing, refuel speed, gas station locations, and free fuel jobs. See the Configuration section below.

Step 5: Restart

Restart your server to load the resource. You should see these messages in the server console:

[nr_fuel] Framework detected: qb       (or esx / qbx)
[nr_fuel] Inventory detected: ox        (or qb)
[nr_fuel] Target system detected: ox    (or qb)

ox_fuel Compatibility

NR_Fuel is designed as a drop-in replacement for ox_fuel. This is achieved through the provide directive in the resource manifest:

-- In fxmanifest.lua:
provide 'ox_fuel'

This tells the FiveM server that NR_Fuel provides the functionality of ox_fuel. Here's what that means in practice:

What Works Automatically

How to Set It Up

If you are migrating from ox_fuel or have scripts that reference it:

🚀 Migration Steps
  1. Stop your server
  2. Remove or rename the ox_fuel resource folder (or simply comment out ensure ox_fuel)
  3. Place NR_Fuel in your resources folder
  4. Add ensure NR_Fuel to your server.cfg
  5. Start your server — all scripts that previously used ox_fuel will now use NR_Fuel

You do not need to edit any other scripts. The provide 'ox_fuel' directive handles the mapping automatically at the server level.

Using ox_fuel Exports with NR_Fuel

If you have custom scripts that call ox_fuel exports, they will continue to work:

-- These calls work with NR_Fuel installed (no changes needed):
local fuel = exports.ox_fuel:GetFuel(vehicle)
exports.ox_fuel:SetFuel(vehicle, 100.0)

You can also call them directly via the NR_Fuel resource name:

-- Direct NR_Fuel export calls:
local fuel = exports.NR_Fuel:GetFuel(vehicle)
exports.NR_Fuel:SetFuel(vehicle, 100.0)

How It Works

1. Approaching a Gas Station

The nearest gas station blip appears on your map automatically. Drive to any gas station and stop near a fuel pump.

2. Opening the Fuel Menu

While sitting in a vehicle near a pump, use your target system to interact with the fuel pump. Select "Refuel Vehicle" to open the fuel menu.

3. Choosing Payment

The menu shows the fuel needed and cost. You can choose:

4. Fueling Process

After paying, your character exits the vehicle, picks up a fuel nozzle from the pump (with a physical hose attached), and you target the vehicle to insert the nozzle. A progress bar shows the refueling progress. When finished, remove the nozzle from the vehicle and return it to the pump.

5. Using a Jerry Can

Equip the jerry can (WEAPON_PETROLCAN), then target any vehicle and select "Refuel with Jerry Can". The jerry can tracks its remaining fuel — once empty it is automatically discarded.

6. Free Fuel (Emergency Services)

Players in configured jobs (police, ambulance, fire by default) who are on duty receive free fuel automatically when interacting with a pump.

Configuration

General Settings

Config.FuelPrice = 5          -- Price per liter of fuel
Config.RefuelRate = 1.5       -- Liters added per second while fueling
Config.MaxFuel = 100          -- Maximum fuel capacity for vehicles
Config.JerryCanCapacity = 8   -- Liters of fuel in a purchased jerry can

Nozzle / Hose Settings

Config.NozzleProp = `prop_cs_fuel_nozle`  -- Prop model for the fuel nozzle
Config.RopeType = 3                        -- 3 = thick hose mesh
Config.RopeMaxLength = 7.0                 -- Max hose length from pump to nozzle
Config.MaxNozzleDistance = 10.0            -- Auto-cancel if player walks this far from pump

Free Fuel Jobs

Jobs listed here get free fuel when on duty:

Config.FreeGasJobs = {
    'police',
    'ambulance',
    'fire'
}

Gas Station Locations

Each entry adds a potential blip location. The script shows a blip for the station nearest to the player:

Config.GasStations = {
    vector3(49.4187, 2778.793, 58.043),
    vector3(263.894, 2606.463, 44.983),
    vector3(1039.958, 2671.134, 39.550),
    -- ... more locations
}

Fuel Pump Props

These prop models are registered as targetable fuel pumps:

Config.FuelProps = {
    `prop_gas_pump_1a`,
    `prop_gas_pump_1b`,
    `prop_gas_pump_1c`,
    `prop_gas_pump_1d`,
    `prop_vintage_pump`,
    `prop_gas_pump_old2`,
    `prop_gas_pump_old3`,
}

Exports

GetFuel

Returns the current fuel level of a vehicle:

-- Client-side
local fuel = exports.NR_Fuel:GetFuel(vehicle)
-- Also works as:
local fuel = exports.ox_fuel:GetFuel(vehicle)

SetFuel

Sets the fuel level of a vehicle (clamped between 0 and Config.MaxFuel):

-- Client-side
exports.NR_Fuel:SetFuel(vehicle, 75.0)
-- Also works as:
exports.ox_fuel:SetFuel(vehicle, 75.0)

setMoneyCheck

Override the default money-checking function with your own:

-- Client-side: custom money check
exports.NR_Fuel:setMoneyCheck(function()
    -- Return the player's available cash amount
    return myCustomGetMoney()
end)

setPaymentMethod

Override the default payment processing on the server side:

-- Server-side: custom payment handler
exports.NR_Fuel:setPaymentMethod(function(src, cost)
    -- Process payment your own way
    -- Return true if payment succeeded, false otherwise
    return myCustomPayment(src, cost)
end)

Commands

Command Description
/checkfuel Displays the current fuel level of the vehicle you're in
/checkjerrycan Displays the remaining fuel in your jerry can

Troubleshooting

Scripts complaining ox_fuel is missing

Fuel pump not targetable

No framework detected

Jerry can not working

Nozzle hose not appearing

Vehicle runs out of fuel too fast

Support

Need help? Join our Discord server for community support and updates.