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

# Integrations & adapters

At start the console prints the framework, inventory and storage that were chosen.

## pma-voice

`pma-voice` is mandatory and is **never modified**: the radio only uses its exports and events (verified on 7.0.1: `setPlayerRadio`, `getPlayersInRadioChannel`, `addChannelCheck`, `setRadioVolume`, events `pma-voice:radioActive` and `pma-voice:setTalkingOnRadio`).

* `setr voice_enableRadioAnim 0` is required (see [Installation](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/installation.md)): the animations are handled by `ghiaccio_radio`.
* Frequencies are converted to integer channels: `channel = frequency * 10^decimals + Config.ChannelOffset` (`config_server.lua`). If other scripts already use small numeric pma-voice channels, raise `Config.ChannelOffset`.
* If pma-voice restarts, the job channel checks are registered again automatically.
* If your pma-voice already has a `radioDelay`, set it or `Config.Ptt.cooldown` to `0` (see [Configuration](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/configuration.md)).
* Other voice systems (SaltyChat, Mumble): implement the same functions as `adapters/voice/pmavoice.lua` and `pmavoice_server.lua` and set `Config.Voice`. Only `'pma-voice'` is bundled.

## Frameworks

`Config.Framework = 'auto'` detects Qbox, QBCore, ESX in this order, otherwise standalone. Force it with `'esx'`, `'qbcore'`, `'qbox'` or `'standalone'`.

* **ESX Legacy**: job and grade from `job.grade`; death from `esx:onPlayerDeath` / `esx:onPlayerSpawn`; usable item with `ESX.RegisterUsableItem`.
* **QBCore / Qbox**: job and grade from `job.grade.level`; on-duty support; death from `PlayerData.metadata.isdead` / `inlaststand`; `metadata.callsign` as fallback callsign.
* **Standalone**: nobody has a job and there is no inventory (the item requirement is ignored with a warning). Plug your own job system by returning `{ name, grade }` from `bridge/server/standalone.lua`.

## Inventories (radio item)

Detected automatically, or forced with `Config.Inventory = 'ox' | 'qb' | 'qs' | 'esx' | 'none'`.

| Inventory                     | How the item is used                                                                                           |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `ox_inventory`                | `client = { event = 'ghiaccio_radio:client:use' }` in the item definition                                      |
| `qb-inventory` (also ps / lj) | `CreateUseableItem` registered by the resource (`Config.UsableItem`)                                           |
| `qs-inventory`                | Not tested (see [Installation](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/installation.md)) |
| ESX inventory                 | `ESX.RegisterUsableItem` registered by the resource                                                            |

The item snippets are in [Installation](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/installation.md). The item name is `Config.Item`.

## Job and grade channels

Defined in `config_server.lua`. Each entry:

| Field       | Meaning                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `id`        | Unique text.                                                                                        |
| `label`     | Text shown in the UI.                                                                               |
| `frequency` | A single frequency, or the one-click join frequency when `range` is used.                           |
| `range`     | `{ min, max }`: the whole range is protected (if no `frequency` is given the join uses `range[1]`). |
| `jobs`      | `{ jobName = minGrade }`.                                                                           |
| `onDuty`    | QBCore/Qbox: `true` = must be on duty (default `Config.JobRequireOnDuty`).                          |

```lua
Config.JobChannels = {
    -- single frequency; police and sheriff, any grade
    { id = 'police', label = 'Police', frequency = 1.00, jobs = { police = 0, sheriff = 0 } },
    -- grade 3 and above only
    { id = 'police_cmd', label = 'Command', frequency = 1.01, jobs = { police = 3 } },
    -- whole range protected (2.00 - 2.09); the "Join" button uses 2.05
    { id = 'ems', label = 'EMS', range = { 2.00, 2.09 }, frequency = 2.05, jobs = { ambulance = 0 } },
    -- must be on duty (QBCore/Qbox)
    { id = 'mech', label = 'Mechanics', frequency = 3.00, jobs = { mechanic = 0 }, onDuty = true },
}
```

* Job and grade are read by the **server** from the framework.
* Access is enforced with pma-voice `addChannelCheck`: typing the frequency, using other scripts or editing the client does **not** bypass it. Frequencies of job channels never need to be hidden.
* The NUI lists in the job tab only the channels the player can use.
* If job or grade change (framework events plus a re-read every `Config.JobRecheckSeconds` seconds) the player is removed from the channel and the list refreshes.
* With `range`, every channel of the range is protected (with 2 decimals `2.00-2.09` is 10 channels; at most `Config.MaxChannelsPerRule`).

## Death and ambulance scripts

`Config.Death.mode` decides when the player is "dead": the radio does not transmit and the UI closes (the radio stays connected).

| `mode`             | How death is detected                                                                                                                                                                                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `'auto'` (default) | Native check, state bags, framework (ESX `esx:onPlayerDeath` / `esx:onPlayerSpawn`; QBCore/Qbox `isdead` / `inlaststand`), death and revive events of `esx_ambulancejob`, `qbx_medical`, `qb-ambulancejob`, plus exports of `qbx_medical` (`IsDead`, `IsLaststand`), `ars_ambulancejob` (`isDead`) and `wasabi_ambulance` (`isPlayerDead`), tried only when the resource is running. |
| `'export'`         | `export = { resource = 'resource_name', name = 'exportName' }`: the client export must return `true` when dead; on failure the native check is used.                                                                                                                                                                                                                                 |
| `'event'`          | `events = { death = { 'event:dead' }, revive = { 'event:revive' } }` (client events) plus the native check.                                                                                                                                                                                                                                                                          |
| `'statebag'`       | `statebag = { 'isDead', 'dead' }`: keys of `LocalPlayer.state` (true or a number above 0) plus the native check.                                                                                                                                                                                                                                                                     |
| `'native'`         | Only `IsEntityDead`, `IsPedFatallyInjured`, `IsPlayerDead`.                                                                                                                                                                                                                                                                                                                          |

{% hint style="warning" %}
The `ars_ambulancejob` and `wasabi_ambulance` export names are not verified against those scripts. If they do not answer, use `'export'` or `'statebag'`.
{% endhint %}

* `blockWhenCuffed = true` also blocks a cuffed player (state bag `cuffedStatebag`, `PlayerData.metadata.ishandcuffed` on QBCore/Qbox, `IsPedCuffed`).
* If a death event is never followed by a revive, the flag is cleared after 5 seconds of the ped being alive with no other source saying dead. It is also cleared on character change.
* With mode `'event'` and the standalone bridge, a downed-death script (ped alive) that exposes neither an export nor a state bag is unblocked after 5 seconds: expose an export or state bag and use mode `'export'` / `'statebag'`.

## Signal towers

Towers are set in `Config.Signal.towers` (`{ name, coords, radius }`), dead zones in `Config.Signal.deadZones`. See [Configuration](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/configuration.md#signal). The six towers in the default config are examples: replace them with the ones of your map.

## Custom radio prop (ghiaccio\_radio\_props)

The companion resource `ghiaccio_radio_props` streams the custom radio props `ghiaccio_radio_a` and `ghiaccio_radio_b`.

* Start it **before** `ghiaccio_radio`.
* `Config.PropModel = 'ghiaccio_radio_b'` is the default. If the model is not found, the radio falls back to `prop_cs_hand_radio` with a console warning (`Config.PropFallbackModel`).
* The custom props have the origin at the base of the body; the per-model correction is in `Config.PropModelOffsets`.
* A preset can use its own model with `prop.model`.

### Your own prop

1. Export the model as `.ydr` (CodeWalker / Sollumz for Blender) with its textures `.ytd`.
2. Copy the files and the `.ytyp` into `ghiaccio_radio/stream/` (everything in `stream/` is streamed automatically).
3. In `fxmanifest.lua` add `data_file 'DLC_ITYP_REQUEST' 'stream/your_prop.ytyp'`.
4. Set `Config.PropModel = 'your_prop'` (or `prop.model` on single presets).
5. Tune `bone`, `pos` and `rot` of the presets and restart. If the prop does not show, the `.ytyp` or the model names do not match: `Config.Debug = true` helps.

## Other scripts

Use the exports and the `ghiaccio_radio:client:use` event described in [Commands, keybinds & permissions](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/radio/commands-and-permissions.md). For example, disconnect a player when they are arrested:

```lua
exports.ghiaccio_radio:disconnect(src, true)   -- server
```


---

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