# Installation

> Setup guide for ML Fuel

Category: FUEL · Source: https://miciomods.it/docs/ml-fuel-installation · Last updated: 2026-07-28

## Overview

ML Fuel replaces pay-at-pump refueling with a survival fuel economy. Vehicles consume typed fuel (gasoline, diesel, kerosene, plus optional types) based on their handling data, and players get fuel from items: refillable jerry cans, one-use containers, siphoning, vehicle wrecks and a rotating set of scavengeable gas stations. Electric vehicles, charging stations, power cells, tank upgrades and per-plate fuel conversions are included.

## Quick Start

1. Download from the CFX Portal
2. Extract to your resources folder as `ml_fuel`
3. Add to `server.cfg`:

**server.cfg**

```cfg
ensure oxmysql
ensure ox_lib
ensure ox_inventory   # or your inventory
ensure ml_bridge
ensure ml_fuel
```

> **WARNING:** Load Order
>
> `ml_fuel` must start AFTER `ml_bridge`, `ox_lib` and your inventory.

> **DANGER:** One fuel resource
>
> Remove any other fuel resource (LegacyFuel, ox_fuel, cdn-fuel, ...) before starting `ml_fuel`. Two fuel scripts writing the same vehicle fuel level fight each other.

## Database

One table is created automatically on first start:

- `ml_fuel_conversions`: per-plate fuel type conversions, tank bonus liters and installed upgrades

> **INFO:** Auto Created
>
> No SQL import is needed. The schema is built automatically on start.

## Item Registration

Register every item referenced by the config in your inventory. Ready-made ox_inventory definitions ship in `install/ox_inventory_items.lua` and `data/items_ox.lua`: adapt the names to match your config keys. The shipped defaults:

- `jerrycan_empty`, `plastic_bottle_empty`: refillable jerry cans (Config.JerryCans)
- `fuel_liter`, `fuel_canister`, `diesel_liter`, `diesel_canister`, `biofuel_bottle`, `kerosene_can`, `fuel_sample`: one-use fuel items (Config.FuelItems)
- `siphon_hose`: siphon hose, also used for wreck scavenging and for installing tank upgrades
- `electric_pump`: electric pump for pump scavenging
- `tank_expansion_small`, `tank_expansion_medium`, `tank_expansion_large`: tank upgrades (Config.TankUpgrades)
- `diesel_conversion_kit`, `biofuel_conversion_kit`, `ethanol_conversion_kit`: conversion kits (`Config.ConversionKits`)
- `power_cell`, `power_cell_heavy`, `solar_cell`: power cells (`Config.PowerCells`)

> **WARNING:** Jerry can item definition
>
> Jerry cans and power cells must be defined with `stack = false` and `consume = 0`: their fuel state lives in item metadata and the item is never removed on use.

## Verify

After starting, the console prints the banner and:

```lua
[ml_fuel] Resource started
[ml_fuel] Developed by Micio Mods | miciomods.it
[ml_fuel] [INFO] Database tables verified!
[ml_fuel] [INFO] Fuel mode forced: advanced
[ml_fuel] [INFO] Station availability initialized with 27 configured stations
[ml_fuel] [INFO] All usable items registered (mode: advanced)
```

Enter a vehicle: the fuel gauge appears and the level starts draining while you drive.

**Troubleshooting**

- Jerry can does nothing on use, the item is not registered in the inventory, or its name does not match a `Config.JerryCans` key
- "Jerry cans are not available with your server inventory system", the resolved fuel mode is `simple` because the inventory does not support metadata. Check `Config.FuelMode` and the startup line `Fuel mode resolved`
- No refuel option on the vehicle, the target only appears while you carry a compatible container, and never on locked vehicles or bicycles
- Pumps never give fuel, station rotation may have them depleted or dormant. Use `/showpumps` as admin to see the active stations, or disable `PumpScavenging.availability`
- Fuel does not drain, check `Config.Features.Consumption` and that no other fuel resource is running
- Version errors at start: make sure ox_lib and your inventory are up to date.