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

# Installazione

## Requisiti

* Un server FiveM recente (artifact con `lua54`).
* Nessuna dipendenza obbligatoria. `oxmysql` serve **solo** con `Config.DbSync = true` (layout sincronizzato nel database).
* Opzionali, rilevati da soli: `esx_status` (fame/sete su ESX), `pma-voice` o `saltychat` (voce), `ox_fuel` / `LegacyFuel` / `cdn-fuel` (carburante).

## 1. Download

Lo script è distribuito tramite **Cfx.re Asset Escrow**. Dopo l'acquisto accedi a [portal.cfx.re](https://portal.cfx.re) con l'account Cfx.re usato per l'acquisto e apri **Granted Assets**. Da lì scarica `ghiaccio_hud`.

{% hint style="info" %}
Le risorse in escrow funzionano solo sui server la cui license key appartiene all'account Cfx.re che ha fatto l'acquisto.
{% endhint %}

## 2. Copia la risorsa

Copia `ghiaccio_hud` in `resources/`.

## 3. Ferma ogni altro HUD

Due HUD si sovrappongono e raddoppiano il costo. All'avvio la risorsa avvisa in console se `qb-hud`, `qbx_hud` o `esx_hud` sono avviati.

{% hint style="warning" %}
Se avvii una cartella di categoria (per esempio `ensure [qb]`), togliere la riga non basta: **sposta la cartella dell'altro HUD fuori da `resources/`**.
{% endhint %}

## 4. server.cfg

Avvia l'HUD **dopo** il framework (e dopo `oxmysql` se usi DbSync):

```cfg
ensure oxmysql            # solo con Config.DbSync = true
ensure es_extended        # oppure qb-core / qbx_core
ensure ghiaccio_hud
add_ace group.admin ghiaccio_hud.admin allow    # opzionale: chi puo' pubblicare il layout del server (oltre a Config.AdminGroups)
```

## 5. Framework

`Config.Framework = 'auto'` rileva il framework in quest'ordine: **Qbox (`qbx_core`), QBCore (`qb-core`), ESX (`es_extended`)**, altrimenti standalone. Qbox viene controllato per primo perché fornisce anche `qb-core`. Puoi forzarlo con `'esx'`, `'qbcore'`, `'qbox'` o `'standalone'`; se il framework forzato non esiste l'HUD passa a standalone con un avviso in console.

{% tabs %}
{% tab title="ESX" %}

* Rimuovi `esx_hud` e simili.
* Fame e sete arrivano da `esx_status`: **senza `esx_status` i widget fame/sete restano nascosti** (mai valori finti).
* Contanti/banca dagli account `money` / `bank`.
* Lo stress usa quello integrato (`Config.Stress`).
  {% endtab %}

{% tab title="QBCore" %}

* Rimuovi `ensure qb-hud`.
* Contanti, fame, sete e stress arrivano dai metadata del giocatore.
* `qb-smallresources` può restare: la sua cintura viene rilevata come cintura esterna.
  {% endtab %}

{% tab title="Qbox" %}

* Rimuovi `qbx_hud`.
* Stessa struttura di QBCore (dati da `qbx_core`).
  {% endtab %}

{% tab title="Standalone" %}

* Nessun framework: niente contanti e niente fame/sete (widget nascosti).
* Vita, armatura, stamina, ossigeno, arma, veicolo, bussola, orologio e minimappa funzionano.
* `Config.Framework = 'standalone'` lo forza.
  {% endtab %}
  {% endtabs %}

## 6. Avvia e controlla la console

Riavvia il server e leggi la console: stampa il framework scelto e gli adapter (carburante, status, voce, cintura). Poi apri l'editor in gioco con `/hud` (o **F7**).

## Opzionale: sincronizzazione database

Per far seguire a ogni giocatore il proprio layout su un altro PC, imposta `Config.DbSync = true` in `config_server.lua` e avvia `oxmysql` **prima** di `ghiaccio_hud`. La tabella del database viene migrata automaticamente.

## Escrow: cosa puoi modificare

Cifrati: `client/`, `server/`, `shared/`. In chiaro e modificabili: `config.lua`, `config_server.lua`, `bridge/`, `adapters/`, `locales/`, `data/`, `LICENSES/`.

## Cambiare il logo

Sostituisci `web/dist/logo.svg` con il tuo logo mantenendo il nome `logo.svg` (oppure usa un altro nome e aggiorna `Config.Logo`). Con `Config.Logo = ''` viene mostrato il testo di `Config.ServerName`.


---

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