> 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/it/hud/configuration.md).

# Configurazione

| File                | Inviato ai client  | Usalo per                                                         |
| ------------------- | ------------------ | ----------------------------------------------------------------- |
| `config.lua`        | **Sì** (condiviso) | Comportamento e integrazioni. Mai segreti qui.                    |
| `config_server.lua` | No (solo server)   | Database, rate limit, gruppi admin, blocco del layout del server. |

{% hint style="info" %}
Il **layout visivo** (posizioni, colori, forme, font, forma della minimappa) **non** si configura in questi file: si fa in gioco con `/hud`, e un admin può pubblicarlo come default del server. Vedi [Guida all'uso](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/hud/usage-guide.md).
{% endhint %}

## Generale

| Opzione             | Default      | Significato                                                                   |
| ------------------- | ------------ | ----------------------------------------------------------------------------- |
| `Config.Locale`     | `'it'`       | Lingua di default, `'it'` o `'en'`. Ogni giocatore può cambiarla nell'editor. |
| `Config.Framework`  | `'auto'`     | `'auto'`, `'esx'`, `'qbcore'`, `'qbox'` o `'standalone'`.                     |
| `Config.Logo`       | `'logo.svg'` | File del logo (in alto a destra) in `web/dist/`. `''` = nessun logo.          |
| `Config.ServerName` | `'Ghiaccio'` | Testo di riserva se il logo manca.                                            |

## Orologio

Data e ora in alto al centro con formato fisso `HH:mm - DD/MM/YY` (es. `21:45 - 11/11/26`).

| Opzione                    | Default         | Significato                                                          |
| -------------------------- | --------------- | -------------------------------------------------------------------- |
| `Config.TimeSource`        | `'real'`        | `'real'` (ora reale del server) o `'game'` (orologio di GTA).        |
| `Config.Timezone`          | `'Europe/Rome'` | Fuso orario IANA per `'real'`. L'ora legale è calcolata dal server.  |
| `Config.TimeResyncMinutes` | `10`            | Ogni quanti minuti il client risincronizza l'orologio con il server. |

## Editor

| Opzione                 | Default | Significato                                                                     |
| ----------------------- | ------- | ------------------------------------------------------------------------------- |
| `Config.Editor.enabled` | `true`  | `false` = editor in gioco disattivato.                                          |
| `Config.Editor.command` | `'hud'` | Comando che apre l'editor.                                                      |
| `Config.Editor.key`     | `'F7'`  | Tasto di default. Ogni giocatore può cambiarlo in Impostazioni > Tasti > FiveM. |

## Comandi e tasti

`''` = nessun comando / nessun tasto di default.

| Opzione                         | Default        | Significato                                      |
| ------------------------------- | -------------- | ------------------------------------------------ |
| `Config.Commands.toggle`        | `'togglehud'`  | Mostra / nasconde l'HUD.                         |
| `Config.Commands.cinematic`     | `'cinematic'`  | Modalità cinematica (bande nere + HUD nascosto). |
| `Config.Commands.cinematicKey`  | `''`           | Tasto della modalità cinematica.                 |
| `Config.Commands.carControl`    | `'carcontrol'` | Pannello car control.                            |
| `Config.Commands.carControlKey` | `''`           | Tasto del pannello car control.                  |
| `Config.Commands.seatbelt`      | `'seatbelt'`   | Cintura integrata.                               |
| `Config.Commands.seatbeltKey`   | `'B'`          | Tasto della cintura.                             |
| `Config.Commands.cruise`        | `'cruise'`     | Cruise control integrato.                        |
| `Config.Commands.cruiseKey`     | `''`           | Tasto del cruise control.                        |
| `Config.Commands.limiter`       | `'limiter'`    | Limitatore di velocità integrato.                |
| `Config.Commands.limiterKey`    | `''`           | Tasto del limitatore.                            |

## Funzionalità

| Opzione                          | Default | Significato                                                                                                              |
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Config.Features.cinematic`      | `true`  | Modalità cinematica disponibile.                                                                                         |
| `Config.Features.streamerMode`   | `true`  | L'opzione modalità streamer compare nell'editor (nasconde ID, contanti, banca, via).                                     |
| `Config.Features.carControl`     | `true`  | Pannello car control disponibile.                                                                                        |
| `Config.Features.hideWhenPaused` | `true`  | Nasconde l'HUD con il menu di pausa aperto.                                                                              |
| `Config.Features.hideWhenDead`   | `false` | Nasconde l'HUD quando il giocatore è morto.                                                                              |
| `Config.Features.hideNativeHud`  | `true`  | Nasconde i componenti nativi sovrapposti (nome veicolo, zona, via, soldi). `false` ferma anche l'unico thread per frame. |

## Componenti dell'HUD nativo

| Opzione                       | Default                              | Significato                                                                                                                                                                                                                             |
| ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.HideNativeComponents` | `{ 1, 2, 3, 4, 6, 7, 8, 9, 13, 20 }` | Componenti dell'HUD nativo di GTA da nascondere: 1 stelle ricercato, 2 icona arma + munizioni, 3 contanti, 4 contanti MP, 6 nome veicolo, 7 nome area, 8 classe veicolo, 9 nome via, 13 variazione contanti, 20 statistiche ruota armi. |

{% hint style="info" %}
14 (mirino), 16 (stazioni radio), 19 (ruota armi), 21 e 22 **non** vengono mai nascosti, anche se elencati.
{% endhint %}

## Intervalli dei loop

| Opzione               | Default | Significato                                                          |
| --------------------- | ------- | -------------------------------------------------------------------- |
| `Config.Tick.onFoot`  | `300`   | ms. Vita, armatura, stamina, ossigeno, arma. 250-500 va bene.        |
| `Config.Tick.vehicle` | `100`   | ms. Velocità, giri, marcia (la NUI interpola). Gira solo in veicolo. |
| `Config.Tick.nav`     | `500`   | ms. Bussola, via, zona.                                              |
| `Config.Tick.slow`    | `2000`  | ms. Fallback fame/sete/stress, fallback soldi, giorno/notte.         |

## Veicolo

| Opzione                          | Default | Significato                                     |
| -------------------------------- | ------- | ----------------------------------------------- |
| `Config.Vehicle.seatbeltWarnKmh` | `20`    | Avviso cintura slacciata sopra questa velocità. |
| `Config.Vehicle.cruiseMinKmh`    | `20`    | Velocità minima del cruise control.             |
| `Config.Vehicle.limiterMinKmh`   | `20`    | Velocità minima del limitatore.                 |

## Integrazioni

`'auto'` rileva da solo; altrimenti il nome dell'adapter; `false` = disattivato. Vedi [Integrazioni e adapter](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/hud/integrations.md).

| Opzione                        | Default  | Valori                                                                                              |
| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------- |
| `Config.Integrations.fuel`     | `'auto'` | `'auto'`, `'ox_fuel'`, `'LegacyFuel'`, `'cdn-fuel'`, `'native'`                                     |
| `Config.Integrations.status`   | `'auto'` | `'auto'`, `'esx_status'`, `'qb'` (metadata QBCore/Qbox), `'exports'`, `false` (fame/sete nascoste)  |
| `Config.Integrations.voice`    | `'auto'` | `'auto'`, `'pma-voice'`, `'saltychat'`, `false`                                                     |
| `Config.Integrations.seatbelt` | `'auto'` | `'auto'` (script esterno noto se avviato, altrimenti integrata), `'builtin'`, `'external'`, `false` |

## Cintura integrata

Usata quando `Config.Integrations.seatbelt` risolve in `'builtin'`. Con uno script cintura esterno decide quello script.

| Opzione                     | Default | Significato                                                                                                                 |
| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Config.Seatbelt.ejection`  | `true`  | `false` = la cintura integrata **non** sbalza **mai** il giocatore fuori dal veicolo dopo un incidente, a nessuna velocità. |
| `Config.Seatbelt.ejectKmh`  | `70`    | Con `ejection = true`: sopra questa velocità, senza cintura, un urto forte sbalza fuori il giocatore (`0` = mai).           |
| `Config.Seatbelt.blockExit` | `true`  | Con la cintura allacciata il tasto di uscita (F) è disattivato.                                                             |

## Stress integrato

Usato solo quando il framework non ne fornisce uno (QBCore/Qbox tengono lo stress nei metadata del giocatore).

| Opzione                     | Default | Significato                                          |
| --------------------------- | ------- | ---------------------------------------------------- |
| `Config.Stress.enabled`     | `true`  | Stress integrato attivo/disattivo.                   |
| `Config.Stress.shooting`    | `1`     | Stress per ogni colpo sparato (armi non silenziate). |
| `Config.Stress.speedingKmh` | `160`   | Velocità oltre la quale la guida aggiunge stress.    |
| `Config.Stress.speeding`    | `1`     | Stress per slow tick mentre si va oltre la soglia.   |
| `Config.Stress.decay`       | `1`     | Diminuzione per slow tick quando si è calmi.         |
| `Config.Stress.effects`     | `true`  | Leggero tremolio della camera sopra 80.              |

## Effetto incidente

Dopo un incidente **grave** in veicolo (mai per piccoli urti): tremolio della camera, tinta/sfocatura che svaniscono, audio ovattato, breve blackout nei casi peggiori e camminata barcollante se scendi durante l'effetto. Se `Config.CrashEffect` manca valgono questi default; ogni chiave è opzionale.

| Opzione           | Default          | Significato                                                            |
| ----------------- | ---------------- | ---------------------------------------------------------------------- |
| `enabled`         | `true`           | `false` = effetto disattivato e nessun thread di rilevamento.          |
| `minSpeedLossKmh` | `60`             | Perdita di velocità improvvisa che conta come incidente grave.         |
| `cooldownSeconds` | `20`             | Pausa minima tra due effetti.                                          |
| `blackout`        | `true`           | Breve schermo nero nei casi peggiori (mai con la cintura allacciata).  |
| `staggerOnFoot`   | `true`           | Camminata barcollante per qualche secondo se scendi durante l'effetto. |
| `seatbeltReduces` | `true`           | Con la cintura allacciata intensità e durata sono ridotte.             |
| `sound`           | `true`           | Audio ovattato durante l'effetto.                                      |
| `excludedClasses` | `{ 14, 15, 16 }` | Classi di veicolo escluse (14 barche, 15 elicotteri, 16 aerei).        |

Il rilevamento usa una finestra mobile di circa 250 ms e ignora frenate, salti/atterraggi, teletrasporti e i primi secondi dopo essere saliti. Il thread esiste solo dentro un veicolo. L'effetto si interrompe e si ripulisce da solo in caso di morte, editor, modalità cinematica o stop della risorsa.

## Minimappa

Forma e posizione si scelgono nell'editor.

| Opzione                      | Default | Significato                                                                                                                                            |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Config.Minimap.enabled`     | `true`  | `false` = la risorsa non tocca mai la minimappa.                                                                                                       |
| `Config.Minimap.masks`       | `'ytd'` | `'ytd'` (`stream/ghud_*map.ytd` inclusi, poi runtime) o `'runtime'` (PNG in `assets/minimap/`, poi ytd). Ognuno ricade sull'altro.                     |
| `Config.Minimap.lockBigmap`  | `true`  | Blocca il radar espanso (tasto Z), che romperebbe la geometria personalizzata.                                                                         |
| `Config.Minimap.calibration` | `{}`    | Regolazione fine per forma: `dx`/`dy` = spostamento in frazioni di schermo (x verso destra, y verso il basso), `scale` = moltiplicatore di dimensione. |

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

## config\_server.lua

| Opzione                           | Default                     | Significato                                                                                                                                                                          |
| --------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Config.DbSync`                   | `false`                     | `false`: i layout restano solo come KVP sul PC del giocatore. `true`: il layout segue il giocatore (license Rockstar) su un altro PC; richiede `oxmysql` avviato **prima** dell'HUD. |
| `Config.RateLimit.requestInit`    | `{ window = 10, max = 1 }`  | Rate limit di rete (finestra in secondi, massimo eventi per finestra). Oltre, l'evento viene ignorato e registrato.                                                                  |
| `Config.RateLimit.timeSync`       | `{ window = 30, max = 1 }`  | Come sopra.                                                                                                                                                                          |
| `Config.RateLimit.saveLayout`     | `{ window = 15, max = 3 }`  | Come sopra.                                                                                                                                                                          |
| `Config.RateLimit.publishDefault` | `{ window = 10, max = 1 }`  | Come sopra.                                                                                                                                                                          |
| `Config.RateLimit.clearDefault`   | `{ window = 10, max = 1 }`  | Come sopra.                                                                                                                                                                          |
| `Config.AdminGroups`              | `{ 'admin', 'superadmin' }` | Gruppi admin dell'HUD. ESX: `xPlayer.getGroup()`; QBCore/Qbox: `HasPermission`; standalone (e fallback per tutti): gruppo ACE `group.<nome>`. `{}` = solo ACE.                       |
| `Config.ServerDefault.locked`     | commentato (spento)         | `true` = i giocatori non admin non possono modificare l'HUD e vedono sempre il layout del server.                                                                                    |
| `Config.LogRejected`              | `true`                      | Registra in console gli eventi rifiutati (validazione, rate limit, permessi).                                                                                                        |

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

## Lingue

`locales/it.lua` e `locales/en.lua` contengono i messaggi del server e le descrizioni dei comandi. Le chiavi che iniziano con `ui.` sovrascrivono i testi della NUI, per esempio:

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


---

# 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/it/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.
