Configuration Guide

This guide explains how to configure LC Fuel to fit your FiveM server's needs. All settings are found in the config.lua file.

General Settings

EnablePumpRope

Determines whether the fuel nozzle has a visible hose attached.

Config.EnablePumpRope = true -- true: enable rope | false: disable

EnableHUD

Enables a simple fuel HUD displaying the current fuel level and consumption. Mostly for debug. We recommend to use a custom HUD.

Config.EnableHUD = false -- true: show debug HUD | false: hide

RefuelTick

Controls the speed of refueling. A lower value means faster refueling.

Config.RefuelTick = 300 -- Time in milliseconds to refuel 0.5L of fuel

Fuel Nozzle & Electric Charger Props

You can customize the props used for fuel nozzles and electric chargers. These props define the visual elements used when refueling or charging electric vehicles. If you want to change them, make sure the new prop names exist in the game.

Config.NozzleProps = {
    gas = "prop_cs_fuel_nozle", -- Prop for gas nozzle
    electric = "prop_eletricpistol" -- Prop for electric charger
}

Jerry Can Settings

Allows players to purchase and use jerry cans for refueling.

Config.JerryCan = {
    enabled = true, -- Enable or disable jerry can purchase
    price = 300, -- Cost of a jerry can
    requiredStock = 10, -- Minimum stock required at gas station
    item = "weapon_petrolcan", -- Inventory item name
    giveAsWeapon = true, -- true: Give as weapon | false: Give as item
    metadata = { ammo = 100 } -- Jerry can fuel capacity
}

Payment Options

Allows players to pay for fuel using different in-game accounts.

Config.Accounts = {
    account1 = "cash", -- Primary payment method
    account2 = "bank"  -- Secondary payment method
}

Job Discounts

You can configure job-specific fuel discounts, allowing certain jobs to receive reduced fuel costs. The discount value is set as a percentage, where 100% means free fuel. You can add or remove jobs from this list as needed.

Config.JobDiscounts = {
    ["police"] = 90, -- Police officers get a 90% discount
    ["ambulance"] = 80, -- Ambulance drivers get a 80% discount
}

Fuel Types & Pricing

You can define different fuel types and their prices. The price is set per liter, and you can modify it based on your server's economy.

Config.DefaultValues = {
    fuelPrice = {
        regular = 1.55,
        plus = 1.69,
        premium = 1.98,
        diesel = 1.49,
    }
}

Player-Owned Gas Stations Integration

If your server uses the player-owned gas station system, you can enable integration so fuel prices and stock are managed dynamically. The script will link gas stations to pumps based on the configured locations. You can add, remove, or modify these locations as needed.

Config.PlayerOwnedGasStations = {
    enabled = false, -- Enable/disable integration with player-owned gas stations
    gasStations = {
        ["gas_station_1"] = { vector = vector3(264.95, -1259.45, 29.14), radius = 30 },
        ["gas_station_2"] = { vector = vector3(819.61, -1028.21, 26.40), radius = 30 },
    }
}

Vehicle Compatibility

This script supports all vehicle types, including:

• Cars & Motorcycles
• Boats
• Helicopters & Aircraft

No additional configuration is needed; the script automatically detects the vehicle type and applies the appropriate fuel consumption logic.

Diesel-Specific Vehicles

Some vehicles are restricted to using only diesel fuel. Putting another fuel type in these vehicles will break their engines.

Config.DieselVehicles = {
    "benson", 
	"biff",
	"mule",
	-- etc
}

Fuel Consumption Per Vehicle Type

Each vehicle type has its own fuel consumption multiplier, which affects how quickly it uses fuel. A lower value means better fuel efficiency, while a higher value increases fuel consumption.

Config.FuelConsumptionPerClass = {
	[0] = 0.6, -- Compacts
	[1] = 0.9, -- Sedans
	[2] = 1.1, -- SUVs
	[3] = 0.8, -- Coupes
	[4] = 1.2, -- Muscle
	[5] = 1.2, -- Sports Classics
	[6] = 1.1, -- Sports
	[7] = 1.2, -- Super
	[8] = 0.4, -- Motorcycles
	[9] = 1.3, -- Off-road
	[10] = 1.9, -- Industrial
	[11] = 1.7, -- Utility
	[12] = 1.6, -- Vans
	[13] = 0.0, -- Cycles
	[14] = 1.0, -- Boats
	[15] = 1.0, -- Helicopters
	[16] = 1.0, -- Planes
	[17] = 1.0, -- Service
	[18] = 1.0, -- Emergency
	[19] = 1.0, -- Military
	[20] = 1.8, -- Commercial
	[21] = 1.0, -- Trains
}

Custom Vehicle Parameters

The Config.CustomVehicleParameters setting allows fine-tuning of nozzle interactions for specific vehicles. This is essential for ensuring that the fuel nozzle and interaction points are correctly aligned, especially for larger, unique, or custom vehicles in your server.

Configuration Example

Config.CustomVehicleParameters = {
    ["default"] = { 
        distance = 1.2, -- Default interaction distance for refueling
        nozzleOffset = { forward = 0.0, right = -0.15, up = 0.5 }, -- Default nozzle position relative to the vehicle
        nozzleRotation = { x = 0, y = 0, z = 0 } -- Default rotation of the nozzle
    },
    ["benson"] = { 
        distance = 2.0, -- Increased interaction distance for large trucks
        nozzleOffset = { forward = 0.3, right = 0.32, up = 0.19 }, -- Adjusted position to fit fuel intake
        nozzleRotation = { x = 0, y = 0, z = 180} -- Rotated to properly align with the vehicle
    }
}

Parameters

• distance (number): Defines how close a player must be to start refueling. Larger vehicles may need a greater distance.
• nozzleOffset (table with x, y, z values): Adjusts the nozzle's position relative to the vehicle.
  • forward (x-axis): Moves the nozzle forward or backward.
  • right (y-axis): Moves the nozzle left or right.
  • up (z-axis): Moves the nozzle up or down.
• nozzleRotation (table with x, y, z values): Adjusts the nozzle's rotation to align with the vehicle's fuel port.
  • x: Rotates the nozzle up/down.
  • y: Rotates the nozzle forward/backward.
  • z: Rotates the nozzle left/right.

Use Cases

• Custom Fueling for Large Vehicles: Adjusts interaction distances for trucks, buses, and aircraft to avoid awkward fueling interactions.
• Realistic Nozzle Positioning: Ensures that nozzles align correctly with fuel ports instead of clipping through the vehicle.
• Compatibility with Custom Vehicles: Enables fine-tuned positioning for modded vehicles that may have different fuel port placements.

Electric Vehicle Configuration

The Config.Electric section allows you to enable and customize electric vehicle charging stations, define their locations, and configure different charging speeds and pricing.

Enable Electric System

This setting enables or disables the electric vehicle charging system entirely.

Config.Electric.enabled = true -- true: Enable electric features | false: Disable

Charging Stations Locations

Defines where the electric chargers will be placed and which prop will be used.

• prop: The 3D model used for the charging station.
• location: The position where the charger will be spawned (vector4 format: x, y, z, heading).
• ropeLength: The maximum distance a vehicle can be to connect the charger cable.

Config.Electric.chargersLocation = {
    { prop = "prop_electric_01", location = vector4(175.9, -1546.65, 28.26, 225.29), ropeLength = 7.5 },
    { prop = "prop_electric_01", location = vector4(279.79, -1237.35, 28.35, 182.07), ropeLength = 7.5 }
}

Charging Station Props

Defines which props are used as chargers and their cable attachment offsets.

• prop: The 3D model of the charger.
• ropeOffset: The position where the charging cable attaches to the vehicle.
  • forward: Moves the cable forward or backward.
  • right: Moves the cable left or right.
  • up: Moves the cable up or down.

Config.Electric.chargersProps = {
    { prop = "prop_electric_01", ropeOffset = { forward = 0.0, right = 0.25, up = 0.3 } }
}

Charging Types

Defines different charging speed options and pricing.

• price: Cost per 1% battery charge.
• time: Time in seconds to charge 0.5% battery (lower values mean faster charging).
• stock: Determines if chargers has stock when gas stations are not player-owned.

Config.Electric.chargeTypes = {
    fast = {
        price = 2.5, -- Price per 1% charge
        time = 0.8,  -- Time in seconds to charge 0.5% battery
        stock = true -- Has stock if not player-owned
    },
    normal = {
        price = 1.8,
        time = 2,
        stock = true
    }
}

Electric Vehicles List

Defines which vehicles are electric and must use charging stations instead of gas stations.

Config.Electric.vehiclesList = {
    "voltic", 
	"voltic2",
	"surge",
	-- etc
}