# Configuration

All settings are found in `config.lua`. This guide explains each section in detail.

***

## General

```lua
Config.Locale = 'en'
Config.Debug = false
```

| Parameter | Type    | Default | Description                                                                                                                  |
| --------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Locale`  | string  | `'en'`  | Language file from `locales/`. Supported: `en`, `fr`, `es`, `de`, `pt`, `it`, `nl`, `pl`, `tr`, `ru`, `zh`, `ja`, `ko`, `ar` |
| `Debug`   | boolean | `false` | Enable detailed logs in console (server + client)                                                                            |

***

## Menu

```lua
Config.Menu = {
    Command     = 'carmenu',
    Keybind     = 'H',
    Description = 'Open vehicle control panel',
    Align       = 'bottom-center',
    Scale       = 1.0,
}
```

| Parameter     | Type   | Default             | Description                                                                                            |
| ------------- | ------ | ------------------- | ------------------------------------------------------------------------------------------------------ |
| `Command`     | string | `'carmenu'`         | Chat command to toggle the menu                                                                        |
| `Keybind`     | string | `'H'`               | Default key binding (FiveM key mapper — players can rebind)                                            |
| `Description` | string | `'Open vehicle...'` | Description shown in FiveM key-binding settings                                                        |
| `Align`       | string | `'bottom-center'`   | Screen position: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right` |
| `Scale`       | float  | `1.0`               | UI scale multiplier (0.8 – 1.2)                                                                        |

***

## Feature Toggles

Enable or disable each feature individually. Disabled features are hidden from the menu.

```lua
Config.Features = {
    Windows       = true,
    Doors         = true,
    Seats         = true,
    Engine        = true,
    Lights        = true,
    InteriorLight = true,
    Indicators    = true,
    Alarm         = true,
    Convertible   = true,
    Neons         = true,
    CruiseControl = true,
    SpeedLimiter  = true,
    DoorLock      = true,
    Radio         = true,
}
```

| Feature         | Description                               |
| --------------- | ----------------------------------------- |
| `Windows`       | Window up/down controls                   |
| `Doors`         | Door open/close (driver only)             |
| `Seats`         | Change seat                               |
| `Engine`        | Engine on/off (driver only)               |
| `Lights`        | Headlights cycle (off → low → high)       |
| `InteriorLight` | Interior light toggle                     |
| `Indicators`    | Left/right turn signals                   |
| `Alarm`         | Hazard lights                             |
| `Convertible`   | Convertible roof toggle                   |
| `Neons`         | Neon lights toggle                        |
| `CruiseControl` | Cruise control                            |
| `SpeedLimiter`  | Speed limiter                             |
| `DoorLock`      | Lock/unlock doors from inside             |
| `Radio`         | GTA V radio control (station switch, off) |

***

## Neon Lights

```lua
Config.Neons = {
    AllowColorChange = true,
    SaveColor = true,
    Presets = {
        { r = 255, g = 0,   b = 0,   label = 'Red' },
        { r = 0,   g = 0,   b = 255, label = 'Blue' },
        { r = 0,   g = 255, b = 0,   label = 'Green' },
        { r = 255, g = 255, b = 255, label = 'White' },
        { r = 128, g = 0,   b = 255, label = 'Purple' },
        { r = 255, g = 255, b = 0,   label = 'Yellow' },
        { r = 0,   g = 255, b = 255, label = 'Cyan' },
        { r = 255, g = 128, b = 0,   label = 'Orange' },
        { r = 255, g = 0,   b = 128, label = 'Pink' },
    },
}
```

| Parameter          | Type    | Default  | Description                                                |
| ------------------ | ------- | -------- | ---------------------------------------------------------- |
| `AllowColorChange` | boolean | `true`   | Let players choose the neon RGB color from the menu        |
| `SaveColor`        | boolean | `true`   | Save the chosen color per vehicle plate (requires oxmysql) |
| `Presets`          | table   | 9 colors | Preset color swatches shown in the picker                  |

{% hint style="info" %}
Players can also use a custom color picker (HTML input) in addition to the preset swatches.
{% endhint %}

***

## Radio

```lua
Config.Radio = {
    DisableWheel = true,
}
```

| Parameter      | Type    | Default | Description                                                                            |
| -------------- | ------- | ------- | -------------------------------------------------------------------------------------- |
| `DisableWheel` | boolean | `true`  | Disable the native GTA V radio wheel so players use the CarControl radio panel instead |

***

## Cruise Control

```lua
Config.CruiseControl = {
    Enabled            = true,
    Keybind            = 'K',
    MinSpeed           = 20,
    SpeedStep          = 5,
    DisableOnBrake     = true,
    DisableOnCollision = true,
    ShowHUD            = true,
}
```

| Parameter            | Type    | Default | Description                                       |
| -------------------- | ------- | ------- | ------------------------------------------------- |
| `Enabled`            | boolean | `true`  | Enable cruise control feature                     |
| `Keybind`            | string  | `'K'`   | Direct keybind (without opening the menu)         |
| `MinSpeed`           | integer | `20`    | Minimum speed required to activate (km/h)         |
| `SpeedStep`          | integer | `5`     | Speed adjustment step when pressing +/- (km/h)    |
| `DisableOnBrake`     | boolean | `true`  | Automatically disengage when the player brakes    |
| `DisableOnCollision` | boolean | `true`  | Automatically disengage on collision              |
| `ShowHUD`            | boolean | `true`  | Show the cruise speed indicator in the NUI header |

{% hint style="warning" %}
The cruise control keybind can be changed by players in the FiveM key-binding settings.
{% endhint %}

***

## Speed Limiter

```lua
Config.SpeedLimiter = {
    Enabled = true,
    Presets = { 30, 50, 80, 110, 130 },
}
```

| Parameter | Type    | Default                    | Description                                                                            |
| --------- | ------- | -------------------------- | -------------------------------------------------------------------------------------- |
| `Enabled` | boolean | `true`                     | Enable speed limiter feature                                                           |
| `Presets` | table   | `{ 30, 50, 80, 110, 130 }` | Preset speeds to cycle through (km/h). The limiter cycles: preset1 → preset2 → … → off |

***

## Door Lock

```lua
Config.DoorLock = {
    Enabled       = true,
    Keybind       = 'U',
    KeysResource  = 'auto',
    SyncToPlayers = true,
}
```

| Parameter       | Type    | Default  | Description                                                                                   |
| --------------- | ------- | -------- | --------------------------------------------------------------------------------------------- |
| `Enabled`       | boolean | `true`   | Enable door lock feature                                                                      |
| `Keybind`       | string  | `'U'`    | Direct keybind (without opening the menu)                                                     |
| `KeysResource`  | string  | `'auto'` | Vehicle keys resource: `'auto'` (detect), `'qbx_vehiclekeys'`, `'qb-vehiclekeys'`, `'native'` |
| `SyncToPlayers` | boolean | `true`   | Sync lock state to nearby players via StateBag (only used with `'native'` mode)               |

{% hint style="info" %}
When set to `'auto'`, the script will detect `qbx_vehiclekeys` or `qb-vehiclekeys` automatically. If neither is found, it falls back to GTA native lock.
{% endhint %}

***

## Keybinds

Direct keybinds that work **without opening the menu**. Set a key to `''` (empty string) to disable.

```lua
Config.Keybinds = {
    IndicatorLeft  = 'LEFT',
    IndicatorRight = 'RIGHT',
    HazardLights   = '',
}
```

| Parameter        | Type   | Default   | Description                         |
| ---------------- | ------ | --------- | ----------------------------------- |
| `IndicatorLeft`  | string | `'LEFT'`  | Left turn signal                    |
| `IndicatorRight` | string | `'RIGHT'` | Right turn signal                   |
| `HazardLights`   | string | `''`      | Hazard lights (disabled by default) |

***

## Auto-Close

```lua
Config.AutoClose = true
```

Close the menu automatically when the player exits the vehicle.

***

## Sounds

```lua
Config.Sounds = {
    Enabled         = true,
    UseCustomSounds = true,
    Volume          = 0.5,
}
```

| Parameter         | Type    | Default | Description                                                            |
| ----------------- | ------- | ------- | ---------------------------------------------------------------------- |
| `Enabled`         | boolean | `true`  | Master toggle for all sounds                                           |
| `UseCustomSounds` | boolean | `true`  | Use custom `.ogg` files in `html/sounds/` instead of native GTA sounds |
| `Volume`          | float   | `0.5`   | Volume for custom sounds (0.0 – 1.0)                                   |

***

## Notifications

```lua
Config.Notifications = {
    Enabled = true,
    Type    = 'framework',
}
```

| Parameter | Type    | Default       | Description                                                                                |
| --------- | ------- | ------------- | ------------------------------------------------------------------------------------------ |
| `Enabled` | boolean | `true`        | Master toggle for all notifications                                                        |
| `Type`    | string  | `'framework'` | Notification system: `'framework'` (QBCore/ESX), `'chat'` (FiveM chat), `'native'` (GTA V) |

***

## Permissions

```lua
Config.Permissions = {
    Enabled       = false,
    AcePermission = '',
}
```

| Parameter       | Type    | Default | Description                                                                                  |
| --------------- | ------- | ------- | -------------------------------------------------------------------------------------------- |
| `Enabled`       | boolean | `false` | Enable server-side permission checks                                                         |
| `AcePermission` | string  | `''`    | Ace permission required to use the menu. Leave empty to allow everyone when `Enabled = true` |

{% hint style="info" %}
When `Enabled = false` (default), all players can use the menu. Enable this only if you want to restrict access via FiveM ace permissions.
{% endhint %}

***

{% hint style="success" %}
After modifying `config.lua`, restart the script with `ensure HZ-CarControl` or restart the server.
{% endhint %}