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

# Risoluzione problemi e FAQ

{% hint style="info" %}
All'avvio l'HUD stampa nella console del server/F8 il framework e gli adapter scelti, più eventuali avvisi. Leggila per prima.
{% endhint %}

### HUD doppio / widget sovrapposti

Ferma `qb-hud` / `qbx_hud` / `esx_hud`. Se vengono avviati tramite una cartella di categoria (`ensure [qb]`), sposta la loro cartella fuori da `resources/`. La console avvisa: " è avviato: ferma l'altro HUD o i due si sovrapporranno".

### Fame e sete mancanti (ESX)

Serve `esx_status`. Senza una fonte i widget sono nascosti di proposito (mai valori finti). Puoi anche alimentarli da qualunque script con `exports.ghiaccio_hud:setStatus` (vedi [Integrazioni e adapter](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/hud/integrations.md)).

### La minimappa quadrata/circolare torna rettangolare

Non si sono caricati né `stream/ghud_*map.ytd` né i PNG in `assets/minimap/` (avviso in F8). Verifica che la risorsa sia completa (riscaricala da [portal.cfx.re](https://portal.cfx.re) > Granted Assets) e che nessun'altra risorsa sostituisca la stessa texture della minimappa.

### Bordo della minimappa disallineato

Regolalo con `Config.Minimap.calibration` (`dx`, `dy`, `scale` per forma). Controlla altre risorse che toccano `radarmasksm`.

### Il layout non segue il giocatore su un altro PC

Attiva `Config.DbSync = true` in `config_server.lua` (serve `oxmysql` avviato prima dell'HUD). Se la console dice "Config.DbSync = true ma oxmysql non è avviata", correggi l'ordine degli ensure.

### Orologio sbagliato

Controlla `Config.Timezone` (nome IANA, es. `Europe/Rome`). La console avvisa se il fuso non è tra quelli noti (l'offset di riserva diventa UTC). `Config.TimeSource = 'game'` mostra invece l'orologio di GTA.

### Non riesco a pubblicare il layout del server

Serve l'ACE `ghiaccio_hud.admin` o un gruppo in `Config.AdminGroups` (ESX: gruppo del giocatore; QBCore/Qbox: permesso; standalone: `add_principal identifier.license:... group.admin`, e se non basta `add_ace group.admin group.admin allow`).

### L'HUD non si può modificare ("L'HUD di questo server è bloccato")

`Config.ServerDefault.locked = true`: solo gli admin possono modificarlo.

### L'editor non si apre

Conflitto di tasti: usa `/hud`. Il personaggio potrebbe non essere ancora caricato. Controlla anche `Config.Editor.enabled`.

### "Config.Framework = '...' ma la risorsa non esiste: si usa standalone."

Il framework forzato non è installato o il nome è sbagliato. Usa `'auto'` o il valore corretto (`'esx'`, `'qbcore'`, `'qbox'`).

### "Troppe richieste, rallenta."

È stato raggiunto un rate limit di rete di `Config.RateLimit`. Attendi qualche secondo.

### I giocatori vengono sbalzati fuori dal veicolo dopo un incidente

È lo sbalzo della cintura integrata. Imposta `Config.Seatbelt.ejection = false` per disattivarlo, oppure alza `ejectKmh`.

### L'effetto incidente è troppo forte / non lo voglio

Regola `Config.CrashEffect` (per esempio `blackout = false`, `minSpeedLossKmh` più alto) oppure imposta `enabled = false`.

## Checklist di prova in gioco

1. `resmon 1`: a piedi a riposo <= 0.02 ms; controlla anche in veicolo.
2. Orologio nel formato `HH:mm - DD/MM/YY`, con `real` e `game`.
3. Sali/scendi da auto, moto, bicicletta, elicottero (altimetro), barca (nodi).
4. Minimappa rect/square/circle a 1080p, 1440p, 21:9; bordo allineato; visibilità sempre/veicolo/mai; pausa e ritorno.
5. HUD base di GTA nascosto (nome via, zona, veicolo, soldi, munizioni, barre vita/armatura); mirino e ruota armi ancora presenti.
6. Editor: trascina, ridimensiona, snap, selezione multipla, undo/redo, salva, riconnessione, export/import, preset.
7. Un admin pubblica il layout del server (attuale e da codice): i giocatori online lo ricevono subito e poi possono modificarlo; chi entra dopo lo riceve una volta; con `locked = true` un non admin non può aprire `/hud` né salvare.
8. ESX senza esx\_status: nessun errore; QBCore/Qbox: valori dai metadata; pma-voice: range, parlato, radio.
9. Cinematica, modalità streamer, car control (portiere, finestrini, motore, luci, sedili), cintura, cruise, limitatore.
10. `qb-hud` / `qbx_hud` fermati.


---

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