Fuel

A resource to handle vehicle fuel.

Info

This resource is intended to give greater control over vehicle fuel economy, while adding another layer of variation and tuning capabilities for our upcoming vehicle tuning resource.

• Different fuel types, each defined with different "stats", e.g: "knock rating", "efficiency rating", "power rating".

• Each vehicle class has a configurable "economy" value, allowing you to effect the drain rate of each vehicle class individually (think: motorcycles drain fuel slower then sports cars).

• Each vehicle class has a configurable "tank size" value. This modifies the amount of time it takes to completely drain a vehicles fuel tank (works in conjunction with class economy above). This value also simulates an increased tank size by effects how long it will take to refuel, and all subsequent fuel "labels" will represent a modified value (e.g: a vehicle with 1.0 tank modifier will read 100 units max, a 3.5 rating would read 350 units max).

• Straight-forward usage-by-rpm modifier.

• Realistic fuel nozzle and hose props that attach nicely to all types of vehicles.

• Addon fuel pumps, allowing you to create special locations for electric vehicle charging, or race fuel restocking, allowing only a given type of fuel.

• Proper electric vehicle handling (electric vehicles can only be charged by electric stations, proper "recharging/refueling" labels, etc).

• Purchase and use jerry cans with specific fuel types for emergency refills.

• Purchase and use battery boosters for an emergency electric-vehicle fuel boost.

• All jerry can/battery booster purchasing facilitated through pump interaction UI.

• Each fuel station has configurable "pump speeds" for added variation of refueling time.

• Each fuel station has configurable fuel types, with stock levels for each station that restock automatically given a configurable amount over-time.

• Station stock levels are stored between restarts.

• Exports provided to increase/reduce stock level at stations as required (if you wish to hook some type of fuel delivery trucking job up to this).

• Toggleable config option to explode pumps if player attempts to drive away while refueling with nozzle still attached to car.

Setup

Config

All of the config vars found below are stored within the config.lua file.

config = {
    -- Interact distance for players. Vehicle interact distance is 2x this.
    interactDist = 2.5,

    -- Hose distance, aka maximum distance for the nozzle to reach.
    hoseDist = 5.0,

    -- Minimum distance to stations to consider any actions.
    renderDist = 25.0,

    -- Size (litres) of a jerry can (or battery, for EVs).
    jerryCanSize = 10.0,

    -- How long it takes to refuel using a jerrycan (or battery).
    jerryCanTime = 5000,

    -- On refueling (nozzle attached to vehicle, actively pumping fuel), when player drives away with nozzle attached.
    allowRefuelingExplosions = true, 

    -- Keep nozzle attached after explosion? May help police figure out who caused a petrol bowser explosion in the area.
    keepNozzleAttached = true, 

    -- Controls how blips are displayed.
    -- 0 = off
    -- 1 = all on
    -- 2 = display only closest
    blipDisplay = 2,

    -- Blip data.
    blip = {
        label = "Fuel Station",
        sprite = 361,
        color = 1,
        alpha = 150,
        scale = 0.5,
        display = 2,
        highDetail = true,
        shortRange = true
    },

    -- How much fuel is drained per fuelDrainRate.
    fuelDrainRate = 0.01,

    -- How fast to drain fuel.
    -- NOTE: With 1.0 fuelDrainRate, and 1000 fuelDrainTime, the drain rate for any vehicle (other modifiers not considered)
    --       would equate to exactly 1% of your fuel being drained every 1000ms (1 second).
    fuelDrainTime = 10000,

    -- Base refuel rate.
    -- Can be supplemented further with individual station pump speeds.
    refuelAddRate = 5.0, 

    -- Fuel economy based on vehicle class
    -- Lower = less fuel used
    classEconomy = {
        [0] = 0.5,
        [1] = 0.8,
        [2] = 1.0,
        [3] = 0.7,
        [4] = 1.0,
        [5] = 1.0,
        [6] = 0.9,
        [7] = 1.0,
        [8] = 0.2,
        [9] = 1.5,
        [10] = 1.5,
        [11] = 0.6,
        [12] = 0.0,
        [13] = 0.0,
        [14] = 0.0,
        [15] = 0.0,
        [16] = 0.1,
        [17] = 0.1,
        [18] = 1.0,
        [19] = 1.0,
        [20] = 1.0,
        [21] = 0.0,
    },

    -- Fuel tank size based on vehicle class
    -- Lower value = less time to burn max fuel reserve,
    --               also less time to refuel vehicle at station.
    classTank = {
        [0] = 0.6,
        [1] = 1.0,
        [2] = 1.5,
        [3] = 0.8,
        [4] = 1.0,
        [5] = 1.0,
        [6] = 0.9,
        [7] = 0.8,
        [8] = 0.3,
        [9] = 0.7,
        [10] = 10.0,
        [11] = 2.0,
        [12] = 2.0,
        [13] = 1.0,
        [14] = 1.0,
        [15] = 100.0,
        [16] = 100.0,
        [17] = 5.0,
        [18] = 5.0,
        [19] = 5.0,
        [20] = 1.0,
        [21] = 1.0,
    },

    -- How much fuel is used at given RPM
    rpmUsage = {
        [1.0] = 1.00,
        [0.9] = 0.90,
        [0.8] = 0.80,
        [0.7] = 0.70,
        [0.6] = 0.60,
        [0.5] = 0.50,
        [0.4] = 0.40,
        [0.3] = 0.30,
        [0.2] = 0.20,
        [0.1] = 0.10,
        [0.0] = 0.00,
    },   

    electricVehicles = {
        `Imorgon`,
        `Neon`,
        `Raiden`,
        `Cyclone`,
        `Voltic`,
        `Voltic2`,
        `Tezeract`,
        `Dilettante`,
        `Dilettante2`,
        `Airtug`,
        `Caddy`,
        `Caddy2`,
        `Caddy3`,
        `Surge`,
        `Khamelion`,
        `RCBandito`,
        `teslax`,
    },
}

Fuel Types

All fuel type configuration can be found within the data/fueltypes.lua file.

For further documentation, read the subpage found here.

Stations

All fuel station configuration can be found within the data/stations.lua file.

For further documentation, read the subpage found here.

Labels

All labels and translations can be found within the labels.lua file.

en = {
    no_vehicles_nearby = "No vehicle nearby",
    empty_driverseat_required = "Vehicle must not have a driver",
    ...
}

Usage

• All modifications handled through the config.lua file.

• All translations are handled in the labels.lua file.

• Use the working examples in config.lua to extend the functionality in any way you please.

• Class restrictions use the same indexes found here: https://docs.fivem.net/natives/?_0x29439776AAA00A62, or you can use -1 to allow all classes at a shop.

• If you're using ox_inventory, add the following to ox_inventory/data/items.lua:

  -- ti_fuel
  ['jerry_can'] = {  
    label = 'Jerry Can',
    weight = 2000,
    stack = false
  },  
  
  ['booster_battery'] = {  
    label = 'Booster Battery',
    weight = 2000,
    stack = false
  },

Example

All events are prefixed with "ti_fuel:", and exports are registered under the same namespace without the prefix.

RegisterCommand("getFuel",function(source,args)    
    local veh = GetVehiclePedIsIn(PlayerPedId())

    exports["ti_fuel"]:setFuel(veh,100.0)
    -- OR
    TriggerEvent("ti_fuel:setFuel",veh,100.0)
end)  

Conflicting Resources

• Basically any other fuel resource.

Dependencies

• ti_utils

• ti_garage * Only required if you want your vehicle fuel type to be saved. * Alternatively, call ti.vehicles.getProperties/setProperties (using ti_utils) from your garage scripts.

Video

Tebex