> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/vehicles/cuxial-fuel/configuration.md). # Configuration Every option of Cuxial Fuel explained: prices, consumption, tanks, pumps, chargers, screens, totems and data lists. Behaviour lives in `shared/config.lua`. The lists of models and positions live in `data/`. Restart the resource after any change. ## General | Option | Type | Default | What it does | | ------------------ | --------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `debug` | boolean | `false` | Prints traces to the console. Also enabled by setting the convar `cuxial_fuel_debug` to `1`. | | `refuelTick` | number | `300` | Milliseconds per 0.5 L at a fuel pump. Lower is faster. | | `ropeEnabled` | boolean | `true` | Draws the hose between the pump and the nozzle. Only the player holding the nozzle sees it. `false` removes the hose; the distance limit still applies. | | `ropeLength` | number | `7.5` | Metres the nozzle can move away from the pump when the pump has no value of its own in `data/`. | | `refundOnReturn` | boolean | `true` | `true` refunds what was paid and not served when the purchase closes. `false` never refunds. | | `saveAllFuelTypes` | boolean | `true` | `true` saves the fuel type of every vehicle. `false` saves only player-owned vehicles; the rest is remembered until the next restart. | | `fuelTypeCommand` | string | `'fuel_type'` | Command that tells the fuel of the vehicle. | | `wrongFuelDelay` | number | `5000` | Milliseconds from driving with the wrong fuel to the engine breaking. | | `accounts` | string\[] | `{ 'cash', 'bank' }` | Accounts the player can pay with. | | `admin.permission` | string | `'admin'` | Framework permission, checked through Cuxial Bridge, required by `/fuel_screen`. | Refunds are rounded down, and less than 1 L left over is not refunded. A purchase is also closed, with its refund, when the player disconnects or changes character. ## Interface · `ui` | Option | Type | Default | What it does | | ----------------- | ------------ | ------------ | -------------------------------------------------------------------------------------- | | `accent` | string (hex) | configurable | Accent colour of the interface. | | `currency.symbol` | string | `'$'` | Symbol shown before every amount. | | `currency.locale` | string | `'en-US'` | Number format (thousands and decimal separators), as a language tag such as `'es-ES'`. | ## Distances · `distances` Maximum distances checked by the server, in metres. | Option | Type | Default | What it does | | ---------- | ------ | ------- | --------------------------------------------------------------------------- | | `pump` | number | `8.0` | From the player to the pump when opening it or paying. | | `vehicle` | number | `8.0` | From the vehicle to the pump. | | `fuelType` | number | `6.0` | From the player to the vehicle when another resource changes its fuel type. | ## Job discounts · `jobDiscounts` A table of `job name = percentage`. The discount applies only while the player is on duty, and uses the job name, not its label. The jobs in the file are examples: replace them with yours. ```lua jobDiscounts = { police = 90, ambulance = 80 }, ``` The jerry can has no discount, and the totems always show the price without discount. {% hint style="warning" %} The discount requires a framework that reports whether the player is on duty. On ESX, use a version with duty status. {% endhint %} ## Default prices and stock · `defaults` Used by pumps that belong to no station: every pump when `cuxial_gasstations` is not running, and the stations without an owner when it is. | Option | Type | Default | What it does | | ------- | ----- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | `price` | table | `regular = 1.55`, `plus = 1.69`, `premium = 1.98`, `diesel = 1.49` | Price per litre of each fuel. | | `stock` | table | all `true` | `true` = the fuel is available, up to 1000 L per purchase. `false` = out of stock. | {% hint style="info" %} A station with no price set (price `0`) also sells at the price in `defaults`. {% endhint %} ## Jerry can · `jerryCan` | Option | Type | Default | What it does | | --------------- | ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` removes the sale at the pump, and cans already owned stop refuelling. | | `price` | number | `300` | Fixed price, without job discount. | | `requiredStock` | number | `10` | Litres taken from the station's stock for each can. The can is filled with the first fuel that has that much stock. | | `item` | string | `'weapon_petrolcan'` | Inventory item given to the player. | | `liters` | number | `100` | Litres the can holds. | The can is only sold at fuel pumps, not at chargers. To use it, the player equips it and picks **Refuel** at the fuel cap of a nearby vehicle. ## Spills · `spill` Starting the engine while refuelling stops the flow and leaves the nozzle plugged in. If the vehicle then moves, the nozzle pops out and the purchase closes. | Option | Type | Default | What it does | | --------------- | ------- | ------- | ----------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` disables the rule: starting the engine only stops the refuel. | | `moveThreshold` | number | `1.5` | Metres the vehicle has to move for the nozzle to pop out. | | `speed` | number | `2.0` | Speed in m/s that also makes it pop out. | | `customerPays` | boolean | `true` | `true` = spilled litres are not refunded. `false` = they are refunded anyway. | The puddle and the litres lost are decided by `cuxial_gasstations`. Without it nothing is spilled and the unused litres are refunded as usual. ## Fuels · `fuelTypes` | Option | Type | Default | What it does | | ---------- | --------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `petrol` | string\[] | `regular`, `plus`, `premium`, `diesel` | Fuels sold at the pumps. | | `electric` | string\[] | `electric_fast`, `electric_normal` | Charging modes sold at the chargers. Each one pairs with an entry of `chargers.types` (`electric_fast` = `fast`). | A vehicle with no saved fuel type takes one from its model: `diesel` if it is in `data/diesel.lua`, electric if it is an electric vehicle, `regular` otherwise. ## Consumption · `consumption` Litres per second = `usage` by RPM × `perClass` × `perFuel` ÷ 10. | Option | Type | Default | What it does | | ---------- | ----- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `perFuel` | table | `regular = 1.0`, `plus = 0.9`, `premium = 0.8`, `diesel = 1.0`, `electric = 1.0` | Multiplier by the fuel in the tank. Lower is more economical. | | `perClass` | table | from `0.0` (cycles) to `4.0` (planes) | Multiplier by GTA vehicle class, `0` to `22`. | | `usage` | table | from `0.0` to `1.3` | Base value for each RPM step, from `0.0` to `1.0`. `0.2` is idle. | When the tank reaches zero the engine turns off. A vehicle that has never had a level gets a random one between 20 % and 80 % the first time someone drives it. ## Tank size · `tank` Tank in litres. The script looks at the model first, then the class, and uses 100 L when neither is set. | Option | Type | Default | What it does | | ------------ | ----- | ----------------------------------- | ------------------------------------------------------------------------------------------- | | `perClass` | table | from `0` (cycles) to `500` (planes) | Litres by GTA vehicle class. `0` = no tank: the vehicle does not consume and cannot refuel. | | `perVehicle` | table | `panto = 40` | Litres by model name. Wins over the class. | ```lua perVehicle = { panto = 40, sultan = 65 }, ``` ## Nozzle · `nozzle` | Option | Type | Default | What it does | | -------------- | ------- | ----------------------------- | ----------------------------------------------- | | `gas` | string | `'prop_cs_fuel_nozle'` | Model of the fuel nozzle. | | `electric` | string | `'prop_eletricpistol'` | Model of the charging connector. | | `bone` | number | `18905` | Ped bone the nozzle is attached to (left hand). | | `handOffset` | vector3 | `vec3(0.13, 0.04, 0.01)` | Position in the hand. | | `handRotation` | vector3 | `vec3(-42.0, -115.0, -63.42)` | Rotation in the hand. | | `ropeOffset` | vector3 | `vec3(0.0, -0.033, -0.195)` | Point of the nozzle where the hose is tied. | ## Pumps · `pumps` | Option | Type | Default | What it does | | ------------ | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `ropeOffset` | table | `forward = 0.0, right = 0.0, up = 2.1` | Point of the pump the hose comes out of, for models without their own. | | `props` | table\[] | seven pump models | Models that work as a pump. Each entry has `prop`, an optional `ropeOffset` and an optional `enabled`. | Any object of the map with one of these models becomes a working pump. `enabled = false` on an entry turns that model off: no interaction and no screen. ```lua props = { { prop = 'prop_gas_pump_1a', ropeOffset = { forward = 0.0, right = 0.0, up = 2.3 } }, { prop = 'my_custom_pump', ropeOffset = { forward = 0.0, right = 0.0, up = 1.9 } }, }, ``` ## Chargers · `chargers` | Option | Type | Default | What it does | | -------------- | --------- | ---------------------------------------------------- | --------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` removes the chargers. Electric vehicles then stop consuming. | | `props` | table\[] | `prop_electric_01` | Models that work as a charger, with the same fields as `pumps.props`. | | `types.fast` | table | `price = 2.5, time = 0.8, stock = true, power = 220` | Fast charge. | | `types.normal` | table | `price = 1.8, time = 2, stock = true, power = 100` | Normal charge. | | `vehicles` | string\[] | list of models | Models treated as electric. | Fields of each charge type: | Field | What it does | | ------- | -------------------------------------------------------------------- | | `price` | Price per battery unit. The battery uses the same scale as the tank. | | `time` | Seconds per unit charged. | | `stock` | `true` = available at pumps that belong to no station. | | `power` | kW shown on the screen. | {% hint style="info" %} On game build 3258 or newer the client also recognises electric vehicles by itself. The server only knows the `vehicles` list, so add your custom electric models to it. {% endhint %} ## Blips · `blips` Blips are off by default because `cuxial_gasstations` already adds its own. | Option | Type | Default | What it does | | ------------- | ---------- | ---------------- | --------------------------------------------------------- | | `enabled` | boolean | `false` | Shows a blip on each position of `coords`. | | `nearestOnly` | boolean | `false` | Shows only the nearest one, recalculated every 5 seconds. | | `sprite` | number | `361` | Blip sprite. | | `color` | number | `41` | Blip colour. | | `scale` | number | `0.6` | Blip size. | | `coords` | vector3\[] | list of stations | Positions of the blips. | ## Pump screen · `screen` The screen is drawn on the pump model. It shows prices while idle and the purchase when a player uses the pump. | Option | Type | Default | What it does | | ----------------- | ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` turns every pump screen off; pumps open a regular panel on the player's screen. | | `renderDistance` | number | `20.0` | Metres within which the idle screen is drawn. | | `idle` | table | `900 × 400` | Resolution of the idle screen on fuel pumps. | | `session` | table | `1080 × 480` | Resolution of the purchase screen on fuel pumps. | | `idleEv` | table | `800 × 450` | Resolution of the idle screen on chargers. | | `sessionEv` | table | `1024 × 576` | Resolution of the purchase screen on chargers. | | `textures` | table | `gas`, `electric`, `vintage` | Texture names the screen replaces on the models delivered in `cuxial_gas_assets`. Leave as is. | | `variants` | table | `vintage` | Alternative screen layouts with their own resolution. A model picks one with `variant`. The classic pump (`vintage`) shows the brand of the locale key `UI_VINTAGE_BRAND`, `FUEL` by default; edit it in `locales/`. | | `camera.distance` | number | `1.2` | Metres from the camera to the screen during the purchase. | | `camera.margin` | number | `1.25` | Margin around the screen in the frame. `1.0` = the screen fills the view. | | `camera.fov` | number | automatic | Optional. Sets a fixed field of view instead of the calculated one. | | `models` | table | eight models | Where the screen sits on each pump or charger model. | ### Screen position per model · `screen.models` Each key is a model name. A pump whose model has no entry here opens the regular panel. | Field | What it does | | ----------------- | ------------------------------------------------------------------------------------------------------------------- | | `offset` | Centre of the screen from the model origin: x right, y forward, z up. | | `yaw` | Rotation in degrees. | | `width`, `height` | Size in metres. | | `sides` | `1` or `2`. With `2` the screen is also drawn on the opposite face. | | `mesh`, `txdName` | Set on the models delivered in `cuxial_gas_assets`, which carry the screen in the model itself. Do not change them. | | `variant` | Layout from `screen.variants`. | To place the screen on a model of your own, stand next to it, run `/fuel_screen` and paste the line it prints into `screen.models`. See [Commands & permissions](/scripts/vehicles/cuxial-fuel/commands.md). ## Price totems · `screen.totems` and `screen.totemBrands` The totems are the large price signs of the stations. They show price per litre, stock, chargers and, with `cuxial_gasstations`, the station name and its promotions. | Option | Type | Default | What it does | | ----------------------- | -------- | ------------------- | --------------------------------------------------------------------------------------------- | | `totems.enabled` | boolean | `true` | `false` turns every totem off. | | `totems.mode` | string | `'prop'` | How the screen is put on the sign. Leave `'prop'`. | | `totems.propDistance` | number | `300.0` | Metres within which the screen of a totem exists. | | `totems.renderDistance` | number | `140.0` | Metres within which the screen is lit. | | `totems.switchMargin` | number | `15.0` | Metres another totem has to be closer before the lit one changes. | | `totems.refreshMs` | number | `60000` | Milliseconds between refreshes. Changes of price, stock or promotions arrive without waiting. | | `totems.maxDuis` | number | `3` | Totem screens lit at once, the nearest ones. | | `totems.models` | table | list of sign models | Sign models and the screens each one carries. Tied to the models in `cuxial_gas_assets`. | | `totems.placements` | table\[] | list of signs | One entry per sign of the map: model, position, station and service lines. | Fields of a placement you may want to edit: | Field | What it does | | ---------- | ----------------------------------------------------------------------------------- | | `station` | Station id in `cuxial_gasstations`. Without it, the station is found from `coords`. | | `services` | Fixed lines of the big screen: `'24h'`, `'shop'`, `'lotto'`, `'wash'`. | `totemBrands` sets the look of each station brand: `name`, `banner` and `disc` images, `mascot`, order of the `fuels`, `slogans` (prefix of the locale keys) and `colors` (`primary`, `secondary`, `digits`, `text`). {% hint style="warning" %} `totems.models` and `totems.placements` match the sign models delivered in `cuxial_gas_assets`. Change prices, brands and services freely; leave positions and model names alone unless you replace the models. {% endhint %} ## Sounds · `audio` | Option | Type | Default | What it does | | ---------------- | ------- | ------------- | ---------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` turns the native sounds off. | | `remote` | boolean | `true` | Lets players hear the flow of other players refuelling. | | `remoteDistance` | number | `25.0` | Metres within which that flow is heard. | | `screenBeep` | boolean | `true` | Beep when pressing the pump screen. | | `debugCommand` | string | `'fuelaudio'` | Command that plays every sound. Only registered with `debug` on. | ## Consumption chart · `chart` | Option | Type | Default | What it does | | ---------- | ------- | -------------- | -------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` removes the chart, its command and its key. | | `command` | string | `'fuel_chart'` | Command that opens and closes the chart. | | `focusKey` | string | `'F3'` | Default key that gives the cursor to the chart. Each player can rebind it in the GTA key settings. | | `position` | string | `'left'` | Side of the screen: `'left'` or `'right'`. | ## Data lists · `data/` | File | What it holds | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data/pumps.lua` | Extra pumps created by the script where the map has none. Each entry has `prop`, `coords` (`vec4`, the fourth value is the heading) and an optional `ropeLength`. | | `data/chargers.lua` | Electric chargers, with the same fields. | | `data/diesel.lua` | Models that run on diesel. Any other fuel breaks their engine, and diesel breaks the engine of the rest. | | `data/blacklist.lua` | Models that do not consume and cannot refuel. | | `data/vehicles.lua` | Refuel point per model: `distance` to interact, `nozzleOffset` from the fuel cap (`forward`, `right`, `up`) and an optional `nozzleRotation`. `default` applies to models not listed. | The positions in `data/pumps.lua` and `data/chargers.lua` are examples for the default map. Replace them with yours. {% code title="data/pumps.lua" %} ```lua { prop = 'prop_gas_pump_1b', coords = vec4(442.2, -977.17, 42.69, 270.3), ropeLength = 14.0 }, ``` {% endcode %} ## Common changes ### Change the prices {% code title="shared/config.lua" %} ```lua defaults = { price = { regular = 2.10, plus = 2.35, premium = 2.80, diesel = 1.95 }, stock = { regular = true, plus = true, premium = true, diesel = true }, }, ``` {% endcode %} ### Add an electric model Add its model name at the end of `chargers.vehicles`, keeping the ones already there: {% code title="shared/config.lua" %} ```lua vehicles = { 'voltic', 'voltic2', 'neon', -- ...the rest of the list 'my_electric_car', }, ``` {% endcode %} ### Make a model run on diesel Add its model name to `data/diesel.lua`: {% code title="data/diesel.lua" %} ```lua 'my_truck', ``` {% endcode %} ### Refuel faster {% code title="shared/config.lua" %} ```lua refuelTick = 150, ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cuxial.com/scripts/vehicles/cuxial-fuel/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.