# esx_cruisecontrol (/docs/addons/esx_cruisecontrol)

esx_cruisecontrol is a client-only ESX Legacy addon that adds two driving features: cruise control that holds your current speed, and a seatbelt that blocks exiting the vehicle and prevents you from being thrown through the windshield in a crash. It pushes both states to [esx_hud](/docs/addons/esx_hud) by default.

## Overview [#overview]

| | |
| --- | --- |
| Resource | `esx_cruisecontrol` (version 1.2) |
| Side | client only |
| Dependencies | `esx_lib`, `es_extended` |
| Optional | `esx_hud` (or any HUD set in `Config.HudResource`) |
| Export | `isSeatbeltOn` (client) |

**Cruise control** engages only when you are the driver, the engine runs and you are moving forward. It then applies throttle to hold the speed, with reduced throttle while steering. Each speed step is 10 mph and the maximum target is 120 mph; stepping down to 0 turns it off. It disengages on brake, handbrake, leaving the seat, engine off, standing still or reversing, or a sudden engine damage hit (more than 10 engine health in one frame).

**Seatbelt** blocks the exit control while buckled. Unbuckled, a frontal crash at more than `EjectCheckSpeed` mph with a strong deceleration throws the player out of the vehicle and ragdolls them. The seatbelt unbuckles automatically when you leave the vehicle. Ejection only applies to regular vehicle classes (classes 0-7, 9-12 and 17-20; motorcycles, bicycles, boats, helicopters, planes and trains are excluded).

## Installation [#installation]

No SQL is needed.

```bash title="server.cfg"
ensure esx_lib
ensure es_extended
ensure esx_hud
ensure esx_cruisecontrol
```

## Configuration [#configuration]

| Key | Default | Description |
| --- | --- | --- |
| `Config.Locale` | `GetConvar('esx:locale', 'en')` | Language. |
| `Config.HudResource` | `'esx_hud'` | HUD resource that receives the state. Skipped if it is not started. |
| `Config.Cruise.Enable` | `true` | Enables cruise control and its keybinds. |
| `Config.Cruise.Key` | `'CAPITAL'` | Default key to toggle cruise control (Caps Lock). |
| `Config.Cruise.Export` | `exports[Config.HudResource]:CruiseControlState(state)` | Function called with `true`/`false` when cruise control changes. |
| `Config.Seatbelt.Enable` | `true` | Enables the seatbelt and ejection. |
| `Config.Seatbelt.Key` | `'B'` | Default key to toggle the seatbelt. |
| `Config.Seatbelt.EjectCheckSpeed` | `45` | Minimum speed in **mph** before an unbuckled player can be ejected. |
| `Config.Seatbelt.RagdollTime` | `1` | How long the player ragdolls after ejection. The code multiplies it by 1000, so the value is in **seconds** (the config comment says MS). |
| `Config.Seatbelt.Export` | `exports[Config.HudResource]:SeatbeltState(state)` | Function called with `true`/`false` when the seatbelt changes. |

The increase and decrease speed keys are not in the config; their defaults are `ADD` and `SUBTRACT` (numpad plus and minus).

### Using another HUD [#using-another-hud]

Replace the two `Export` functions with whatever your HUD expects:

```lua title="config.lua"
Config = {
    Locale = GetConvar('esx:locale', 'en'),
    HudResource = 'my_hud',
    Cruise = {
        Enable = true,
        Key = 'CAPITAL',
        Export = function(state)
            exports['my_hud']:setCruise(state)
        end,
    },
    Seatbelt = {
        Enable = true,
        Key = 'B',
        EjectCheckSpeed = 45,
        RagdollTime = 1,
        Export = function(state)
            exports['my_hud']:setBelt(state)
        end,
    },
}
```

If the export call errors, the resource prints the error and a hint, but keeps working.

## Keybinds [#keybinds]

Registered through `xLib.addKeybind`, so players can rebind them in **Settings > Key Bindings > FiveM**.

| Name | Default | Action |
| --- | --- | --- |
| `esx_cruisecontrol:Enable` | `Config.Cruise.Key` | Toggle cruise control |
| `esx_cruisecontrol:IncreaseSpeed` | `ADD` | Raise target speed by 10 mph |
| `esx_cruisecontrol:DecreaseSpeed` | `SUBTRACT` | Lower target speed by 10 mph |
| `esx_cruisecontrol:ToggleSeatbelt` | `Config.Seatbelt.Key` | Toggle seatbelt |

## Exports [#exports]

### isSeatbeltOn (client) [#isseatbelton-client]

```lua
local buckled = exports.esx_cruisecontrol:isSeatbeltOn()
```

Returns `true` when the local player's seatbelt is fastened. Useful for police fines or a custom HUD:

```lua title="client/main.lua"
RegisterCommand('checkbelt', function()
    local buckled = exports.esx_cruisecontrol:isSeatbeltOn()
    ESX.ShowNotification(buckled and 'Seatbelt on' or 'Seatbelt off')
end, false)
```

The resource registers no server events or callbacks.

## Common issues [#common-issues]

- **Cruise control will not engage**: you must be the driver, moving forward with the engine running.
- **Keys changed in config have no effect**: FiveM stores key mappings per player after the first bind. Existing players keep their old key until they rebind it.
- **Console error about `CruiseControlState`**: `Config.HudResource` points to a resource that does not provide these exports. Adjust the `Export` functions.
- **Players never get ejected**: ejection needs a frontal crash above `EjectCheckSpeed` mph with a very sharp deceleration, in a supported vehicle class.

## Related [#related]

- [esx_hud](/docs/addons/esx_hud)
- [esx_policejob](/docs/addons/esx_policejob)
- [Client functions](/docs/es_extended/client/functions)