> For the complete documentation index, see [llms.txt](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/configuration.md).

# Configuration

| File                | Sent to clients  | Use it for                                               |
| ------------------- | ---------------- | -------------------------------------------------------- |
| `config.lua`        | **Yes** (shared) | Behavior and integrations. Never put secrets here.       |
| `config_server.lua` | No (server only) | Database, rate limits, admin groups, server layout lock. |

{% hint style="info" %}
The **visual layout** (positions, colors, shapes, fonts, minimap shape) is **not** configured in these files: do it in game with `/hud`, and an admin can publish it as the server default. See [Usage guide](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/usage-guide.md).
{% endhint %}

## General

| Option              | Default      | Meaning                                                                      |
| ------------------- | ------------ | ---------------------------------------------------------------------------- |
| `Config.Locale`     | `'it'`       | Default language, `'it'` or `'en'`. Each player can change it in the editor. |
| `Config.Framework`  | `'auto'`     | `'auto'`, `'esx'`, `'qbcore'`, `'qbox'` or `'standalone'`.                   |
| `Config.Logo`       | `'logo.svg'` | Logo file (top right) in `web/dist/`. `''` = no logo.                        |
| `Config.ServerName` | `'Ghiaccio'` | Fallback text when the logo is missing.                                      |

## Clock

The date/time at the top center uses the fixed format `HH:mm - DD/MM/YY` (e.g. `21:45 - 11/11/26`).

| Option                     | Default         | Meaning                                                                 |
| -------------------------- | --------------- | ----------------------------------------------------------------------- |
| `Config.TimeSource`        | `'real'`        | `'real'` (real server time) or `'game'` (GTA clock).                    |
| `Config.Timezone`          | `'Europe/Rome'` | IANA time zone for `'real'`. Daylight saving is computed by the server. |
| `Config.TimeResyncMinutes` | `10`            | How often (minutes) the client re-syncs its clock with the server.      |

## Editor

| Option                  | Default | Meaning                                                                    |
| ----------------------- | ------- | -------------------------------------------------------------------------- |
| `Config.Editor.enabled` | `true`  | `false` = in-game editor disabled.                                         |
| `Config.Editor.command` | `'hud'` | Command that opens the editor.                                             |
| `Config.Editor.key`     | `'F7'`  | Default key. Each player can rebind it in Settings > Key Bindings > FiveM. |

## Commands and keys

`''` = no command / no default key.

| Option                          | Default        | Meaning                                   |
| ------------------------------- | -------------- | ----------------------------------------- |
| `Config.Commands.toggle`        | `'togglehud'`  | Show / hide the HUD.                      |
| `Config.Commands.cinematic`     | `'cinematic'`  | Cinematic mode (black bars + HUD hidden). |
| `Config.Commands.cinematicKey`  | `''`           | Key for cinematic mode.                   |
| `Config.Commands.carControl`    | `'carcontrol'` | Car control panel.                        |
| `Config.Commands.carControlKey` | `''`           | Key for the car control panel.            |
| `Config.Commands.seatbelt`      | `'seatbelt'`   | Built-in seatbelt.                        |
| `Config.Commands.seatbeltKey`   | `'B'`          | Seatbelt key.                             |
| `Config.Commands.cruise`        | `'cruise'`     | Built-in cruise control.                  |
| `Config.Commands.cruiseKey`     | `''`           | Cruise control key.                       |
| `Config.Commands.limiter`       | `'limiter'`    | Built-in speed limiter.                   |
| `Config.Commands.limiterKey`    | `''`           | Speed limiter key.                        |

## Features

| Option                           | Default | Meaning                                                                                                                   |
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Config.Features.cinematic`      | `true`  | Cinematic mode available.                                                                                                 |
| `Config.Features.streamerMode`   | `true`  | The streamer mode option appears in the editor (hides ID, cash, bank, street).                                            |
| `Config.Features.carControl`     | `true`  | Car control panel available.                                                                                              |
| `Config.Features.hideWhenPaused` | `true`  | Hide the HUD while the pause menu is open.                                                                                |
| `Config.Features.hideWhenDead`   | `false` | Hide the HUD while the player is dead.                                                                                    |
| `Config.Features.hideNativeHud`  | `true`  | Hide the overlapping native components (vehicle name, zone, street, money). `false` also stops the only per-frame thread. |

## Native HUD components

| Option                        | Default                              | Meaning                                                                                                                                                                                         |
| ----------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.HideNativeComponents` | `{ 1, 2, 3, 4, 6, 7, 8, 9, 13, 20 }` | GTA native HUD components to hide: 1 wanted stars, 2 weapon icon + ammo, 3 cash, 4 MP cash, 6 vehicle name, 7 area name, 8 vehicle class, 9 street name, 13 cash change, 20 weapon wheel stats. |

{% hint style="info" %}
14 (reticle), 16 (radio stations), 19 (weapon wheel), 21 and 22 are **never** hidden, even if listed.
{% endhint %}

## Loop intervals

| Option                | Default | Meaning                                                              |
| --------------------- | ------- | -------------------------------------------------------------------- |
| `Config.Tick.onFoot`  | `300`   | ms. Health, armor, stamina, oxygen, weapon. 250-500 is fine.         |
| `Config.Tick.vehicle` | `100`   | ms. Speed, RPM, gear (the NUI interpolates). Runs only in a vehicle. |
| `Config.Tick.nav`     | `500`   | ms. Compass, street, zone.                                           |
| `Config.Tick.slow`    | `2000`  | ms. Hunger/thirst/stress fallback, money fallback, day/night.        |

## Vehicle

| Option                           | Default | Meaning                                       |
| -------------------------------- | ------- | --------------------------------------------- |
| `Config.Vehicle.seatbeltWarnKmh` | `20`    | Unfastened-seatbelt warning above this speed. |
| `Config.Vehicle.cruiseMinKmh`    | `20`    | Minimum speed for cruise control.             |
| `Config.Vehicle.limiterMinKmh`   | `20`    | Minimum speed for the limiter.                |

## Integrations

`'auto'` detects by itself; otherwise the adapter name; `false` = disabled. See [Integrations & adapters](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/integrations.md).

| Option                         | Default  | Values                                                                                               |
| ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `Config.Integrations.fuel`     | `'auto'` | `'auto'`, `'ox_fuel'`, `'LegacyFuel'`, `'cdn-fuel'`, `'native'`                                      |
| `Config.Integrations.status`   | `'auto'` | `'auto'`, `'esx_status'`, `'qb'` (QBCore/Qbox metadata), `'exports'`, `false` (hunger/thirst hidden) |
| `Config.Integrations.voice`    | `'auto'` | `'auto'`, `'pma-voice'`, `'saltychat'`, `false`                                                      |
| `Config.Integrations.seatbelt` | `'auto'` | `'auto'` (known external script if running, otherwise built-in), `'builtin'`, `'external'`, `false`  |

## Built-in seatbelt

Used when `Config.Integrations.seatbelt` resolves to `'builtin'`. With an external seatbelt script, that script decides.

| Option                      | Default | Meaning                                                                                                         |
| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `Config.Seatbelt.ejection`  | `true`  | `false` = the built-in seatbelt **never** throws players out of the vehicle after a crash, at any speed.        |
| `Config.Seatbelt.ejectKmh`  | `70`    | With `ejection = true`: above this speed, without a seatbelt, a hard crash throws the player out (`0` = never). |
| `Config.Seatbelt.blockExit` | `true`  | While the seatbelt is fastened the exit key (F) is disabled.                                                    |

## Built-in stress

Only used when the framework provides none (QBCore/Qbox keep stress in the player metadata).

| Option                      | Default | Meaning                                       |
| --------------------------- | ------- | --------------------------------------------- |
| `Config.Stress.enabled`     | `true`  | Built-in stress on/off.                       |
| `Config.Stress.shooting`    | `1`     | Stress per shot fired (unsuppressed weapons). |
| `Config.Stress.speedingKmh` | `160`   | Speed above which driving adds stress.        |
| `Config.Stress.speeding`    | `1`     | Stress per slow tick while speeding.          |
| `Config.Stress.decay`       | `1`     | Decrease per slow tick while calm.            |
| `Config.Stress.effects`     | `true`  | Slight camera shake above 80.                 |

## Crash effect

After a **severe** crash in a vehicle (never for light bumps): camera shake, tint/blur that fade out, muffled audio, a short blackout in the worst cases and a staggering walk if you leave the vehicle during the effect. If `Config.CrashEffect` is missing these defaults apply; every key is optional.

| Option            | Default          | Meaning                                                              |
| ----------------- | ---------------- | -------------------------------------------------------------------- |
| `enabled`         | `true`           | `false` = effect off and no detection thread.                        |
| `minSpeedLossKmh` | `60`             | Sudden speed loss that counts as a severe crash.                     |
| `cooldownSeconds` | `20`             | Minimum pause between two effects.                                   |
| `blackout`        | `true`           | Short black screen in the worst cases (never with the seatbelt on).  |
| `staggerOnFoot`   | `true`           | Staggering walk for a few seconds if you step out during the effect. |
| `seatbeltReduces` | `true`           | With the seatbelt on, intensity and duration are reduced.            |
| `sound`           | `true`           | Muffled audio during the effect.                                     |
| `excludedClasses` | `{ 14, 15, 16 }` | Excluded vehicle classes (14 boats, 15 helicopters, 16 planes).      |

Detection uses a sliding window of about 250 ms and ignores braking, jumps/landings, teleports and the first seconds after entering. The thread only exists inside a vehicle. The effect stops and cleans up by itself on death, editor, cinematic or resource stop.

## Minimap

Shape and position are chosen in the editor.

| Option                       | Default | Meaning                                                                                                                                    |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Config.Minimap.enabled`     | `true`  | `false` = the resource never touches the minimap.                                                                                          |
| `Config.Minimap.masks`       | `'ytd'` | `'ytd'` (bundled `stream/ghud_*map.ytd`, then runtime) or `'runtime'` (PNGs in `assets/minimap/`, then ytd). Each falls back to the other. |
| `Config.Minimap.lockBigmap`  | `true`  | Blocks the expanded radar (Z key), which would break the custom geometry.                                                                  |
| `Config.Minimap.calibration` | `{}`    | Per-shape fine tuning: `dx`/`dy` = offset in screen fractions (x right, y down), `scale` = size multiplier.                                |

```lua
Config.Minimap.calibration = { circle = { dx = 0.004, dy = -0.002, scale = 1.03 } }
```

## config\_server.lua

| Option                            | Default                     | Meaning                                                                                                                                                                            |
| --------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.DbSync`                   | `false`                     | `false`: layouts are stored only as KVP on the player's PC. `true`: the layout follows the player (Rockstar license) to another PC; requires `oxmysql` started **before** the HUD. |
| `Config.RateLimit.requestInit`    | `{ window = 10, max = 1 }`  | Network rate limit (window in seconds, max events per window). Beyond that the event is ignored and logged.                                                                        |
| `Config.RateLimit.timeSync`       | `{ window = 30, max = 1 }`  | As above.                                                                                                                                                                          |
| `Config.RateLimit.saveLayout`     | `{ window = 15, max = 3 }`  | As above.                                                                                                                                                                          |
| `Config.RateLimit.publishDefault` | `{ window = 10, max = 1 }`  | As above.                                                                                                                                                                          |
| `Config.RateLimit.clearDefault`   | `{ window = 10, max = 1 }`  | As above.                                                                                                                                                                          |
| `Config.AdminGroups`              | `{ 'admin', 'superadmin' }` | HUD admin groups. ESX: `xPlayer.getGroup()`; QBCore/Qbox: `HasPermission`; standalone (and fallback for all): ACE group `group.<name>`. `{}` = ACE only.                           |
| `Config.ServerDefault.locked`     | commented out (off)         | `true` = non-admin players cannot edit the HUD and always see the server layout.                                                                                                   |
| `Config.LogRejected`              | `true`                      | Log rejected events (validation, rate limit, permissions) to the console.                                                                                                          |

```lua
Config.ServerDefault = {
    locked = true,
}
```

## Locales

`locales/en.lua` and `locales/it.lua` contain the server messages and command descriptions. Keys starting with `ui.` override NUI texts, for example:

```lua
['ui.hud.widget.health'] = 'Health',
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
