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

# Configurazione

| File                | Inviato ai client  | Usalo per                                                                              |
| ------------------- | ------------------ | -------------------------------------------------------------------------------------- |
| `config.lua`        | **Sì** (condiviso) | Comportamento, funzioni, segnale, animazioni, rilevamento morte. Mai inserire segreti. |
| `config_server.lua` | No (solo server)   | Salvataggio, canali lavoro, lista membri, rate limit.                                  |

## Generale (config.lua)

| Opzione                   | Default                                      | Significato                                                                                                |
| ------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Config.Locale`           | `'it'`                                       | Lingua predefinita, `'it'` o `'en'`. I giocatori possono cambiarla nelle impostazioni della radio.         |
| `Config.Framework`        | `'auto'`                                     | `'auto'` (Qbox, QBCore, ESX, standalone) oppure forzato: `'esx'`, `'qbcore'`, `'qbox'`, `'standalone'`.    |
| `Config.Voice`            | `'pma-voice'`                                | Adapter voce (`adapters/voice/`). Incluso solo `'pma-voice'`.                                              |
| `Config.MuteNativeClicks` | `true`                                       | Silenzia i click del microfono di pma-voice (la NUI riproduce i suoi).                                     |
| `Config.Debug`            | `false`                                      | `true` stampa lo stato delle animazioni (TaskPlayAnim, riapplicata, dizionario mancante) nella console F8. |
| `Config.Frequency`        | `min = 1.00`, `max = 999.99`, `decimals = 2` | Intervallo delle frequenze digitabili e decimali (0..3).                                                   |

## Item radio

| Opzione              | Default   | Significato                                                                                                                                         |
| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.RequireItem` | `true`    | Il giocatore deve avere l'item per aprire la radio e restare connesso (controllato dal server).                                                     |
| `Config.Item`        | `'radio'` | Nome dell'item.                                                                                                                                     |
| `Config.Inventory`   | `'auto'`  | `'auto'`, `'ox'`, `'qb'`, `'qs'`, `'esx'` o `'none'`.                                                                                               |
| `Config.UsableItem`  | `true`    | Usare l'item apre la radio (ox\_inventory: vedi [Installazione](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/radio/installation.md)). |

## Comandi e funzioni

| Opzione                    | Default                                                                    | Significato                                                                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Commands`          | `open = 'radio'`, `openKey = 'F5'`, `anim = 'radioanim'`, `animKey = 'F4'` | `''` = nessun comando / nessun tasto predefinito.                                                                                                                                        |
| `Config.Features`          | tutte `true`                                                               | `memberList`, `clickSounds`, `favorites`, `signal`, `volume`, `scale`, `animations`, `jobChannels`. `false` disattiva la funzione per tutti (nascosta nella NUI e rifiutata dal server). |
| `Config.HideMembersPublic` | `false`                                                                    | `true` nasconde la lista membri sui canali pubblici (non lavoro) nella NUI. Il server la impone anche con `Config.Members.showOnPublic`.                                                 |
| `Config.Favorites.slots`   | `8`                                                                        | Numero di slot di memoria.                                                                                                                                                               |
| `Config.Volume.default`    | `60`                                                                       | Volume iniziale (0..100) di un nuovo giocatore.                                                                                                                                          |

Gli extra (membri, suoni, preferiti, segnale, volume, dimensione) possono essere disattivati da te con `Config.Features` **e** da ogni giocatore nelle impostazioni della radio (salvato per giocatore).

## Input della UI e push-to-talk

| Opzione                        | Default | Significato                                                                                                                                                                                                        |
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Config.UI.keepInputWhileOpen` | `true`  | Il gioco mantiene la tastiera con la UI aperta (`SetNuiFocusKeepInput`): il PTT di pma-voice funziona e l'animazione parte con la UI aperta. Mentre un campo di testo ha il focus tutti i controlli sono bloccati. |
| `Config.UI.txIndicator`        | `true`  | Piccolo segno TX a schermo mentre trasmetti con la UI chiusa.                                                                                                                                                      |
| `Config.UI.blockMovement`      | `false` | `true` = il giocatore non può camminare con la UI aperta.                                                                                                                                                          |
| `Config.Ptt.cooldown`          | `750`   | Anti-spam in ms: una pressione prima di questo tempo dal rilascio della trasmissione precedente viene rifiutata. `0` = disattivato.                                                                                |
| `Config.Ptt.notifyBusy`        | `false` | `true` mostra una piccola notifica "radio occupata" quando una pressione viene rifiutata.                                                                                                                          |

{% hint style="warning" %}
Se il tuo pma-voice ha già un suo `radioDelay` (`client/module/radio.lua`), i due cooldown si sommano. Imposta uno dei due a `0`, per esempio tieni `radioDelay` e metti `Config.Ptt.cooldown = 0`.
{% endhint %}

## Branding

Logo, testo ed etichetta del modello incisi sul corpo della radio.

| Opzione                    | Default      | Significato                                                        |
| -------------------------- | ------------ | ------------------------------------------------------------------ |
| `Config.Branding.showLogo` | `true`       | `false` nasconde il logo.                                          |
| `Config.Branding.logo`     | `'logo.svg'` | Un file in `web/dist`, un percorso `nui://` o un URL https.        |
| `Config.Branding.logoTint` | `true`       | `true` = aspetto inciso monocromatico, `false` = colori originali. |
| `Config.Branding.text`     | `'GHIACCIO'` | Testo del marchio (`''` = nascosto).                               |
| `Config.Branding.model`    | `'GX-9'`     | Etichetta del modello (`''` = nascosta).                           |

Per sostituire il logo copia il tuo PNG/SVG (meglio quadrato con sfondo trasparente) in `web/dist/` (oppure `web/public/` prima di `npm run build`) e imposta `logo = 'mio.png'`.

## Segnale

`Config.Signal` in `config.lua`. Vedi la [Guida all'uso](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/radio/usage-guide.md) per il comportamento del segnale.

| Opzione              | Default  | Significato                                                                                                     |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `interval`           | `700`    | Ms tra due valutazioni (solo da connessi o con UI aperta).                                                      |
| `staticBelow`        | `2`      | Barre sotto questo valore: statico e avviso.                                                                    |
| `minTransmit`        | `1`      | Barre necessarie per trasmettere.                                                                               |
| `blockTransmit`      | `true`   | `false` = con poco segnale compare solo l'avviso.                                                               |
| `interiorPenalty`    | `0.35`   | Sottratto al rapporto di segnale (0..1) dentro un interno.                                                      |
| `undergroundPenalty` | `0.5`    | Sottratto sotto `undergroundZ`.                                                                                 |
| `undergroundZ`       | `-5.0`   | Z sotto la quale il giocatore è considerato sottoterra.                                                         |
| `towers`             | 6 esempi | `{ name, coords, radius }`: segnale 1.0 alla torre, 0 a `radius` metri (distanza 2D). Sostituiscile con le tue. |
| `deadZones`          | vuoto    | `{ name, coords, radius, penalty }`: penalità extra dentro il cerchio (`1.0` = nessun segnale).                 |

## Pulsante di emergenza (SOS)

`Config.Emergency` in `config.lua`.

| Chiave            | Default                                 | Significato                                                                        |
| ----------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| `enabled`         | `true`                                  | `false` = pulsante nascosto e richiesta rifiutata dal server.                      |
| `cooldown`        | `60`                                    | Secondi tra due SOS dello stesso giocatore (oltre a `Config.RateLimit.emergency`). |
| `jobChannelsOnly` | `true`                                  | `true` = solo su un canale lavoro; `false` = su qualsiasi frequenza.               |
| `alertOnDutyJob`  | `false`                                 | `true` = avvisa anche ogni giocatore in servizio con il lavoro di chi invia.       |
| `log`             | `true`                                  | Log nella console del server.                                                      |
| `blip`            | vedi file                               | `enabled`, `sprite`, `colour`, `scale`, `seconds`, `flash`, `route`.               |
| `sound`           | `TIMER_STOP` / `HUD_MINI_GAME_SOUNDSET` | `name` e `set` di `PlaySoundFrontend`.                                             |

## Nominativo

`Config.Callsign` in `config.lua`.

| Chiave      | Default       | Significato                                                                |
| ----------- | ------------- | -------------------------------------------------------------------------- |
| `enabled`   | `true`        | Abilita i nominativi.                                                      |
| `maxLength` | `8`           | 1..16.                                                                     |
| `pattern`   | `'^[%w%-]+$'` | Pattern Lua che l'intero nominativo deve rispettare (lettere, cifre, `-`). |
| `uppercase` | `true`        | Salvato in maiuscolo.                                                      |
| `display`   | `'both'`      | Lista membri: `'callsign'`, `'name'` o `'both'` (`[A-12] Nome`).           |

## Rilevamento morte

`Config.Death` decide quando il giocatore è considerato morto (nessuna trasmissione, la UI si chiude, la radio resta connessa). Per le modalità vedi [Integrazioni](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/radio/integrations.md#morte-e-script-ambulanza).

| Chiave            | Default                                      | Significato                                                     |
| ----------------- | -------------------------------------------- | --------------------------------------------------------------- |
| `mode`            | `'auto'`                                     | `'auto'`, `'export'`, `'event'`, `'statebag'`, `'native'`.      |
| `export`          | `{ resource = '', name = '' }`               | Per la modalità `'export'`.                                     |
| `events`          | `{ death = {}, revive = {} }`                | Eventi client per la modalità `'event'` (aggiunti in `'auto'`). |
| `statebag`        | `{ 'isDead', 'dead' }`                       | Chiavi di `LocalPlayer.state`.                                  |
| `blockWhenCuffed` | `true`                                       | Anche un giocatore ammanettato non può trasmettere.             |
| `cuffedStatebag`  | `{ 'isHandcuffed', 'handcuffed', 'cuffed' }` | Chiavi state bag per ammanettato.                               |

## Prop radio e animazioni

| Opzione                                     | Default                | Significato                                                                                                               |
| ------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Config.PropModel`                          | `'ghiaccio_radio_b'`   | Modello della radio in mano (prop personalizzato di `ghiaccio_radio_props`). Alternativa: `'ghiaccio_radio_a'`.           |
| `Config.PropFallbackModel`                  | `'prop_cs_hand_radio'` | Usato in automatico, con un avviso in console, se il modello non viene trovato.                                           |
| `Config.PropModelOffsets`                   | per modello            | Correzione sopra l'offset del preset (`pos`, `rot`) per ogni modello personalizzato.                                      |
| `Config.Prop.enabled`                       | `true`                 | Prop radio in mano.                                                                                                       |
| `Config.Prop.networked`                     | `true`                 | Gli altri giocatori vedono il prop.                                                                                       |
| `Config.Prop.whileUI`                       | `true`                 | Radio in mano (e animazione) con la finestra aperta.                                                                      |
| `Config.Anim.enabled`                       | `true`                 | Animazioni radio.                                                                                                         |
| `Config.Anim.inVehicle`                     | `true`                 | `false` = mai animare dentro i veicoli.                                                                                   |
| `Config.Anim.blockFiring`                   | `true`                 | Niente sparo / corpo a corpo mentre trasmetti.                                                                            |
| `Config.Anim.blockJump`                     | `false`                | Niente salto mentre trasmetti.                                                                                            |
| `Config.Anim.withWeapon`                    | `true`                 | Animazione di conversazione anche con un'arma in mano (i preset con mano destra passano a `default`).                     |
| `Config.Anim.whileAiming`                   | `true`                 | Animazione di conversazione anche mentre mira. `false` = in pausa mentre mira.                                            |
| `Config.Anim.previewOnSelect` / `previewMs` | `false` / `2500`       | Riproduce l'animazione per un momento alla conferma con "Usa".                                                            |
| `Config.Anim.default`                       | `'default'`            | Preset usato se il giocatore non ha mai scelto.                                                                           |
| `Config.HoldAnim`                           | attiva                 | Animazione di attesa "radio in mano" con la UI aperta (`dict`, `anim`, `flag`, `blendIn`, `blendOut`, `vehicle`, `prop`). |

### Preset di animazione

`Config.AnimPresets` elenca le animazioni di conversazione che i giocatori scelgono in `/radioanim`: Default, Default fast, Shoulder slow, Shoulder fast, Police, Ear 1, Ear 2, Ear 3. I preset vengono validati all'avvio: uno non valido viene saltato con un avviso che indica preset e campo. Per aggiungerne uno, aggiungi una voce:

```lua
{ id = 'my_anim', label = 'preset.my_anim', dict = 'random@arrests', anim = 'generic_radio_chatter',
  flag = 50, blendIn = 8.0, blendOut = 2.5, vehicle = true,
  prop = { bone = 60309, pos = { 0.06, 0.05, 0.04 }, rot = { -90.0, 30.0, 0.0 } } }
```

| Campo                 | Significato                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | Obbligatorio, unico, lettere / cifre / `_` / `-` (max 40). Non cambiarlo una volta in produzione.                                       |
| `label`               | Obbligatorio, una chiave locale `preset.<id>` o testo semplice (max 32).                                                                |
| `dict`, `anim`        | Obbligatori, dizionario e clip di animazione (max 64 ciascuno).                                                                         |
| `flag`                | Obbligatorio. Si sommano: 1 loop, 2 resta sull'ultimo frame, 16 solo parte superiore, 32 controllabile. `50` = 2+16+32, `49` = 1+16+32. |
| `blendIn`, `blendOut` | Obbligatori, -16..16. Negativo = istantaneo.                                                                                            |
| `vehicle`             | Opzionale, default `false`. `true` = parte anche da seduti in un veicolo.                                                               |
| `prop`                | Opzionale: `bone` (ID osso del ped), `pos` `{x,y,z}` (max +-5 m), `rot` `{x,y,z}` (max +-360), `model` (default `Config.PropModel`).    |

{% hint style="warning" %}
Il prop va sulla mano che la clip **muove**. Le clip `random@arrests` alzano la mano SINISTRA alla spalla: osso `60309`. Le clip stile telefono (`cellphone@...`, Ear, Police) muovono la mano DESTRA: osso `28422`. Una radio sulla mano ferma sembra "prop in mano, nessuna animazione".
{% endhint %}

## config\_server.lua

| Opzione                       | Default       | Significato                                                                                                                                                                                                          |
| ----------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Database`             | `'auto'`      | `'auto'` (oxmysql se avviato, altrimenti KVP), `true` (solo oxmysql), `false` (solo KVP).                                                                                                                            |
| `Config.ChannelOffset`        | `0`           | Offset aggiunto al canale intero di pma-voice (`channel = frequency * 10^decimals + offset`). Alzalo se altri script usano canali numerici piccoli di pma-voice.                                                     |
| `Config.JobChannels`          | vuoto         | Canali privati per lavoro, vedi [Integrazioni](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/it/radio/integrations.md#canali-lavoro-e-grado).                                                              |
| `Config.JobRequireOnDuty`     | `false`       | QBCore/Qbox: il giocatore deve essere in servizio (per canale con `onDuty`).                                                                                                                                         |
| `Config.JobRecheckSeconds`    | `30`          | Rilettura periodica di lavoro e grado.                                                                                                                                                                               |
| `Config.MaxChannelsPerRule`   | `5000`        | Limite di sicurezza dei canali protetti per una regola `range`.                                                                                                                                                      |
| `Config.ItemCheckSeconds`     | `5`           | Ogni quanto il server controlla che il giocatore abbia ancora l'item.                                                                                                                                                |
| `Config.Members.showOnPublic` | `true`        | `false` = i membri vengono inviati solo sui canali lavoro.                                                                                                                                                           |
| `Config.Members.nameSource`   | `'rp'`        | `'rp'` (nome del personaggio), `'steam'` (nome FiveM) o `'id'` (ID server).                                                                                                                                          |
| `Config.Members.showCallsign` | `true`        | QBCore/Qbox: si usa `metadata.callsign` se il giocatore non ne ha impostato uno.                                                                                                                                     |
| `Config.Members.max`          | `64`          | Massimo di membri inviati.                                                                                                                                                                                           |
| `Config.RateLimit`            | per richiesta | `{ window = secondi, max = eventi }` per `init`, `open`, `power`, `connect`, `disconnect`, `joinJobChannel`, `saveSettings`, `saveFavorite`, `deleteFavorite`, `selectAnim`, `getAnims`, `emergency`, `setCallsign`. |
| `Config.LogRejected`          | `true`        | Registra le richieste rifiutate (validazione, rate limit, permessi).                                                                                                                                                 |

## Frequenze e canali pma-voice

pma-voice accetta un numero come canale e la radio non invia mai decimali: `channel = frequency * 10^decimals + Config.ChannelOffset` (per esempio `101.50` con 2 decimali diventa il canale `10150`). I giocatori non lo vedono mai.

## Sistemi voce

La logica passa da una piccola interfaccia: `adapters/voice/pmavoice.lua` (client: volume, parlato, PTT) e `adapters/voice/pmavoice_server.lua` (server: canale, membri, controlli di accesso). Per supportare un altro sistema voce implementa le stesse funzioni (documentate in cima ai file) e cambia `Config.Voice`.


---

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