# Installation

This page takes you from the downloaded archive to a running HUD.
It takes about five minutes; the only setting you must check is the owned-vehicles table used by nitro.

## Requirements

| Resource | Required | What the HUD uses it for |
| --- | --- | --- |
| [koja-lib](https://github.com/Koja-Scripts/koja-lib) | Yes | Framework detection, player data, money, fuel, inventory, key binds, callbacks |
| [oxmysql](https://github.com/overextended/oxmysql) | Yes | Reading and saving nitro per vehicle |
| A framework | Yes | ESX (`es_extended`), QBCore (`qb-core`), QBox (`qbx_core`) or ox_core |
| [pma-voice](https://github.com/AvarianKnight/pma-voice) | No | The voice range bar. Without it the bar does not change |
| `esx_status` | ESX only | Hunger and thirst on ESX |
| `ox_fuel` or `LegacyFuel` | No | Fuel level. Without either, the native fuel level is shown |

:::hint{type="warning" title="Start order matters"}
`koja-hud` calls `exports['koja-lib']` the moment it loads.
If `koja-lib` is not started first, the resource errors on start and nothing appears.
:::

## Install

:::steps

### Put the resource in `resources`

Unpack the archive and keep the folder name `koja-hud`.

```text
resources/
└── [koja]/
    ├── koja-lib/
    └── koja-hud/
```

The folder name is the resource name.
Other resources call `exports['koja-hud']`, so renaming the folder breaks every export call — silently.

### Add it to `server.cfg`

Start it after its dependencies:

```cfg title="server.cfg"
ensure oxmysql
ensure koja-lib
ensure koja-hud
```

### Point nitro at your owned-vehicles table

Open `editable/shared/config.lua` and set the table that stores player vehicles:

```lua title="editable/shared/config.lua"
KOJA.Nitro = {
    -- ...
    Tables = {
        GaragesTable = 'owned_vehicles', -- ESX
        OwnerColumn = 'owner'
    },
}
```

| Framework | `GaragesTable` | `OwnerColumn` |
| --- | --- | --- |
| ESX | `owned_vehicles` | `owner` |
| QBCore / QBox | `player_vehicles` | `citizenid` |

The HUD adds a `nitro` column to that table on start.
If you do not want nitro at all, set `KOJA.Nitro.Enabled = false` instead — the server side then does nothing.

### Restart the server

Restart the server, or run `ensure koja-hud` in the server console.
The `nitro` column is created as soon as `oxmysql` connects.

:::

## Check that it works

1. Join the server. The status bars appear about a second after your character has loaded.
2. Type `/settings` in chat. The settings menu opens.
3. Get in a vehicle. The speedometer appears and the minimap switches on.

To test notifications, the progress bar and the text UI without writing code, set `KOJA.Debug = true` and restart the resource — it registers `/testnotify`, `/testprogress`, `/testtextui` and `/hidetextui`.
Turn it off again before going live.

## Next steps

- [Configuration](/free/hud/configuration) — keys, notifications, minimap, watermark and refresh rates.
- [Player settings](/free/hud/player-settings) — the defaults new players get, your Discord link and logo.
- [Troubleshooting](/free/hud/troubleshooting) — if something above did not happen.