# Configuration

Server-side behaviour of the HUD lives in `editable/shared/config.lua`.
This page goes through it top to bottom: what each option does, its default, and when you would change it.

Changes take effect after `ensure koja-hud` (or a server restart).
What players see by default — styles, colours, which elements are on — is not in this file; that is [Player settings](/free/hud/player-settings).

| File | What it controls |
| --- | --- |
| `editable/shared/config.lua` | Everything on this page |
| `editable/shared/js.json` | Player defaults, key hints, Discord and logo, the settings menu — see [Player settings](/free/hud/player-settings) |
| `editable/shared/utils.lua` | Your own notification function, and the pma-voice hook — see [Custom notifications](#custom-notifications) |
| `locales/*.json` | Every text — see [Translations](/free/hud/translations) |

## General

```lua title="editable/shared/config.lua"
KOJA.Debug = false
KOJA.Locale = 'en'
KOJA.SettingsCommand = 'settings'
KOJA.HideMinimapOnFoot = true
KOJA.HideHudOnPauseMenu = true
KOJA.Notify = 'hud'
```

| Option | Default | What it does |
| --- | --- | --- |
| `KOJA.Debug` | `false` | Prints HUD events to the F8 console and registers the test commands `/testnotify`, `/testprogress`, `/testtextui`, `/hidetextui`. Keep it off on a live server. |
| `KOJA.Locale` | `'en'` | Language file loaded from `locales/`: `en`, `pl`, `de`, `es`, `fr`, `hi`. An unknown code falls back to English. |
| `KOJA.SettingsCommand` | `'settings'` | Chat command that opens the settings menu. Without the slash. |
| `KOJA.HideMinimapOnFoot` | `true` | The minimap visibility new players start with: `true` shows it only in vehicles, `false` always. Players can change it in **Settings → MAIN → Minimap**. |
| `KOJA.HideHudOnPauseMenu` | `true` | Hides the whole HUD while the pause menu or the full map is open. |
| `KOJA.Notify` | `'hud'` | Which notification system the HUD's own messages use (engine, seatbelt, cruise, nitro). See below. |

### Notification system

`KOJA.Notify` only decides where the HUD's **own** messages go.
`exports['koja-hud']:sendNotify` always uses the HUD's notifications, whatever you set here.

| Value | Messages are shown by |
| --- | --- |
| `'hud'` | The HUD's notifications |
| `'esx'`, `'qb'`, `'ox'` | koja-lib's `SendNotify`, which uses the notification system configured in koja-lib |
| `'custom'` | `Misc.Utils.CustomNotify` in `editable/shared/utils.lua` |

### Custom notifications

With `KOJA.Notify = 'custom'`, fill in the function in `editable/shared/utils.lua`.
It receives the translated title and text:

```lua title="editable/shared/utils.lua"
Misc.Utils.CustomNotify = function(data)
    -- data.title, data.desc, data.type, data.icon, data.color, data.time
    exports['my-notify']:Show(data.title, data.desc)
end
```

## Forcing components off

```lua title="editable/shared/config.lua"
KOJA.HideComponents = {
    status = false,
    carhud = false,
    progressbar = false,
    notify = false,
    textui = false,
    informations = false
}
```

Set a component to `true` to hide it for everyone, whatever players choose in the settings menu.
Use it when another resource already provides that element — for example `progressbar = true` if you keep using `ox_lib` progress bars.

| Key | Component |
| --- | --- |
| `status` | Status bars |
| `carhud` | Speedometer |
| `progressbar` | Progress bar |
| `notify` | Notifications |
| `textui` | Text UI prompt |
| `informations` | Cash, bank, job, ID, clock, Discord and logo panel |

The same names work at runtime with the [`HideComponent`](/free/hud/exports-and-events#hidecomponent) export.

## Minimap item

```lua title="editable/shared/config.lua"
KOJA.NeedItemForMinimap = false
KOJA.MinimapItem = 'phone'
```

With `KOJA.NeedItemForMinimap = true`, the minimap is shown only while the player has at least one `KOJA.MinimapItem` in their inventory.
The check runs every 300 ms through koja-lib, so it follows your inventory resource.

## Voice

```lua title="editable/shared/config.lua"
KOJA.Microphone = {
    Enabled = true,
    Custom = false,
    Levels = {
        [1] = 25,
        [2] = 75,
        [3] = 100,
    },
}
```

| Option | What it does |
| --- | --- |
| `Enabled` | `false` turns off the pma-voice integration. |
| `Custom` | `true` skips the pma-voice integration, so you can feed the voice bar from another voice resource by editing `editable/shared/utils.lua`. |
| `Levels` | Maps each pma-voice range (mode 1, 2, 3) to how full the voice bar is, 0–100. Add entries if your pma-voice config has more modes. |

The "talking" highlight on the voice indicator does not depend on this block: it comes from the game's own voice chat state.

## Nitro

```lua title="editable/shared/config.lua"
KOJA.Nitro = {
    Enabled = true,
    Key = 'N',
    Desc = 'Toggle nitro',
    Tables = {
        GaragesTable = 'owned_vehicles',
        OwnerColumn = 'owner'
    },
    NitroForce = 1.5,
    RemoveNitroOnMilliseconds = 2,
    Item = 'nitro'
}
```

| Option | Default | What it does |
| --- | --- | --- |
| `Enabled` | `true` | Turns the whole nitro system on or off, client and server. |
| `Key` | `'N'` | Default key for boosting. Players can rebind it in GTA's key bindings or in **Settings → BINDS**. |
| `Desc` | `'Toggle nitro'` | The label shown in GTA's key binding menu. |
| `Tables.GaragesTable` | `'owned_vehicles'` | Your owned-vehicles table. A `nitro` column is added to it. |
| `Tables.OwnerColumn` | `'owner'` | The column holding the owner's identifier. Use `citizenid` on QBCore and QBox. |
| `NitroForce` | `1.5` | Engine power multiplier while boosting. `1.5` is +50%. |
| `RemoveNitroOnMilliseconds` | `2` | Nitro used every 100 ms of boosting, out of 100. At `2`, a full tank lasts 5 seconds. |
| `Item` | `'nitro'` | Item taken from the player when nitro is installed. `false` means no item is needed — install only through [`SetNitro`](/free/hud/exports-and-events#setnitro). |

How nitro is installed and saved is described in [Features → Nitro](/free/hud/features#nitro).

:::hint{type="warning"}
The HUD does not register a usable item.
To let players install nitro by using the item, call `exports['koja-hud']:SetNitro()` from your inventory's use handler — see [SetNitro](/free/hud/exports-and-events#setnitro).
:::

## Engine

```lua title="editable/shared/config.lua"
KOJA.Engine = {
    Enabled = true,
    Key = 'B',
    Desc = 'Toggle engine',
    StartEngineOnEntering = false
}
```

| Option | Default | What it does |
| --- | --- | --- |
| `Enabled` | `true` | Lets the driver switch the engine on and off with `Key`. |
| `Key` / `Desc` | `'B'` | Default key, and its label in GTA's key binding menu. |
| `StartEngineOnEntering` | `false` | `false`: a vehicle you get into with the engine off stays off — accelerating and braking are blocked until you press the key. `true`: the engine starts as soon as you take the driver's seat. |

## Seatbelt

```lua title="editable/shared/config.lua"
KOJA.Seatbelt = {
    Enabled = true,
    Key = 'L',
    Desc = 'Toggle seatbelt',
    MaxVehicleSpeedToRagdoll = 70
}
```

| Option | Default | What it does |
| --- | --- | --- |
| `Enabled` | `true` | Seatbelt key, ejection and the seatbelt icon. |
| `Key` / `Desc` | `'L'` | Default key, and its label in GTA's key binding menu. |
| `MaxVehicleSpeedToRagdoll` | `70` | Speed in km/h. An unbelted player travelling faster than this is thrown through the windscreen when the vehicle loses more than 20% of its speed at once. |

While the belt is on, the player cannot leave the vehicle with **F**.

## Cruise control

```lua title="editable/shared/config.lua"
KOJA.CruiseMode = {
    Enabled = true,
    Key = 'T',
    Desc = 'Toggle cruise control',
    MinSpeed = 20.0
}
```

| Option | Default | What it does |
| --- | --- | --- |
| `Enabled` | `true` | Lets the driver hold the current speed. |
| `Key` / `Desc` | `'T'` | Default key, and its label in GTA's key binding menu. |
| `MinSpeed` | `20.0` | Lowest speed in km/h at which cruise control engages. |

Cruise control switches off when the driver brakes, leaves the seat, or the vehicle leaves the ground.

## Compass

```lua title="editable/shared/config.lua"
KOJA.Compass = {
    Enabled = true
}
```

`false` removes the compass for everyone and stops the thread that tracks the camera heading.
With it on, players pick the style and when it shows.

## Refresh rates

```lua title="editable/shared/config.lua"
KOJA.Refresh = {
    Hud = 1500,
    PauseMenu = 200,
    Compass = 90,
    Weapon = 250,
    Vehicle = 150
}
```

How often, in milliseconds, each part of the HUD is updated.
Lower is smoother and costs more client CPU.

| Key | Updates |
| --- | --- |
| `Hud` | Status bars, cash, bank, job and talking state |
| `PauseMenu` | Whether the pause menu is open |
| `Compass` | Compass heading |
| `Weapon` | Weapon name and ammo |
| `Vehicle` | Speedometer, while in a vehicle |

The defaults are a good balance. If you lower `Vehicle`, do not go below about 50.

## Watermark

```lua title="editable/shared/config.lua"
KOJA.Watermark = {
    Enabled = false,
    Text = 'HEXEL RP'
}
```

Shows your server name at the top of the screen.
`Enabled = false` hides it for everyone.
With it on, players choose the style, font, size and colour in **Settings → MAIN → PVP Mode**, and can hide it there.
In PVP mode the watermark also shows the player's health and armour.

## Vehicle menu

```lua title="editable/shared/config.lua"
KOJA.VehicleMenu = {
    Enabled = true,
    Key = 'U',
    Command = 'vehicle',
    Desc = 'Open vehicle control menu'
}
```

| Option | Default | What it does |
| --- | --- | --- |
| `Enabled` | `true` | The vehicle control menu: engine, seatbelt, lights, turn signals, hazards, doors, hood, trunk. |
| `Key` | `'U'` | Default key. It is registered in GTA's key bindings, so players can rebind it there. |
| `Command` | `'vehicle'` | Extra chat command that opens the menu. Set it to `false` for key-only. |
| `Desc` | — | Label shown in GTA's key binding menu. |

The menu opens only for the driver.

## Killfeed

```lua title="editable/shared/config.lua"
KOJA.Killfeed = {
    Enabled = false,
    AnyDistance = true,
    Distance = 100
}
```

These are the **defaults** for new players; each player can change them in **Settings → MAIN → Killfeed**.

| Option | Default | What it does |
| --- | --- | --- |
| `Enabled` | `false` | Whether the killfeed is on for a player who has not changed it. |
| `AnyDistance` | `true` | Show kills at any distance. |
| `Distance` | `100` | With `AnyDistance = false`, kills further away than this many metres are not shown. |

The killfeed records kills made by the player themself out of the box.
To show other kills, send them from your own code — see [AddKillfeed](/free/hud/exports-and-events#addkillfeed).

## Status effects

```lua title="editable/shared/config.lua"
KOJA.StatusEffects = {
    Builtin = false
}
```

`true` shows two effects the HUD detects by itself: **sprinting** and **swimming**.
Effects you add from code are shown either way — see [Status effects](/free/hud/exports-and-events#status-effects).

## Minimap

```lua title="editable/shared/config.lua"
KOJA.MiniMap = {
    Enabled = true,
}
```

`true` replaces the round GTA radar with the square minimap that players can move and resize in **Settings → Edit layout**.
`false` leaves the game's own minimap alone.

### Fine-tuning the minimap

Advanced: the square minimap's geometry has defaults you can override by adding keys to `KOJA.MiniMap`.
They are fractions of the screen; leave them alone unless the map looks misaligned on your setup.

| Key | Default |
| --- | --- |
| `OffsetX`, `OffsetY` | `0.01`, `-0.05` |
| `Width`, `Height` | `0.150`, `0.188888` |
| `MaskOffsetX`, `MaskOffsetY` | `0.010`, `-0.030` |
| `MaskWidth`, `MaskHeight` | `0.101`, `0.159` |
| `BlurOffsetX`, `BlurOffsetY` | `0.00`, `-0.040` |
| `BlurWidth`, `BlurHeight` | `0.250`, `0.237` |
| `EditorBoxScaleX`, `EditorBoxScaleY` | `1.28`, `1.12` — size of the frame drawn around the map in the layout editor |

```lua title="editable/shared/config.lua"
KOJA.MiniMap = {
    Enabled = true,
    OffsetY = -0.04,
}
```

## Data files

Two lists in `data/` are worth knowing about:

| File | What it is |
| --- | --- |
| `data/electricmodels.lua` | Vehicle models that show a battery instead of a fuel pump. Add your electric add-on cars here. |
| `data/weapons.lua` | Weapon hash → display name, used by the weapon panel. Add-on weapons not in the list are shown as "Weapon". |

```lua title="data/electricmodels.lua"
ElectricModels = {
    [GetHashKey('voltic')] = true,
    [GetHashKey('my_addon_ev')] = true,
}
```