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

# Installazione

## Requisiti

* Un server FiveM recente (artifact con `lua54`).
* **`pma-voice`** (obbligatorio). Non viene mai modificato: si usano solo i suoi export ed eventi. Verificato su pma-voice 7.x (7.0.1).
* La risorsa companion **`ghiaccio_radio_props`**, avviata **prima** di `ghiaccio_radio`.
* Opzionali, rilevati da soli: `oxmysql` (altrimenti impostazioni, preferiti e animazione scelta vanno nei KVP del server) e `ox_inventory` / `qb-inventory` / `qs-inventory` / inventario ESX (item radio).
* Node 20+ solo per modificare la NUI (vedi `web/`). La NUI compilata è già in `web/dist/`.

## 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_radio` e `ghiaccio_radio_props`.

{% 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 le risorse

Copia `ghiaccio_radio` e `ghiaccio_radio_props` in `resources/`.

## 3. server.cfg

Avvia la radio **dopo** `pma-voice`, il framework e `oxmysql`, e `ghiaccio_radio_props` **prima** di `ghiaccio_radio`:

```cfg
ensure pma-voice
setr voice_enableRadioAnim 0        # OBBLIGATORIO: le animazioni radio le gestisce ghiaccio_radio
ensure oxmysql                      # opzionale
ensure es_extended                  # oppure qb-core / qbx_core
ensure ghiaccio_radio_props         # PRIMA di ghiaccio_radio (prop radio)
ensure ghiaccio_radio
```

{% hint style="danger" %}
**`setr voice_enableRadioAnim 0` è obbligatorio.** Impostalo prima di `ensure pma-voice` / prima dell'avvio del server. Senza, pma-voice riproduce la sua animazione sopra la nostra (la console lo segnala).
{% endhint %}

Con `Config.MuteNativeClicks = true` (default) i click del microfono di pma-voice sono silenziati: la NUI della radio riproduce i suoi suoni.

## 4. Crea l'item `radio`

L'item radio è richiesto di default (`Config.RequireItem = true`). Usa lo snippet del tuo inventario, oppure imposta `Config.RequireItem = false`.

{% tabs %}
{% tab title="ox\_inventory" %}
In `ox_inventory/data/items.lua` (anche per Qbox):

```lua
['radio'] = {
    label = 'Radio',
    weight = 500,
    stack = false,
    close = true,
    description = 'Un walkie-talkie.',
    client = { event = 'ghiaccio_radio:client:use' },   -- usare l'item apre la radio
},
```

{% endtab %}

{% tab title="qb-inventory" %}
In `qb-core/shared/items.lua` (qb-inventory, ps-inventory, lj-inventory):

```lua
radio = { name = 'radio', label = 'Radio', weight = 500, type = 'item', image = 'radio.png', unique = true, useable = true, shouldClose = true, description = 'Un walkie-talkie.' },
```

L'uso viene registrato dalla risorsa con `CreateUseableItem` quando `Config.UsableItem = true`.
{% endtab %}

{% tab title="qs-inventory" %}
In `qs-inventory/shared/items.lua`:

```lua
['radio'] = { name = 'radio', label = 'Radio', weight = 500, type = 'item', image = 'radio.png', unique = true, useable = true, shouldClose = true, description = 'Un walkie-talkie.' },
```

{% hint style="warning" %}
Non testato: `qs-inventory` non era disponibile nell'ambiente di test. I nomi degli export `GetItemTotalAmount` / `GetItemByName` sono presi dalla sua documentazione.
{% endhint %}
{% endtab %}

{% tab title="Inventario ESX" %}
Esegui sulla tabella `items`:

```sql
INSERT INTO `items` (`name`, `label`, `weight`) VALUES ('radio', 'Radio', 1);
-- versioni con colonna `limit`:  (`name`, `label`, `limit`) VALUES ('radio', 'Radio', 1);
```

L'uso viene registrato con `ESX.RegisterUsableItem`.
{% endtab %}
{% endtabs %}

Nome item diverso: `Config.Item`. Inventario forzato: `Config.Inventory = 'ox' | 'qb' | 'qs' | 'esx' | 'none'`. Senza inventario (standalone) il requisito viene ignorato con un avviso in console.

Il **server** controlla l'item all'apertura, all'accensione, a ogni connessione e ogni `Config.ItemCheckSeconds` secondi (default 5): se il giocatore lo perde, la radio si spegne e la finestra si chiude.

## 5. Avvia e controlla la console

Riavvia il server e leggi la console: stampa il framework, l'inventario e il salvataggio scelti. Poi apri la radio in gioco con `/radio` (o **F5**).

## Database

Nessun SQL da eseguire a mano. Con `oxmysql` avviato, le tabelle `ghiaccio_radio_players` e `ghiaccio_radio_migrations` vengono create dalle migrazioni. Senza `oxmysql` i dati vanno nei KVP del server (`Config.Database = 'auto'`). `ghiaccio_radio_anims` resta solo per le installazioni che già l'avevano e non è più usata.

## Escrow: cosa puoi modificare

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


---

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