> 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/developers.md).

# Exports & events

Public API of Cuxial Fuel: exports and the state bag to read and set fuel from other resources.

Read and set the fuel of a vehicle from your own resources, on the client or on the server. Fuel is always a percentage of the tank, from `0` to `100`.

## State bag

The fuel level of every vehicle is published in its state bag `fuel` (`number`, `0` to `100`). It is replicated, so it can be read anywhere:

```lua
local level = Entity(vehicle).state.fuel
```

The value is `nil` until someone has driven the vehicle or a resource has set it. To write it, use the exports below.

## Client exports

### GetFuel

Returns the fuel level of a vehicle.

```lua
local level = exports.cuxial_fuel:GetFuel(vehicle)
```

| Parameter | Type   | Description     |
| --------- | ------ | --------------- |
| `vehicle` | number | Vehicle entity. |

**Returns:** `number`, from `0` to `100`. `0` when the vehicle does not exist.

```lua
if exports.cuxial_fuel:GetFuel(cache.vehicle) < 10 then
    lib.notify({ description = 'Low fuel' })
end
```

### SetFuel

Sets the fuel level of a vehicle.

```lua
exports.cuxial_fuel:SetFuel(vehicle, value)
```

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `vehicle` | number | Vehicle entity.                   |
| `value`   | number | Percentage. Clamped to `0`–`100`. |

```lua
exports.cuxial_fuel:SetFuel(vehicle, 100.0)
```

{% hint style="warning" %}
The level only reaches the other players when the client that calls the export owns the vehicle on the network, usually its driver. From any other client, use the server export.
{% endhint %}

### SetFuelType

Sets the fuel type saved for a vehicle. It does not empty the tank.

```lua
exports.cuxial_fuel:SetFuelType(vehicle, fuel)
```

| Parameter | Type          | Description                                                                                                                                                                                    |
| --------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vehicle` | number        | Vehicle entity. It has to be networked.                                                                                                                                                        |
| `fuel`    | string \| nil | `'regular'`, `'plus'`, `'premium'`, `'diesel'`, `'electric_fast'` or `'electric_normal'`. `nil`, `''` or `'default'` clears the saved type, and the vehicle goes back to the one of its model. |

The player has to be inside the vehicle or within `distances.fuelType` metres of it. The server accepts 5 changes every 10 seconds per player.

```lua
exports.cuxial_fuel:SetFuelType(vehicle, 'diesel')
```

### Lowercase aliases

`getFuel`, `setFuel` and `setFuelType` are the same exports with a lowercase first letter.

```lua
local level = exports.cuxial_fuel:getFuel(vehicle)
```

## Server exports

### GetFuel

Returns the fuel level of a vehicle.

```lua
local level = exports.cuxial_fuel:GetFuel(vehicle)
```

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `vehicle` | number | Vehicle entity on the server. |

**Returns:** `number` from `0` to `100`, or `nil` when the vehicle does not exist or has no level.

```lua
local vehicle = NetworkGetEntityFromNetworkId(netId)
local level = exports.cuxial_fuel:GetFuel(vehicle) or 0
```

### SetFuel

Sets the fuel level of a vehicle. The client that owns the vehicle applies it to the game.

```lua
local ok = exports.cuxial_fuel:SetFuel(vehicle, value)
```

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `vehicle` | number | Vehicle entity on the server.     |
| `value`   | number | Percentage. Clamped to `0`–`100`. |

**Returns:** `boolean`. `false` when the vehicle does not exist or the value is not a number.

```lua
-- Full tank for a vehicle taken out of a garage
exports.cuxial_fuel:SetFuel(vehicle, 100)
```

## Compatibility with other fuel scripts

Cuxial Fuel declares, with `provide`, the resource names of the most common fuel scripts. They are listed at the top of its `fxmanifest.lua`. A resource that calls the fuel exports through one of those names keeps working without changes:

| Side   | Exports answered under those names                               |
| ------ | ---------------------------------------------------------------- |
| Client | `GetFuel`, `SetFuel`, `SetFuelType`, and their lowercase aliases |
| Server | `GetFuel`, `SetFuel`                                             |

## Events

Cuxial Fuel has no public events. Use the exports and the state bag.

## Integration with Cuxial Gas Stations

The link with `cuxial_gasstations` is automatic: when that resource is running, Cuxial Fuel asks it for prices, stock and promotions and reports each sale, refund and spill to it. There is nothing to configure and nothing to call from your own resources.


---

# 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/developers.md?ask=<question>&goal=<user_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.