> 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/usage-guide.md).

# Guida all'uso

## Aprire l'editor

Premi **F7** o scrivi `/hud`. Al centro dello schermo si apre il **menu /hud a schede** con queste pagine:

| Pagina              | Cosa ci fai                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Sposta elementi** | Tela drag & drop a tutto schermo: sposta e ridimensiona i widget, griglia e guide magnetiche, selezione multipla.                  |
| **Icone di stato**  | Il gruppo delle icone di stato.                                                                                                    |
| **Veicolo**         | I widget e il gruppo di icone del veicolo.                                                                                         |
| **Minimappa**       | Forma (rettangolare / quadrata / circolare), posizione, dimensione, visibilità.                                                    |
| **Stile**           | Aspetto dell'HUD (forma, colori, gradiente, glow, soglie, auto-hide) e globali (tema, font, unità, lingua, palette per daltonici). |
| **Info e testo**    | Widget di informazioni e testo.                                                                                                    |
| **Preset**          | Preset pronti e preset personali.                                                                                                  |
| **Condividi**       | Export / import del codice di layout; sezione **Server** per gli admin.                                                            |

**Esc** torna indietro (sulla Home chiude). Tieni premuto **Spazio** per vedere l'HUD senza la finestra. **Ctrl+Z / Ctrl+Y** annullano e ripetono.

![Editor](https://3177857830-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhwAzH8Ldsma9DIjFIAp1%2Fuploads%2Fgit-blob-6c4bab3c40963ae56c15ade9c0e4748dfab24c59%2Fhud-editor.webp?alt=media)

## Profili e gruppi

* Profili separati **a piedi** e **in veicolo**.
* Le icone di stato e del veicolo sono **gruppi**: si trascinano come un unico blocco e le icone mancanti si richiudono senza buchi (stile di default: anelli).
* Il logo è un'immagine semplice; l'ID mostra solo il numero su una pillola semitrasparente; i gradi della bussola sono spenti di default.

## Salvataggio

Il layout si salva da solo (sul tuo PC come KVP, 1 secondo dopo l'ultima modifica). All'avvio il layout viene scelto con questa precedenza:

**KVP > DB (se `Config.DbSync`) > default del server > default di fabbrica**

Con `Config.DbSync = true` il tuo layout ti segue su un altro PC. I layout v1 vengono migrati automaticamente.

## Preset e condivisione

![Preset](https://3177857830-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhwAzH8Ldsma9DIjFIAp1%2Fuploads%2Fgit-blob-ee025aa4fe546148acaf8136cb7c74de7a3b6fc0%2Fhud-presets.webp?alt=media)

* 24 preset pronti più fino a **10 preset personali** (salvati come KVP).
* **Esporta** produce un codice `GHUD1.z....` da copiare.
* **Importa** incolla un codice. Viene controllato con CRC, non viene mai eseguito né inviato al server finché non salvi.

## Layout del server (admin)

Gli admin dell'HUD (vedi [Comandi, tasti e permessi](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/hud/commands-and-permissions.md)) vedono **/hud > Condividi > Server**:

* **Pubblica il layout attuale** come layout del server;
* incolla un codice `GHUD1.z....` e **Pubblica codice** (il tuo layout non cambia; il server rivalida dimensione e schema);
* **Rimuovi layout del server**.

Ogni pubblicazione ha una versione (timestamp, salvata in `data/server_default.json` + `.ts`). I giocatori che entrano, o sono online in quel momento, e non hanno ancora ricevuto quella versione la ricevono in automatico: sostituisce il loro layout **una volta**. Dopo possono modificarlo, e la loro modifica resta fino alla pubblicazione successiva (chi pubblica tiene il proprio). Con `DbSync` la versione ricevuta segue il giocatore su altri PC. Pubblicazioni e rimozioni sono nel log del server.

## Minimappa

* Forme: **rect** (vanilla), **square** (quadrata), **circle** (circolare). Posizione e dimensione vengono dal layout.
* Visibilità: sempre / solo in veicolo / mai.
* Le barre native di vita/armatura sono nascoste; la minimappa viene riapplicata dopo pausa e cambi di risoluzione o safe zone.
* Il bordo è disegnato dalla NUI sul rettangolo effettivo della minimappa.
* Quadrata e circolare usano le maschere incluse (`stream/ghud_squaremap.ytd`, `stream/ghud_circlemap.ytd`). Se un `.ytd` non si carica entro 5 secondi, viene usata la texture runtime costruita dai PNG in `assets/minimap/`. Se non si carica nessuna delle due, la forma torna a `rect` con un avviso unico in console. Non c'è nulla da produrre o rigenerare.
* Il radar espanso (tasto Z) è bloccato di default (`Config.Minimap.lockBigmap`).

{% hint style="warning" %}
La sostituzione della maschera della minimappa è globale: può andare in conflitto con altre risorse di minimappa personalizzata.
{% endhint %}

## Funzioni del veicolo

* **Cintura** (`/seatbelt`, **B**): con la cintura integrata il tasto di uscita (F) è bloccato quando è allacciata; senza cintura un urto forte sopra `ejectKmh` può sbalzarti fuori (se `ejection = true`). Sopra `seatbeltWarnKmh` compare un avviso se è slacciata.
* **Cruise control** (`/cruise`) e **limitatore di velocità** (`/limiter`).
* **Car control** (`/carcontrol`): portiere, finestrini, motore, luci, sedili.
* **Effetto incidente** dopo un incidente grave (vedi [Configurazione](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/hud/configuration.md)).

## Modalità

* **Modalità streamer** (opzione nell'editor): nasconde ID, contanti, banca, via.
* **Modalità cinematica** (`/cinematic`): bande nere, HUD nascosto.
* `/togglehud` mostra / nasconde l'HUD.

## Controllo prestazioni

Misura in gioco con `resmon 1`: obiettivo a piedi a riposo <= 0.02 ms, in veicolo <= 0.06 ms.


---

# 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/usage-guide.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.
