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

# Configuration

| File                | Sent to clients  | Use it for                                                                       |
| ------------------- | ---------------- | -------------------------------------------------------------------------------- |
| `config.lua`        | **Yes** (shared) | Behavior, features, signal, animations, death detection. Never put secrets here. |
| `config_server.lua` | No (server only) | Storage, job channels, member list, rate limits.                                 |

## General (config.lua)

| Option                    | Default                                      | Meaning                                                                                             |
| ------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `Config.Locale`           | `'it'`                                       | Default language, `'it'` or `'en'`. Players can change it in the radio settings.                    |
| `Config.Framework`        | `'auto'`                                     | `'auto'` (Qbox, QBCore, ESX, standalone) or forced: `'esx'`, `'qbcore'`, `'qbox'`, `'standalone'`.  |
| `Config.Voice`            | `'pma-voice'`                                | Voice adapter (`adapters/voice/`). Only `'pma-voice'` is bundled.                                   |
| `Config.MuteNativeClicks` | `true`                                       | Mutes the pma-voice microphone clicks (the NUI plays its own).                                      |
| `Config.Debug`            | `false`                                      | `true` prints the animation state (TaskPlayAnim, re-applied, missing dictionary) in the F8 console. |
| `Config.Frequency`        | `min = 1.00`, `max = 999.99`, `decimals = 2` | Range of typable frequencies and decimals (0..3).                                                   |

## Radio item

| Option               | Default   | Meaning                                                                                                                                            |
| -------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.RequireItem` | `true`    | The player needs the item to open the radio and stay connected (checked by the server).                                                            |
| `Config.Item`        | `'radio'` | Item name.                                                                                                                                         |
| `Config.Inventory`   | `'auto'`  | `'auto'`, `'ox'`, `'qb'`, `'qs'`, `'esx'` or `'none'`.                                                                                             |
| `Config.UsableItem`  | `true`    | Using the item opens the radio (ox\_inventory: see [Installation](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/installation.md)). |

## Commands and features

| Option                     | Default                                                                    | Meaning                                                                                                                                                                                       |
| -------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Commands`          | `open = 'radio'`, `openKey = 'F5'`, `anim = 'radioanim'`, `animKey = 'F4'` | `''` = no command / no default key.                                                                                                                                                           |
| `Config.Features`          | all `true`                                                                 | `memberList`, `clickSounds`, `favorites`, `signal`, `volume`, `scale`, `animations`, `jobChannels`. `false` disables the feature for everybody (hidden in the NUI and refused by the server). |
| `Config.HideMembersPublic` | `false`                                                                    | `true` hides the member list on public (non-job) channels in the NUI. The server also enforces it with `Config.Members.showOnPublic`.                                                         |
| `Config.Favorites.slots`   | `8`                                                                        | Number of memory slots.                                                                                                                                                                       |
| `Config.Volume.default`    | `60`                                                                       | Initial volume (0..100) of a new player.                                                                                                                                                      |

The extras (members, sounds, favorites, signal, volume, size) can be switched off by you with `Config.Features` **and** by each player in the radio settings (saved per player).

## UI input and push-to-talk

| Option                         | Default | Meaning                                                                                                                                                                                                  |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.UI.keepInputWhileOpen` | `true`  | The game keeps the keyboard while the UI is open (`SetNuiFocusKeepInput`): pma-voice PTT works and the talk animation plays with the UI open. While a text field has the focus all controls are blocked. |
| `Config.UI.txIndicator`        | `true`  | Small TX mark on screen while transmitting with the UI closed.                                                                                                                                           |
| `Config.UI.blockMovement`      | `false` | `true` = the player cannot walk while the UI is open.                                                                                                                                                    |
| `Config.Ptt.cooldown`          | `750`   | Anti-spam in ms: a press less than this after the previous transmission was released is refused. `0` = off.                                                                                              |
| `Config.Ptt.notifyBusy`        | `false` | `true` shows a small "radio busy" notification when a press is refused.                                                                                                                                  |

{% hint style="warning" %}
If your pma-voice already has its own `radioDelay` (`client/module/radio.lua`), the two cooldowns stack. Set one of them to `0`, for example keep `radioDelay` and set `Config.Ptt.cooldown = 0`.
{% endhint %}

## Branding

The logo, text and model label engraved on the radio body.

| Option                     | Default      | Meaning                                                       |
| -------------------------- | ------------ | ------------------------------------------------------------- |
| `Config.Branding.showLogo` | `true`       | `false` hides the logo.                                       |
| `Config.Branding.logo`     | `'logo.svg'` | A file in `web/dist`, a `nui://` path or an https URL.        |
| `Config.Branding.logoTint` | `true`       | `true` = monochrome engraved look, `false` = original colors. |
| `Config.Branding.text`     | `'GHIACCIO'` | Brand text (`''` = hidden).                                   |
| `Config.Branding.model`    | `'GX-9'`     | Model label (`''` = hidden).                                  |

To replace the logo, copy your PNG/SVG (square, transparent background works best) into `web/dist/` (or `web/public/` before `npm run build`) and set `logo = 'mine.png'`.

## Signal

`Config.Signal` in `config.lua`. See [Usage guide](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/usage-guide.md) for how the signal behaves.

| Option               | Default    | Meaning                                                                                                           |
| -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `interval`           | `700`      | Ms between two evaluations (only while connected or UI open).                                                     |
| `staticBelow`        | `2`        | Bars below this: static and warning.                                                                              |
| `minTransmit`        | `1`        | Bars needed to transmit.                                                                                          |
| `blockTransmit`      | `true`     | `false` = low signal only shows the warning.                                                                      |
| `interiorPenalty`    | `0.35`     | Subtracted from the signal ratio (0..1) inside an interior.                                                       |
| `undergroundPenalty` | `0.5`      | Subtracted below `undergroundZ`.                                                                                  |
| `undergroundZ`       | `-5.0`     | Z below which the player counts as underground.                                                                   |
| `towers`             | 6 examples | `{ name, coords, radius }`: signal 1.0 at the tower, 0 at `radius` meters (2D distance). Replace them with yours. |
| `deadZones`          | empty      | `{ name, coords, radius, penalty }`: extra penalty inside the circle (`1.0` = no signal).                         |

## Emergency button (SOS)

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

| Key               | Default                                 | Meaning                                                                         |
| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
| `enabled`         | `true`                                  | `false` = button hidden and request refused by the server.                      |
| `cooldown`        | `60`                                    | Seconds between two SOS of the same player (plus `Config.RateLimit.emergency`). |
| `jobChannelsOnly` | `true`                                  | `true` = only on a job channel; `false` = on any frequency.                     |
| `alertOnDutyJob`  | `false`                                 | `true` = also alerts every on-duty player with the sender's job.                |
| `log`             | `true`                                  | Server console log.                                                             |
| `blip`            | see file                                | `enabled`, `sprite`, `colour`, `scale`, `seconds`, `flash`, `route`.            |
| `sound`           | `TIMER_STOP` / `HUD_MINI_GAME_SOUNDSET` | `PlaySoundFrontend` `name` and `set`.                                           |

## Callsign

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

| Key         | Default       | Meaning                                                           |
| ----------- | ------------- | ----------------------------------------------------------------- |
| `enabled`   | `true`        | Enables callsigns.                                                |
| `maxLength` | `8`           | 1..16.                                                            |
| `pattern`   | `'^[%w%-]+$'` | Lua pattern the whole callsign must match (letters, digits, `-`). |
| `uppercase` | `true`        | Stored in upper case.                                             |
| `display`   | `'both'`      | Member list: `'callsign'`, `'name'` or `'both'` (`[A-12] Name`).  |

## Death detection

`Config.Death` decides when the player counts as dead (no transmission, UI closes, the radio stays connected). See [Integrations](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/integrations.md#death-and-ambulance-scripts) for the modes.

| Key               | Default                                      | Meaning                                                    |
| ----------------- | -------------------------------------------- | ---------------------------------------------------------- |
| `mode`            | `'auto'`                                     | `'auto'`, `'export'`, `'event'`, `'statebag'`, `'native'`. |
| `export`          | `{ resource = '', name = '' }`               | For mode `'export'`.                                       |
| `events`          | `{ death = {}, revive = {} }`                | Client events for mode `'event'` (added in `'auto'`).      |
| `statebag`        | `{ 'isDead', 'dead' }`                       | `LocalPlayer.state` keys.                                  |
| `blockWhenCuffed` | `true`                                       | A cuffed player cannot transmit either.                    |
| `cuffedStatebag`  | `{ 'isHandcuffed', 'handcuffed', 'cuffed' }` | State bag keys for cuffed.                                 |

## Radio prop and animations

| Option                                      | Default                | Meaning                                                                                                                 |
| ------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `Config.PropModel`                          | `'ghiaccio_radio_b'`   | Model of the radio in hand (custom prop from `ghiaccio_radio_props`). Alternative: `'ghiaccio_radio_a'`.                |
| `Config.PropFallbackModel`                  | `'prop_cs_hand_radio'` | Used automatically, with a console warning, when the model is not found.                                                |
| `Config.PropModelOffsets`                   | per model              | Correction on top of the preset offset (`pos`, `rot`) for each custom model.                                            |
| `Config.Prop.enabled`                       | `true`                 | Radio prop in hand.                                                                                                     |
| `Config.Prop.networked`                     | `true`                 | Other players see the prop.                                                                                             |
| `Config.Prop.whileUI`                       | `true`                 | Radio in hand (and animation) while the window is open.                                                                 |
| `Config.Anim.enabled`                       | `true`                 | Radio animations.                                                                                                       |
| `Config.Anim.inVehicle`                     | `true`                 | `false` = never animate inside vehicles.                                                                                |
| `Config.Anim.blockFiring`                   | `true`                 | No shooting / melee while transmitting.                                                                                 |
| `Config.Anim.blockJump`                     | `false`                | No jumping while transmitting.                                                                                          |
| `Config.Anim.withWeapon`                    | `true`                 | Talk animation also with a weapon in hand (right-hand presets fall back to `default`).                                  |
| `Config.Anim.whileAiming`                   | `true`                 | Talk animation also while aiming. `false` = paused while aiming.                                                        |
| `Config.Anim.previewOnSelect` / `previewMs` | `false` / `2500`       | Plays the animation for a moment when confirmed with "Use".                                                             |
| `Config.Anim.default`                       | `'default'`            | Preset used when the player never chose.                                                                                |
| `Config.HoldAnim`                           | enabled                | "Radio in hand" idle animation while the UI is open (`dict`, `anim`, `flag`, `blendIn`, `blendOut`, `vehicle`, `prop`). |

### Animation presets

`Config.AnimPresets` lists the talk animations players pick in `/radioanim`: Default, Default fast, Shoulder slow, Shoulder fast, Police, Ear 1, Ear 2, Ear 3. Presets are validated at start: an invalid one is skipped with a warning naming the preset and the field. To add one, add an entry:

```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 } } }
```

| Field                 | Meaning                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | Required, unique, letters / digits / `_` / `-` (max 40). Never change it once live.                                             |
| `label`               | Required, a `preset.<id>` locale key or plain text (max 32).                                                                    |
| `dict`, `anim`        | Required, animation dictionary and clip (max 64 each).                                                                          |
| `flag`                | Required. Add up: 1 loop, 2 stay on last frame, 16 upper body only, 32 controllable. `50` = 2+16+32, `49` = 1+16+32.            |
| `blendIn`, `blendOut` | Required, -16..16. Negative = instant.                                                                                          |
| `vehicle`             | Optional, default `false`. `true` = also plays seated in a vehicle.                                                             |
| `prop`                | Optional: `bone` (ped bone id), `pos` `{x,y,z}` (max +-5 m), `rot` `{x,y,z}` (max +-360), `model` (default `Config.PropModel`). |

{% hint style="warning" %}
The prop goes on the hand the clip **moves**. The `random@arrests` clips raise the LEFT hand to the shoulder: bone `60309`. The phone-style clips (`cellphone@...`, Ear, Police) move the RIGHT hand: bone `28422`. A radio on the idle hand looks like "prop in hand, no animation".
{% endhint %}

## config\_server.lua

| Option                        | Default     | Meaning                                                                                                                                                                                                              |
| ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.Database`             | `'auto'`    | `'auto'` (oxmysql if started, otherwise KVP), `true` (oxmysql only), `false` (KVP only).                                                                                                                             |
| `Config.ChannelOffset`        | `0`         | Offset added to the integer pma-voice channel (`channel = frequency * 10^decimals + offset`). Raise it if other scripts use small numeric pma-voice channels.                                                        |
| `Config.JobChannels`          | empty       | Private job channels, see [Integrations](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/integrations.md#job-and-grade-channels).                                                                      |
| `Config.JobRequireOnDuty`     | `false`     | QBCore/Qbox: the player must be on duty (per channel with `onDuty`).                                                                                                                                                 |
| `Config.JobRecheckSeconds`    | `30`        | Periodic re-read of job and grade.                                                                                                                                                                                   |
| `Config.MaxChannelsPerRule`   | `5000`      | Safety limit of protected channels for one `range` rule.                                                                                                                                                             |
| `Config.ItemCheckSeconds`     | `5`         | How often the server checks the player still owns the item.                                                                                                                                                          |
| `Config.Members.showOnPublic` | `true`      | `false` = members are sent only on job channels.                                                                                                                                                                     |
| `Config.Members.nameSource`   | `'rp'`      | `'rp'` (character name), `'steam'` (FiveM name) or `'id'` (server id).                                                                                                                                               |
| `Config.Members.showCallsign` | `true`      | QBCore/Qbox: `metadata.callsign` is used when the player set none.                                                                                                                                                   |
| `Config.Members.max`          | `64`        | Maximum members sent.                                                                                                                                                                                                |
| `Config.RateLimit`            | per request | `{ window = seconds, max = events }` for `init`, `open`, `power`, `connect`, `disconnect`, `joinJobChannel`, `saveSettings`, `saveFavorite`, `deleteFavorite`, `selectAnim`, `getAnims`, `emergency`, `setCallsign`. |
| `Config.LogRejected`          | `true`      | Logs rejected requests (validation, rate limit, permissions).                                                                                                                                                        |

## Frequencies and pma-voice channels

pma-voice takes a number as channel, and the radio never sends decimals: `channel = frequency * 10^decimals + Config.ChannelOffset` (for example `101.50` with 2 decimals becomes channel `10150`). Players never see it.

## Voice systems

The logic goes through a small interface: `adapters/voice/pmavoice.lua` (client: volume, talking, PTT) and `adapters/voice/pmavoice_server.lua` (server: channel, members, access checks). To support another voice system implement the same functions (documented at the top of the files) and change `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/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.
