# ACE Permissions (https://timmygstudios.com/docs/faq-ace-permissions)
How to use FiveM's ACE permissions system to grant players and groups access to script commands.

FiveM's ACE system is how scripts decide who can run which commands. TIMMYG Studios scripts use it for admin-only features — for example, opening the tELS editor requires the `tlib.admin` permission.

Permission checks happen **server-side**, so changes require either an `ensure` of the resource or a server restart to take effect.

---

## Principals

A _principal_ is an identifier that holds permissions (which FiveM calls **ACEs**). Principals are either:

- **Player identifiers** — a specific player's Discord ID, Steam ID, License, etc.
- **Groups** — made-up identifiers prefixed with `group.` (e.g., `group.admin`, `group.moderator`). Groups don't need to be declared — they exist the moment you reference one.

Groups are the recommended approach since they let you assign the same permissions to many players at once.

### Adding a player to a group

```ini
title="server.cfg" add_principal identifier.discord:394446211341615104 group.admin
```

This adds the player with Discord ID `394446211341615104` to `group.admin`. Any ACEs granted to `group.admin` now apply to that player.

### Nesting groups

```ini
title="server.cfg" add_principal group.admin group.moderator
```

`group.admin` now inherits every permission that `group.moderator` has.

  Lines starting with `#` in `server.cfg` are comments and are ignored by the parser.

---

## Granting permissions

Use `add_ace` to grant a permission node, `remove_ace` to revoke it. Permissions can be attached to a group or directly to a player identifier.

    ```ini
    title="server.cfg" # Grant the tlib.admin permission to the admin group add_ace group.admin "tlib.admin" allow # Add the player to the group — they inherit all of its permissions add_principal identifier.discord:394446211341615104 group.admin
    ```

    Any player added to `group.admin` now has `tlib.admin`. Add or remove players from the group without touching the ACE itself.

    ```ini
    title="server.cfg" # Grant the permission directly to one player add_ace identifier.discord:394446211341615104 "tlib.admin" allow
    ```

    Faster for a single player, but doesn't scale. Prefer groups if more than one person will ever need the permission.

### Removing permissions

```ini
title="server.cfg" # Revoke from the group remove_ace group.admin "tlib.admin" allow # Revoke from a specific player remove_ace identifier.discord:394446211341615104 "tlib.admin" allow
```

The `allow` at the end must match the original grant.

---

## Example: giving someone tELS editor access

The tELS editor is gated behind `tlib.admin`. To grant a player access:

### Open server.cfg

Locate `server.cfg` in your server's root directory.

### Grant the ACE to a group

```ini
title="server.cfg" add_ace group.admin "tlib.admin" allow
```

### Add the player to the group

```ini
title="server.cfg" add_principal identifier.discord:394446211341615104 group.admin
```

Replace the Discord ID with your admin's identifier. You can also use `identifier.steam:...`, `identifier.license:...`, or `identifier.fivem:...`.

### Restart the server

ACE changes are loaded at startup. Restart the server or run `refresh` + `restart` on the resources that check the permission.

### Verify

The admin runs `/telsedit` in-game. If the permission is correct, the editor opens. If it still says permission denied, check the identifier matches exactly — Discord IDs must be numeric with no prefix beyond `identifier.discord:`.

---

## Related

    Where `tlib.admin` is used — gates the editor and server-wide defaults.

  Provides the admin ACE and permission helpers used across TIMMYG Studios scripts.

    If commands fail for reasons other than permissions, start here.

<!-- llms-full-doc-separator -->

# tRadio API Reference (https://timmygstudios.com/docs/tRadio/api-reference)
Lua exports, REST API, Socket.IO events, and the dispatch panel theming SDK for Tommy's Radio.

## Server exports

Call these from any server-side script as `exports['tRadio']:name(...)`. The `provide 'tRadio'` alias means the folder name does not matter.

### Channel information

| Export                      | Parameters                  | Returns                                                                   |
| --------------------------- | --------------------------- | ------------------------------------------------------------------------- |
| `getSpeakersInChannel`      | `frequency: string\|number` | `table` — server IDs connected as speakers                                |
| `getListenersInChannel`     | `frequency`                 | `table` — server IDs scanning (listen only)                               |
| `getAllUsersInChannel`      | `frequency`                 | `table` — speakers and listeners combined                                 |
| `getActiveTalkersInChannel` | `frequency`                 | `table` — server IDs holding PTT right now                                |
| `getActiveChannels`         | —                           | `string[]` — frequencies with at least one active user                    |
| `getChannelInfo`            | `frequency`                 | `{ speakers, listeners, activeTalkers }` or `nil`                         |
| `getAllChannels`            | —                           | `table[]` — the full configured channel list with zones, names, and types |

```lua
local speakers = exports['tRadio']:getSpeakersInChannel("154.755")
local info     = exports['tRadio']:getChannelInfo("154.755")
-- info = { speakers = {...}, listeners = {...}, activeTalkers = {...} }
```

### Alerts and panic

| Export              | Parameters                                                                    | Returns                                                                                        |
| ------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `getChannelAlert`   | `frequency`                                                                   | The active alert config, or `nil`                                                              |
| `setAlertOnChannel` | `frequency`, `enabled: boolean\|nil`, `alertIndexOrName: number\|string\|nil` | —                                                                                              |
| `setChannelSignal`  | `frequency`, `enabled: boolean`                                               | `true` — fires the **first** configured alert. The export equivalent of the in-game SGN button |
| `getChannelPanic`   | `frequency`                                                                   | `{ [serverId] = serverId, ... }`                                                               |
| `setChannelPanic`   | `frequency`, `serverId`, `enabled: boolean`                                   | `boolean`                                                                                      |
| `getUserPanicState` | `serverId`, `frequency`                                                       | `boolean`                                                                                      |

`setAlertOnChannel` resolves its third argument like this:

- omitted or `nil` → the first alert in the list
- a number → 1-based index into the alerts array
- a string → case-insensitive name match
- `enabled = nil` → toggle the current state

```lua
exports['tRadio']:setAlertOnChannel("154.755", true)                -- first alert, activate
exports['tRadio']:setAlertOnChannel("154.755", true, "SIGNAL 100")  -- by name
exports['tRadio']:setAlertOnChannel("154.755", nil, 2)              -- toggle the second alert
exports['tRadio']:setChannelPanic("154.755", 5, true)
```

### User management

| Export           | Parameters                      | Returns                                           |
| ---------------- | ------------------------------- | ------------------------------------------------- |
| `setUserChannel` | `serverId: number`, `frequency` | `boolean` — handles trunked routing automatically |
| `disconnectUser` | `serverId: number`              | `boolean`                                         |
| `isUserTalking`  | `serverId: number`, `frequency` | `boolean`                                         |

### User information

| Export              | Parameters                  | Returns                                                                             |
| ------------------- | --------------------------- | ----------------------------------------------------------------------------------- |
| `getPlayerName`     | `serverId`                  | `string`                                                                            |
| `getPlayerNacId`    | `serverId`                  | `string` or `nil`                                                                   |
| `getUserInfo`       | `serverId`                  | `{ name, nacId }`                                                                   |
| `hasRadioAccess`    | `serverId`                  | `boolean`                                                                           |
| `setUserNacId`      | `serverId`, `nacId: string` | `boolean` — display override until the next `refreshNacId`                          |
| `refreshNacId`      | `serverId`                  | `boolean` — re-resolves access and pushes it to the client. Call after a job change |
| `refreshPlayerInfo` | —                           | `number` — count of players whose NAC ID and name were refreshed                    |
| `getAcePermissions` | `serverId`                  | `{ connect, scan, gps, zones, dispatch }`                                           |

```lua
local perms = exports['tRadio']:getAcePermissions(5)
-- connect/scan/gps are frequency arrays, zones is a 1-based index array,
-- dispatch is a boolean (supervisor privileges)
```

### Codeplugs and subscribers

| Export               | Parameters | Returns                                                                             |
| -------------------- | ---------- | ----------------------------------------------------------------------------------- |
| `getSubscriberInfo`  | `serverId` | The subscriber record, or `nil`                                                     |
| `getSubscriberZones` | `serverId` | `table[]` of zone objects, or `nil`                                                 |
| `refreshSubscriber`  | `serverId` | `boolean` — rebuilds the whole subscriber record. More thorough than `refreshNacId` |

`getSubscriberInfo` returns:

```lua
{
    codeplugId         = "leo",
    unitId             = "1041",
    nac                = "141",
    allowedModels      = { "QRX-720", "HLX-120" },
    defaultLayouts     = { Handheld = "QRX-720", Vehicle = "HLX-120" },
    features           = { gps = true, scan = true, emergencyButton = true, manDown = false },
    tones              = { ... },
    emergency          = { emergencyChannelId = nil, autoTransmitDuration = 5 },
    announcementVolume = 0.8,
}
```

Each subscriber gets a P25 unit ID derived from their codeplug ID and license hash, so the same player on the same codeplug keeps the same unit ID across sessions and restarts.

### Callsigns

Requires **Enable Callsigns** in the admin panel.

| Export        | Parameters                                                    | Returns           |
| ------------- | ------------------------------------------------------------- | ----------------- |
| `setCallsign` | `serverId`, `callsign: string\|nil` — `""` or `nil` clears it | —                 |
| `getCallsign` | `serverId`                                                    | `string` or `nil` |

### Audio

| Export              | Parameters                  | Returns |
| ------------------- | --------------------------- | ------- |
| `playToneOnChannel` | `frequency`, `tone: string` | —       |
| `playToneOnSource`  | `serverId`, `tone: string`  | —       |

```lua
exports['tRadio']:playToneOnChannel("154.755", "ALERT_A")
exports['tRadio']:playToneOnSource(5, "BEEP")
```

Tone keys come from the [tone catalog](/docs/tRadio/configuration#tone-catalog).

---

## Client exports

  All volume exports use **0.0–1.0**. The admin and dispatch panels use **0–100** — divide by 100
  before passing a panel value to an export.

### Radio control

| Export                   | Parameters                        | Returns                               |
| ------------------------ | --------------------------------- | ------------------------------------- |
| `openRadio`              | `focus: boolean` (default `true`) | —                                     |
| `closeRadio`             | —                                 | —                                     |
| `connectToFrequency`     | `frequency`                       | `boolean`                             |
| `setCurrentChannel`      | `frequency`                       | —                                     |
| `getCurrentFrequency`    | —                                 | frequency, or `-1` when not connected |
| `getCurrentChannel`      | —                                 | channel object                        |
| `addListeningChannel`    | `frequency`                       | —                                     |
| `removeListeningChannel` | `frequency`                       | —                                     |
| `getListeningChannels`   | —                                 | `string[]` — active scan frequencies  |

```lua
exports['tRadio']:openRadio()       -- open with NUI focus
exports['tRadio']:openRadio(false)  -- open without focus
exports['tRadio']:connectToFrequency("154.755")
```

`radio:client:openRadio` is also fired as a client event when a player uses the radio item from their inventory — handle it yourself only if `Config.inventory.system = 'custom'`.

### Transmission

| Export                   | Parameters         | Returns                                  |
| ------------------------ | ------------------ | ---------------------------------------- |
| `startTransmitting`      | —                  | —                                        |
| `stopTransmitting`       | —                  | —                                        |
| `setTalking`             | `talking: boolean` | — — same as start/stop                   |
| `isTransmitting`         | —                  | `boolean`                                |
| `getActiveTalker`        | —                  | `{ serverId, name, frequency }` or `nil` |
| `activateProximityVoice` | —                  | — — triggers in-game proximity voice     |

### Radio state

| Export            | Returns                         |
| ----------------- | ------------------------------- |
| `isConnected`     | `boolean`                       |
| `isPowerOn`       | `boolean`                       |
| `isRadioOpen`     | `boolean`                       |
| `isRadioFocused`  | `boolean`                       |
| `setPower(state)` | — — omit the argument to toggle |

### Volume and audio

| Export                            | Parameters     | Returns                                          |
| --------------------------------- | -------------- | ------------------------------------------------ |
| `setVolume` / `getVolume`         | `0.0–1.0`      | — / `number`                                     |
| `setToneVolume` / `getToneVolume` | `0.0–1.0`      | — / `number`                                     |
| `set3DVolume` / `get3DVolume`     | `0.0–1.0`      | — / `number`                                     |
| `playTone`                        | `tone: string` | — — plays locally only                           |
| `NotifySirenChanged`              | —              | — — forces an immediate re-poll of `bgModeCheck` |

### Appearance and settings

| Export                                    | Parameters                | Returns       |
| ----------------------------------------- | ------------------------- | ------------- |
| `setRadioLayout` / `getRadioLayout`       | `model: string`           | — / `string`  |
| `setRadioTheme` / `getRadioTheme`         | `"Auto"\|"Light"\|"Dark"` | — / `string`  |
| `setAnimationId` / `getAnimationId`       | `id: string`              | — / `string`  |
| `setEarbudsEnabled` / `getEarbudsEnabled` | `boolean`                 | — / `boolean` |
| `setGPSEnabled` / `getGPSEnabled`         | `boolean`                 | — / `boolean` |

### Alerts and panic

| Export                  | Parameters                                      |
| ----------------------- | ----------------------------------------------- |
| `triggerAlertOnChannel` | `frequency`, `enabled: boolean`, `alertConfig?` |
| `panicButton`           | `frequency`, `enabled: boolean`                 |

### Player and system information

| Export                            | Returns                         |
| --------------------------------- | ------------------------------- |
| `getCurrentName`                  | `string`                        |
| `getCurrentNacId`                 | `string`                        |
| `refreshMyNacId`                  | — — re-fetches from the server  |
| `getMyCallsign` / `setMyCallsign` | `string\|nil` / — (`""` clears) |
| `getZone`                         | `string` — current zone name    |
| `getBatteryLevel`                 | `number` (0–100)                |
| `getSignalStrength`               | `number` (0–5)                  |
| `getConnectionDiagnostics`        | diagnostic snapshot table       |

---

## Web API

### Authenticating

Protected endpoints need a per-session token obtained at runtime. This is **not** `Config.authToken`.

```bash
curl -X POST http://203.0.113.10:7777/radio/dispatch/auth \
  -H "Content-Type: application/json" \
  -d '{"nacId": "4417", "callsign": "Dispatcher-01"}'
```

```python

res = requests.post(
    "http://203.0.113.10:7777/radio/dispatch/auth",
    json={"nacId": "4417", "callsign": "Dispatcher-01"},
).json()
auth_token, session_id = res["authToken"], res["sessionId"]
```

```javascript
const res = await fetch("http://203.0.113.10:7777/radio/dispatch/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ nacId: "4417", callsign: "Dispatcher-01" }),
}).then((r) => r.json());
const { authToken, sessionId } = res;
```

```json
{
  "success": true,
  "sessionId": "dispatch_abc123",
  "authToken": "550e8400-e29b-41d4-a716-446655440000"
}
```

Then send both headers on every protected request:

```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
x-session-id: dispatch_abc123
```

- `nacId` must match `dispatchNacId` in `config.lua`
- Sessions last **24 hours**; at most 100 exist at once, oldest evicted first
- Authentication is rate-limited to 15 attempts per 15 minutes per IP
- With Discord auth enabled the same endpoint returns `202` and a `redirectUri` instead
- After a server restart, re-issue a session with `POST /radio/dispatch/reauth` sending only the `Authorization` header

### Endpoint prefixes

| Prefix             | Purpose                                                  |
| ------------------ | -------------------------------------------------------- |
| `/api/`            | General integrations — bots, CAD, external monitoring    |
| `/radio/dispatch/` | Full dispatcher presence and real-time state             |
| `/dispatch/`       | Unit management — controlling individual in-game players |

  Prefer `GET /radio/dispatch/status` over `GET /api/status` for integrations. It is a superset and
  the actively maintained one.

### Public endpoints

| Method | Path                          | Description                                                                      |
| ------ | ----------------------------- | -------------------------------------------------------------------------------- |
| `GET`  | `/api/health`                 | `{ status, service, serviceName, authMethod }`. Used by the startup health check |
| `GET`  | `/api/locale`                 | The string table from `config/locales.json`                                      |
| `GET`  | `/radio/dispatch/installer`   | Windows desktop app installer. Rate-limited to 5/min                             |
| `GET`  | `/radio/dispatch/update.json` | Desktop app auto-updater manifest                                                |

### Status and config

| Method | Path                     | Description                                           |
| ------ | ------------------------ | ----------------------------------------------------- |
| `GET`  | `/radio/dispatch/status` | Users, channels, panic, alerts, patches — preferred   |
| `GET`  | `/api/status`            | A subset of the above                                 |
| `GET`  | `/radio/dispatch/config` | Zones, alerts, volumes, FX settings, installed themes |
| `GET`  | `/radio/dispatch/tones`  | Available tone list                                   |

### Broadcasts and tones

| Method | Path                           | Body                                    | Description                                                 |
| ------ | ------------------------------ | --------------------------------------- | ----------------------------------------------------------- |
| `POST` | `/radio/dispatch/broadcast`    | `{ message, frequency?, type?, tone? }` | Broadcast to a channel or all                               |
| `POST` | `/api/trigger-broadcast`       | `{ message, frequency?, type? }`        | Broadcast, no tone field                                    |
| `POST` | `/radio/dispatch/tone`         | `{ frequency, tone }`                   | Play a tone on a channel                                    |
| `POST` | `/api/play-tone`               | `{ frequency, tone }`                   | Alias of the above                                          |
| `POST` | `/radio/dispatch/speaker-tone` | `{ targetId, tone }`                    | Play a tone at a world speaker, or every speaker in a group |

### Alerts

| Method | Path                            | Body                                                        |
| ------ | ------------------------------- | ----------------------------------------------------------- |
| `POST` | `/radio/dispatch/alert/trigger` | `{ frequency, alertType, alertConfig }`                     |
| `POST` | `/radio/dispatch/alert/clear`   | `{ frequency }`                                             |
| `POST` | `/radio/dispatch/alert/oneshot` | `{ frequency, alertConfig }` — fire once without persisting |

### Channels and units

| Method | Path                                 | Body                                    | Description                                                |
| ------ | ------------------------------------ | --------------------------------------- | ---------------------------------------------------------- |
| `POST` | `/radio/dispatch/switchChannel`      | `{ serverId, frequency, oldFrequency }` | Move an in-game player                                     |
| `POST` | `/dispatch/user/alert`               | `{ userId, message, frequency }`        | Send an alert to one player                                |
| `POST` | `/dispatch/user/disconnect`          | `{ userId }`                            | Disconnect a player from the radio                         |
| `POST` | `/dispatch/user/set-player-callsign` | `{ userId, callsign }`                  | Set an in-game player's callsign                           |
| `POST` | `/dispatch/user/update-callsign`     | `{ callsign, userId }`                  | Update a dispatcher's callsign — `userId` must be negative |

### Patches

| Method | Path                | Body                                            |
| ------ | ------------------- | ----------------------------------------------- |
| `GET`  | `/api/patches`      | —                                               |
| `POST` | `/api/patch/create` | `{ label, frequencies: ["154.755", "460.25"] }` |
| `POST` | `/api/patch/remove` | `{ id }`                                        |

```bash
SESSION_TOKEN="550e8400-e29b-41d4-a716-446655440000"
SESSION_ID="dispatch_abc123"

curl http://203.0.113.10:7777/radio/dispatch/status \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "x-session-id: $SESSION_ID"

curl -X POST http://203.0.113.10:7777/api/patch/create \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "x-session-id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"label": "TAC1-FIRE", "frequencies": ["154.755", "460.25"]}'

curl -X POST http://203.0.113.10:7777/radio/dispatch/tone \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "x-session-id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"frequency": "154.755", "tone": "ALERT_A"}'
```

```python

headers = {
    "Authorization": f"Bearer {auth_token}",
    "x-session-id": session_id,
}

status = requests.get(
    "http://203.0.113.10:7777/radio/dispatch/status", headers=headers
).json()

requests.post(
    "http://203.0.113.10:7777/api/patch/create",
    headers=headers,
    json={"label": "TAC1-FIRE", "frequencies": ["154.755", "460.25"]},
)

requests.post(
    "http://203.0.113.10:7777/radio/dispatch/tone",
    headers=headers,
    json={"frequency": "154.755", "tone": "ALERT_A"},
)
```

### Error responses

All errors are `application/json`.

| Status | Body                                     | Cause                           |
| ------ | ---------------------------------------- | ------------------------------- |
| `400`  | `{ "error": "..." }`                     | Missing or invalid parameters   |
| `401`  | `{ "error": "Authentication required" }` | Missing or invalid auth headers |
| `404`  | `{ "error": "Channel not found" }`       | Unknown frequency               |
| `429`  | `{ "error": "Too many..." }`             | Rate limited                    |
| `500`  | `{ "error": "..." }`                     | Server error                    |

**Type notes.** Frequencies accept strings (`"154.755"`) or numbers (`154.755`) everywhere. Dispatcher `serverId` values must be **negative**; in-game player IDs are positive. CORS is enabled for all origins.

---

## Socket.IO

Connect to appear as a dispatcher and receive real-time events.

```javascript
const res = await fetch("http://203.0.113.10:7777/radio/dispatch/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ nacId: "4417", callsign: "Bot-01" }),
}).then((r) => r.json());

const socket = io("http://203.0.113.10:7777", {
  auth: {
    authToken: res.authToken, // per-session UUID — not Config.authToken
    sessionId: res.sessionId,
    serverId: -(1000 + Math.floor(Math.random() * 10000)), // must be negative
  },
});
```

### Emit — client to server

| Event                    | Payload                            | Description                                                             |
| ------------------------ | ---------------------------------- | ----------------------------------------------------------------------- |
| `setDispatchSession`     | `sessionId: string`                | Link the socket to the auth session                                     |
| `updateUserInfo`         | `{ name, nacId }`                  | Set dispatcher identity                                                 |
| `setSpeakerChannel`      | `frequency: string`                | Join a channel to speak                                                 |
| `addListeningChannel`    | `frequency: string`                | Start scanning                                                          |
| `removeListeningChannel` | `frequency: string`                | Stop scanning                                                           |
| `listenToUser`           | `targetServerId: number`           | Follow a user across any frequency                                      |
| `stopListeningToUser`    | `targetServerId: number`           | Stop following                                                          |
| `setTalking`             | `{ state, frequency?, override? }` | PTT. `override: true` bypasses half-duplex blocking and is audit-logged |
| `voice`                  | `{ data, encoding?, frequency? }`  | Base64 Opus packet; `encoding: "imbe"` for P25                          |
| `heartbeat`              | `Date.now()`                       | Keep-alive                                                              |

### Listen — server to client

| Event                             | Payload                                                           | Fires when                                          |
| --------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------- |
| `voice`                           | `{ serverId, frequency, data, encoding?, receiveType, patchId? }` | A voice packet is relayed                           |
| `talkingState`                    | `{ serverId, frequency, state }`                                  | PTT starts or stops                                 |
| `speakerJoined` / `speakerLeft`   | `{ serverId, frequency, name?, nacId? }`                          | A speaker joins or leaves                           |
| `listenerJoined` / `listenerLeft` | `{ serverId, frequency }`                                         | A listener joins or leaves                          |
| `channelState`                    | `{ frequency, speakers, listeners, activeTalkers, empty }`        | Full channel snapshot                               |
| `patchStatus`                     | `{ patchId, active, label, frequencies }`                         | A patch is created or removed                       |
| `serverTone`                      | `{ tone, frequency }`                                             | A tone plays on a channel                           |
| `dispatchNotification`            | `{ type, ...payload }`                                            | Cross-dispatcher notification                       |
| `playerInfoUpdate`                | `{ serverId, name?, nacId?, unitId? }`                            | Player identity changes                             |
| `configUpdate`                    | `{ ... }`                                                         | Slim config re-broadcast, no zones or alerts inline |
| `configRefresh`                   | `{}`                                                              | Re-fetch `/radio/dispatch/config`                   |
| `ptt:denied`                      | `{ frequency, reason, currentTalker? }`                           | PTT denied — channel busy                           |

---

## Dispatch panel theming

The dispatch panel is themeable in **four tiers**, from a colour swap to a fully
custom console. Each tier is more capable than the last and carries more of the
work — pick the lowest one that meets your goal.

| Tier                  | You write                  | Effort  | Host keeps feature-gating, a11y, i18n, keyboard?                                 | Auto-publishes?                     |
| --------------------- | -------------------------- | ------- | -------------------------------------------------------------------------------- | ----------------------------------- |
| **1 — Design tokens** | `cssVars`                  | Lowest  | Yes — stock panel                                                                | Yes                                 |
| **2 — CSS**           | `cssText`                  | Low     | Yes — stock panel                                                                | Yes                                 |
| **3 — Slot override** | `slots`                    | Medium  | **Yes** — the host keeps every gate and guard; you swap only the markup you name | Yes                                 |
| **4 — Full takeover** | `template` and/or `jsText` | Highest | **No** — you own parity for everything you render                                | `template`-only: yes · `jsText`: no |

Layers combine — `cssVars` + a couple of `slots`, or `cssVars` + `cssText` + a
full `template`. The rule that governs publishing is simple: **a theme with no
`jsText` is declarative and installs without the JavaScript source-review gate;
adding `jsText` reintroduces it** (see [Security Model](#security-model)).

Themes are installed from **Admin Panel → Marketplace → Themes**. Building and
publishing one is covered in [Publishing a theme](#publishing-a-theme) below.

  **Which tier?** Recolouring the stock panel → Tier 1 / 2. Restyling one kind of component (channel
  cards, unit rows, 911 cards) while everything else stays stock → Tier 3. A genuinely different
  console layout → Tier 4. Reach for Tier 4 last: it is the only tier where a new panel feature does
  **not** appear automatically, because you have replaced the component that would have rendered it.

### Tier 1 — Design tokens

The "change some colours" surface. Every dispatch component is styled with CSS
custom properties; set them via a theme's `cssVars`, a `:root { … }` block in
`cssText`, or `theme.setVar()` at runtime — no markup, no JavaScript. The table
below is the complete, authoritative registry, generated from
`server/web/src/theme-sdk/tokens.ts` (the same source the panel and the admin
Theme Studio read):

{/* GENERATED:tokens START — auto-generated by scripts/gen-theme-docs.ts (`bun run docs:tables`); do not edit by hand. */}

| Token                     | Category   | Default (dark)                | Controls                                                                                    |
| ------------------------- | ---------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
| `--bg-primary`            | Surfaces   | `#030303`                     | App background behind everything.                                                           |
| `--bg-secondary`          | Surfaces   | `#141414`                     | Header, bars, cards, panels.                                                                |
| `--bg-hover`              | Surfaces   | `#262626`                     | Hover/pressed state for interactive rows and buttons.                                       |
| `--card`                  | Surfaces   | `hsl(0 0% 8%)`                | Raised card/dialog surface (shadcn-derived components).                                     |
| `--text-primary`          | Text       | `#fafafa`                     | Default foreground text colour.                                                             |
| `--text-secondary`        | Text       | `#a3a3a3`                     | Muted labels, metadata, secondary rows.                                                     |
| `--foreground`            | Text       | `hsl(0 0% 98%)`               | Base foreground for shadcn-derived components.                                              |
| `--accent-raw`            | Accent     | `#3b82f6`                     | Primary accent — active channel, PTT, selected states.                                      |
| `--primary`               | Accent     | `hsl(204 77% 47%)`            | Primary colour for shadcn-derived buttons and rings.                                        |
| `--ring`                  | Accent     | `hsl(0 0% 83%)`               | Keyboard focus outline colour.                                                              |
| `--danger`                | Status     | `#ef4444`                     | Panic, destructive actions, error states.                                                   |
| `--success`               | Status     | `#22c55e`                     | Connected/healthy indicators.                                                               |
| `--destructive`           | Status     | `hsl(0 84% 60%)`              | Destructive colour for shadcn-derived components; drives panic flash.                       |
| `--my-dispatch-bg`        | Dispatch   | `hsl(220 100% 13%)`           | Background tint for units controlled by this dispatcher.                                    |
| `--my-dispatch-border`    | Dispatch   | `hsl(220 100% 28%)`           | Border for units controlled by this dispatcher.                                             |
| `--other-dispatch-bg`     | Dispatch   | `hsl(270 100% 13%)`           | Background tint for units controlled by another dispatcher.                                 |
| `--other-dispatch-border` | Dispatch   | `hsl(270 100% 28%)`           | Border for units controlled by another dispatcher.                                          |
| `--border`                | Structure  | `hsl(0 0% 15%)`               | Default border/divider colour.                                                              |
| `--input`                 | Structure  | `hsl(0 0% 18%)`               | Form control border colour.                                                                 |
| `--radius`                | Structure  | `0.5rem`                      | Base border-radius for cards and controls.                                                  |
| `--font-sans`             | Typography | `"JetBrains Mono", monospace` | UI font stack. Also settable via the theme `font` field.                                    |
| `--font-size`             | Typography | `100%`                        | Root font size as a percentage (100% = 16px). Also settable via the theme `fontSize` field. |

{/* GENERATED:tokens END */}

`--font-sans` and `--font-size` are also settable through a theme's dedicated
`font` / `fontSize` fields.

The table above is the **dispatch-panel** token contract (`tokens.ts`). The
shared UI kit — every dialog, button, input and select — is styled by a _second_
set of tokens on the shadcn/UnoCSS convention: `--background`, `--foreground`,
`--card` / `--card-foreground`, `--primary` / `--primary-foreground`,
`--secondary` / `--secondary-foreground`, `--muted` / `--muted-foreground`,
`--accent` / `--accent-foreground`, `--destructive` / `--destructive-foreground`,
`--border`, `--input`, `--ring`, `--radius`. These are consumed through utility
classes (`bg-background` compiles to `var(--background)` via `uno.config.ts`), so
a `grep 'var(--background)'` over source will not find them even though they are
very much in use. **A full-panel or takeover theme that only sets the dispatch
tokens will leave the modal dialogs on the default palette** — set the UI-kit
tokens too so Settings, Broadcast, Patches and the confirm dialogs match. Note
`--accent` (UI-kit hover) is a different token from `--accent-raw` (dispatch).

### Tier 2 — CSS

`cssText` is injected as a `<style>` block, so it can restyle any part of the
stock panel, not merely recolour it — target the panel's own class names or the
Tier 1 tokens. It is **sanitized at install** (see [Security Model](#security-model)):
`@import`, `expression(…)` and every `url(…)` — including relative paths and
`data:` URIs — are removed, so use gradients or unicode glyphs for imagery.
`cssVars` values are applied as custom properties and are not sanitized as rules,
though `{`, `}` and `;` are stripped from each value.

Set `extends` to a built-in theme ID to inherit its tokens and override only what
you need. Built-in IDs: `dark-minimal` (default), `dark`, `dark-blue`, `basic`,
`basic-dark` — all five are also directly selectable in the panel's own
**Settings → Theme** picker, no install required.

### Tier 3 — Slot overrides

A slot replaces **one kind of component** — a channel card, a unit row, a 911
call card — while the host keeps the shell around it: the feature gates, keyboard
handling, ARIA, localisation and every guard the stock component applies. Anything
you do not override stays stock and keeps improving. This is the right tier when
you want console-style channel tiles but not a from-scratch panel; it is a
rounding error in size next to a full takeover, and it cannot get the gating wrong
because it never sees those decisions.

A slot fragment is ordinary `data-rd-*` markup (the same binding language as
[declarative templates](#declarative-templates)), bound by the same binder and the
same [action allow-list](#declarative-templates). The only difference is scope: an
item slot's fragment is evaluated with the item bound to a **scope variable** _in
addition to_ the root view model, so both `ch.name` and `counts.panics` resolve
inside a `channel` fragment. Ship them on a theme's `slots` map:

```json
{
  "id": "mcc5500-slots",
  "name": "Console (slots)",
  "cssText": "/* .mx-tile { … } */",
  "slots": {
    "channel": "<div class=\"mx-tile\" data-rd-class=\"cur:ch.isCurrent\">…</div>",
    "unit": "<div class=\"mx-u\" data-rd-text=\"u.identityLine\"></div>"
  }
}
```

A slot-only theme (no `jsText`) auto-publishes, exactly like a template theme, and
each fragment is sanitized identically to `template`.

{/* GENERATED:slots START — auto-generated by scripts/gen-theme-docs.ts (`bun run docs:tables`); do not edit by hand. */}

| Slot               | Scope var | Replaces                                                         | Host gates (owned by the panel)   |
| ------------------ | --------- | ---------------------------------------------------------------- | --------------------------------- |
| `header`           | — (root)  | Top bar: connection, callsign, counts, voice status, global PTT. | —                                 |
| `announcement-bar` | `g`       | One announcement-group button.                                   | `announcementGroups.length`       |
| `zone`             | `zone`    | A zone column, including its header and collapsed strip.         | —                                 |
| `channel`          | `ch`      | A channel card: name, badges, roster, and its controls.          | —                                 |
| `unit`             | `u`       | One unit row inside a channel roster.                            | —                                 |
| `tx-entry`         | `tx`      | One transmission-log row.                                        | `settings.transmissionLogEnabled` |
| `call-card`        | `c`       | One 911 call card.                                               | `call911Enabled`                  |
| `patch-row`        | `p`       | One active-patch row.                                            | —                                 |
| `speaker-row`      | `sp`      | One speaker or speaker-group row on the tone board.              | `counts.speakers`                 |

{/* GENERATED:slots END */}

The **host gates** column lists the view-model conditions the panel checks
_before_ it renders the slot at all. A theme never sees them — an overridden
`call-card` cannot appear on a server with 911 disabled, because the host never
reaches the slot. Slots with no gates (and `header`) always render. A worked,
annotated example ships in the repo as **`mcc5500-slots-demo.js`**: three
overridden slots (`channel`, `unit`, `call-card`) and nothing else, inheriting the
entire stock shell.

#### Compatibility — `requires`

The view-model shape and the slot registry are versioned independently
(`viewModelVersion`, `slotRegistryVersion`), and an older panel may not provide
what a theme targets. A theme declares its floor:

```json
{ "requires": { "viewModel": 2, "slots": 1 } }
```

Both fields are optional **floors**, not pins: the contract is additive, so a
theme that needs view model v2 runs on v2 and every later version and fails only
downward. A theme with no `requires` is treated as requiring v1 — the contract
before the field existed — so nothing already published is affected. On a
mismatch the failure is legible rather than silent: **install is rejected** with a
message like _"needs view model v2, but this panel provides v1 — update tRadio"_,
and an incompatible theme that is somehow already stored **fails safe at mount** —
the panel falls back rather than binding a fragment against data it does not have.

### Tier 4 — Full takeover

The highest tier hides the stock panel and renders your own, two ways that can be
combined:

- **[Declarative templates](#declarative-templates)** — a `template` of
  `data-rd-*` markup driven by the binder. No JavaScript, so it **auto-publishes**.
  This is the recommended way to build a whole custom panel.
- **[Theme JavaScript](#theme-javascript)** — `jsText`, imperative code with full
  DOM access. Maximum control; **trips the source-review gate** and is never
  auto-published.

Either way you take on the full parity burden: every feature gate, list, guard,
keyboard and a11y affordance the stock panel had is now yours to reproduce. Two
worked references live in the repo root: **`mcc5500-slots-demo.js`** (the slot
tier above, for contrast) and **`mcc5500-theme.js`** — a template that
rebuilds a full dispatch console from scratch and delegates the handful of
things a template cannot express (free-text dialogs, PTT key capture,
drag-and-drop) to a small `jsText` layer.

#### Theme JavaScript

  JS themes run directly in the dispatch panel with full DOM access. Dispatchers are shown the
  complete source code and must explicitly accept a warning before installation.

Theme JavaScript receives three injected globals:

| Global          | Purpose                                                 |
| --------------- | ------------------------------------------------------- |
| `dispatch`      | Read state, subscribe to events, call actions           |
| `theme`         | CSS helpers, DOM control                                |
| `onUnmount(fn)` | Register cleanup for when the theme changes or unmounts |

### Reading state

`dispatch.getViewModel()` returns the typed **view model** — the same versioned
contract the declarative templates bind to, and a superset of `getState()`. It
adds 911 calls and precomputes the booleans/counts a panel renders
(`channel.hasPanic`, `channel.isCurrent`, `zone.userCount`, `counts.panics`, …).
Prefer it for new themes. Grab [`dispatch-theme.d.ts`](/assets/tRadio/dispatch-theme.d.ts) for
full autocomplete while authoring.

```javascript
const vm = dispatch.getViewModel();
vm.version; // contract version (currently 2)
vm.channels; // every channel, flattened across zones
vm.counts.panics; // active panics across the board
vm.calls911; // 911 queue (not in getState())
```

`dispatch.getState()` returns the original flat snapshot of the store. Neither
call sets up reactive subscriptions.

| Field                     | Type                     | Description                                                            |
| ------------------------- | ------------------------ | ---------------------------------------------------------------------- |
| `channel`                 | `string`                 | Currently monitored frequency                                          |
| `scannedChannels`         | `string[]`               | Additional scanned frequencies                                         |
| `zones`                   | `Zone[]`                 | Full zone → channel → user tree                                        |
| `pttActive`               | `boolean`                | Global PTT active                                                      |
| `channelPttActive`        | `boolean`                | Per-channel PTT active                                                 |
| `channelPttFrequency`     | `string`                 | Frequency for active channel PTT                                       |
| `voiceStatus`             | `string`                 | `MUTED` \| `LISTENING` \| `TRANSMITTING` \| `TX (IMBE)` \| `TX (Opus)` |
| `micReady`                | `boolean \| null`        | Microphone availability                                                |
| `activeAlerts`            | `Record<string, string>` | `{ [frequency]: alertName }`                                           |
| `alertTypes`              | `AlertType[]`            | Available alert configs                                                |
| `tones`                   | `{ id, name }[]`         | Available tones for broadcast alerts                                   |
| `patches`                 | `Patch[]`                | Active frequency patches                                               |
| `transmissions`           | `TransmissionEntry[]`    | Last 50 transmission log entries                                       |
| `announcementGroups`      | `AnnouncementGroup[]`    | Group definitions                                                      |
| `activeAnnouncementGroup` | `string \| null`         | Currently armed group ID                                               |
| `settings`                | `DispatchSettings`       | PTT bindings, volumes, callsign                                        |
| `callsign`                | `string`                 | Dispatcher callsign                                                    |
| `serverName`              | `string`                 | Connected server name                                                  |
| `connected`               | `boolean`                | Socket connection state                                                |
| `health`                  | `string`                 | `connected` \| `stale` \| `disconnected`                               |
| `authenticated`           | `boolean`                | Auth state                                                             |

**Zone shape:**

```javascript
{
  id: string, name: string,
  channels: [{
    id: string, frequency: string, name: string,
    type: string,           // "conventional" | "trunked"
    canTransmit: boolean,
    listeners: number,
    users: [{
      id: string, name: string,
      nacId: string | null, unitId: string | null,
      transmitting: boolean, panic: boolean
    }]
  }]
}
```

**DispatchSettings shape:**

```javascript
{
  callsign: string,
  voiceVolume: number,   // 0–100
  sfxVolume: number,     // 0–100
  globalPTT: { pttKey, pttType, pttMouseButton },
  channelPTT: { [frequency]: PTTSettings },
  announcementGroupPTT: { [groupId]: PTTSettings }
}
```

### Events

Subscribe with `dispatch.on(event, callback)`. All events fire immediately on subscribe with the current state — no separate initialisation call needed.

```javascript
dispatch.on("dispatch:zones", ({ zones }) => render(zones));

// Unsubscribe
const handler = ({ active }) => {
  /* ... */
};
dispatch.on("dispatch:ptt", handler);
onUnmount(() => dispatch.off("dispatch:ptt", handler));
```

| Event                         | Payload                       | Fires when                                         |
| ----------------------------- | ----------------------------- | -------------------------------------------------- |
| `dispatch:zones`              | `{ zones }`                   | Any channel, user, panic, or listener-count change |
| `dispatch:ptt`                | `{ active }`                  | Global PTT pressed or released                     |
| `dispatch:channel`            | `{ freq }`                    | Main monitored channel changes                     |
| `dispatch:channel-ptt`        | `{ active, freq }`            | Per-channel PTT starts or stops                    |
| `dispatch:voice-status`       | `{ status }`                  | Voice status changes                               |
| `dispatch:connection`         | `{ connected, health }`       | Connection state changes                           |
| `dispatch:alerts`             | `{ alerts: [{id, name}] }`    | Active channel alerts change                       |
| `dispatch:alert-types`        | `{ alertTypes }`              | Alert config reloads                               |
| `dispatch:scans`              | `{ scanned: string[] }`       | Scanned channel list changes                       |
| `dispatch:patches`            | `{ patches }`                 | Patches created or removed                         |
| `dispatch:transmissions`      | `{ transmissions }`           | TX log entry added or completed                    |
| `dispatch:callsign`           | `{ callsign }`                | Dispatcher callsign changes                        |
| `dispatch:announcement-group` | `{ groupId: string \| null }` | Active announcement group changes                  |
| `dispatch:settings`           | `{ settings }`                | Any PTT binding or volume setting changes          |

### Actions

**Channel:**

```javascript
dispatch.joinChannel("460.25");
dispatch.leaveChannel();
dispatch.addScan("154.755");
dispatch.removeScan("154.755");
```

**PTT:**

```javascript
dispatch.startPTT(); // global PTT — requires microphone + active channel
dispatch.stopPTT();
dispatch.startChannelPTT("460.25"); // per-channel PTT
dispatch.stopChannelPTT();
```

  PTT silently no-ops if the dispatcher has no active channel, the channel has `canTransmit: false`,
  or another PTT is already active.

**Announcement groups:**

```javascript
dispatch.activateAnnouncementGroup("group-id"); // arm
dispatch.activateAnnouncementGroup(null); // disarm
```

**Alerts:**

```javascript
dispatch.triggerAlert("460.25", "SIGNAL 100");

dispatch.sendBroadcastAlert({
  frequency: "460.25",
  type: "Priority Alert", // "General Alert" | "Information Alert" | "Priority Alert" | "Emergency Alert"
  message: "All units respond to 123 Main St",
  tone: "PRIORITY",
});

dispatch.acknowledgePanic(serverId, unitId); // unitId optional
```

**Patches:**

```javascript
// createPatch(label, frequencies) — frequencies are numbers. Resolves to { ok, error? }.
await dispatch.createPatch("Tac 1", [460.25, 154.755]);

// removePatch takes a patch id from the view model, not the create result.
const patch = dispatch.getViewModel().patches[0];
if (patch) await dispatch.removePatch(patch.id);
```

**Settings and unit management:**

```javascript
dispatch.updateSettings({ voiceVolume: 80 });
dispatch.updateSettings({ callsign: "DISP-1" });
dispatch.openSettings();
dispatch.closeSettings();

// All return Promise<boolean>
dispatch.kickUser(serverId);
dispatch.alertUser(serverId, "Message text", frequency);
dispatch.setUserCallsign(serverId, "UNIT-5");
dispatch.switchUserChannel(serverId, "462.45", "460.25"); // (id, newFreq, oldFreq)
```

### DOM control

All CSS changes through the theme API are automatically reversed when the theme changes or the panel unmounts.

```javascript
theme.setVar("--accent-raw", "#ff6600"); // set a CSS variable on <html>
theme.removeVar("--accent-raw");

// Adds "tj-ptt-active" to <html> (auto-prefixed)
theme.addClass("ptt-active");
theme.removeClass("ptt-active");

theme.hideDefaultUI(); // hides Header, ZoneList, and announcement bar
theme.showDefaultUI(); // restores them

// Persistent <div> inside .dispatch-app — mount custom HTML here
const root = theme.getContainer();
```

Variable names: `--[a-zA-Z][a-zA-Z0-9-]*` (max 60 chars). Class names: `[a-zA-Z][a-zA-Z0-9-_]*` (max 40 chars, without the `tj-` prefix). `hideDefaultUI()` does not affect Settings, broadcast, or patch modals — they render in overlay portals.

### Declarative templates

The recommended way to build a custom panel. Instead of hand-writing DOM and
wiring event listeners, you write HTML annotated with `data-rd-*` attributes and
hand it to `theme.mountTemplate()`. The binder pushes the view model in, keeps it
in sync, and **reconciles lists by key** — a single unit's status changing
updates one node rather than rebuilding the panel. No arbitrary JavaScript runs,
so template-only themes are safe by construction.

```javascript
theme.hideDefaultUI();
theme.mountTemplate(`
  <div class="panel">
    <header data-rd-text="serverName"></header>
    <div data-rd-repeat="ch in channels" data-rd-key="ch.id"
         data-rd-class="active:ch.isCurrent"
         data-rd-on="click:join(ch.frequency)">
      <span data-rd-text="ch.name"></span>
      <span data-rd-show="ch.hasPanic">⚠ PANIC</span>
    </div>
  </div>
`);
```

`mountTemplate` returns a binder and handles updates and teardown for you — no
render loop, no manual `dispatch.on(...)`. A complete, styled starting point
lives at [`reference-panel.html`](/assets/tRadio/reference-panel.html).

#### No-JS template themes

A theme can ship a template directly, with **no JavaScript at all**, via a
`template` field on the theme definition:

```json
{
  "id": "my-cad-panel",
  "name": "CAD Panel",
  "cssVars": { "--accent-raw": "#22d3ee" },
  "template": "<div class=\"p\">…data-rd-* markup…</div>"
}
```

When the theme is active, the panel hides its default UI and auto-mounts the
template — you never write `mountTemplate` yourself. Because the markup is
declarative and **sanitized at install** (`<script>`, inline `on*` handlers, and
`javascript:` URIs are stripped), a template theme installs **without the
JavaScript source-review gate** that `jsText` themes require. Use `data-rd-on`
for behaviour instead of inline handlers. For logic beyond the template's reach,
add a `jsText` — but that reintroduces the review gate.

**Building a theme — test against the real panel, not a mock.** Open your own
dispatch panel while logged in, open your browser's devtools (or any extension
you like), and:

- Inject a `<style>` tag for CSS — this already works with zero cooperation
  from tRadio, and is exactly how `cssText` is applied once installed.
- For templates and JS, use `window.__tjDev` — see [Live authoring](#live-authoring)
  below. It exposes the exact same `dispatch`/`theme` objects an installed
  theme runs against, bound to your panel's real live data, so nothing changes
  between testing and shipping.

Once it looks right, install it straight to this server (no marketplace, no
editing `data.json`) by POSTing the finished definition from the same devtools
console:

```javascript
fetch("/admin/api/themes", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
  body: JSON.stringify({
    name: "My Theme",
    cssVars: { "--accent-raw": "#22d3ee" },
    cssText: "",
    jsText: "",
    template: "",
  }),
});
```

Requires an active admin session (you're already logged into `/admin`). It
appears in the dispatch panel's **Settings → Theme** picker immediately —
pass the same `id` on a later call to edit it in place instead of creating a
duplicate.

### Live authoring

Any dispatch panel exposes `window.__tjDev = { dispatch, theme }` while you're
logged in — the same `dispatch`/`theme` objects a `jsText` theme receives as
function arguments, just reachable from your own devtools/extension console
instead. There's no separate opt-in flag: authentication into the panel is
already the only gate that matters, and any installed `jsText` theme already
has this exact same unsandboxed access once published, so exposing it to you
while you're logged into your own panel doesn't cross a new trust boundary.

```javascript
// In your browser's devtools console, on your own authenticated dispatch panel:
window.__tjDev.theme.hideDefaultUI();
window.__tjDev.theme.mountTemplate(`
  <div data-rd-repeat="zone in zones" data-rd-key="zone.id">…</div>
`);

// Read real live state:
window.__tjDev.dispatch.getViewModel();
```

A good iteration loop for the template string specifically: keep it in your
browser's DevTools **Snippets** panel (Chrome: Sources → Snippets; Firefox has
an equivalent) rather than retyping it into the console each time — a real
multi-line, syntax-highlighted editor that persists across reloads, with a
keyboard shortcut (Ctrl+Enter) to re-run `window.__tjDev.theme.mountTemplate(...)`
after each edit. Editing the live-rendered DOM directly in the Elements panel
does **not** work for anything the binder controls — it re-asserts state from
its compiled template on every reactive update and will silently overwrite
manual DOM edits.

**Binding attributes:**

| Attribute        | Example                                                   | Effect                                       |
| ---------------- | --------------------------------------------------------- | -------------------------------------------- |
| `data-rd-text`   | `data-rd-text="ch.name"`                                  | Sets `textContent`                           |
| `data-rd-html`   | `data-rd-html="ch.note"`                                  | Sets `innerHTML` (values are trusted markup) |
| `data-rd-show`   | `data-rd-show="ch.transmitting"`                          | Shows when truthy (`!` to negate)            |
| `data-rd-hide`   | `data-rd-hide="ch.userCount"`                             | Hides when truthy                            |
| `data-rd-attr`   | `data-rd-attr="title:ch.name; data-freq:ch.frequency"`    | Sets/removes attributes                      |
| `data-rd-class`  | `data-rd-class="active:ch.isCurrent; tx:ch.transmitting"` | Toggles classes                              |
| `data-rd-style`  | `data-rd-style="color:accent"`                            | Sets inline style properties                 |
| `data-rd-repeat` | `data-rd-repeat="ch in zone.channels"`                    | Repeats the element per list item            |
| `data-rd-key`    | `data-rd-key="ch.id"`                                     | Reconciliation key (defaults to index)       |
| `data-rd-on`     | `data-rd-on="click:join(ch.frequency)"`                   | Binds events to actions                      |

**Expressions** are dotted paths (`zone.channels`, `ch.isCurrent`) and literals
(`'text'`, `42`, `true`, `null`), combined with a small, fixed set of operators:

| Form                             | Example                                                  |
| -------------------------------- | -------------------------------------------------------- |
| Negation                         | `data-rd-show="!ch.isCurrent"`                           |
| Comparison (strict, no coercion) | `data-rd-show="settings.transmissionLogFilter == 'all'"` |
| Ordering                         | `data-rd-show="counts.users > 0"`                        |
| And / or (short-circuit)         | `data-rd-show="ch.transmitting && !ch.hasPanic"`         |
| Ternary                          | `data-rd-text="ch.isCurrent ? 'ACTIVE' : 'STANDBY'"`     |
| Grouping                         | `data-rd-show="(a \|\| b) && c"`                         |
| Filters                          | `data-rd-text="tx.startTime \| elapsed"`                 |

Repeat variables shadow the view model, and nested repeats see their parent's
scope (`data-rd-repeat="ch in zone.channels"` can reference `zone`). Use
`data-rd-repeat="ch, i in channels"` to bind an index variable.

**Filters** transform a value with `expression | name` or `expression | name:arg`,
and chain left to right (`transmissions | where:'hasAudio' | limit:5`). The list
is fixed — a theme cannot define its own — and an unknown name simply passes the
value through. The **Args** column is the number of arguments each filter takes
(`elapsed`, `upper`, … take none; `round`/`join` take an optional one):

{/* GENERATED:filters START — auto-generated by scripts/gen-theme-docs.ts (`bun run docs:tables`); do not edit by hand. */}

| Filter     | Args | Result                                                               |
| ---------- | ---- | -------------------------------------------------------------------- |
| `default`  | 1    | the argument when the value is null, undefined or ""                 |
| `elapsed`  | none | epoch ms → time since, "3:07" past a minute else "42s" (uses vm.now) |
| `join`     | 0–1  | array → string joined by the separator (default ", ")                |
| `limit`    | 1    | array → at most N leading items                                      |
| `lower`    | none | lowercase text                                                       |
| `pct`      | none | number 0–100 → "50%"                                                 |
| `plural`   | 2    | number → first argument when exactly 1, else the second              |
| `round`    | 0–1  | number → rounded to N decimal places (default 0)                     |
| `sortBy`   | 1    | array → stably sorted ascending by the named field                   |
| `time`     | none | epoch ms → local wall clock "14:32:07"                               |
| `upper`    | none | uppercase text                                                       |
| `where`    | 1    | array → only items whose named field is truthy                       |
| `whereNot` | 1    | array → only items whose named field is falsy                        |

{/* GENERATED:filters END */}

Filter arguments are themselves expressions, so field names must be quoted
(`where:'hasAudio'`, not `where:hasAudio`). A `|` inside an argument ends that
argument — wrap it in parentheses to filter within one, e.g. `default:(a | upper)`.

**Template actions** (`data-rd-on`) — a fixed, safe allow-list. This is the same
capability registry the JS `dispatch` API exposes, so every action below is also
callable as `dispatch.<name>(…)` from a `jsText` theme. The **Args** column is the
number of positional arguments each takes:

{/* GENERATED:actions START — auto-generated by scripts/gen-theme-docs.ts (`bun run docs:tables`); do not edit by hand. */}

| Action                        | Args |
| ----------------------------- | ---- |
| `acceptCall911()`             | 1    |
| `acknowledgePanic()`          | 2    |
| `activateGroup()`             | 1    |
| `addScan()`                   | 1    |
| `checkUpdate()`               | none |
| `clearLog()`                  | none |
| `closeBroadcast()`            | none |
| `closePatchPanel()`           | none |
| `closeSettings()`             | none |
| `endCall911()`                | 1    |
| `expandSidebar()`             | none |
| `focusCall911()`              | 1    |
| `join()`                      | 1    |
| `kickUser()`                  | 1    |
| `leave()`                     | none |
| `logout()`                    | none |
| `openBroadcast()`             | 1    |
| `openPatchPanel()`            | none |
| `openSettings()`              | none |
| `playTransmission()`          | 1    |
| `removePatch()`               | 1    |
| `removeScan()`                | 1    |
| `setAutoCollapse()`           | 1    |
| `setLogFilter()`              | 1    |
| `setSfxVolume()`              | 1    |
| `setTransmissionLogEnabled()` | 1    |
| `setVoiceVolume()`            | 1    |
| `speakerTone()`               | 2    |
| `startChannelPtt()`           | 1    |
| `startPtt()`                  | none |
| `stopChannelPtt()`            | none |
| `stopPtt()`                   | none |
| `stopTransmission()`          | 1    |
| `toggleCallQueue()`           | none |
| `toggleChannel()`             | 2    |
| `toggleTxLog()`               | none |
| `toggleZone()`                | 1    |
| `triggerAlert()`              | 2    |
| `unfocusCall911()`            | none |

{/* GENERATED:actions END */}

A few semantics worth stating, since the table only lists arity:

- `activateGroup(null)` disarms the armed announcement group; `focusCall911` /
  `openBroadcast` take a **frequency**, `acceptCall911` / `endCall911` a **call
  id**, `removePatch` a **patch id** (from `vm.patches[].id`).
- `removePatch` removes a patch, but **creating** one needs free text and so the
  JS API (`dispatch.createPatch`) — a template cannot.
- `setLogFilter` accepts only `'all'`, `'monitored'` or `'current'`;
  `setVoiceVolume` / `setSfxVolume` take a number **0–100** (the grammar has no
  arithmetic, so render discrete steps).
- `playTransmission` / `stopTransmission` replay buffered audio — gate the button
  on `tx.hasAudio`. `acknowledgePanic`'s second argument (`unitId`) is optional at
  runtime even though its signature lists two.

**Reaching what a template cannot express.** The binder passes only paths and
literals to an action, so it can never read a value out of an `<input>`. Anything
needing free text (creating a patch, composing a broadcast, changing a unit's
callsign), live key capture (PTT rebinding), drag-and-drop or a popout window
has to be delegated. Two ways to do that:

**1. Open a built-in modal.** `SettingsModal`, `BroadcastModal`, `SpeakerBoard`
and `PatchPanel` render _outside_ `.dispatch-default-ui`, so they stay fully
usable after `hideDefaultUI()`. Open them with `openPatchPanel()` /
`openBroadcast(freq)` / `openSettings()` rather than rebuilding them.

**2. Go hybrid — a `jsText` theme that mounts the same template.**
`theme.mountTemplate()` is available inside `jsText`, so you keep declarative
rendering for the 95% that is lists and state binding, and write imperative code
only for the rest. Mark intent in the template with a plain `data-*` attribute
(the binder ignores unknown ones) and handle it with a delegated listener:

```js
theme.hideDefaultUI();
theme.mountTemplate(TEMPLATE);
const root = theme.getContainer();

//   <button data-rd-attr="data-alert-user:u.id">Alert…</button>
root.addEventListener(
  "click",
  (e) => {
    const el = e.target.closest?.("[data-alert-user]");
    if (el) myDialog((msg) => dispatch.alertUser(el.dataset.alertUser, msg, freq));
  },
  true,
);
```

Two things will bite you here. **Listen in the capture phase** (the `true` above):
the binder calls `stopPropagation()` on every `click`/`mouse*` it handles, so a
bubbling listener never fires for a button nested under an element that has its
own `data-rd-on`. And **append your own dialogs to `document.body`, not the theme
canvas** — `mountTemplate()` assigns `container.innerHTML`, and repeat
reconciliation replaces nodes, so anything parked inside is destroyed on the next
update. A `<style>` block inside the template is document-global once parsed, so
body-level nodes still pick up its CSS.

Note the trade-off: a `jsText` theme runs unsandboxed on the panel's origin, is
recorded in the audit log, and on the marketplace requires review before
publishing, whereas a template-only theme publishes automatically.

**Two authoring traps worth knowing before you write a template.**

**1. Give every `data-rd-repeat` its own parent element.** Bindings are addressed
by a `childNodes` index path captured when the template compiles, but a repeat
inserts its items _before_ its anchor at runtime — shifting the index of every
later sibling in the same parent. A binding placed after an un-wrapped repeat
will resolve to the wrong node and throw
`Cannot set properties of undefined (setting 'display')`. The usual victim is an
empty-state message following a list:

```html
<!-- WRONG — the empty state's index shifts as items render -->
<div class="list">
  <div data-rd-repeat="p in patches" data-rd-key="p.id">…</div>
  <div data-rd-hide="patches.length">No patches.</div>
</div>

<!-- RIGHT — the repeat gets its own container (display:contents keeps layout identical) -->
<div class="list">
  <div style="display:contents">
    <div data-rd-repeat="p in patches" data-rd-key="p.id">…</div>
  </div>
  <div data-rd-hide="patches.length">No patches.</div>
</div>
```

**2. `data-rd-text` sets `textContent`, which erases child elements.** An element
cannot both carry `data-rd-text` and contain markup (an icon, a coloured dot).
Put the text in its own child span.

### Publishing a theme

Themes are authored and submitted in the [theme editor](/app/marketplace/theme-editor)
— **tgstudios → Marketplace → Themes → Create Theme**. Build against your own
live panel first (see [Live authoring](#live-authoring)), then paste the result in.

The editor is **one form, not a set of modes**. Every layer composes at runtime,
so a single theme can carry colours _and_ a slot override _and_ JavaScript. A
"This theme:" strip at the top shows which layers you currently have: Colours &
CSS, N slot overrides, Full template, JavaScript.

| Section                                 | What it takes                                                                                                                                        |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name, Description, Resource, Screenshot | Listing metadata. **Resource is locked once the theme exists**                                                                                       |
| **Colours & variables**                 | Key/value rows with a colour swatch. A `:root { … }` block in Custom CSS feeds these rows and vice versa                                             |
| **Custom CSS**                          | Free-form CSS. Applies to the stock panel _and_ to any slot overrides                                                                                |
| **Component overrides**                 | Pick a slot from the dropdown and write its `data-rd-*` fragment                                                                                     |
| **Advanced**                            | Hidden behind a disclosure, and auto-opened when you edit a theme that already uses it. Holds the **Full-panel template** and the **JavaScript** box |

A live preview sits above the editors: a representative mock panel styled by your
colours and CSS, plus a real binder view running your template or slots against
mock dispatch data as soon as either exists. **JavaScript cannot be previewed**
— build it against your live panel. Validation errors block submission; warnings
do not.

  A template replaces the whole panel, so any slots you have defined are ignored while it is set.
  The editor warns you when both are present. Clear the template to go back to slots.

**What happens on submit**

| Your theme contains                                   | Result                                                                        |
| ----------------------------------------------------- | ----------------------------------------------------------------------------- |
| Only `cssVars`, `cssText`, `slots`, and/or `template` | **Published immediately.** No staff review                                    |
| Any `jsText`                                          | **Pending staff review.** A staff member reads the source before it goes live |

Editing an existing theme follows the same rule: a CSS-, slot- or template-only
edit republishes straight away, while an edit that introduces JavaScript drops
the theme back to pending — _even if it was already approved_. That is deliberate,
and it is why the gate cannot be worked around by getting a benign version
approved and then swapping the JavaScript in afterwards.

Once live, updates reach servers that installed the theme on their next
dispatch-panel refresh.

A theme is capped at **10 MB** for the whole definition and **256** CSS
variables.

### Security model

| What                              | How it's enforced                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CSS injection**                 | In `cssText`, `@import`, `expression(…)` and **every** `url(…)` — including relative paths and `data:` URIs — are stripped at install time. Use gradients or unicode glyphs instead. A `<style>` block inside a theme's `template` is sanitized as HTML rather than CSS, so `url()` survives there.                                                                                                                                                       |
| **Declarative templates & slots** | `data-rd-*` bindings resolve only dotted paths, literals, operators over them and the fixed filter list; events dispatch only to the fixed action allow-list. No `eval`, no indexing, no theme-defined functions — no arbitrary code runs. Slot fragments are sanitized identically to `template` (`<script>`, inline `on*` handlers and `javascript:` URIs stripped). A template/slot theme with no `jsText` is safe by construction and auto-publishes. |
| **JS execution**                  | Runs directly in the dispatch panel — no iframe sandbox. Full DOM access by design.                                                                                                                                                                                                                                                                                                                                                                       |
| **Install review**                | Any theme containing `jsText` shows a mandatory source-review dialog. Cannot be bypassed.                                                                                                                                                                                                                                                                                                                                                                 |
| **JS badge**                      | Theme cards in **Admin Panel → Marketplace** carry a visible **JS** badge when the theme includes JavaScript, before you open it.                                                                                                                                                                                                                                                                                                                         |
| **Auto-cleanup**                  | CSS vars, classes, canvas contents, and `hideDefaultUI` state are all reversed automatically on theme change or panel close.                                                                                                                                                                                                                                                                                                                              |

<!-- llms-full-doc-separator -->

# tels API Reference (https://timmygstudios.com/docs/tels/api-reference)
Exports, state bags, and network events for integrating with tELS from other scripts.

## Client exports

Both exports return `nil` when the entity isn't a tELS-configured vehicle — useful for detecting tELS vehicles without hard-coding model lists.

### IsSirenActive

Returns whether any siren is playing (main, aux, or burst).

```lua
local active = exports['tELS']:IsSirenActive(vehicle)
-- true | false | nil
```

| Parameter | Type   | Notes                 |
| --------- | ------ | --------------------- |
| `vehicle` | number | Vehicle entity handle |

### AreLightsActive

Returns whether emergency lights are on (any stage > 0).

```lua
local on = exports['tELS']:AreLightsActive(vehicle)
-- true | false | nil
```

| Parameter | Type   | Notes                 |
| --------- | ------ | --------------------- |
| `vehicle` | number | Vehicle entity handle |

### IsPaActive

Returns whether the local player's PA mic is currently active. Returns `nil` if pma-voice is unavailable.

```lua
local active = exports['tELS']:IsPaActive()
-- true | false | nil
```

> **Note:** This export takes no arguments — it reflects the calling client's own PA state only.

### IsPaAvailable

Returns whether the PA mic system is available (pma-voice is running).

```lua
local available = exports['tELS']:IsPaAvailable()
-- true | false
```

---

## State bags

Lighting and siren state syncs via OneSync state bags, so any script on any client can read the current state of any vehicle — no server round-trip required.

### Entity state bags

Read with `Entity(vehicle).state['key']` from either client or server.

| Key                     | Type    | Description                                                                                                              |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `tels:active`           | boolean | Emergency lights active                                                                                                  |
| `tels:patternIdx`       | number  | Pattern index (1-based; 0 = lights-only)                                                                                 |
| `tels:stage`            | number  | Current stage (0 = off, 1–3)                                                                                             |
| `tels:sirenOn`          | boolean | Main siren playing                                                                                                       |
| `tels:sirenTone`        | number  | Main siren tone index                                                                                                    |
| `tels:auxSirenOn`       | boolean | Aux siren playing                                                                                                        |
| `tels:auxSirenTone`     | number  | Aux siren tone index                                                                                                     |
| `tels:sirenBurst`       | boolean | Burst tone currently held                                                                                                |
| `tels:hornActive`       | boolean | Horn / airhorn active                                                                                                    |
| `tels:cruiseOn`         | boolean | Cruise mode on                                                                                                           |
| `tels:takedownOn`       | boolean | Takedown mode on                                                                                                         |
| `tels:taMode`           | string  | `"off"`, `"left"`, `"right"`, `"center"`                                                                                 |
| `tels:presenceEnabled`  | boolean | Presence detection armed                                                                                                 |
| `tels:presenceDetected` | boolean | Presence condition currently satisfied (pushed by the owning client)                                                     |
| `tels:chirpActive`      | boolean | Chirp tone running                                                                                                       |
| `tels:rumblerOn`        | boolean | Rumbler variant active                                                                                                   |
| `tels:argesOn`          | boolean | Arges spotlight active                                                                                                   |
| `tels:argesAimYaw`      | number  | Arges spotlight aim (horizontal, degrees)                                                                                |
| `tels:argesAimPitch`    | number  | Arges spotlight aim (vertical, degrees)                                                                                  |
| `tels:paActive`         | boolean | PA mic currently broadcasting from this vehicle's driver                                                                 |
| `tels:ownedBy`          | number  | Server ID of the player who claimed ownership of this vehicle (set by `tels:claimOwnership` when a player takes control) |

### Player state bag

| Key          | Type    | Description                                                                                                              |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `tels:owner` | boolean | `true` on the local player while they own any tELS vehicle. Used to filter out other officers from `presence` detection. |

### Example

```lua
-- On the client: react to a nearby vehicle going Code 3
CreateThread(function()
    while true do
        Wait(500)
        local veh = GetClosestVehicle(coords.x, coords.y, coords.z, 30.0, 0, 71)
        if veh ~= 0 and Entity(veh).state['tels:active']
                    and (Entity(veh).state['tels:stage'] or 0) >= 2
                    and Entity(veh).state['tels:sirenOn'] then
            -- code 3 behavior
        end
    end
end)
```

---

## Network events

### Server → client

| Event                     | Payload                               | Purpose                                                             |
| ------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
| `tels:config_receive`     | `configs` (table: modelName → config) | Broadcast full vehicle configs after a save or server start         |
| `tels:serverDefaults`     | `defaults` (table)                    | Admin display defaults + available layouts + `isAdmin` flag         |
| `tels:stateSync`          | `senderSrc, netId, delta`             | Relayed local-state delta for remote clients when ownership changes |
| `tels:presenceSyncClient` | `senderSrc, netId, detected`          | Presence state broadcast from the owning client                     |
| `tels:notify`             | `msg`                                 | Server-initiated on-screen notification                             |

### Client → server

| Event                         | Payload                        | ACE          | Purpose                                                            |
| ----------------------------- | ------------------------------ | ------------ | ------------------------------------------------------------------ |
| `tels:requestDefaults`        | —                              | —            | Request current server defaults and available layouts              |
| `tels:saveServerDefaults`     | `data`                         | `tlib.admin` | Persist new server defaults                                        |
| `tels:claimOwnership`         | `netId`                        | —            | Claim vehicle ownership for state relay                            |
| `tels:stateBagRelay`          | `netId, delta`                 | —            | Relay a state delta when the client loses network-entity ownership |
| `tels:presenceSync`           | `netId, detected`              | —            | Owner client pushes its presence state for other clients           |
| `tels:ref_edit_pattern_delta` | `model, patternName, editData` | `tlib.admin` | Apply a pattern delta to a referenced source vehicle               |
| `tels:ref_edit_trigger`       | `model, triggerId, newTrigger` | `tlib.admin` | Replace a trigger in a referenced source vehicle                   |
| `tels:ref_edit_siren`         | `model, newSirenConfig`        | `tlib.admin` | Update siren tones / airhorn / chirp on a referenced source        |
| `tels:ref_edit_settings`      | `model, newConfig`             | `tlib.admin` | Update siren behavior settings on a referenced source              |

### Configs auto-registered by Discovery

tELS uses tLib's Discovery module, which registers its own event set in addition to the above. The relevant ones from a consumer's perspective:

| Event                     | Direction | Purpose                                        |
| ------------------------- | --------- | ---------------------------------------------- |
| `tels:config_receive`     | S → C     | Authoritative config broadcast                 |
| `tels:externalSourceInfo` | S → C     | Which resource bundled each model's config     |
| `tels:exportTargets`      | S → C     | List of models available for export / bundling |

---

## Discovery metadata

Vehicle resources that ship a bundled config declare it via fxmanifest metadata:

| Field            | Value                                 |
| ---------------- | ------------------------------------- |
| Metadata key     | `tels_config`                         |
| Default filename | `tels.json`                           |
| Local storage    | `data.json` at the tELS resource root |
| Event prefix     | `tels`                                |

See [Configuration → Vehicle-developer export](/docs/tels/configuration#vehicle-developer-export) for the full setup.

---

## Internal globals (advanced)

These are Lua globals exposed across tELS client files. They're intended for internal use but can be read from scripts that merge into the tELS resource. Do **not** rely on them from other resources — signatures and names may change.

| Global                                  | Source             | Purpose                                                  |
| --------------------------------------- | ------------------ | -------------------------------------------------------- |
| `lbarGetLocalState(vehicle)`            | `cl_lights.lua`    | Local state table for a vehicle (returns nil for remote) |
| `lbarGetMaxStage(modelName)`            | `cl_lights.lua`    | Max configured stage for a vehicle model                 |
| `getVehicleConfig(modelName)`           | `cl_lights.lua`    | Full resolved config for a model                         |
| `getCustomPatterns(modelName)`          | `cl_lights.lua`    | Resolved patterns list (refs dereferenced)               |
| `getResolvedTriggers(modelName)`        | `cl_lights.lua`    | Resolved triggers list                                   |
| `getSirenConfig(modelName)`             | `cl_lights.lua`    | Resolved siren config                                    |
| `resolveColorIndex(led, index, frame)`  | `shared/utils.lua` | Pattern-cell lookup with legacy fallback                 |
| `renderLEDSet(veh, leds, colors, opts)` | `cl_renderer.lua`  | Unified LED render entry point                           |

If you're building tooling or extensions inside the tELS resource, these are the right hooks. External integrations should stick to the exports and state bags above.

<!-- llms-full-doc-separator -->

# tAFK API Reference (https://timmygstudios.com/docs/tAFK/api-reference)
Exports, events, state bags, and server-side admin events for integrating with tAFK.

## Client exports

All exports live on `exports['tAFK']` and operate on the local player.

### IsAFK

Returns whether the local player is currently in the AFK cinematic.

```lua
local afk = exports['tAFK']:IsAFK()
-- true | false
```

No parameters. Reflects real-time state — `true` from the moment the fade-in completes to the moment any input exits.

### StartAFK

Triggers AFK manually on the local player. Equivalent to `/afk` when already valid.

```lua
local started = exports['tAFK']:StartAFK()
-- true  — entered AFK (will fade in over 1s)
-- false — system disabled or not in a vehicle
```

Sets the internal `manualAFK` flag, which bypasses the idle-input sensitivity during fade-in (so the user's mouse movement from triggering the command doesn't instantly cancel).

### StopAFK

Exits AFK immediately. No-op if not currently AFK.

```lua
exports['tAFK']:StopAFK()
```

Returns nothing. Fires `tafk:stateChanged(false)` and clears the state bag.

### ToggleAFK

```lua
local isAfkNow = exports['tAFK']:ToggleAFK()
-- true  — was off, now on
-- false — was on, now off; OR system disabled / no vehicle
```

Does the right thing based on current state. Fires the appropriate event and state-bag write.

### IsAFKEnabled

```lua
local enabled = exports['tAFK']:IsAFKEnabled()
-- true | false
```

Reflects the **session** enable state, which respects the player's persistent `tafk:playerDisabled` KVP at boot. Different from `IsAFK()` — `IsAFKEnabled` says whether the system _can_ trigger; `IsAFK` says whether it _is_ triggering.

### SetAFKEnabled

```lua
local ok = exports['tAFK']:SetAFKEnabled(false)  -- suppress tAFK for this session
-- true on valid input; false if arg isn't a boolean
```

Session-only switch. Pass `false` to disable auto and manual triggers and stop an in-progress cinematic. Pass `true` to re-enable. Does **not** to KVP — for persistent player preferences, use the `/tafk` dialog.

---

## Client events

### `tafk:stateChanged`

Fires on the local client every time AFK state changes.

```lua
AddEventHandler('tafk:stateChanged', function(isAfk)
  if isAfk then
    -- entering AFK
  else
    -- leaving AFK
  end
end)
```

Single argument: `boolean`. Fires before the state bag is written, so handlers see the new local state but remote clients may not yet have received the bag update.

  `tafk:stateChanged` is a local event on one client only. To react to another player's AFK status,
  read `Player(src).state.afk` or subscribe to the state-bag change handler.

---

## State bags

### `LocalPlayer.state.afk`

Replicated player-state bag, set on AFK enter/exit and on resource start:

```lua
-- Set internally by tAFK — do not write from other scripts
LocalPlayer.state:set('afk', true, true)
```

Readable from any client or the server:

```lua
-- Client, any other client
local ok = Player(playerServerId).state.afk   -- true | false | nil

-- Server
local ok = Player(source).state.afk

-- State-bag change handler (any script)
AddStateBagChangeHandler('afk', nil, function(bagName, key, value, reserved, replicated)
    local playerId = GetPlayerFromStateBagName(bagName)
    -- playerId is the server ID; handle transitions
end)
```

`nil` means the player hasn't loaded tAFK yet (e.g., disconnected or resource not started). Treat `nil` as "not AFK" for most purposes.

---

## Server-side admin events

All admin events are registered via `exports['tLib']:RegisterAdminEvent(...)`, which gates on the `tlib.admin` ACE **before** the handler runs. Non-admins can trigger these events but the handler returns immediately.

Admin menus fire these from the client, but external scripts can too.

### `tafk:admin:updateSetting`

```lua
TriggerServerEvent('tafk:admin:updateSetting', key, value)
-- key:   'timeoutSeconds' | 'minDurationMs' | 'maxDurationMs' | 'beatAnchorMs'
--      | 'musicVolume'    | 'useMusic'      | 'hideHudInAFK'
-- value: coerced to the expected type server-side
```

Unknown keys log a warning and no-op.

### `tafk:admin:upsertSequence`

Create or update a global sequence.

```lua
TriggerServerEvent('tafk:admin:upsertSequence', {
    id = 'custom_hero_shot',
    name = 'Hero Shot',
    enabled = true,
    vehicles = { '*' },
    start = { offset = { x = 0, y = 4, z = 1 }, rotation = { x = 0, y = 0, z = 180 }, fov = 45, dof = {...} },
    ['end'] = { ... },
})
```

If an entry with the same `id` exists, it's replaced. Otherwise appended. Validated via `tafkValidateSequence` — failures toast back to the admin with the specific error.

### `tafk:admin:upsertVehicleSequence`

Same as above but written into `data.json.vehicleConfigs[<model>].sequences` via the Discovery instance.

```lua
TriggerServerEvent('tafk:admin:upsertVehicleSequence', 'bati801', seqObject)
```

### `tafk:admin:toggleSequence`, `tafk:admin:deleteSequence`

```lua
TriggerServerEvent('tafk:admin:toggleSequence', 'seed_01', false)  -- disable
TriggerServerEvent('tafk:admin:deleteSequence', 'seed_01')         -- permanent
```

  Music is discovered from the `audio/` folder at resource start (see [Configuration → Music
  tracks](/docs/tAFK/configuration#music-tracks)). There are no register/toggle/delete events — drop
  files into `audio/` and restart the resource.

---

## Client config events

### `tafk:request_config`

Client → server. Triggers the server to send its current config to this client. Useful if your script loads late.

```lua
TriggerServerEvent('tafk:request_config')
-- server replies with TriggerClientEvent('tafk:config_receive', src, mergedData)
```

### `tafk:config_receive`

Server → client. Carries the full `data.json` contents.

```lua
RegisterNetEvent('tafk:config_receive', function(data)
    -- data = { version, settings, sequences, musicTracks, ... }
end)
```

tAFK registers this internally — only subscribe from another resource if you need to mirror the config.

### `tafk:vcfg:config_receive`

Per-vehicle configs from Discovery. Payload is `{ [model] = { sequences = [...] } }`.

```lua
RegisterNetEvent('tafk:vcfg:config_receive', function(vehicleConfigs)
    -- keyed by lowercase model name
end)
```

Auto-requested on resource start via `tafk:vcfg:config_request`.

---

## Deprecation note

If you're upgrading from the legacy `tommys-afk` resource:

| Old                                               | New                                         |
| ------------------------------------------------- | ------------------------------------------- |
| `exports['tommys-afk']:IsAFK()`                   | `exports['tAFK']:IsAFK()`                   |
| `exports['tommys-afk']:StartAFK()`                | `exports['tAFK']:StartAFK()`                |
| `AddEventHandler('tommys-afk:stateChanged', ...)` | `AddEventHandler('tafk:stateChanged', ...)` |
| _(none)_                                          | `Player(src).state.afk`                     |

The resource name, all export names, and the event name changed. Update any integration code — there's no compatibility shim.

<!-- llms-full-doc-separator -->

# tRadio Configuration (https://timmygstudios.com/docs/tRadio/configuration)
Complete configuration reference for Tommy's Radio — config.lua, framework hooks, zones and channels, codeplugs, every admin panel setting, sounds, and integrations.

## Where each setting lives

| Source                    | Contains                                                                             | Edited in           | Applies                |
| ------------------------- | ------------------------------------------------------------------------------------ | ------------------- | ---------------------- |
| `config/config.lua`       | Network, auth, Discord, framework, inventory                                         | Text editor         | After `restart tRadio` |
| `config/sv_functions.lua` | Server hooks — job→codeplug mapping, access, player names, 911 caller ID             | Text editor         | After `restart tRadio` |
| `config/cl_functions.lua` | Client hooks — `canTalk`, battery, background sound detection, animations            | Text editor         | After `restart tRadio` |
| `data.json`               | Zones, channels, codeplugs, alerts, speakers, towers, geo zones, all server settings | **Web admin panel** | Instantly, no restart  |

The rule of thumb: a setting lives in a `.lua` file only if it is a genuine Lua function, or if applying it binds a port or registers a command that FiveM cannot undo. Everything else is in the admin panel at `http://your-server-ip:port/admin`.

---

## config.lua

### Server and authentication

```lua
Config = {
    serverAddress     = "http://203.0.113.10:7777",
    isSatelliteServer = false,
    serverPort        = 7777,
    authToken         = "<20+ random characters>",
    adminPassword     = "<your admin password>",
    dispatchNacId     = "4417",
}
```

| Key                 | Default       | Description                                                                                                                                                              |
| ------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `serverAddress`     | `"localhost"` | Public IP or domain of the voice server, including the port. `""` auto-detects the public IP. Behind a reverse proxy, use the full URL: `"https://radio.yourdomain.com"` |
| `isSatelliteServer` | `false`       | `true` on secondary game servers that federate into one shared host — see [Multi-server federation](#multi-server-federation)                                            |
| `serverPort`        | `7777`        | TCP port for the voice server, dispatch panel, and admin panel. Must be free and open                                                                                    |
| `authToken`         | `"CHANGE_ME"` | Shared secret between the game server and the voice server. Use 20+ random characters                                                                                    |
| `adminPassword`     | `"141"`       | Web admin panel password. `""` disables password login (Discord auth then required)                                                                                      |
| `dispatchNacId`     | `"141"`       | Passphrase dispatchers type on the dispatch panel login screen. Not related to in-game channel access                                                                    |

  `dispatchNacId`, a codeplug's `nac`, and the NAC shown on a radio screen are three different
  things. None of them gate which channels a player can use — that is entirely [codeplugs and ACE
  grants](#codeplugs).

### Discord authentication

Optional OAuth for the dispatch panel and the admin panel. Create an application at the [Discord Developer Portal](https://discord.com/developers/applications), then add both redirect URIs under **OAuth2 → Redirects**:

```
http://203.0.113.10:7777/radio/dispatch/auth
http://203.0.113.10:7777/admin/auth/callback
```

```lua
Config = {
    discord = {
        authEnabled  = true,
        clientId     = "1284739201847362048",
        clientSecret = "<your discord client secret>",
        guildId      = "938271046582910384",
        roles        = "938271046582910111,938271046582910222",
        adminRoles   = "938271046582910333",
        redirectUri  = "",
    },
}
```

| Key            | Default | Description                                                                                         |
| -------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `authEnabled`  | `false` | Require Discord login for the **dispatch** panel. Every other field is ignored when this is `false` |
| `clientId`     | `""`    | Discord application client ID                                                                       |
| `clientSecret` | `""`    | Discord application client secret                                                                   |
| `guildId`      | `""`    | Your Discord server (guild) ID                                                                      |
| `roles`        | `""`    | Comma-separated role IDs allowed into the dispatch panel. `""` allows any guild member              |
| `adminRoles`   | `""`    | Comma-separated role IDs allowed into the **admin** panel. `""` disables Discord admin access       |
| `redirectUri`  | `""`    | Override the OAuth redirect. Only needed behind a reverse proxy or custom domain                    |

Password and Discord login can both be active — the login page shows both. Dispatch sessions last 24 hours; role changes take effect at next login.

### Framework detection

```lua
Config = {
    framework          = 'auto',
    frameworkResources = {
        esx = 'es_extended', qbcore = 'qb-core', qbx = 'qbx_core',
        nd = 'ND_Core', ox_core = 'ox_core', nat2k15 = 'framework',
    },
    autoRefreshOnJobChange = true,
}
```

| Key                      | Default   | Description                                                                                                                      |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `framework`              | `'auto'`  | `'auto'`, `'esx'`, `'qbcore'`, `'qbx'`, `'nd'`, `'ox_core'`, `'nat2k15'`, or `'custom'`                                          |
| `frameworkResources`     | see above | Resource names used for detection. Only change these if you renamed a framework resource                                         |
| `autoRefreshOnJobChange` | `true`    | Listen for your framework's job-change event and refresh the player's codeplug immediately instead of waiting for the ~15 s poll |

`'auto'` probes in order: qbx → qbcore → esx → nd → ox_core → nat2k15, falling back to `'custom'`. The job-change listeners live in escrow-protected server code, not in `sv_functions.lua`, so they survive an upgrade even if you keep a customised `sv_functions.lua`. Set `autoRefreshOnJobChange = false` only if your own code already calls `exports['tRadio']:refreshNacId(source)`.

### Inventory item requirement

```lua
Config = {
    inventory = {
        enabled = true,
        item    = 'radio',
        system  = 'auto',
    },
}
```

| Key       | Default   | Description                                                 |
| --------- | --------- | ----------------------------------------------------------- |
| `enabled` | `false`   | When `true`, a player must carry the item to open the radio |
| `item`    | `'radio'` | Item name as registered in your inventory resource          |
| `system`  | `'auto'`  | `'auto'`, `'ox_inventory'`, `'qb'`, `'esx'`, or `'custom'`  |

`'auto'` tries ox_inventory first, then falls back to the active framework's inventory. When the item requirement is enabled, tRadio also **registers the item as usable automatically** for ox_inventory, QBCore, QBX, and ESX — using it from the inventory opens the radio. You do not need to write a `CreateUseableItem` call.

  tRadio never creates the item. Add it to your inventory resource's item list before enabling this.
  On ox_inventory installs bridged to ESX or QBox, item use is routed before tRadio's hook is
  consulted — if using the item does nothing, add `client.event = "radio:client:openRadio"` to the
  radio entry in your `items.lua`.

Grant the `tRadio.access` ACE to let specific players or groups bypass the item check. For an unsupported inventory such as VORP, set `system = 'custom'` and replace `Config.playerHasRadioItem` in `sv_functions.lua`:

```lua
Config.playerHasRadioItem = function(serverId)
    local item = (Config.inventory and Config.inventory.item) or 'radio'
    local p = promise.new()
    exports.vorp_inventory:getItemCount(serverId, item, function(count) p:resolve(count) end)
    return (Citizen.Await(p) or 0) >= 1
end
```

---

## Framework integration

### Assigning codeplugs to jobs

A player needs a codeplug to open a radio at all. Map jobs to codeplug IDs in `config/sv_functions.lua`. Keys must match a codeplug's `id` in the admin panel. Changes require `restart tRadio`.

`config/sv_functions.lua (shipped)`

```lua
local JOB_CODEPLUG_MAP = {
    ['police']    = 'leo',
    ['sheriff']   = 'leo',
    ['ambulance'] = 'leo',
    ['fire']      = 'leo',
}
```

The lookup is case-insensitive, and works unchanged on ESX, QBCore, QBX, ND_Core, ox_core, and nat2k15 — the framework-specific job lookup is already written for you. On nat2k15, keys are dept level keys (`'lspd_level'`, `'bcso_level'`) rather than job names.

**Different codeplugs per rank.** A value can be a table of grade thresholds instead of a plain string. The highest threshold at or below the player's grade wins:

```lua
local JOB_CODEPLUG_MAP = {
    ['police'] = { [0] = 'leo', [3] = 'leo-supervisor', [8] = 'leo-command' },
    ['fire']   = 'fire',
}
```

Grades 0–2 get `leo`, 3–7 get `leo-supervisor`, 8+ get `leo-command`. A grade below the lowest key gets no codeplug — the same secure default as an unmapped job.

  Civilians and any job not listed receive no codeplug. Returning a fallback codeplug would silently
  grant that job whatever the fallback allows — and a codeplug with empty access lists resolves to
  "every zone". If you do want open access, uncomment the `return 'leo'` line at the bottom of
  `Config.getPlayerCodeplugId` and make sure that codeplug's lists are deliberately broad.

With `framework = 'custom'` and no changes, every player receives the `leo` codeplug.

### Server hooks

All four live in `config/sv_functions.lua` and ship with working implementations for every supported framework. Edit them only to change behaviour.

| Hook                                   | Returns                     | Called                                                                                                                                                         |
| -------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.getPlayerAccess(serverId)`     | `boolean`                   | On every server-side radio event. `false` denies the radio entirely. The shipped version checks the inventory item (when enabled) and then requires a codeplug |
| `Config.playerHasRadioItem(serverId)`  | `boolean`                   | Only when `Config.inventory.enabled` is `true`. Replace this when `system = 'custom'`                                                                          |
| `Config.getPlayerCodeplugId(serverId)` | codeplug ID string or `nil` | On access resolution. The shipped version reads `JOB_CODEPLUG_MAP`                                                                                             |
| `Config.getPlayerName(serverId)`       | `string`                    | For the name shown on radios and the dispatch panel. Falls back to extracting a callsign suffix such as `1A-12` from the server display name                   |

### Refreshing access after a job change

With `autoRefreshOnJobChange = true` (the default) this is automatic on QBCore, QBX, ESX, ND_Core, and ox_core. nat2k15 has no job-change event and relies on the ~15 s poll.

To trigger it yourself from your own resource:

```lua
exports['tRadio']:refreshNacId(source)
```

Access is re-resolved immediately and pushed to the client. A player sitting on a channel they can no longer reach is disconnected from it.

### Client hooks

In `config/cl_functions.lua`.

**`Config.canTalk()`** — runs while PTT is held. Return `false` to block transmission.

```lua
Config.canTalk = function()
    if IsPlayerDead(PlayerId()) then return false end
    if IsPedSwimming(PlayerPedId()) then return false end
    return true
end
```

If this starts returning `false` mid-transmission, the client force-stops PTT and logs `canTalk check failed mid-transmission` to F8. This is the most common non-hardware cause of "my mic doesn't work".

**`Config.batteryTick(currentBattery, deltaTime)`** — returns the new battery level. `deltaTime` is in seconds, so rates are battery-percent per second.

```lua
Config.batteryTick = function(currentBattery, deltaTime)
    local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
    if vehicle ~= 0 then
        return math.min(100.0, currentBattery + (0.5 * deltaTime)) -- full charge in ~3 min
    else
        return math.max(0.0, currentBattery - (0.1 * deltaTime))   -- full drain in ~17 min
    end
end
```

Charging in **any** vehicle, driver or passenger, with no dock prop, is intentional. Add your own vehicle-type or prop condition here to restrict it. To switch battery drain off entirely, use **Battery Drain** in **Admin Panel → Settings → General** — that skips this hook and holds every battery at 100%.

**`Config.bgModeCheck()`** — polled about every 500 ms. Returns a mode string that selects the background sound other players hear behind your voice, or `false` for silence. The shipped version returns `"helicopter"` when piloting a helicopter, `"k9"` when a dog ped from `Config.k9Models` is in a passenger seat, and otherwise delegates to the configured siren provider. Mode strings map to WAV files in **Admin Panel → Sounds → Background Sound Modes**; see [Background sounds](#background-sounds).

**`Config.k9Models`** — ped model names that trigger `"k9"`. Ships with seven GTA dog models; add your own custom K9 peds here.

**`Config.animations`** — the animation list players choose from in their settings. See [Animations](/docs/tRadio/usage#animations).

---

## Zones and channels

Managed live in **Admin Panel → Zones & Channels**. Changes reach every connected client in real time.

A **zone** is a group of channels — usually a region or an agency. A **channel** is one frequency inside it.

### Channel types

**Conventional** — one shared frequency. Everyone connected hears everyone else regardless of location. Use this for almost everything.

**Trunked** — units are assigned a sub-frequency automatically based on where they are, so crews in different parts of the map do not step on each other. Dispatchers reach every unit through the control frequency. Requires a frequency range (the sub-frequency pool) and a coverage radius in metres (the cell size).

### Channel fields

| Field               | Type        | Default        | Description                                                                              |
| ------------------- | ----------- | -------------- | ---------------------------------------------------------------------------------------- |
| Name                | string      | —              | Display name on the radio, e.g. `DISP`                                                   |
| Frequency           | number      | —              | MHz. Must be unique across all zones                                                     |
| Type                | select      | `conventional` | `conventional` or `trunked`                                                              |
| Mode                | select      | `analog`       | `p25_digital` runs this channel's audio through the P25 IMBE vocoder; `analog` does not  |
| Dispatch            | toggle      | off            | **Monitor only** — dispatchers can listen but not transmit (stores `canTransmit: false`) |
| Frequency range     | two numbers | —              | Trunked only. Start and end of the sub-frequency pool                                    |
| Coverage            | number      | —              | Trunked only. Cell radius in metres                                                      |
| Encryption          | select      | `clear`        | `secure` marks the channel encrypted on the display                                      |
| GPS colour override | blip ID     | unset          | Overrides the codeplug's GPS colour for players on this channel only                     |

Each channel has a generated **channel ID** shown in small text under its name (for example `disp-lx1gi`). That ID is what codeplugs reference — not the frequency, and not the name.

### Hiding a zone from dispatch

Each zone has a **Hide from dispatch** toggle. A hidden zone is withheld from the dispatch panel entirely: its channels do not appear, and its traffic stays out of the transmission log and user counts. In-game it works exactly as before.

Use it for zones that exist purely for roleplay — civilian, criminal, or business radio — that would otherwise clutter a dispatcher's board.

  Hiding a zone does not change which players can use its channels. To restrict *player* access, use
  codeplug channel access. A dispatcher connected to or scanning a channel when you hide its zone is
  removed from it on the next config refresh, and announcement groups skip hidden channels when
  broadcast.

### Announcement groups

Also on the Zones & Channels page. A group is a named set of channel IDs. A dispatcher arms a group and their next PTT fans out to every channel in it simultaneously. The panel shows a **GROUPS** bar above the zone list whenever at least one group exists, and each group can get its own PTT key.

Two ship by default: `* DISP` and `* C2C`, each spanning all three starter zones.

### Geo zones

**Admin Panel → Geo Zones.** A circular area that switches a player's radio to a target frequency when they walk in, and switches back when they leave.

| Field              | Description                                                                         |
| ------------------ | ----------------------------------------------------------------------------------- |
| Position (X, Y, Z) | World coordinates of the centre                                                     |
| Radius             | Metres                                                                              |
| Vertical bounds    | Optional min/max world Z, for stacked areas like parking garages. Min must be ≤ max |
| Target frequency   | Must match a frequency on a configured channel, or the save is rejected             |

Auto-switching is **opt-in per player and per zone**. A player must enable both the master **Geo Auto-Switch** toggle and the individual zone's checkbox in `/tradio` → Style. Zones a player's codeplug cannot reach are hidden from that list.

Use `/_tradio_coords` in-game to copy your current position straight into the X/Y/Z fields.

---

## Codeplugs

A codeplug is a radio personality: which channels a player gets, which radio models they can pick, which features are on, and what their emergency button does. Managed in **Admin Panel → Codeplugs**; job assignment happens in `sv_functions.lua`.

<video
  class="not-prose my-6 w-full rounded-2xl"
  width="960"
  height="540"
  autoPlay
  muted
  loop
  playsInline
  preload="metadata"
  poster="/assets/tRadio/codeplugs-poster.jpg"
>
  <source src="/assets/tRadio/codeplugs.webm" type="video/webm" />
  <source src="/assets/tRadio/codeplugs.mp4" type="video/mp4" />
</video>

### Codeplug sections

| Section                     | What you set                                                                                                                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Identity**                | ID (locked after creation — it is what `JOB_CODEPLUG_MAP` and ACE grants reference), name, and NAC. The NAC is cosmetic: it shows on the radio screen and dispatch panel and gates nothing    |
| **Allowed Models**          | Which radio models players may select. Selecting none leaves them with no radio                                                                                                               |
| **Default Layouts**         | The model shown first per context — on-foot focused, on-foot unfocused, ground vehicle, watercraft, air vehicle. Also per-spawncode and per-spawncode+livery overrides, which take priority   |
| **Channel Access**          | Channels this codeplug can connect and transmit on. Scan access is granted automatically for these. **Zone access is derived** — a zone is granted as soon as any of its channels is selected |
| **Scan Access**             | Extra listen-only channels on top of the connect-access ones                                                                                                                                  |
| **Scan Lists**              | Named presets players load from `/tradio` → Scan Lists to populate their scan channels in one click. Each entry has a priority: 1 High, 2 Normal, 3 Low                                       |
| **Features**                | GPS Blips, Scan, Emergency Button, Man Down                                                                                                                                                   |
| **Supervisor Access**       | Grants the in-game **SGN** sign-on button and trunked control-channel access, without granting server admin rights                                                                            |
| **Emergency Configuration** | Which channel to switch to on emergency (or stay put), auto-transmit on/off, transmit duration in seconds, and panic tone repeat interval                                                     |
| **GPS Visibility**          | Which _other_ codeplugs' blips a player on this codeplug can see, plus this codeplug's own blip colour and its flash colour during panic                                                      |

**Minimum viable codeplug:** an ID, a name, at least one allowed model, and at least one channel. Everything else has a safe default.

Codeplug changes reach a player the next time their job loads or you call `refreshNacId`.

### How access is resolved

Every radio open attempt and every `refreshNacId` call runs this chain. A player gets the union of codeplug access and ACE grants.

| Step | Gate                                                                                                    | Denied when                                                   |
| ---- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| 1    | `Config.getPlayerAccess(serverId)`                                                                      | Returns `false` — no radio at all                             |
| 2    | Codeplug assignment via `JOB_CODEPLUG_MAP`, `Config.getPlayerCodeplugId`, or `tRadio.codeplug.{id}` ACE | No codeplug — no radio                                        |
| 3    | Zone visibility — derived from selected channels, or `tRadio.zone.{N}` ACE                              | No channel in the zone and no ACE                             |
| 4    | Channel connect — codeplug channel access or `tRadio.connect.{freq}` ACE                                | Neither — channel hidden                                      |
| 5    | Scan — codeplug scan access, connect access, or `tRadio.scan.{freq}` ACE                                | Neither — no scan                                             |
| 6    | GPS visibility — codeplug GPS Visibility list or `tRadio.gps.{freq}` ACE                                | Neither — no blips                                            |
| 7    | Supervisor controls (SGN, trunked CT/TK)                                                                | Requires `tlib.admin` ACE or the codeplug's Supervisor toggle |

### ACE permissions

An alternative or supplement to codeplug assignment. `tRadio.codeplug.{id}` has the highest priority and overrides `JOB_CODEPLUG_MAP`.

| ACE                     | Grants                                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| `tRadio.access`         | Bypass the inventory item requirement                                                                       |
| `tRadio.codeplug.{id}`  | Assign codeplug `{id}` directly                                                                             |
| `tRadio.connect.{freq}` | Connect and transmit on a frequency                                                                         |
| `tRadio.scan.{freq}`    | Scan (listen only) a frequency                                                                              |
| `tRadio.gps.{freq}`     | See GPS blips on a frequency                                                                                |
| `tRadio.zone.{N}`       | Access zone N by its **1-based position** in the zone list                                                  |
| `tlib.admin`            | In-game SGN button, trunked CT/TK controls, and the 3D prop editor. Does **not** unlock the web admin panel |

Frequency keys drop the decimal point: `154.815` → `154815`, `856.1125` → `8561125`.

`server.cfg`

```txt
add_ace group.admin tRadio.access allow
add_ace identifier.steam:110000100000001 tRadio.codeplug.leo allow
add_ace group.ems tRadio.connect.154755 allow
add_ace group.ems tRadio.scan.8561125 allow
add_ace group.ems tRadio.gps.154755 allow
add_ace group.ems tRadio.zone.1 allow
add_ace group.admin tlib.admin allow
```

  Zone ACEs key off a zone's position in the list, not a stable ID. Deleting a zone shifts every
  later-numbered grant. Review your ACE config after reordering or deleting zones — the admin panel
  warns you at the point of deletion.

---

## Server settings

**Admin Panel → Server Settings**, four tabs. Every value below applies live to all connected clients unless marked **restart required**.

### General tab

| Setting                     | Default    | Description                                                                                                                                                                                            |
| --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Check for Updates           | `true`     | Check for new tRadio versions on start. Read live                                                                                                                                                      |
| Include Pre-release Updates | `false`    | Also pull release candidates. For testers. Read live                                                                                                                                                   |
| 911 Calling                 | `true`     | **Experimental.** Master switch for the whole 911 system. Disabling is enforced immediately server-side, but the `/911` command itself only disappears for players who reconnect. **Restart required** |
| 911 Call Cooldown           | `30` s     | **Experimental.** Minimum wait between a player's 911 calls. `0` disables it; a 5-second server backstop still applies. Read live                                                                      |
| Low Battery Chirp           | `true`     | Warning chirp under 50% battery, more frequent under 30%                                                                                                                                               |
| Battery Drain               | `true`     | When off, every battery is held at 100% and `Config.batteryTick` is skipped                                                                                                                            |
| Log Level                   | `3`        | `0` Error · `1` Warnings · `2` Minimal · `3` Normal · `4` Debug · `5` Verbose. Applies live                                                                                                            |
| Radio Blips                 | `true`     | Master switch for minimap blips of players on your channel                                                                                                                                             |
| Blip Update Rate            | `50` ms    | Client-side render interval. Below 50 ms is not recommended                                                                                                                                            |
| Radio Animations            | `true`     | Show the animation selector in player settings                                                                                                                                                         |
| Focus Layout Mode           | `false`    | Default for new players — a separate radio skin when the UI is open but unfocused. Needs a `HandheldUnfocused` default layout                                                                          |
| Enable Callsigns            | `true`     | Let players set a personal callsign                                                                                                                                                                    |
| Callsign Command            | `callsign` | The chat command name, without the slash. **Restart required**                                                                                                                                         |
| Man-Down by Default         | `false`    | New players have man-down monitoring on                                                                                                                                                                |
| Warning Delay               | `45` s     | How long a player must be down before the warning tone. Range 10–300                                                                                                                                   |
| Emergency Delay             | `20` s     | Time after the warning before it escalates to a full emergency broadcast. Range 5–120                                                                                                                  |
| TTS by Default              | `true`     | New players hear spoken zone and channel announcements when switching                                                                                                                                  |

### Audio & Radio tab

  The admin panel and dispatch panel use **0–100**. The Lua export API uses **0.0–1.0**. Divide by
  100 when passing a config value to an export: `voiceVolume = 65` → `setVolume(0.65)`.

**Audio Defaults** — applied when a player first connects; they can override them.

| Setting         | Default | Description                                      |
| --------------- | ------- | ------------------------------------------------ |
| Voice Volume    | `65`    | Default radio voice volume (0–100)               |
| SFX Volume      | `35`    | Default tone and effect volume (0–100)           |
| 3D Audio Volume | `50`    | Default 3D spatial volume (0–100)                |
| Volume Step     | `5`     | Change per press of a volume keybind. Range 1–25 |

**PTT & Transmission**

| Setting                | Default  | Description                                                                                                          |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| PTT Release Delay      | `350` ms | How long the radio stays open after releasing PTT, so speech is not clipped. Range 0–2000                            |
| PTT Triggers Proximity | `true`   | With no radio equipped, PTT activates proximity voice instead of doing nothing. Requires MumbleVoice proximity audio |
| Transmission Tones     | `true`   | Play `TX_START` / `TX_END` tones when someone begins or ends transmitting                                            |
| Analog Tones           | `true`   | Use analog-style squelch sounds (`PTT` / `PTT_END`, heard by the transmitter) instead of the digital receiver tones  |
| Panic Alert Timeout    | `60` s   | How long a panic stays active before auto-clearing. `0` = manual clearance only                                      |
| Panic Alert Cooldown   | `15` s   | Minimum wait before the same player can panic again on that channel                                                  |

**Half-Duplex (Bonking)** — what happens when someone keys up while another unit is talking.

| Setting             | Default   | Description                                                                              |
| ------------------- | --------- | ---------------------------------------------------------------------------------------- |
| Block Transmission  | `true`    | Deny the PTT attempt. When off, the transmission goes through but a collision tone plays |
| Play Bonk Tone      | `true`    | Play a tone to the blocked user                                                          |
| Bonk Tone to All    | `true`    | Everyone on the channel hears it, not just the sender                                    |
| Double-Tap Override | `true`    | Two quick PTT presses force a blocked transmission through                               |
| Double-Tap Window   | `1500` ms | How close the two presses must be. Range 100–5000                                        |

**3D Positional Audio** — everything below the master switch is hidden until it is on.

| Setting                | Default | Description                                                                      |
| ---------------------- | ------- | -------------------------------------------------------------------------------- |
| Enable 3D Audio        | `false` | Master switch — allows players to turn 3D audio on                               |
| 3D Audio On by Default | `false` | New players start with it enabled (their Earbuds toggle off)                     |
| Vehicle 3D Audio       | `true`  | A vehicle the player has been in keeps rebroadcasting their radio from itself    |
| Vehicle 3D Distance    | `3` m   | How far the player must walk from the vehicle before it takes over as the source |
| Player Speaker Range   | `35` m  | How far a handheld radio carries                                                 |
| Vehicle Speaker Range  | `60` m  | How far a vehicle-sourced radio carries                                          |

**Signal Coverage**

| Setting               | Default | Description                                                                   |
| --------------------- | ------- | ----------------------------------------------------------------------------- |
| Always Full Signal    | `false` | Force full bars and no degradation, without deleting your tower configuration |
| Signal Degradation    | `false` | Reduce audio quality with distance from the nearest tower                     |
| Falloff Rate          | `24`    | How fast quality drops with distance. `0` gradual, `100` steep                |
| Degradation Intensity | `50`    | How severe the degradation is at low signal                                   |

Degradation does nothing until towers exist — see [Signal towers](#signal-towers).

**Dispatch Scanning**

| Setting                 | Default | Description                                                                                                                                           |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Simultaneous Scan Audio | `false` | Off: a transmission on the dispatcher's main channel mutes scanned channels until it ends. On: every scanned channel plays independently, overlapping |

**Radio Audio Effects** — see [Radio FX](#radio-fx).

### Controls tab

Default keybinds registered through FiveM's `RegisterKeyMapping`. Players can rebind any of them in **FiveM → Settings → Key Bindings → FiveM**. Click a field to capture a key, right-click to clear it (registering the action unbound).

| Action                                                                                                       | Default                                        |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| Push-to-Talk                                                                                                 | `B`                                            |
| Toggle Radio                                                                                                 | `F6`                                           |
| Voice Volume Up / Down                                                                                       | `=` / `-`                                      |
| SFX Volume Up / Down                                                                                         | `]` / `[`                                      |
| Close Radio, Power, Channel Up/Down, Zone Up/Down, Menu Up/Down/Left/Right/Home, Menu Buttons 1–3, Emergency | unbound                                        |
| Style Up / Down                                                                                              | unbound — hidden unless Radio Animations is on |
| 3D Volume Up / Down                                                                                          | unbound — hidden unless 3D Audio is on         |

### Advanced tab

**Earpiece / Items** — GTA outfit slots that switch a player's earbuds on automatically. With earbuds active a player emits no 3D audio, so nearby players cannot hear their radio.

| Field       | Description                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Type        | `prop` for accessories, `component` for clothing                                                        |
| Slot        | The GTA slot — props include Hat/Helmet (0), Glasses (1), **Ear/Earpiece (2)**, Watch (6), Bracelet (7) |
| Drawable ID | The 0-based clothing variant index. Find it with a ped editor                                           |

Clothing is checked every 7 seconds. A manual earbud toggle is respected until the player's clothing changes again.

**LB Phone / LB Radio Integration** — see [LB Phone and LB Radio](#lb-phone-and-lb-radio). Experimental.

**ImperialCAD Integration** — see [ImperialCAD](#imperialcad).

---

## Sounds

**Admin Panel → Sounds.** All changes broadcast instantly.

### Tone catalog

Every tone is a named slot mapped to a WAV file. Map them under **Global Tone Mappings**, and upload new WAVs from **Marketplace → Sounds**.

| Tone                                                 | Plays when                                        |
| ---------------------------------------------------- | ------------------------------------------------- |
| `PTT` / `PTT_TRUNKED` / `PTT_PATCHED`                | You key up — conventional / trunked / patched     |
| `PTT_END` / `PTT_END_TRUNKED` / `PTT_END_PATCHED`    | You release                                       |
| `TX_START` / `TX_START_TRUNKED` / `TX_START_PATCHED` | Someone else keys up                              |
| `TX_END` / `TX_END_TRUNKED` / `TX_END_PATCHED`       | Someone else releases                             |
| `BEEP`                                               | Generic alert beep                                |
| `BONK`                                               | Transmission collision                            |
| `CHIRP`                                              | Short acknowledgement, also the low-battery chirp |
| `ECHO`                                               | Message received                                  |
| `PANIC`                                              | Panic button activation                           |
| `ALERT_A` / `ALERT_B` / `ALERT_C`                    | Default alert-tone slots                          |
| `ALERT_SIGNAL3`                                      | Signal 3 alert tone                               |
| `PRIORITY` / `PRIORITY_REPEAT`                       | Priority alert activation and each repeat         |
| `RING_OUT`                                           | Heard by a 911 caller while their call rings      |
| `RING_IN`                                            | Heard by dispatchers when a 911 call arrives      |

**Per-model overrides** replace a single tone for one radio model only, taking priority over the global mapping. You can also drop WAVs directly at `layouts/{MODEL}/sounds/{TONE_NAME}.wav`.

### Background sounds

These fixed-filename WAVs in `layouts/sounds/` play during a received transmission and cannot be renamed:

| File                                               | Purpose                                          |
| -------------------------------------------------- | ------------------------------------------------ |
| `transStart.wav`                                   | Click-in at the start of a received transmission |
| `transMid.wav`                                     | Looping background noise during it               |
| `transEnd.wav` / `transEnd1.wav` / `transEnd2.wav` | Click-out — one of the three is picked at random |
| `bgSiren.wav`                                      | Siren loop                                       |
| `bgHeli.wav`                                       | Helicopter rotors                                |
| `bgDog.wav`                                        | K9                                               |
| `bgShot.wav`                                       | Gunshot fallback                                 |

**Background Sound Modes** maps the strings `Config.bgModeCheck` returns to WAV files. Three ship mapped: `siren` → `bgSiren.wav`, `helicopter` → `bgHeli.wav`, `k9` → `bgDog.wav`. Return any other string from `bgModeCheck`, add the mapping here, and upload the WAV — unmapped modes simply play nothing.

For example, to play a different WAV per LVC siren tone, return distinct modes from `bgModeCheck`:

```lua
if tone == 2 then return "sirenWail" end
if tone == 3 then return "sirenYelp" end
if tone > 0  then return "siren"     end
```

then map `sirenWail` and `sirenYelp` here.

### Siren detection

Which ELS resource `bgModeCheck` reads to decide a siren is on.

| Provider                                          | Value            |
| ------------------------------------------------- | ---------------- |
| Auto — try each installed provider in order       | `auto` (default) |
| tELS only                                         | `tels`           |
| Luxart Vehicle Control only                       | `lvc`            |
| LVC Fleet only                                    | `lvc_fleet`      |
| ELS-FiveM only                                    | `els_fivem`      |
| JLS only                                          | `jls`            |
| Advanced Lighting System only                     | `als`            |
| Native GTA siren only                             | `native`         |
| Skip detection — implement `bgModeCheck` yourself | `custom`         |

Auto order is tELS → LVC / LVC Fleet → ELS-FiveM → JLS → ALS → native. Each provider returns "not my vehicle" when it does not recognise the car, so mixed fleets work. Resource-name overrides for tELS, LVC, and JLS are on the same page and only needed if you renamed one; LVC Fleet, ALS, and ELS-FiveM use events and need no name.

To force an immediate re-poll after a custom siren state change:

```lua
exports['tRadio']:NotifySirenChanged()
```

### Radio FX

The DSP chain applied to all incoming radio voice: `mic → input gain → highpass → lowpass → compressor → limiter → saturation → mid EQ → output`.

| Setting         | Default   | Range                                              |
| --------------- | --------- | -------------------------------------------------- |
| Radio FX        | `true`    | Master switch. Everything below is hidden when off |
| Distortion Mode | `classic` | `classic` hard-clip, `tube` smooth saturation      |
| Highpass Cutoff | `250` Hz  | 80–800                                             |
| Lowpass Cutoff  | `3500` Hz | 1200–8000                                          |
| Compression     | `60`      | 0–100                                              |
| Distortion      | `30`      | 0–100                                              |
| Mid Boost       | `2` dB    | −12 to 12                                          |
| Input Gain      | `1.65`    | 0.5–3.0                                            |

| Problem                     | Fix                                              |
| --------------------------- | ------------------------------------------------ |
| Too muffled, telephone-like | Raise Lowpass Cutoff to 4000–5000                |
| Too tinny or harsh          | Lower Highpass Cutoff to 150–200                 |
| Volume pumping              | Lower Compression                                |
| Crackling or clipped        | Lower Input Gain to 0.8–1.2, or lower Distortion |

**P25 is separate and per-channel.** There is no global P25 switch. Set a channel's **Mode** to `P25 Digital` and every listener on it — in-game, dispatch, and 3D bystanders — hears real IMBE vocoder audio. The analog FX chain applies on top. The first transmission of a session has a brief WASM warm-up.

---

## Alerts

**Admin Panel → Alerts.** An alert puts a coloured banner on every radio connected to the channel. The **first alert in the list** is what the in-game SGN button fires.

An alert has three phases, each with an optional tone: **activate** (once), **repeat** (persistent alerts only, every `repeatInterval`), and **deactivate** (once, on clear).

| Field                 | Default       | Description                                               |
| --------------------- | ------------- | --------------------------------------------------------- |
| Name                  | —             | Display text on the radio                                 |
| Color                 | —             | Hex colour of the banner                                  |
| Persistent            | `false`       | Stays active until manually cleared                       |
| Tone                  | —             | Single tone used for all phases                           |
| Multi-tone            | off           | Switches to separate activate / repeat / deactivate tones |
| Repeat every          | random 5–10 s | Gap between repeats. Minimum 1000 ms                      |
| Show banner on repeat | `true`        | Flash the banner on each repeat                           |
| Deactivate label      | `RESUME`      | Banner text shown on clearance                            |
| Deactivate color      | `#126300`     | Colour of the clearance banner                            |
| Tone Only             | `false`       | Play the tone with no visual banner                       |
| Channel filter        | all channels  | Restrict this alert to specific channels                  |

Four ship by default: SIGNAL 100, SIGNAL 3, Ping, and Bonk.

---

## Speakers

**Admin Panel → Speakers.** World-placed tone-board speakers that dispatchers can broadcast a tone to from the panel — station alerting, tone-outs, PA stingers.

| Field              | Default | Description                                                                                           |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| Position (X, Y, Z) | —       | World coordinates                                                                                     |
| Heading            | `0`     | Prop rotation in degrees. Only affects the visible prop                                               |
| Radius             | `60` m  | Audible reach. Controls both who receives the tone and how far it carries. Applies from the next tone |
| Prop Model         | none    | Optional. Leave blank to place no prop — the speaker still plays from its coordinates                 |
| Group              | none    | Speakers sharing a group name are one selectable target on the dispatch panel                         |

Grab coordinates in-game with `/_tradio_coords`. Dispatchers use them from the **Speakers** button in the dispatch panel; see [Usage](/docs/tRadio/usage#working-the-board).

---

## Signal towers

**Admin Panel → Towers.** Physical towers that provide coverage. Signal strength falls off with distance from the nearest one, and with **Signal Degradation** on, audio quality degrades with it.

| Field              | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| Name               | Label in the panel                                                 |
| Position (X, Y, Z) | World coordinates                                                  |
| Prop model         | Optional. Blank places no prop — the tower still provides coverage |

Signal strength is measured from the **nearest** tower, so coverage is a union of each tower's reach rather than a sum. Place them where you want usable comms, and leave gaps where you want players to lose signal.

Towers configured before this page existed are migrated automatically on first start, with no action needed.

---

## Integrations

### LB Phone and LB Radio

Fully managed in **Admin Panel → Settings → Advanced → LB Phone / LB Radio Integration**. Nothing to configure in `config.lua`.

  Both integrations are experimental, and the phone dial-in is an entry point into the [911
  system](/docs/tRadio/usage#911-calls), which is experimental in its own right. Leave them off if
  you would rather not run them on a live server yet.

| Setting                   | Default | Description                                                                                                                              |
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| LB Phone 911 Dial-In      | Off     | Players dial 911 from the in-game phone and receive call status as phone notifications. Requires `lb-phone`                              |
| LB Radio Frequency Mirror | Off     | Mirrors the player's frequency, connection status, and user count into LB Phone's Radio app. Read-only and cosmetic. Requires `lb-radio` |

The two are independent — you can run either one alone, or neither.

  While **LB Phone 911 Dial-In** is on, the `/911` chat command is **not registered at all**. Both
  routes reach the same queue, so nothing else changes. If lb-phone is not actually installed and
  started, players have no way to reach 911 — tRadio logs a warning at startup when it detects
  exactly this. Turn the setting off to get the chat command back.

The phone dial-in carries a restart badge: each player is given exactly one 911 entry point when they connect, and FiveM cannot un-register a chat command or an lb-phone custom number mid-session. Already-connected players keep whichever entry point they were given until they reconnect or the resource restarts. The mirror has no such constraint and applies live.

The 911 system as a whole is switched on and off in **Admin Panel → Settings → General → 911 Calling**.

### ImperialCAD

Fully managed in **Admin Panel → Settings → Advanced**. Nothing to configure in `config.lua`, and both toggles apply live.

| Setting                        | Default | Description                                                                       |
| ------------------------------ | ------- | --------------------------------------------------------------------------------- |
| Enable ImperialCAD Integration | `false` | Mirror every queued 911 call into ImperialCAD as a parallel call record           |
| Sync Panic to ImperialCAD      | `true`  | Also mirror radio panic activations into ImperialCAD's `Panic()` / `ClearPanic()` |

Requires the `ImperialCAD` resource to be started under exactly that name, with its own `imperial_community_id` and `imperialAPI` convars set per ImperialCAD's own docs. tRadio only calls its exports. If the integration is on but the resource is not running, tRadio logs the reason at startup and on every call rather than failing silently.

**Call ownership.** A mirrored call is deleted from ImperialCAD only if it dies _unanswered_ — queue timeout, or the caller hangs up while still ringing. Once a tRadio dispatcher accepts it, tRadio never touches ImperialCAD's copy again, on the assumption a CAD dispatcher now owns it.

### 911 hooks

Two optional hooks in `config/sv_functions.lua`. Both have sensible defaults and neither needs editing.

```lua
-- The caller ID a dispatcher sees. A real 911 dispatcher only ever gets a number,
-- so this — not getPlayerName — is what the call card shows.
-- Default: the caller's real LB Phone number when available, otherwise a stable
-- 555-XXXX placeholder derived from their license, so the same player always gets
-- the same number across sessions.
Config.getCall911CallerNumber = function(serverId)
    return "555-0142"
end

-- Fires when a call is placed while no dispatch panel is connected. The call still
-- queues and appears the moment a dispatcher logs in — this is an immediate,
-- best-effort notice so it is not silently missed.
-- Default: chat-broadcast to every player with radio access.
-- `call` fields: callerName, callerUnitId, callerNumber, message, coords, frequency, createdAt.
Config.call911NoDispatcherFallback = function(call)
    -- Discord webhook, NPC dispatch, or your own alerting here
end
```

  `radio:911:noDispatcherOnline(call)` fires as a normal server event, so you can `AddEventHandler`
  it from your own resource rather than editing `sv_functions.lua` — which keeps your customisations
  across a tRadio update. `radio:911:answered` and `radio:911:ended` work the same way.

---

## Multi-server federation

Run several game servers against **one** shared voice server and dispatch panel, so dispatchers see every unit in one place.

- **Host (Server A)** runs the voice backend. Leave `isSatelliteServer = false` and keep its own `serverAddress` and `authToken`.
- **Satellites (Server B and up)** run no backend of their own. They point at the host and federate player, panic, tone, and alert state to it over HTTP.

`config/config.lua` on each satellite:

```lua
Config = {
    serverAddress     = "http://203.0.113.10:7777", -- Server A's public URL, port included
    isSatelliteServer = true,
    authToken         = "<same value as Server A>", -- must match Server A exactly
}
```

  Federation requests are HMAC-signed with `authToken`. A mismatch fails validation and the
  satellite's players never appear on the host's dispatch panel.

A satellite binds no HTTP or Socket.IO server, so `serverAddress` must be set — an empty value is rejected with an explicit error at startup. Satellites also pull zone, channel, and codeplug config from the host roughly every 30 seconds, so an admin panel change on the host reaches them without a restart.

911 calls require the host's voice server, so a satellite's callers connect through Server A like everyone else.

<!-- llms-full-doc-separator -->

# tels Configuration (https://timmygstudios.com/docs/tels/configuration)
Vehicle config structure, developer-bundled configs, cross-vehicle references, and server defaults.

## Overview

All vehicle configuration lives in a single `data.json` at the resource root, keyed by vehicle model name. You almost never need to edit it by hand — the in-game editor is the source of truth.

The file is managed by tLib's **Discovery** module, which also scans other resources for bundled configs on server start. Any server edit to a vehicle writes back to this file.

```
tELS/
  data.json    — vehicle configs + server display defaults (all in one file)
```

---

## Vehicle config structure

Each model entry has four sections:

| Section    | Holds                                                     |
| ---------- | --------------------------------------------------------- |
| `leds`     | LED positions, rotations, sizes, groups, bone attachments |
| `patterns` | Color palettes, frame sequences, timing, playback flags   |
| `triggers` | Compound condition rules with actions                     |
| `siren`    | Tone slots, airhorn, horn / chirp behavior, suspend flags |
| `arges`    | Arges spotlight props (optional)                          |

### LED entry

`data.json / leds[]`

```json
{
  "id": "a3f1b2c4d5e6f7a8",
  "name": "Front Right 1",
  "x": 0.1,
  "y": 0.5,
  "z": 0.7,
  "yaw": 0,
  "pitch": 0,
  "roll": 0,
  "sw": 0.044,
  "sh": 0.02,
  "side": 1,
  "bone": "siren1",
  "groups": [
    "Right",
    "Front"
  ]
}
```

| Field                  | Type     | Notes                                                                                       |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `id`                   | string   | 16-char hex UUID — stable identity used by patterns. Never reference LEDs by name or index. |
| `x`, `y`, `z`          | number   | Local offset (relative to `bone` if set, otherwise the chassis)                             |
| `yaw`, `pitch`, `roll` | number   | Rotation in degrees                                                                         |
| `sw`, `sh`             | number   | Surface width and height, metres                                                            |
| `side`                 | number   | `1` Right, `2` Left, `3` Center                                                             |
| `bone`                 | string   | Optional vehicle bone name                                                                  |
| `groups`               | string[] | Display/filter tags                                                                         |
| `shape`                | string   | `"circle"`, or omit for rectangle (default)                                                 |
| `bloom`                | string   | `"corona"`, `"both"`, or omit for sprite-only                                               |
| `extra`                | number   | Optional GTA extra ID — LED only renders when that extra is enabled                         |

### Pattern entry

`data.json / patterns[]`

```json
{
  "name": "Code 3",
  "fps": 10,
  "colors": [
    {
      "r": 255,
      "g": 0,
      "b": 0,
      "a": 1.0,
      "name": "Red"
    },
    {
      "r": 0,
      "g": 120,
      "b": 255,
      "a": 1.0,
      "name": "Blue"
    }
  ],
  "frames": [
    {
      "cells": {
        "a3f1b2c4d5e6f7a8": 1,
        "b4e2c3d5f6a7b8c9": 2
      },
      "dimCells": {
        "a3f1b2c4d5e6f7a8": true
      },
      "duration": 1
    }
  ],
  "triggerOnly": false,
  "syncNear": false,
  "useEmergencyLights": false,
  "useHighBeams": false,
  "livery": 0
}
```

| Field                | Type    | Notes                                                            |
| -------------------- | ------- | ---------------------------------------------------------------- |
| `cells`              | object  | LED UUID → 1-based color index (0 = off)                         |
| `dimCells`           | object  | LED UUID → `true` for smooth interpolation into the next frame   |
| `duration`           | number  | Ticks at the pattern's `fps`                                     |
| `triggerOnly`        | boolean | Skipped by 9/0 cycling, still usable by trigger actions          |
| `syncNear`           | boolean | Sync the frame index across clients using the server clock       |
| `useEmergencyLights` | boolean | Hold GTA's native emergency-lights flag while this pattern plays |
| `useHighBeams`       | boolean | Hold high beams while this pattern plays                         |
| `livery`             | number  | Restrict to a specific livery index. Omit for any livery.        |

### Trigger entry

`data.json / triggers[]`

```json
{
  "id": "c5d6e7f8a9b0c1d2",
  "conditions": [
    "brake",
    "speed_30"
  ],
  "negated": [
    false,
    false
  ],
  "operator": "and",
  "enabled": true,
  "actions": [
    {
      "type": "pattern_overlay",
      "patternName": "Brake Warning"
    }
  ]
}
```

| Field        | Type      | Notes                                                                     |
| ------------ | --------- | ------------------------------------------------------------------------- |
| `id`         | string    | 16-char hex UUID — stable identity used by trigger refs                   |
| `conditions` | string[]  | See [Editor → Condition reference](/docs/tels/editor#condition-reference) |
| `negated`    | boolean[] | Parallel to `conditions`. `true` flips that condition.                    |
| `operator`   | string    | `"and"` or `"or"`                                                         |
| `actions`    | object[]  | See [Editor → Action types](/docs/tels/editor#action-types)               |
| `enabled`    | boolean   | Ignored when false                                                        |

Legacy triggers that use `{ trigger: "brake", patternName: "..." }` auto-migrate to the compound form on load.

### Siren config

`data.json / siren`

```json
{
  "tones": [
    {
      "name": "Wail",
      "sound": "VEHICLES_HORNS_SIREN_1",
      "serverSound": "",
      "serverSoundRef": "",
      "rumblerSound": "",
      "rumblerServerSound": "",
      "rumblerServerSoundRef": "",
      "enabled": true,
      "triggerOnly": false
    }
  ],
  "airhorn": "SIRENS_AIRHORN",
  "serverAirhorn": "",
  "serverAirhornRef": "",
  "serverAirhornRumbler": "",
  "serverAirhornRumblerRef": "",
  "hornInterrupt": true,
  "parkKill": true,
  "useNormalHorn": true,
  "hornProgrammable": false,
  "lightsSuspendTA": true,
  "lightsSuspendTakedown": true,
  "chirpTone": 1,
  "chirpByCode": false,
  "noUserControls": false,
  "disabledExtras": []
}
```

| Field            | Type     | Notes                                                                                                                                  |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `chirpByCode`    | boolean  | `true` = hold tone for full chirp duration; `false` = short 75–125 ms blips                                                            |
| `paEnabled`      | boolean  | `false` disables the PA mic on this vehicle. Omit or `true` to allow it.                                                               |
| `noUserControls` | boolean  | `true` disables all player keybinds (Q, R, 1-8, Alt, etc.) for this vehicle. Useful for cinematic or display-only vehicles.            |
| `disabledExtras` | number[] | GTA extra IDs (1–12) to force off on this vehicle. The specified extras will not be enabled regardless of the vehicle's default state. |

Server-sided sounds are preferred when configured **and** the player has `Server-sided Sirens` enabled in `/tels`. Otherwise the vanilla `sound` is used.

---

## Vehicle-developer export

Vehicle makers can bundle a tELS config inside the vehicle resource so it loads automatically on server start — no manual copy from the server owner.

### How it works

tLib's Discovery module scans every running resource for the `tels_config` metadata key. When it finds one, the referenced file is parsed and its configs are merged into tELS on boot. Server-owner edits in the editor are written to `data.json` and **take priority** over any bundled config, so customizations never get overwritten.

### Add metadata to `fxmanifest.lua`

`your-vehicle/fxmanifest.lua`

```lua
tels_config 'data/tels.json'
```

The default filename is `tels.json` — if you use that exact path, the metadata line can be omitted entirely.

### Create the config file

`your-vehicle/data/tels.json`

```json
{ "police4": { "leds": [ /* ... */ ], "patterns": [ /* ... */ ], "triggers": [ /* ... */ ], "siren": { /* ... */ } } }
```

Easiest workflow: configure the vehicle in-game with `/telsedit`, then copy that model's entry from `data.json` into your resource's `tels.json`.

### Ship the resource

Server owners install the vehicle resource as usual. tELS picks up the bundled config on start — confirmed in the server console.

---

## Cross-vehicle references

Don't duplicate patterns, triggers, or sirens across similar vehicles. Reference them instead, and edit the source once to update all referents.

### Reference shapes

`Single pattern reference`

```json
{
  "$ref": "police4",
  "patternName": "Code 3"
}
```

`Single trigger reference`

```json
{
  "$ref": "police4",
  "triggerId": "c5d6e7f8a9b0c1d2"
}
```

`Bulk import (all patterns or triggers)`

```json
{
  "$ref": "police4",
  "$all": true
}
```

`Siren config reference (top-level)`

```json
"sirenRef": "police4"
```

`Settings reference (top-level)`

```json
"settingsRef": "police4"
```

Pattern and trigger refs live inline in the `patterns` / `triggers` arrays — they stand in for the referenced item.

### Behavior

- Refs are resolved at access time, never copied.
- Editing a referenced pattern or trigger edits the **source** vehicle's data.
- Refs don't chain — a ref pointing at a ref won't resolve.
- Orphaned refs (source deleted) are cleaned up automatically after any save.
- The editor marks imported items with a **link** icon and items referenced by other vehicles with a **share** icon.

  Configure `police4` fully, then reference its patterns, triggers, and siren from `police5`,
  `police6`, and `police7`. Any future pattern edit only has to happen once.

---

## Server defaults

Admins with `tlib.admin` can save their current display settings as the server-wide fallback via `/tels → Set as Server Defaults`. Defaults are stored as top-level keys in `data.json` (the same file as vehicle configs) and sent to every client on connect.

| Setting           | Default    | Range     | Description                                                              |
| ----------------- | ---------- | --------- | ------------------------------------------------------------------------ |
| `bloom`           | 1.0        | 0.1 – 3.0 | Bloom brightness multiplier                                              |
| `envQuality`      | 4          | 0 – 4     | Environmental lighting quality (Off / Low / Medium / High / Smart)       |
| `lightingQuality` | 4          | 0 – 4     | LED render pipeline quality                                              |
| `hudVisible`      | true       | boolean   | HUD visibility fallback                                                  |
| `hudLayout`       | —          | string    | Default HUD layout name                                                  |
| `autoCalib`       | false      | boolean   | Whether auto-calibration runs periodically for clients who have opted in |
| `paRange`         | 25         | 5 – 150   | Default PA mic range in metres                                           |
| `paPreset`        | `"police"` | string    | Default PA submix preset (`"police"`, `"fire"`, or `"clean"`)            |

Players' personal KVP settings take priority — server defaults only apply where the player hasn't already picked a value.

---

## Discovery parameters

For reference, tELS configures tLib Discovery like this:

| Parameter        | Value                 |
| ---------------- | --------------------- |
| Metadata key     | `tels_config`         |
| Default filename | `tels.json`           |
| Local file       | `data.json`           |
| Log tag          | `Lightbar`            |
| Chat tag         | `[tELS]`              |
| Event prefix     | `tels`                |
| Receive event    | `tels:config_receive` |

If you're integrating or debugging, these are the strings to look for in the server console and in your own listeners.

<!-- llms-full-doc-separator -->

# tAFK Configuration (https://timmygstudios.com/docs/tAFK/configuration)
The data.json schema, per-vehicle sequence packs, admin settings, and player KVP overrides.

## Where configuration lives

tAFK has three layers of configuration, resolved at playback time:

| Layer                    | Scope                     | Storage                      | Owner                                         |
| ------------------------ | ------------------------- | ---------------------------- | --------------------------------------------- |
| **Built-in defaults**    | All players               | `shared/schema.lua`          | Resource — restored if `data.json` is missing |
| **Server state**         | All players, all vehicles | `data.json` at resource root | Admins via `/tafk` or direct JSON edit        |
| **Per-vehicle pack**     | One model                 | `<otherResource>/tafk.json`  | Vehicle pack authors                          |
| **Per-player overrides** | One player                | tLib KVP (`tafk:*` keys)     | The player, via `/tafk`                       |

Merge order (lowest to highest priority): defaults → data.json → player KVP for settings; data.json union per-vehicle pack union (never conflicts — different scopes) for sequences.

---

## `data.json` shape

Lives at `tAFK/data.json`. Created on first boot from `shared/schema.lua` defaults. Read once at server start. Editing `data.json` on disk requires a resource restart to take effect. Broadcast to clients via `tafk:config_receive`.

```json
title="data.json" { "version": 1, "settings": { "timeoutSeconds": 30, "useMusic": true, "musicVolume": 0.035, "hideHudInAFK": true, "beatAnchorMs": -15, "minDurationMs": 5000, "maxDurationMs": 10000 }, "sequences": [ { "id": "seed_01", "name": "Low Ground Wide Side Pan", "enabled": true, "vehicles": ["*"], "start": { "offset": [-6.0, -7.0, 0.1], "rotation": [3.0, 0.0, 30.0], "fov": 55.0, "dof": { "near": 2.0, "far": 20.0, "strength": 0.7 } }, "end": { "offset": [-5.0, -6.5, 0.1], "rotation": [3.0, 0.0, 28.0], "fov": 55.0, "dof": { "near": 2.0, "far": 20.0, "strength": 0.7 } } } ], "vehicleConfigs": { "bati801": { "sequences": [ { "id": "bati_low_pass", "name": "Low Pass", "vehicles": ["bati801"], "enabled": true, "start": {...}, "end": {...} } ] } } }
```

  Audio files are discovered automatically at server start by scanning the `audio/` folder. See
  [Music tracks](#music-tracks) below.

### `settings`

| Key              | Type        | Default | Description                                                                                                         |
| ---------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `timeoutSeconds` | int         | `30`    | Idle seconds before auto-AFK fires. Zero disables auto-trigger                                                      |
| `useMusic`       | bool        | `true`  | Whether to start music on AFK enter                                                                                 |
| `musicVolume`    | float (0–1) | `0.035` | NUI audio element target volume                                                                                     |
| `hideHudInAFK`   | bool        | `true`  | Whether to hide HUD + minimap while AFK. When `true`, `DisplayHud(false)` / `DisplayRadar(false)` fire on AFK enter |
| `beatAnchorMs`   | int         | `-15`   | Offset applied to next-beat timing. Negative = cut before beat (anticipation)                                       |
| `minDurationMs`  | int         | `5000`  | Lower bound for sequence duration; beat-sync stays within range                                                     |
| `maxDurationMs`  | int         | `10000` | Upper bound for sequence duration                                                                                   |

### `sequences[]`

Each entry:

| Field           | Type     | Notes                                                                                                                |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `id`            | string   | Stable identifier. Used for player opt-outs, admin edits. Generate once (`seq_<timestamp>` is fine) and never change |
| `name`          | string   | Display name in `/tafk` menus                                                                                        |
| `enabled`       | bool     | When `false`, skipped by the director                                                                                |
| `vehicles`      | string[] | `["*"]` = all vehicles. List specific model names (lowercase) to restrict. Match is case-insensitive                 |
| `start` / `end` | object   | See [Keyframe shape](#keyframe-shape)                                                                                |

### Keyframe shape

```json
{
  "offset":   [x, y, z],
  "rotation": [pitch, roll, yaw],
  "fov":      55.0,
  "dof":      { "near": 2.0, "far": 20.0, "strength": 0.7 }
}
```

- `offset` — vehicle-local coordinates (right = +x, forward = +y, up = +z). Metres
- `rotation` — degrees. Applied as delta to the implicit "point at vehicle" rotation at runtime
- `fov` — camera field of view in degrees (10–120)
- `dof.near` / `.far` — depth-of-field range in metres
- `dof.strength` — DOF intensity, 0 (no blur) to 1 (full)

Offsets also accept the alternate object form `{ "x": ..., "y": ..., "z": ... }` — both shapes round-trip through `tafkToVec3`.

### Music tracks

tAFK picks up audio files at server start. Supported extensions: `.ogg`, `.mp3`, `.wav`. There are two ways to get a file into the rotation:

**Option 1 — name it one of the recognised patterns (zero config):**

| Pattern        | Range | Example              |
| -------------- | ----- | -------------------- |
| `bg<N>`        | 1–99  | `bg1.ogg`, `bg6.ogg` |
| `track<N>`     | 1–99  | `track1.mp3`         |
| `afk<N>`       | 1–99  | `afk1.ogg`           |
| `music<N>`     | 1–99  | `music1.ogg`         |
| `cinematic<N>` | 1–99  | `cinematic1.wav`     |

**Option 2 — list _any_ filename in `audio/manifest.txt`:**

```txt
title="audio/manifest.txt" # One filename per line. Blank lines and #-comments are ignored. intro.ogg chill-beat.mp3 synthwave drive.wav
```

Both methods run at boot and results are merged (files listed in both places de-dupe). Delete a file from `audio/` or remove its line from `manifest.txt` and restart to drop the track.

  FiveM's Lua runtime has no directory-enumeration API — the server can't ask "what's in audio/?" on
  its own. The pattern scan uses `LoadResourceFile` to probe 1,485 known names at startup (99 × 5
  prefixes × 3 extensions), completes in milliseconds. `manifest.txt` fills the gap for any other
  name without you having to rename your files.

### `vehicleConfigs`

Managed by tLib's Discovery module — **do not edit this section directly in `data.json`**. The admin editor writes to it via `tafk:admin:upsertVehicleSequence`, and external vehicle packs contribute via `tafk_config` metadata. See below.

---

## Per-vehicle sequence packs

Vehicle resources can bundle their own AFK sequences. When the pack starts, tLib's Discovery module scans it for a `tafk_config` metadata key, loads the referenced JSON, and merges the keyed entries into the global `vehicleConfigs` map.

### Pack layout

```
my-vehicle-pack/
├── fxmanifest.lua
├── stream/mycar.yft, .ytd, ...
└── tafk.json
```

### Manifest declaration

```lua
title="fxmanifest.lua" fx_version 'cerulean' game 'gta5' files { 'tafk.json' } tafk_config 'tafk.json'
```

  `tafk_config` points at a single JSON file per resource. Multiple vehicles can live in the same
  file, keyed by model name.

### JSON shape

```json
title="tafk.json" { "mycar": { "sequences": [ { "id": "mycar_front_pan", "name": "Front Bumper Pan", "enabled": true, "vehicles": ["mycar"], "start": { "offset": [-0.8, 3.5, 0.4], "rotation": [-2.0, 0.0, 175.0], "fov": 42.0, "dof": { "near": 0.5, "far": 4.0, "strength": 1.0 } }, "end": { "offset": [0.8, 3.5, 0.4], "rotation": [-2.0, 0.0, 185.0], "fov": 42.0, "dof": { "near": 0.5, "far": 4.0, "strength": 1.0 } } } ] }, "mysecondcar": { "sequences": [ { ... } ] } }
```

- Top-level keys are **lowercase vehicle model names**
- Each value has `{ "sequences": [...] }` with entries in the same shape as `data.json.sequences[]`
- `vehicles` inside each entry should include the parent model for consistency but it's not enforced

### Priority rules

When the same model name appears in multiple running resources, Discovery deduplicates: the **first-scanned wins**. Server-side admin edits through the tAFK UI write to `data.json.vehicleConfigs` and take priority over pack entries.

### When configs refresh

- Server start — Discovery scans every running resource once
- `onResourceStart` — when a pack starts after server boot, its configs merge in and clients get a fresh broadcast
- Admin saves — `/tafkedit` with scope=vehicle writes and broadcasts immediately

---

## Admin settings via `/tafk`

Every field in `settings` is tunable from `/tafk` when the player has the `tlib.admin` ACE. Changes apply live:

- Sliders fire `tafk:admin:updateSetting` on every value change (coerced server-side to the correct type, clamped where needed)
- Checkboxes fire on toggle
- Server persists with the read-merge-write pattern (preserves `vehicleConfigs`) and broadcasts updated config to all clients

  Dragging a slider fires one event per step. With the step sizes chosen (5 for timeout, 500 for ms
  durations, 5 for beat anchor), a full drag produces ~100 events. This is intentional for live
  preview and stays well within FiveM's event-rate limits.

---

## Player KVP overrides

Backed by tLib's KVP module. Keys are prefixed `tafk:`:

| Key                   | Type            | Default             | Sets when…                                                |
| --------------------- | --------------- | ------------------- | --------------------------------------------------------- |
| `tafk:playerDisabled` | bool            | not-set (→ enabled) | Player toggles **AFK System** off in `/tafk`              |
| `tafk:music`          | bool            | not-set (→ inherit) | Player toggles **Music**                                  |
| `tafk:volume`         | float           | not-set (→ inherit) | Player moves the **Music Volume** slider                  |
| `tafk:hudHide`        | bool            | not-set (→ inherit) | Player toggles **Hide HUD While AFK**                     |
| `tafk:seqDisabled`    | string[] (JSON) | `[]`                | Player unchecks a sequence in **My Sequence Preferences** |

`tafkGetSettings()` in `cl_bridge.lua` layers these on top of the server-distributed values. `tafkGetSequences(model)` filters by `tafk:seqDisabled`.

---

## Reloading after manual edits

`data.json` is read once at resource start. If you edit the file directly, restart the resource (`restart tAFK` from console) to apply changes. Audio files in the `audio/` folder are also re-scanned on restart.

Invalid sequences are dropped with a warning log and never reach clients.

<!-- llms-full-doc-separator -->

# tels Editor (https://timmygstudios.com/docs/tels/editor)
In-game LED placement, Arges spotlights, pattern sequencing, trigger rules, and siren configuration.

## Overview

`/telsedit` opens the editor while you're in a vehicle (any seat). Requires the `tlib.admin` ACE.

### Tab workflow

Work the tabs in this order — each builds on the previous one.

1. **LEDs** — place (or auto-generate) the physical lights on the vehicle using a Three.js gizmo.
2. **Patterns** — arrange those LEDs into frame-by-frame flash sequences with live preview.
3. **Triggers** — compound condition rules that drive patterns, stages, and sirens from vehicle state.
4. **Sirens** — tone slots, airhorn, rumbler, and chirp sounds.
5. **Settings** — per-vehicle siren behavior (horn interrupt, park kill, suspend flags).
6. **Arges** _(optional)_ — attach and aim spotlight props.

All tabs share a single orbit camera. Press **Enter** at any point to save every tab at once; **Escape** to cancel without saving.

---

## Camera controls

| Input                  | Action                   |
| ---------------------- | ------------------------ |
| **Middle Mouse**       | Orbit around the vehicle |
| **Shift + MMB**        | Pan                      |
| **Shift + Ctrl + MMB** | Dolly (zoom)             |
| **Scroll Wheel**       | Zoom                     |

View-snap buttons and a "focus on selection" control are available in the sidebar.

---

## LEDs tab

  New to a vehicle? Click **Create from siren bones** in the sidebar. tELS scans the vehicle's
  `siren1`…`sirenN` bones and drops a starter LED at each one, pre-grouped and sided. It's the
  fastest way to go from empty editor to a working lightbar — you can refine positions after.

Click any LED in the 3D viewport or the sidebar list to select it. The gizmo appears at the selection center. Hold **Shift+click** for range select or **Ctrl+click** to toggle individual LEDs in the selection.

### LED properties

| Property                        | Description                                                                                               |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Position** `x, y, z`          | Local offset from the vehicle chassis, or from `bone` if one is set                                       |
| **Rotation** `yaw, pitch, roll` | Orientation in degrees — drives directional bloom / corona output                                         |
| **Size** `sw, sh`               | Surface width and height in metres                                                                        |
| **Side**                        | `1` Right, `2` Left, `3` Center — used by traffic-advisor patterns                                        |
| **Name**                        | Display name (e.g., "Front Right 1")                                                                      |
| **Groups**                      | Tags used to bulk-select and filter in the pattern editor                                                 |
| **Bone**                        | Optional vehicle bone name (e.g., `siren1`, `door_dside_f`)                                               |
| **Shape**                       | `rect` (default) or `circle`                                                                              |
| **Bloom**                       | `sprite`, `corona`, or `both`                                                                             |
| **Extra**                       | Optional GTA vehicle-extra ID (1–15). LED only renders when that extra is enabled on the spawned vehicle. |

### Identity

Every LED carries a 16-char hex UUID. Patterns reference LEDs by this UUID, never by name or array position — renaming, reordering, or regrouping LEDs never breaks a saved pattern.

### Custom LED textures

By default tELS uses its built-in LED sprite. Vehicle resources can supply their own PNG texture by declaring it in their `fxmanifest.lua`:

`your-vehicle/fxmanifest.lua`

```lua
tels_led_png 'textures/my_led.png' files { 'textures/my_led.png' }
```

tELS discovers this automatically when the resource starts and makes the texture available in the LED editor's texture picker.

### Bone attachment

When `bone` is set, `x/y/z` and `yaw/pitch/roll` are interpreted in the bone's local frame, so LEDs on doors, the hood, or the trunk move with those parts as they open.

### Multi-select operations

With multiple LEDs selected you can:

- Move, rotate, or scale them together
- Duplicate (`Shift+D`)
- Mirror left-to-right around the vehicle's centerline (`Shift+M`)
- Swap positions (pairs)
- Delete (`Delete` or `Backspace`)
- Batch-edit any shared property in the properties panel

### Keyboard shortcuts (LEDs tab)

| Shortcut               | Action                                           |
| ---------------------- | ------------------------------------------------ |
| **W / R / S**          | Switch the gizmo to translate, rotate, or scale  |
| **X**                  | Toggle between world-space and local-space gizmo |
| **Q / E**              | Select previous / next LED                       |
| **Shift+D**            | Duplicate selected LEDs                          |
| **Shift+M**            | Mirror selected LEDs                             |
| **Delete / Backspace** | Remove selected LEDs                             |
| **Ctrl** (held)        | Temporarily toggle grid snap                     |

Global shortcuts (all tabs): **Ctrl+Z / Ctrl+Y** undo/redo · **Enter** save and exit · **Escape** cancel and exit.

---

## Arges tab

Arges spotlights are attachable light props (base + head + arm) that track an aim direction. They're useful for roof-mounted worklights or side spotlights.

Each Arges entry has:

| Property                  | Description                                            |
| ------------------------- | ------------------------------------------------------ |
| **Position** `x, y, z`    | Anchor point on the vehicle                            |
| **Rotation** `rx, ry, rz` | Base orientation                                       |
| **Arm**                   | `curve` or `straight` — changes which arm prop is used |
| **Bone**                  | Optional bone attachment                               |

At runtime the player aims the head with Numpad 8/5/4/6. Aim angles sync to other clients via state bags, so everyone sees the same beam direction.

---

## Patterns tab

A grid sequencer — columns are frames, rows are LEDs. The pattern previews live on the vehicle as you edit.

### Creating a pattern

### Add the pattern

Click **Add Pattern** in the sidebar.

### Set the FPS

All frame durations are measured in ticks at this rate.

### Define the color palette

Add RGB colors with optional alpha and a name. Each pattern owns its own palette.

### Paint cells

Click cells in the grid to assign colors. A cell value of `0` is off.

### Color palette

Each pattern owns its palette. Palette entries have `r`, `g`, `b`, optional `a`, and a `name`. Cell values are 1-based indices into the palette.

### Frame timing

Each frame has a `duration` in ticks. At 10 FPS, `duration: 1` = 100 ms, `2` = 200 ms, etc.

### Smooth dimming

Any cell can be marked **dimmable** — its color interpolates smoothly into the next frame instead of snapping. Click the **~** button next to a frame row to toggle dim on every cell in that frame at once.

### Pattern options

| Option                   | Effect                                                                                                                                                     |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trigger Only**         | Hidden from 9/0 cycling. Only activatable via trigger actions.                                                                                             |
| **Sync Near**            | All clients sync the frame index to a server-derived clock — everyone sees the same frame at the same time. Use for synchronized fleet patterns.           |
| **Use Emergency Lights** | While this pattern is active, GTA's native emergency-lights flag is enabled (drives the red-blue environment tint the game applies to emergency vehicles). |
| **Use High Beams**       | High beams are held on while this pattern is active.                                                                                                       |
| **Livery**               | Restricts this pattern to a specific livery index. Omit for any livery.                                                                                    |

### Keyboard shortcuts (Patterns tab)

| Shortcut            | Action                        |
| ------------------- | ----------------------------- |
| **Space**           | Play / pause the live preview |
| **Ctrl+Z / Ctrl+Y** | Undo / Redo (global)          |

---

## Triggers tab

Each trigger is a rule: **IF** a compound of conditions is true, **THEN** run one or more actions.

### Building a trigger

### Add the trigger

Click **Add Trigger** in the sidebar.

### Pick conditions

Add one or more conditions from the reference below, and choose `AND` (all must be true) or `OR` (any suffices).

### Negate where needed

Toggle the `NOT` modifier on individual conditions for "only when X is _not_ true".

### Attach actions

Actions run in list order. Most triggers just overlay or switch a pattern; see the action reference below for the rest.

### Order by priority

Drag triggers in the list to reorder. Pattern overlays stack in list order, so later triggers paint on top of earlier ones.

### Condition reference

#### Lights & stages

| Condition                         | Fires when                                         |
| --------------------------------- | -------------------------------------------------- |
| `lights_on`                       | Emergency lights active                            |
| `stage_1` / `stage_2` / `stage_3` | Vehicle is at that stage                           |
| `park_kill`                       | Driver exited with sirens running; park kill fired |
| `chirping`                        | Chirp tone is playing                              |

#### Audio

| Condition                       | Fires when                                 |
| ------------------------------- | ------------------------------------------ |
| `siren`                         | Any siren active (main, aux, or burst)     |
| `main_siren_on`                 | Main siren active                          |
| `aux_siren_on`                  | Aux siren active                           |
| `rumbler`                       | Rumbler variant playing                    |
| `airhorn`                       | Airhorn playing                            |
| `horn_tap`                      | Horn tapped (< 400 ms press)               |
| `horn_double_tap`               | Horn double-tapped (< 600 ms between taps) |
| `horn_hold`                     | Horn held (> 500 ms)                       |
| `siren_tone_1` … `siren_tone_8` | Main siren is playing this specific tone   |

#### Modes

| Condition                            | Fires when                        |
| ------------------------------------ | --------------------------------- |
| `cruise`                             | Cruise mode on                    |
| `takedown`                           | Takedown mode on                  |
| `ta_left` / `ta_right` / `ta_center` | Traffic advisor in that direction |

#### Vehicle state

| Condition                                         | Fires when                            |
| ------------------------------------------------- | ------------------------------------- |
| `engine_on` / `engine_off`                        | Engine running / stopped              |
| `stationary`                                      | Speed below 2 mph                     |
| `speed_15` / `speed_30` / `speed_60` / `speed_90` | Speed above that mph threshold        |
| `headlights`                                      | Headlights on                         |
| `highbeam`                                        | High beams on                         |
| `day` / `night`                                   | In-game clock (`night` = 20:00–05:00) |

#### Controls

| Condition                  | Fires when                              |
| -------------------------- | --------------------------------------- |
| `brake`                    | Brake pedal engaged                     |
| `handbrake`                | Handbrake engaged                       |
| `reverse`                  | Reverse gear + actually moving backward |
| `turn_left` / `turn_right` | Turn signal on                          |
| `hazards`                  | Hazards on                              |

#### Doors

| Condition                                     | Fires when        |
| --------------------------------------------- | ----------------- |
| `door_fl` / `door_fr` / `door_rl` / `door_rr` | That door is open |
| `hood`                                        | Hood open         |
| `trunk`                                       | Trunk open        |
| `any_door_open`                               | Any of the above  |
| `locked`                                      | Vehicle locked    |
| `unlocked`                                    | Vehicle unlocked  |

#### Steering & transmission

| Condition                      | Fires when                                |
| ------------------------------ | ----------------------------------------- |
| `steer_left`                   | Steering wheel turned left more than 15°  |
| `steer_right`                  | Steering wheel turned right more than 15° |
| `rpm_25` / `rpm_50` / `rpm_75` | Engine RPM above 25%, 50%, or 75%         |
| `gear_1` … `gear_6`            | Transmission in that specific gear        |

#### Health

| Condition         | Fires when            |
| ----------------- | --------------------- |
| `vehicle_damaged` | Body health under 900 |
| `flipped`         | Vehicle upside-down   |

#### Occupancy

| Condition                            | Fires when                                                             |
| ------------------------------------ | ---------------------------------------------------------------------- |
| `driver_in_veh`                      | Driver seat occupied                                                   |
| `passenger_front` / `passenger_rear` | Specific seats occupied                                                |
| `any_passenger`                      | Any passenger seat occupied                                            |
| `presence`                           | Presence mode armed + on-foot player (not another tELS owner) in range |
| `presence_mode`                      | Presence mode armed + owner away + vehicle locked                      |

### Action types

| Action                                    | Effect                                                                                                                                                                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **pattern_overlay**                       | Layer a pattern on top of the base while the rule is true. Overlays stack in list order.                                                                                                                                                    |
| **pattern_set**                           | Switch the base pattern on rising edge (once when the rule becomes true).                                                                                                                                                                   |
| **stage_set**                             | Activate a specific stage (1–3). Rising edge only.                                                                                                                                                                                          |
| **main_siren_set**                        | Start the main siren on a specific tone.                                                                                                                                                                                                    |
| **aux_siren_set**                         | Start the aux siren on a specific tone.                                                                                                                                                                                                     |
| **siren_overlay**                         | Play a tone while the rule is true; stops automatically on false.                                                                                                                                                                           |
| **siren_next_tone** / **siren_prev_tone** | Cycle the main siren's tone.                                                                                                                                                                                                                |
| **park_chirp**                            | Fire a single park chirp (rising edge).                                                                                                                                                                                                     |
| **chirp_stop**                            | Stop an in-progress chirp.                                                                                                                                                                                                                  |
| **horn_play_airhorn**                     | Play the airhorn while the rule is true (respects horn interrupt).                                                                                                                                                                          |
| **horn_play_vehicle_horn**                | Play the native vehicle horn while the rule is true.                                                                                                                                                                                        |
| **arges_on** / **arges_off**              | Enable or disable the Arges spotlight.                                                                                                                                                                                                      |
| **arges_sweep**                           | Run a sweep animation while the rule is true.                                                                                                                                                                                               |
| **ers_pullover**                          | Briefly activates GTA's native emergency-lights flag (visual only, audio muted) on rising edge. Use with ERS-compatible scripts that gate pullover detection on this flag. See [Integrations → ERS](/docs/tels/integrations#ers-night_ers). |

**Rising edge vs held:** actions like `pattern_set`, `stage_set`, `park_chirp`, and `ers_pullover` only fire the moment a rule becomes true. `pattern_overlay`, `siren_overlay`, and `horn_play_airhorn` run continuously while the rule is true and stop automatically on false.

---

## Sirens tab

### Tone slots

Up to 8 tone slots. Each slot:

| Property                                     | Description                                                                    |
| -------------------------------------------- | ------------------------------------------------------------------------------ |
| **Name**                                     | Display name ("Wail", "Yelp", "Priority")                                      |
| **Sound**                                    | Vanilla GTA sound string (e.g., `VEHICLES_HORNS_SIREN_1`)                      |
| **Server Sound** / **Server Sound Ref**      | Custom server-bundled audio. Used when `Server-sided Sirens` is on in `/tels`. |
| **Rumbler Sound** / **Rumbler Server Sound** | Alternate sounds when the rumbler mode is on. Only applies to the main siren.  |
| **Enabled**                                  | Off slots are skipped by every lookup                                          |
| **Trigger Only**                             | Skipped by R, 1-8, and tone cycling, but usable by trigger actions             |

### Airhorn

Separate vanilla / server / rumbler-server fields for the airhorn. Falls back to the default `SIRENS_AIRHORN` soundset if nothing is configured.

### Chirp

| Field                               | Description                                                                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Chirp Tone**                      | Which tone slot plays on the park chirp                                                                                                          |
| **Play Full Siren** (`chirpByCode`) | Hold the tone for the entire chirp duration instead of short 75–125 ms blips. Use this when your audio file already contains the chirp envelope. |

---

## Settings tab

Per-vehicle siren behavior. These apply only to the vehicle you're editing.

| Setting                     | Default | Description                                                                                                                                                                      |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Horn Interrupt**          | On      | Main siren pauses while the airhorn plays, resumes on release                                                                                                                    |
| **Park Kill**               | On      | Sirens stop when the driver exits; fires the `park_kill` trigger condition                                                                                                       |
| **Use Normal Horn**         | On      | `E` plays the native vehicle horn when lights are off. Turn off to make the airhorn play regardless.                                                                             |
| **Programmable Horn**       | Off     | Skip the default horn/airhorn audio and interrupt. Triggers drive the horn with `horn_tap` / `horn_hold` / `horn_double_tap`.                                                    |
| **Lights Suspend TA**       | On      | Traffic advisor suspends when lights activate                                                                                                                                    |
| **Lights Suspend Takedown** | On      | Takedown suspends when lights activate                                                                                                                                           |
| **No User Controls**        | Off     | Disables all player keybinds (Q, R, 1–8, Alt, etc.) for this vehicle. Useful for display or cinematic vehicles where lights are driven entirely by triggers or external scripts. |
| **Disabled Extras**         | —       | Comma-separated list of GTA vehicle extra IDs (1–12) to force off on this vehicle.                                                                                               |

---

## Cross-vehicle references

Open the reference menu on any pattern, trigger, siren, or settings block to import it from another vehicle model instead of duplicating.

- Imported items display a **link** icon; items referenced by other vehicles display a **share** icon.
- Editing a referenced pattern or trigger edits the **source**. Changes propagate to every vehicle that references it.
- Bulk references (`$all`) import every non-referenced pattern or trigger from the source in one go.

See [Configuration › Cross-Vehicle References](/docs/tels/configuration#cross-vehicle-references) for the underlying data format.

---

## Saving

**Save** persists all tabs at once to `data.json` and broadcasts the updated config to every client. If you edited a referenced pattern or trigger, a separate ref-edit event is sent to update the source.

Undo history clears on save.

<!-- llms-full-doc-separator -->

# tAFK Editor (https://timmygstudios.com/docs/tAFK/editor)
In-vehicle orbit-camera keyframe editor. Author new sequences without touching JSON.

## Overview

`/tafkedit` (or **Open Sequence Editor** in `/tafk`) is the single surface for authoring, browsing, renaming, editing, and deleting every sequence that applies to the current vehicle. Requires the `tlib.admin` ACE.

A sequence is just two keyframes — a **start** and an **end** camera position — plus a name, scope, and DOF settings. The editor shows the full list on the left, inline detail editor on the right, and a game-engine viewport in between.

  tAFK's editor renders through the real game camera — the vehicle, lighting, and environment are
  in-engine. The NUI overlays a sequence list, details form, and action bar on top. There's no
  separate 3D viewport to sync.

---

## Layout

- **Left panel** — sequence list. Every sequence that applies to your current vehicle (global `*` + per-model). Click a row to load it for editing, click the checkbox to toggle enabled without loading. **+ New Sequence** at the top.
- **Right panel** — details of whichever sequence is currently loaded. Name, scope, DOF sliders, Delete button. Scope is editable only while the draft hasn't been saved yet (new drafts).
- **Bottom bar** — Set Start / Set End / Preview / Save Changes / Exit. Keyboard shortcuts `1 / 2 / 3 / 4 / Esc`.
- **Top-left header** — vehicle + FOV + clickable `Start ✓` / `End ✓` chips that snap the camera to either captured keyframe.
- **Top-right card** — camera control reference.

## Workflow: create a sequence

### Enter the editor

Be in a vehicle. Run `/tafkedit` or open `/tafk` → **Open Sequence Editor**. The player ped freezes, the vehicle freezes, and the orbit camera starts behind the car at 7m.

### Click **+ New Sequence**

A blank draft appears in the details panel with an auto-generated name like _"Sequence 12"_. Overwrite the name inline as you author.

### Position and capture

Orbit/fly the camera (see controls below), then press **1** to capture the start. Reposition, press **2** to capture the end. The chips in the header go green, and sphere markers appear in the world showing where the keyframes are.

### Tune

Adjust DOF near/far/strength with the sliders in the details panel. Pick scope (Global = plays on any vehicle, This model = plays only on this vehicle).

### Preview

Press **3** to play the animation.

### Save

Press **4** (or click **Save Changes**). The sequence persists to `data.json` and broadcasts to all clients. The draft stays loaded so you can keep tweaking.

## Workflow: edit an existing sequence

### Click a row in the sequence list

Keyframes, DOF, name, and scope all load into the details panel. Sphere markers appear at the saved keyframe positions.

### Inspect framing

Click the green **Start ✓** chip in the header to teleport the camera to the saved start pose. Click **End ✓** for the end. Orbit around from there to evaluate.

### Tweak

Re-capture keyframes with **1**/**2** to overwrite. Rename. Adjust DOF. Click **Save Changes** to commit.

## Workflow: delete a sequence

Load it (click in the list), then click the red **Delete this sequence** button in the details panel. A confirm button appears — click it to finalize. Editor switches back to a fresh draft.

## Workflow: toggle enabled

Click the checkbox next to a sequence's name in the list. Persists immediately, no need to Save Changes.

---

## Camera controls

| Input                | Action                                   |
| -------------------- | ---------------------------------------- |
| **MMB drag**         | Orbit camera around the current pivot    |
| **Shift + MMB drag** | Pan — slides camera and pivot together   |
| **RMB drag**         | Look around (rotate in place)            |
| **Mouse wheel**      | FOV zoom (10°–120°)                      |
| **W A S D**          | Smooth fly-cam translation in view space |
| **Space / Ctrl**     | Move up / down (world Z)                 |
| **Shift** _(hold)_   | 3× speed                                 |
| **Alt** _(hold)_     | 0.3× speed                               |

The pivot follows you when you fly. It stays put when you orbit. It re-anchors forward when you look (RMB). This matches the standard orbit-cam behaviour used in tELS and tRadio's editors.

## Action hotkeys

| Key     | Action                 |
| ------- | ---------------------- |
| **1**   | Capture Start keyframe |
| **2**   | Capture End keyframe   |
| **3**   | Preview                |
| **4**   | Save Changes           |
| **Esc** | Exit editor            |

---

## How keyframes are stored

Each keyframe captures the camera's world position and rotation at the moment you press 1 or 2, then converts to **vehicle-local offsets** so the sequence replays correctly regardless of vehicle heading or position.

Stored fields per keyframe:

| Field                             | Type        | Source                                                       |
| --------------------------------- | ----------- | ------------------------------------------------------------ |
| `offset`                          | `{x, y, z}` | World cam pos rotated into vehicle-local space               |
| `rotation`                        | `{x, y, z}` | Cam world rot minus the implicit "point at vehicle" rotation |
| `fov`                             | number      | Current cam FOV at capture                                   |
| `dof.near` / `.far` / `.strength` | number      | Set in the save dialog (applies to both keyframes)           |

The `rotation` is a _delta from point-at-vehicle_, so sequences still track the vehicle during playback even though the exact cam pose at each frame is derived from the lerped offset + the runtime's `PointCamAtCoord`.

---

## Save scope

**Global (`vehicles: ["*"]`)** — lives in `data.json.sequences`. Plays on any vehicle. Best for generic shots (low pans, overhead orbits) that work universally.

**Per-vehicle (`vehicles: [<model>]`)** — lives in `data.json.vehicleConfigs[<model>].sequences`. Only plays on that specific model. Best for shots that rely on the model's geometry — framing a specific body panel, lining up with headlights, etc.

Both paths are validated server-side via `tafkValidateSequence` before persistence. Invalid entries (missing start/end, bad offset shape) are rejected with a toast.

  If you're building a vehicle pack and want to ship camera sequences, author them in the editor under the "This model only" scope to get the JSON right, then copy the entries from `data.json.vehicleConfigs[<model>]` into your pack's own `tafk.json`. See [Configuration → Per-vehicle packs](/docs/tAFK/configuration#per-vehicle-sequence-packs).

---

## Leaving the editor safely

- **Exit** (Esc / toolbar X) — no changes written for an unsaved draft. Already-saved sequences stay on disk.
- **`onResourceStop`** — editor auto-exits; camera, freeze, NUI focus all cleaned up.

Losing the reference vehicle (despawn, destroy) during editing shows an error toast and exits cleanly.

  If you have an unsaved draft and click another sequence in the list, the draft is replaced. Hit
  **Save Changes** first if you don't want to lose your work.

<!-- llms-full-doc-separator -->

# tlib Exports (https://timmygstudios.com/docs/tlib/exports)
All tLib Lua exports — menus, dialogs, toasts, themes, logger, HTTP, and permissions.

All exports are called via `exports['tLib']:FunctionName(...)`.

---

## Menu System

A full NUI menu system with submenus, item types, and dynamic updates.

### Lifecycle

| Export                                                       | Description                                       |
| ------------------------------------------------------------ | ------------------------------------------------- |
| `CreateMenu(menuId, title, subtitle, onOpen, onClose, opts)` | Create a new menu. Returns the resolved `menuId`. |
| `OpenMenu(menuId)`                                           | Open a menu.                                      |
| `CloseMenu(menuId)`                                          | Close a specific menu.                            |
| `CloseAll()`                                                 | Close all open menus.                             |
| `DeleteMenu(menuId)`                                         | Remove a menu entirely.                           |
| `ClearMenu(menuId)`                                          | Remove all items from a menu.                     |
| `CheckMenu(menuId)`                                          | Returns `true` if the menu exists.                |
| `IsOpen()`                                                   | Returns `true` if any menu is open.               |

### Item Types

| Export                                                                                           | Description                        |
| ------------------------------------------------------------------------------------------------ | ---------------------------------- |
| `AddButton(menuId, itemId, label, description, onSelect, opts)`                                  | Add a button item.                 |
| `AddCheckbox(menuId, itemId, label, description, checked, onToggle, opts)`                       | Add a checkbox item.               |
| `AddSlider(menuId, itemId, label, description, min, max, value, step, onChange, onSelect, opts)` | Add a slider item.                 |
| `AddList(menuId, itemId, label, description, values, index, onChange, onSelect, opts)`           | Add a list selector item.          |
| `AddSpacer(menuId, itemId, label, description, opts)`                                            | Add a non-interactive spacer.      |
| `AddSubmenuButton(menuId, itemId, submenuId, label, description, onSelect, opts)`                | Add a button that opens a submenu. |

### Mutation

| Export                                  | Description                                                                 |
| --------------------------------------- | --------------------------------------------------------------------------- |
| `UpdateMenu(menuId, changes)`           | Merge top-level menu fields (title, subtitle, banner, position, size, etc). |
| `SetMenuTitle(menuId, title)`           | Update the menu title.                                                      |
| `SetMenuSubtitle(menuId, subtitle)`     | Update the menu subtitle.                                                   |
| `SetMenuBanner(menuId, banner)`         | Update the menu banner image.                                               |
| `SetMenuLayout(menuId, position, size)` | Update position and size.                                                   |
| `RefreshMenu(menuId)`                   | Push pending item changes to the UI. Call after batched `Add*` calls.       |

### CreateMenu Options

| Key             | Type               | Description                                                 |
| --------------- | ------------------ | ----------------------------------------------------------- |
| `position`      | `string`           | `"top-left"`, `"top-center"`, `"bottom-right"`, etc.        |
| `size`          | `string`           | `"sm"`, `"md"`, or `"lg"`                                   |
| `banner`        | `string\|function` | URL displayed above the title.                              |
| `blockInput`    | `boolean`          | Block player movement and camera while open.                |
| `inheritLayout` | `boolean`          | Inherit position/size from parent when opened as a submenu. |
| `theme`         | `string`           | Id of a registered tLib theme.                              |
| `itemHeight`    | `number`           | Fixed row height in pixels (default: `40`).                 |

### Example

```lua
local menuId = exports['tLib']:CreateMenu('demo', 'Demo Menu', 'Pick an option', nil, nil, {
    position = 'top-left',
    size = 'md',
})

exports['tLib']:AddButton(menuId, 'greet', 'Say Hello', 'Prints a greeting', function()
    print('Hello!')
end)

exports['tLib']:AddCheckbox(menuId, 'toggle', 'Toggle Option', 'On or off', false, function(checked)
    print('Toggled:', checked)
end)

exports['tLib']:AddSlider(menuId, 'vol', 'Volume', 'Adjust volume', 0, 100, 50, 1, function(val)
    print('Volume:', val)
end)

exports['tLib']:RefreshMenu(menuId)
exports['tLib']:OpenMenu(menuId)
```

---

## Dialog System

Modal form dialogs with multiple field types. Results are delivered via events.

### Exports

| Export                 | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `ShowDialog(id, opts)` | Open a dialog. Returns the resolved dialog `id`.  |
| `CloseDialog(id)`      | Close an open dialog (fires the cancelled event). |

### ShowDialog Options

| Key           | Type      | Description                                 |
| ------------- | --------- | ------------------------------------------- |
| `title`       | `string`  | Dialog heading.                             |
| `description` | `string`  | Optional subheading.                        |
| `submitLabel` | `string`  | Submit button label (default `"Submit"`).   |
| `cancelLabel` | `string`  | Cancel button label (default `"Cancel"`).   |
| `size`        | `string`  | `"sm"`, `"md"`, or `"lg"` (default `"md"`). |
| `theme`       | `string`  | Id of a registered tLib theme.              |
| `fields`      | `table[]` | Array of field definitions.                 |

### Field Types

| Type                                     | Extra Keys                                                      |
| ---------------------------------------- | --------------------------------------------------------------- |
| `text`, `number`, `password`, `textarea` | `placeholder`, `defaultValue`, `min`/`max` (number only)        |
| `select`, `radio`                        | `options` (`{ value, label }[]`), `placeholder`, `defaultValue` |
| `slider`                                 | `min`, `max`, `step`, `defaultValue`                            |
| `checkbox`                               | `defaultValue` (boolean)                                        |

All fields share: `id` (required), `type`, `label`, `description`, `required`, `disabled`.

### Events

- `tLib:dialog:opened` — `(dialogId)`
- `tLib:dialog:submitted` — `(dialogId, values)` — `values` is a table keyed by field `id`.
- `tLib:dialog:cancelled` — `(dialogId)`

### Example

```lua
local dialogId = exports['tLib']:ShowDialog('my_dialog', {
    title = 'Player Info',
    fields = {
        { id = 'name', type = 'text', label = 'Name', required = true },
        { id = 'age', type = 'number', label = 'Age', min = 1, max = 120 },
        { id = 'role', type = 'select', label = 'Role', options = {
            { value = 'civ', label = 'Civilian' },
            { value = 'leo', label = 'Law Enforcement' },
        }},
    },
})

AddEventHandler('tLib:dialog:submitted', function(id, values)
    if id == dialogId then
        print('Name:', values.name, 'Age:', values.age, 'Role:', values.role)
    end
end)
```

---

## Toast / Notification System

Lightweight toast notifications that stack in the corner of the screen.

### Exports

| Export                                                          | Description                              |
| --------------------------------------------------------------- | ---------------------------------------- |
| `ShowToast(id, toastType, title, description, duration, theme)` | Show a toast. Returns the resolved `id`. |
| `UpdateToast(id, changes)`                                      | Update a live toast in place.            |
| `DismissToast(id)`                                              | Dismiss a single toast.                  |
| `DismissAll()`                                                  | Dismiss all visible toasts.              |

### Toast Types

| Type      | Default Duration                        |
| --------- | --------------------------------------- |
| `success` | 4000 ms                                 |
| `error`   | 6000 ms                                 |
| `warning` | 5000 ms                                 |
| `info`    | 4000 ms                                 |
| `loading` | Persistent (until dismissed or updated) |

### Events

- `tLib:toast:shown` — `(id, toastType, title)`
- `tLib:toast:updated` — `(id, patch)`
- `tLib:toast:dismissed` — `(id)`
- `tLib:toast:dismissedAll`

### Example

```lua
-- Simple notification
exports['tLib']:ShowToast(nil, 'success', 'Saved', 'Your settings have been saved.')

-- Loading toast that resolves
local toastId = exports['tLib']:ShowToast(nil, 'loading', 'Saving...', 'Please wait.')
-- Later...
exports['tLib']:UpdateToast(toastId, { type = 'success', title = 'Done', description = 'Save complete.' })
```

---

## Theme System

Register and apply CSS variable-based themes, scoped globally or per-component.

### Exports

| Export               | Description                                       |
| -------------------- | ------------------------------------------------- |
| `AddTheme(id, opts)` | Register a new theme. Returns `true` on success.  |
| `RemoveTheme(id)`    | Unregister a theme. Returns `true` if it existed. |
| `SetTheme(id)`       | Apply a theme globally. Pass `""` to clear.       |
| `GetTheme(id)`       | Returns a copy of a theme definition, or `nil`.   |
| `GetThemes()`        | Returns all registered themes keyed by id.        |

### AddTheme Options

| Key           | Type     | Description                                                            |
| ------------- | -------- | ---------------------------------------------------------------------- |
| `name`        | `string` | Human-readable display name.                                           |
| `description` | `string` | Optional description.                                                  |
| `cssVars`     | `table`  | CSS variable name → value map. Keys must not include the leading `--`. |
| `extends`     | `string` | Id of another theme to inherit from.                                   |
| `font`        | `string` | Font-family string (sets `--font-sans`).                               |
| `fontSize`    | `string` | Base font-size percentage, e.g. `"87.5%"`.                             |

### Events

- `tLib:theme:added` — `(id)`
- `tLib:theme:removed` — `(id)`
- `tLib:theme:set` — `(id)`

---

## Logger

Structured console logger with level filtering. Available on both client and server.

| Export                | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| `Log(loggerId, args)` | Format and filter a log line. Returns the formatted string or `nil`. |
| `SetLogLevel(level)`  | Set the global minimum log level (`1`–`4`).                          |

Levels: `1` = DEBUG, `2` = INFO, `3` = WARN, `4` = ERROR

```lua
local log = function(msg, level)
    local line = exports['tLib']:Log('myresource', { msg, level or 2 })
    if line then print(line) end
end

log('Server started')          -- INFO
log('Debug details', 1)        -- DEBUG
log('Something went wrong', 4) -- ERROR
```

---

## HTTP Helper

Non-blocking HTTP/HTTPS client.

| Export                  | Description           |
| ----------------------- | --------------------- |
| `Fetch(opts, callback)` | Make an HTTP request. |

### Fetch Options

| Key       | Type      | Description                               |
| --------- | --------- | ----------------------------------------- |
| `url`     | `string`  | Full URL including scheme. Required.      |
| `method`  | `string`  | HTTP method (default `"GET"`).            |
| `headers` | `table`   | Request headers.                          |
| `body`    | `string`  | Request body.                             |
| `timeout` | `number`  | Timeout in seconds (default `10`).        |
| `verify`  | `boolean` | Verify TLS certificate (default `false`). |

Callback: `function(err, statusCode, body)` — on success `err` is `nil`.

```lua
exports['tLib']:Fetch({
    url = 'https://httpbin.org/get',
    method = 'GET',
}, function(err, status, body)
    if err then
        print('Error:', err)
    else
        print('Status:', status, 'Body:', body)
    end
end)
```

<Callout type="info">HTTPS requires LuaSec. HTTP/2 is not supported.</Callout>

---

## Permission System

Admin permission caching with level-based access.

| Export                     | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `IsAdmin()`                | Returns `true` if the player is an admin.                            |
| `GetPermissionLevel()`     | Returns permission level: `0` = none, `1` = admin, `2` = superadmin. |
| `RefreshAdminPermission()` | Refresh the cached admin permission.                                 |

<!-- llms-full-doc-separator -->

# Failed to Verify Protected Resource (https://timmygstudios.com/docs/faq-failed-to-verify)
Fixing the "Failed to verify protected resource" error in FiveM.

## Error Message

```
[svadhesive] Failed to verify protected resource your_resource
```

## Possible Causes

  The `.fxap` file is required for escrow-protected resources. It's a hidden file and some FTP
  programs skip it.

  FileZilla damages escrow-protected files during transfer. Some hosting providers use FileZilla
  internally as well.

  Dragging the folder through Remote Desktop or an FTP client file-by-file corrupts the escrow
  files. Always upload the `.zip` and extract on the server.

  The download from the CFX Portal was incomplete or corrupted. Re-download and compare file sizes.

  Some FTP programs skip hidden files like `.fxap` by default. In WinSCP, enable **Show hidden
  files** (Options → Preferences → Panels).

---

## Solutions

### Fresh download and upload

1. Download the script again from the [CFX Portal](https://portal.cfx.re/)
2. Upload using [WinSCP](https://winscp.net/eng/download.php) — **not** FileZilla
3. Make sure hidden files (including `.fxap`) are transferred
4. Restart the server

  Upload the `.zip` file to your server and extract it there. Do **not** drag-and-drop the folder
  file-by-file, especially over Remote Desktop — this damages escrow files.

### Verify the .fxap file exists

In WinSCP, enable **Show hidden files** (Options → Preferences → Panels → Show hidden files), then navigate to the resource folder and confirm `.fxap` is present.

### Disable anticheat

Some anticheat systems dump or modify Lua files, which breaks escrow protection. Temporarily disable your anticheat to test. If that fixes it, configure your anticheat to exclude the resource folder.

### Update server artifacts

Make sure your server is on artifacts version **4752** or higher. Run `version` in the server console to check.

See [Syntax Error / Error Parsing → Update server artifacts](/docs/syntax-error#solutions) for update instructions.

---

## Related

    Overview of all escrow errors and how to identify which one you're seeing.

  Same underlying cause (bad upload) — different symptom in the console.

    If you've confirmed the files are intact, check whether your key matches the purchasing account.

<!-- llms-full-doc-separator -->

# General Issues (https://timmygstudios.com/docs/faq-general-issues)
Overview of common FiveM escrow system errors and how to identify them.

If your scripts work initially but stop working after restarting the server a few times, you
  likely have a virus on your server. We cannot help in that case — see [What to Do If Nothing Fixes
  the Errors](#if-nothing-fixes-the-errors).

## How to Identify FiveM Escrow Errors

To determine if a script issue is caused by the FiveM asset escrow system:

1. Restart the script causing issues using `ensure your_script_name` in the txAdmin console
2. Check **both** the txAdmin console (server console) **and** the F8 in-game console for errors
3. If the error matches one of the types below, it's caused by the FiveM escrow system

---

## Common Escrow Errors

    `syntax error near '<\1>'` or `Error parsing script` — usually a bad upload.

  `Failed to verify protected resource` — missing `.fxap` or corrupted transfer.

    `You lack the required entitlement` — server key doesn't match the purchasing account.

---

## General Solutions

If you can't start or use a script, try these in order:

- Update to **minimum** server artifacts version **4752** or higher
- **Don't** use FileZilla — use [WinSCP](https://winscp.net/eng/download.php) instead
- Use the correct license key generated by the same account where you downloaded the script
- Upload the `.zip` file to your server and extract it there — do **not** transfer files individually

---

## If Nothing Fixes the Errors

If none of the solutions on these pages resolve your issue:

1. Verify you've tried **every** solution listed on the relevant error page
2. Try a completely fresh install of the script
3. Check if your server has been compromised — scripts that break after a few restarts often indicate a virus modifying files
4. Contact support on [Discord](https://timmygstudios.com/discord) with details about what you've tried

---

## Related

    How to grant players and groups access to script commands via FiveM's permission system.

<!-- llms-full-doc-separator -->

# tels HUD Layouts (https://timmygstudios.com/docs/tels/layouts)
Build custom HUD overlays for tELS with HTML, CSS, and optional JavaScript.

## Overview

A HUD layout is a self-contained HTML file plus assets in a folder under `layouts/`. Lua pushes vehicle state to the NUI every tick, and the layout binds DOM elements to state fields with `data-hud-*` attributes. Lua does no presentation logic — the layout decides how to display what it receives.

Folders in `layouts/` are auto-discovered by the server and appear in the HUD Layout selector in `/tels`.

---

## Create a layout

### Create the folder

`layouts/MyLayout/` — the folder name is what players see in the layout selector.

### Add `ui.html`

This is the layout's entry point. It can contain all HTML, CSS, and (optionally) a single `<script data-hud-script>` block for presentation logic.

### Add assets (optional)

```
layouts/MyLayout/
  ui.html
  icons/       PNG / SVG assets
  sounds/      On.ogg, Off.ogg, Press.ogg (optional)
```

Reference assets relatively. `ui.html` is served from inside `layouts/<name>/` — use paths like `icons/foo.png`.

### Restart the resource

Layouts are enumerated on server start. Restart `tELS` and the new layout appears in `/tels → HUD Layout`.

---

## Data bindings

Attach `data-hud-*` attributes to DOM elements. The binder processes them on every update.

| Attribute            | Example                               | Behavior                                                        |
| -------------------- | ------------------------------------- | --------------------------------------------------------------- |
| `data-hud-text`      | `data-hud-text="patternName"`         | Set `textContent` to the state value                            |
| `data-hud-html`      | `data-hud-html="customHtml"`          | Set `innerHTML` (be careful with untrusted values)              |
| `data-hud-led`       | `data-hud-led="sirenOn"`              | Toggle `.active` class when truthy                              |
| `data-hud-show`      | `data-hud-show="inVehicle"`           | Show when truthy, hide when falsy                               |
| `data-hud-hide`      | `data-hud-hide="engineOn"`            | Hide when truthy                                                |
| `data-hud-eq`        | `data-hud-eq="taMode:left"`           | Toggle `.active` when `state[key] === value`                    |
| `data-hud-attr`      | `data-hud-attr="gear:data-gear"`      | Copy state value to an HTML attribute                           |
| `data-hud-led-color` | `data-hud-led-color="leds.R1"`        | Set `background-color` from `{r, g, b, a}`                      |
| `data-hud-btn`       | `data-hud-btn="toggleSiren"`          | Click fires a Lua `tels:hudButton` callback with this action ID |
| `data-hud-keys`      | `data-hud-keys="sirenTones,maxStage"` | Declare extra data dependencies for scripts (see below)         |

Use dot paths for nested state: `leds.R1` resolves to `state.leds.R1`.

### Example

```html
<div data-hud-show="inVehicle">
  <span data-hud-text="patternName">—</span>
  <div data-hud-led="sirenOn" class="indicator">SIREN</div>
  <div data-hud-eq="taMode:left" class="arrow">◄</div>
  <div data-hud-led-color="leds.R1" class="pip"></div>
  <button data-hud-btn="cycle_pattern">Next</button>
</div>
```

---

## Available state keys

Lua sends raw data only — no derived strings or presentation. Every key below is optional: the binder only sends keys the layout references (via `data-hud-*` attributes or `data-hud-keys`).

### Core

| Key         | Type    | Description                            |
| ----------- | ------- | -------------------------------------- |
| `inVehicle` | boolean | Player is in a vehicle                 |
| `active`    | boolean | Emergency lights are on                |
| `stage`     | number  | Current stage (0 = off, 1–3)           |
| `maxStage`  | number  | Max configured stages for this vehicle |

### Pattern

| Key            | Type   | Description                                  |
| -------------- | ------ | -------------------------------------------- |
| `patternName`  | string | Current pattern name (empty for lights-only) |
| `patternIdx`   | number | 1-based pattern index (0 = lights-only)      |
| `patternCount` | number | Total patterns for this vehicle              |

### Siren

| Key             | Type    | Description                                                |
| --------------- | ------- | ---------------------------------------------------------- |
| `sirenOn`       | boolean | Main siren playing                                         |
| `sirenTone`     | number  | Main siren tone index (1-based)                            |
| `sirenToneName` | string  | Main siren tone display name                               |
| `sirenTones`    | array   | `[{idx, name}, ...]` — all configured tone slots           |
| `auxSirenOn`    | boolean | Aux siren playing                                          |
| `auxSirenTone`  | number  | Aux siren tone index                                       |
| `auxToneName`   | string  | Aux siren tone display name                                |
| `hornActive`    | boolean | Airhorn or horn held (zero-latency, driven by global flag) |
| `chirping`      | boolean | Chirp tone currently playing                               |
| `rumblerOn`     | boolean | Rumbler variant active                                     |
| `paActive`      | boolean | PA mic currently transmitting                              |
| `paAvailable`   | boolean | PA mic system available (pma-voice running)                |
| `paRange`       | number  | Current PA range in metres                                 |

### Modes

| Key        | Type    | Description                                 |
| ---------- | ------- | ------------------------------------------- |
| `cruise`   | boolean | Cruise on                                   |
| `takedown` | boolean | Takedown on                                 |
| `taMode`   | string  | `"off"`, `"left"`, `"right"`, or `"center"` |
| `presence` | boolean | Presence detection armed                    |

### Vehicle

| Key         | Type    | Description                   |
| ----------- | ------- | ----------------------------- |
| `modelKey`  | string  | Vehicle model key (lowercase) |
| `modelName` | string  | Display name (e.g. "POLICE")  |
| `speedMph`  | number  | Rounded speed in mph          |
| `engineOn`  | boolean | Engine running                |
| `gear`      | number  | Current gear (0 = reverse)    |
| `rpm`       | number  | 0–100 scaled RPM              |
| `health`    | number  | Engine health (0–1000)        |
| `livery`    | number  | Livery index                  |
| `locked`    | boolean | Vehicle locked                |
| `isDriver`  | boolean | Player is in the driver seat  |

### Lights

| Key          | Type    | Description   |
| ------------ | ------- | ------------- |
| `headlights` | boolean | Headlights on |
| `highbeams`  | boolean | High beams on |

### Controls

| Key         | Type    | Description                       |
| ----------- | ------- | --------------------------------- |
| `brake`     | boolean | Brake pedal pressed               |
| `handbrake` | boolean | Handbrake engaged                 |
| `reverse`   | boolean | Gear 0 + actually moving backward |

### Signals

| Key         | Type    | Description        |
| ----------- | ------- | ------------------ |
| `turnLeft`  | boolean | Left indicator on  |
| `turnRight` | boolean | Right indicator on |
| `hazards`   | boolean | Hazards on         |

### Doors

| Key                                    | Type    | Description       |
| -------------------------------------- | ------- | ----------------- |
| `doorFL`, `doorFR`, `doorRL`, `doorRR` | boolean | That door is open |
| `hood`                                 | boolean | Hood open         |
| `trunk`                                | boolean | Trunk open        |

### LEDs

| Key    | Type   | Description                                                         |
| ------ | ------ | ------------------------------------------------------------------- |
| `leds` | object | Live LED colors, keyed by LED name (e.g., `{ R1: { r, g, b, a } }`) |

Bind individual LEDs with `data-hud-led-color="leds.<name>"`. The LED colors stream at roughly 20 Hz, independent of the full state update.

---

## Layout scripts

For derived values, dynamic HTML, or anything beyond simple bindings, add a `<script data-hud-script>` block. The script registers a callback that runs after each binder pass.

```html
<script data-hud-script>
  (function () {
    window.__telsLayoutUpdate = function (state, root) {
      // state: raw data from Lua
      // root:  this layout's container element

      var el = root.querySelector(".reverse-indicator");
      if (el) el.style.display = state.reverse ? "" : "none";

      var kphEl = root.querySelector(".speed-kph");
      if (kphEl) kphEl.textContent = Math.round((state.speedMph || 0) * 1.609);
    };

    // Optional cleanup when the layout is unloaded.
    window.__telsLayoutDestroy = function () {
      // cancel timers, detach listeners, etc.
    };
  })();
</script>
```

### Declaring extra data

Lua only sends keys the layout references in `data-hud-*` attributes. If a script needs a key that isn't bound to any attribute, declare it with `data-hud-keys`:

```html
<div data-hud-keys="sirenTones,maxStage,sirenTone">…</div>
```

Without this, Lua skips computing those keys and your script receives `undefined`.

---

## Buttons

`data-hud-btn="<action>"` fires a `tels:hudButton` client event with the action string:

```lua
AddEventHandler("tels:hudButton", function(action)
  if action == "cycle_pattern" then
    ExecuteCommand("+lbar_pattern")
  end
end)
```

Wire it to your own handlers in a separate resource, or reuse the built-in ones.

---

## Sounds

Optional `sounds/` folder. The HUD plays:

- `On.ogg` — on toggle-on actions
- `Off.ogg` — on toggle-off actions
- `Press.ogg` — on button press

File paths resolve relative to the layout folder: `layouts/<name>/sounds/<file>.ogg`.

---

## UI Studio

Build and publish HUD layouts with the **[UI Studio](https://timmygstudios.com/marketplace/studio)**. See the [Marketplace docs](/docs/marketplace#ui-studio) for the full walkthrough — creating drafts, design vs HTML mode, lint rules, bundle limits, forking, and publishing.

---

## Performance notes

- Lua only computes keys the active layout references. `data-hud-*` attributes and `data-hud-keys` together drive this filter.
- Full state updates run at ~5 Hz. LED colors (`leds.*`) update separately at ~20 Hz.
- Cache query selectors in your script closure — it runs on every tick.

<!-- llms-full-doc-separator -->

# tlib Import Modules (https://timmygstudios.com/docs/tlib/import-modules)
Lightweight Lua modules that load on demand — coords, kvp, settings, and layouts.

Import modules are lightweight Lua modules that your resource declares in `fxmanifest.lua` and accesses via the `tlib` global. They load on demand — only when first accessed.

## Setup

```lua
title="fxmanifest.lua" dependencies { 'tLib' } shared_scripts { '@tLib/imports.lua' } tlib_modules { 'coords', 'kvp', 'settings', 'layouts' }
```

Then in your scripts:

```lua
local kvp = tlib.kvp
local settings = tlib.settings
```

---

## coords

Vehicle coordinate math helpers for transforming positions between local and world space.

| Function                                               | Description                                                     |
| ------------------------------------------------------ | --------------------------------------------------------------- |
| `Coords.localToWorld(right, fwd, up, pos, lx, ly, lz)` | Vehicle-local → world position.                                 |
| `Coords.worldToLocal(right, fwd, up, pos, wx, wy, wz)` | World → vehicle-local position.                                 |
| `Coords.buildBoneRotMatrix(rx, ry, rz)`                | Build world-space rotation matrix from bone angles (ZXY order). |
| `Coords.boneLocalToWorld(...)`                         | Bone-relative → world position.                                 |
| `Coords.worldToBoneLocal(...)`                         | World → bone-relative position.                                 |

```lua
local Coords = tlib.coords

-- Get vehicle matrix
local veh = GetVehiclePedIsIn(PlayerPedId(), false)
local right, fwd, up, pos = GetEntityMatrix(veh)

-- Convert a local offset to world position
local wx, wy, wz = Coords.localToWorld(right, fwd, up, pos, 0.5, 1.0, 0.0)
```

---

## kvp

Typed KVP wrapper with automatic community-server prefixing. Each server gets isolated storage via `tlib_community_id` or `sv_projectName`.

### Typed Getters / Setters

| Function                      | Description               |
| ----------------------------- | ------------------------- |
| `kvp.getString(key, default)` | Get a string value.       |
| `kvp.getFloat(key, default)`  | Get a float value.        |
| `kvp.getInt(key, default)`    | Get an integer value.     |
| `kvp.getBool(key, default)`   | Get a boolean value.      |
| `kvp.getJson(key, default)`   | Get a JSON-decoded value. |
| `kvp.setString(key, value)`   | Set a string value.       |
| `kvp.setFloat(key, value)`    | Set a float value.        |
| `kvp.setInt(key, value)`      | Set an integer value.     |
| `kvp.setBool(key, value)`     | Set a boolean value.      |
| `kvp.setJson(key, value)`     | Set a JSON-encoded value. |

### Auto-Detect

| Function                | Description                |
| ----------------------- | -------------------------- |
| `kvp.get(key, default)` | Auto-detect type on read.  |
| `kvp.set(key, value)`   | Auto-detect type on write. |

### Utilities

| Function          | Description                           |
| ----------------- | ------------------------------------- |
| `kvp.has(key)`    | Returns `true` if the key exists.     |
| `kvp.delete(key)` | Delete a key.                         |
| `kvp.key(key)`    | Returns the full prefixed key string. |

```lua
local kvp = tlib.kvp

kvp.setString('callsign', '1-Adam-12')
local callsign = kvp.getString('callsign', 'Unknown')

kvp.setJson('loadout', { primary = 'rifle', secondary = 'pistol' })
local loadout = kvp.getJson('loadout', {})
```

---

## settings

Typed settings store backed by KVP. Supports default values, user-set tracking, and server-pushed defaults.

| Function                     | Description                                                        |
| ---------------------------- | ------------------------------------------------------------------ |
| `settings.create(defs)`      | Create a store from a definition array `{ key, type, default }[]`. |
| `store:get(key)`             | Get a setting value.                                               |
| `store:set(key, value)`      | Set a setting value (persisted to KVP).                            |
| `store:isUserSet(key)`       | `true` if the player explicitly set this value.                    |
| `store:applyDefaults(table)` | Apply server defaults only to keys the player hasn't set.          |
| `store:reset(key)`           | Reset to default and remove from KVP.                              |

```lua
local settings = tlib.settings

local store = settings.create({
    { key = 'volume', type = 'float', default = 0.8 },
    { key = 'darkMode', type = 'bool', default = false },
    { key = 'language', type = 'string', default = 'en' },
})

local vol = store:get('volume')    -- 0.8 (default)
store:set('volume', 0.5)           -- Persisted to KVP
store:isUserSet('volume')          -- true
store:reset('volume')              -- Back to 0.8
```

---

## layouts

Server-side layout discovery and file loading with template variable substitution.

| Function                                                                    | Description                              |
| --------------------------------------------------------------------------- | ---------------------------------------- |
| `layouts.scan(basePath, matchFile, resourceName?)`                          | Scan a directory for layout folders.     |
| `layouts.load(basePath, layoutName, fileName, resourceName?)`               | Load a layout file's contents.           |
| `layouts.loadTemplate(basePath, layoutName, fileName, vars, resourceName?)` | Load and replace `{{KEY}}` placeholders. |
| `layouts.clearCache()`                                                      | Clear the scan cache.                    |

```lua
local layouts = tlib.layouts

-- Scan for available layouts
local available = layouts.scan('layouts', 'layout.html')

-- Load a specific layout with template variables
local html = layouts.loadTemplate('layouts', 'default', 'layout.html', {
    TITLE = 'My HUD',
    VERSION = '1.0',
})
```

<!-- llms-full-doc-separator -->

# tRadio Installation (https://timmygstudios.com/docs/tRadio/installation)
Install Tommy's Radio on your FiveM server, open the voice port, and confirm players can transmit.

## Requirements

| Requirement                                        | Detail                                                                                            |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| FiveM server artifact                              | **4752 or newer** — run `version` in your server console to check                                 |
| [tLib](https://github.com/tommy141x/tLib/releases) | **v0.6+**. Install the **release** zip, not the source zip — the source zip has no built files    |
| A free TCP port                                    | Default `7777`. It cannot be shared with FiveM (30120) or txAdmin (40120)                         |
| Framework                                          | Optional. ESX, QBCore, QBX, ND_Core, ox_core, and nat2k15 are auto-detected; standalone works too |

tRadio runs its own voice server inside the FiveM process. That server needs its own port, reachable from the internet. Opening that port is the step that goes wrong most often, so it has its own section below.

---

### Extract the files

Download the release zip, transfer it to your server, and unzip it **on the server**. Place the extracted folder in `resources/`.

  FTP clients in ASCII mode (FileZilla's default) and Windows Remote Desktop drag-and-drop corrupt
  Lua files, producing a `<\1>` syntax error on start. Transfer the `.zip` and unzip on the server,
  or use WinSCP in binary mode. Also enable "show hidden files" so the dot-prefixed `.fxap` escrow
  file comes across.

Name the folder anything you like. `provide 'tRadio'` in `fxmanifest.lua` aliases the exports, so other scripts calling `exports['tRadio']:someExport()` find it regardless of folder name. Use your real folder name in `server.cfg`.

### Set the five required values

Open `config/config.lua`. Only these five fields must be set before first start — everything else is configured later in the web admin panel.

`config/config.lua`

```lua
Config = {
    serverAddress = "http://203.0.113.10:7777", -- Ships as "localhost", which only works if the
                                                -- server runs on your own PC. Set your public
                                                -- IP/domain WITH the port, or "" to auto-detect.
    serverPort    = 7777,                       -- Must be free and open (next step)
    authToken     = "<20+ random characters>",  -- Generate one at randomkeygen.com
    adminPassword = "<your admin password>",    -- Web admin panel login
    dispatchNacId = "4417",                     -- Code dispatchers type on the panel login screen
}
```

  `authToken` protects your voice server. `adminPassword` protects a panel that can change every
  server setting and install marketplace content. `dispatchNacId` ships as `"141"`, which is also
  the public demo server's dispatch code — leave it and anyone who knows it can log into your
  dispatch panel.

Setting `adminPassword = ""` disables password login for the admin panel. Only do that if you set up [Discord authentication](/docs/tRadio/configuration#discord-authentication) instead — with neither, nobody can log in, and tRadio prints a startup warning saying so.

### Open the port

The voice server needs its own TCP port, separate from FiveM and txAdmin.

1. In your panel, find **Network**, **Ports**, or **Allocations** and add a port (for example `50978`)
2. Set both values in `config/config.lua` to that port:

```lua
Config = {
    serverPort    = 50978,
    serverAddress = "http://203.0.113.10:50978",
}
```

3. Restart the **entire server** from the panel — restarting the resource alone does not bind a new allocation
4. With the resource running, test the port at [portchecker.co](https://portchecker.co/check-v0)

  Gravel Host, RocketNode, VibeGames and similar providers often block the port at the network level
  even after you add it in the panel. Open a ticket saying: _"I need port [PORT] opened for a custom
  voice server resource."_

Open the port in your firewall, then set `serverAddress = ""` so tRadio auto-detects the public IP.

```bash
# Ubuntu / Debian
sudo ufw allow 7777

# CentOS / RHEL
sudo firewall-cmd --permanent --add-port=7777/tcp && sudo firewall-cmd --reload
```

```powershell
# Windows Server
netsh advfirewall firewall add rule name="tRadio" dir=in action=allow protocol=TCP localport=7777
```

Forward port 7777 (TCP) to your machine in your router, then set your public IP explicitly:

```lua
Config = { serverPort = 7777, serverAddress = "http://203.0.113.10:7777" }
```

**Port mistakes that account for nearly every failed install:**

- Using 30120 or 40120 — already taken by FiveM and txAdmin
- Leaving `serverAddress = "localhost"` on a remote server, so no player can reach it
- `serverPort` and the port inside `serverAddress` not matching
- Omitting the `http://` prefix or the port — the format is exactly `http://IP:PORT`
- Testing before the resource starts — the port only opens while tRadio is running

### Start the resource

`server.cfg`

```txt
ensure tLib
ensure tRadio
```

tLib must load **before** tRadio. Use your real folder name (for example `ensure [tScripts]/tRadio`). Restart the server.

A healthy start prints a banner with these rows:

| Row          | Healthy value                                      |
| ------------ | -------------------------------------------------- |
| **Status**   | `Server started successfully`                      |
| **Panel**    | `http://203.0.113.10:7777` — the dispatch panel    |
| **Admin**    | `http://203.0.113.10:7777/admin` — the admin panel |
| **NAC ID**   | Your `dispatchNacId`                               |
| **FX Ver**   | `bodacious`                                        |
| **Config**   | `3 zones, 12 channels`                             |
| **Warnings** | Empty                                              |

If **Status** is amber saying the port is reachable on localhost but the public probe failed, the radio works for players — this host just can't reach its own public IP (hairpin NAT, CGNAT, or a reverse proxy). Confirm from [portchecker.co](https://portchecker.co/check-v0) or a phone on mobile data. If it is red, the port is genuinely closed — see [Troubleshooting](/docs/tRadio/troubleshooting#the-radio-wont-connect).

### Confirm a player can transmit

tRadio ships preconfigured, so this should work immediately.

1. Join your server as a player whose job is `police`, `sheriff`, `ambulance`, or `fire`
2. Press **F6** — the radio opens
3. Press the on-radio **CH** button, pick **DISP**, and press **CON**
4. Hold **B** and speak — the display shows `TX:` with your name

If the radio does not open at all, the server has not granted radio access — see [Give your players radios](/docs/tRadio/configuration#framework-integration).

---

## What ships preconfigured

A new install is not empty. `data.json` arrives with a working starter configuration:

| Item                    | Shipped content                                                                |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Zones**               | Statewide, Los Santos, Blaine County                                           |
| **Channels**            | `DISP`, `C2C` (trunked), `10-1`, `OPS-1` (encrypted) in each zone              |
| **Codeplug**            | One, with ID `leo`, NAC `141`                                                  |
| **Job mapping**         | `police`, `sheriff`, `ambulance`, `fire` → `leo`, in `config/sv_functions.lua` |
| **Alerts**              | SIGNAL 100, SIGNAL 3, Ping, Bonk                                               |
| **Announcement groups** | `* DISP` and `* C2C`, each spanning all three zones                            |

Everything above is editable live in the admin panel at `http://your-server-ip:port/admin` — no restart. Only `config/config.lua` and `config/sv_functions.lua` need a `restart tRadio`.

Your first real configuration jobs are usually: rename the zones and channels to match your city, then split the single `leo` codeplug into one per department. Both are covered in [Configuration](/docs/tRadio/configuration#zones-and-channels).

---

## Updating tRadio

Six items hold your configuration. Everything else is replaceable.

| Keep                      | Replace         |
| ------------------------- | --------------- |
| `config/config.lua`       | Everything else |
| `config/cl_functions.lua` |                 |
| `config/sv_functions.lua` |                 |
| `config/locales.json`     |                 |
| `data.json`               |                 |
| `layouts/`                |                 |

1. Download the new release zip and extract it somewhere temporary
2. Delete everything in your existing folder **except** the six items above
3. Copy the new files in
4. Run `restart tRadio`

  Release notes call out any change to `config.lua` keys. Read them before updating — new keys are
  not added to your existing file automatically.

To reset every admin-panel setting to factory defaults, stop the resource, delete `data.json`, and start it again. You lose all zones, channels, codeplugs, alerts, speakers, towers, and audio settings; the panel then offers **Load Defaults** buttons on the Zones, Alerts, and Codeplugs pages to rebuild the starter set.

<!-- llms-full-doc-separator -->

# tlib Installation (https://timmygstudios.com/docs/tlib/installation)
How to install tLib on your FiveM or Helix server.

## Prerequisites

- FiveM or Helix server

---

### Download

Download the latest release from [GitHub Releases](https://github.com/tommy141x/tLib/releases).

### Extract

Place the `tLib` folder in your server's `resources` directory.

### Start the Resource

Add to your `server.cfg` **before** any resource that depends on it:

```txt
title="server.cfg" ensure tLib
```

---

## Usage in Your Resource

To use tLib as a dependency, add it to your resource's `fxmanifest.lua`:

```lua
title="fxmanifest.lua" dependencies { 'tLib' }
```

### Using Exports

Call tLib systems directly via exports:

```lua
-- Create and open a menu
local menuId = exports['tLib']:CreateMenu('my_menu', 'My Menu', 'Subtitle')
exports['tLib']:AddButton(menuId, 'btn1', 'Click Me', 'A button', function()
    print('clicked!')
end)
exports['tLib']:RefreshMenu(menuId)
exports['tLib']:OpenMenu(menuId)
```

### Using Import Modules

For lightweight modules (coords, kvp, settings, layouts), declare them in your `fxmanifest.lua` and add the imports script:

```lua
title="fxmanifest.lua" dependencies { 'tLib' } shared_scripts { '@tLib/imports.lua' } tlib_modules { 'kvp', 'settings' }
```

Then access them via the `tlib` global:

```lua
local kvp = tlib.kvp
local value = kvp.getString('my_key', 'default')
```

Modules are lazy-loaded — they only load when first accessed.

<!-- llms-full-doc-separator -->

# tels Installation (https://timmygstudios.com/docs/tels/installation)
How to install and configure tELS for your FiveM server.

## Prerequisites

- FiveM server with **OneSync** enabled (Infinity or Legacy)
- **tLib** resource (minimum version `0.6`) — tELS depends on it for discovery, persistence, admin ACE, dialogs, layouts, and the move-mode HUD editor
- Lua 5.4 (the manifest already declares `lua54 'yes'`)

  tELS does not load existing ELS or non-ELS vehicle packs. Vehicles are configured from scratch
  using the in-game editor, or by bundling a `tels.json` inside the vehicle resource.

---

## Install

### Extract the resource

Drop the `tELS` folder into your server's `resources` directory. If you group resources (e.g., `[tScripts]`), place it alongside them.

### Start tLib before tELS

Order matters — tELS resolves tLib exports at load time.

`server.cfg`

```ini
ensure tLib ensure tELS
```

### Grant admin access

The editor and server-wide defaults require tLib's admin ACE. Add it to any group that should be able to edit vehicles:

`server.cfg`

```ini
add_ace group.admin tlib.admin allow
```

Admins can:

- Open `/telsedit`
- Save server-wide display defaults (emissive, bloom, env quality, HUD layout) from `/tels`
- Open the editor button in `/tels`

### Start the server

On first run tELS creates `data.json` at the resource root to store vehicle configs. No further setup is required.

---

## Quick start: light up your first vehicle

Goal: get an emergency vehicle flashing red and blue in under two minutes. Deeper configuration is covered in the [Editor guide](/docs/tels/editor).

### Spawn the vehicle

Spawn any emergency vehicle (e.g., `police4`) and get in.

### Open the editor

Run `/telsedit`. The 3D editor opens with an empty LED list — the vehicle has no config yet.

### Auto-create LEDs from the lightbar

In the **LEDs** tab sidebar, click **Create from siren bones**. tELS scans the vehicle's `siren1`…`sirenN` bones and adds a starter LED at each one, already grouped and sided. No manual placement needed to get started.

### Add a basic pattern

Switch to the **Patterns** tab, click **Add Pattern**, set it to about 10 FPS, add a **Red** and a **Blue** color to the palette, then paint a few alternating columns across the grid. The pattern previews live on the vehicle as you paint.

### Save and exit

Press **Enter** (or click **Save**). The config writes to `data.json` and broadcasts to every connected client.

### Press Q

Back in the vehicle, press **Q** — lights on. Press **R** to burst the siren. Press **9 / 0** to cycle through any additional patterns.

From here, see:

- [Editor guide](/docs/tels/editor) — full LED / pattern / trigger / siren workflow
- [Usage guide](/docs/tels/usage) — every keybind, client setting, and mode
- [Configuration](/docs/tels/configuration) — the `data.json` schema and cross-vehicle references

---

## File layout

| Path                     | Purpose                                                                           |
| ------------------------ | --------------------------------------------------------------------------------- |
| `fxmanifest.lua`         | Resource manifest                                                                 |
| `data.json`              | Per-vehicle configs + server display defaults (auto-generated)                    |
| `shared/`                | Shared helpers (UUIDs, resolvers, LED defaults, audio banks, PA config, geometry) |
| `server/sv_configs.lua`  | Discovery + ref-edit relays + server defaults                                     |
| `server/sv_relay.lua`    | State bag ownership + remote state sync                                           |
| `client/cl_lights.lua`   | Pattern playback and stage state                                                  |
| `client/cl_triggers.lua` | Trigger condition evaluation                                                      |
| `client/cl_siren.lua`    | Siren tone playback                                                               |
| `client/cl_arges.lua`    | Arges spotlight props                                                             |
| `client/cl_pa.lua`       | PA mic (pma-voice integration)                                                    |
| `client/cl_hud.lua`      | HUD overlay + `/tels` dialog                                                      |
| `client/cl_input.lua`    | Keybinds, commands, park-kill thread                                              |
| `client/cl_editor.lua`   | NUI editor bridge                                                                 |
| `client/ui/`             | Built NUI assets (do not edit)                                                    |
| `client/web/`            | NUI source (SolidJS + Three.js)                                                   |
| `layouts/`               | HUD layouts (auto-discovered)                                                     |
| `audio/`                 | Custom siren sounds (awc + dat54)                                                 |
| `stream/`                | Arges spotlight ytyp                                                              |

  These are built NUI assets. Source for the editor and HUD lives in `client/web/`. Build with `bun
  run build` from the resource root.

<!-- llms-full-doc-separator -->

# tDetector Installation (https://timmygstudios.com/docs/tDetector/installation)
How to install tDetector on your FiveM server.

## Prerequisites

- FiveM server with **OneSync** enabled (Infinity or Legacy)
- **tLib** — provides settings persistence, move mode, dialog system, and layout discovery
- At least one supported radar resource (see below). tDetector loads cleanly without one, but nothing will be detected.

### Supported radar resources

| Resource                        | Notes                                        |
| ------------------------------- | -------------------------------------------- |
| **Wraith ARS 2X** (`wk_wars2x`) | Requires a one-time export patch (see below) |
| **Seeker Dual** (`seeker_dual`) | Requires a one-time export patch (see below) |

Both can run simultaneously — tDetector checks each one and stops at the first active hit.

## Install

### Extract the resource

Drop the `tDetector` folder into your `resources` directory (e.g., alongside other `[tScripts]`).

### Patch your radar resource(s)

tDetector reads radar-gun state through a client export named `IsRadarActive`. Add it once to whichever radar resource(s) you run.

#### Wraith ARS 2X (`wk_wars2x`)

**`wk_wars2x/fxmanifest.lua`** — add one line before the client scripts block:

```lua
client_export "IsRadarActive"
```

**`wk_wars2x/cl_radar.lua`** — add anywhere at the top level (after the `RADAR` table is defined):

```lua
exports('IsRadarActive', function()
    return RADAR:IsPowerOn() and RADAR:IsEitherAntennaOn()
end)
```

#### Seeker Dual (`seeker_dual`)

**`seeker_dual/fxmanifest.lua`** — add one line before the client scripts block:

```lua
client_export "IsRadarActive"
```

**`seeker_dual/client/exports.lua`** (or any client script) — add:

```lua
exports('IsRadarActive', function()
    return Radar.power and (Radar.frontXmit or Radar.rearXmit)
end)
```

  Without this export tDetector loads cleanly but cannot detect any active radar guns. The export is
  read-only and does not change the radar resource's behavior.

### Add to server.cfg

`tLib` must start before `tDetector`. Your radar resource(s) should also be running.

`server.cfg`

```ini
ensure tLib
ensure wk_wars2x   # and/or seeker_dual
ensure tDetector
```

### Start the server

No further setup is required. Per-player settings (speed unit, layout, HUD position) are stored in KVP. The server creates `data.json` automatically on first start to store the sound configuration.

## Configuration

Open `shared/config.lua` to change the resource name, default speed unit, or enable QBCore item support:

`shared/config.lua`

```lua
Config = {}

-- List every radar resource tDetector should listen for.
-- Each must expose a client export named IsRadarActive() → boolean.
-- Resources that are not running are skipped silently.
Config.radarResources = {
    "wk_wars2x",
    "seeker_dual",
}

-- Default speed unit: 'mph' or 'kph'
-- Players can override this per-session from /tDet
Config.speedUnit = "mph"

-- Who can open /tDet — "everyone", "ace", or "item" (see Access control below)
Config.accessMode    = "everyone"
Config.acePermission = "tdetector.use"

-- QBCore item support (optional)
-- Set useAsItem to true and ensure qb-core is running to allow the detector to be used as a QB item.
Config.useAsItem  = false
Config.qbItemName = "radardetector"
```

  Unlike per-player settings, `Config.accessMode` and `Config.acePermission` are read on resource
  start. Run `restart tDetector` after changing them.

## Access control

`Config.accessMode` controls who can toggle the detector:

| Mode         | Behavior                                                                                                                                                                                                                                                                          |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"everyone"` | Default. Anyone can run `/tDet` and use the toggle button.                                                                                                                                                                                                                        |
| `"ace"`      | Only players granted `Config.acePermission` can run `/tDet` at all. Everyone else gets a chat message and the dialog never opens.                                                                                                                                                 |
| `"item"`     | `/tDet` still opens for everyone — speed unit, HUD layout, and reposition all still work — but the toggle button is disabled. The detector can only be enabled/disabled through the QBCore item, which this mode turns on by itself (`Config.useAsItem` does not need to be set). |

The `"ace"` check runs server-side on every `/tDet` invocation, so granting or revoking the permission takes effect immediately — no reconnect needed. `"item"` mode's toggle lock is decided client-side (it just reads `Config.accessMode`, which is a shared script) since it's a UI restriction, not a permission check.

To grant the ace permission in `server.cfg`:

`server.cfg`

```ini
add_ace group.mechanic tdetector.use allow
add_principal identifier.license:xxxxxxxx group.mechanic
```

(Swap `group.mechanic` and the permission name for whatever fits your server — `Config.acePermission` can be renamed to anything.)

  Speed unit, layout choice, and HUD position are all saved in player KVP via `/tDet`. You only need
  to edit `shared/config.lua` to change the server-wide default or add/remove radar resources.

## QBCore item support (optional)

tDetector can be triggered as a useable inventory item instead of (or alongside) the `/tDet` toggle button.

  That mode enables the item hook by itself — skip straight to [Add the item to QB shared
  items](#add-the-item-to-qb-shared-items). `Config.useAsItem` below is only for running the item
  *alongside* an active `/tDet` command (`accessMode` `"everyone"` or `"ace"`).

### Enable item usage

In `shared/config.lua` set:

```lua
Config.useAsItem  = true
Config.qbItemName = "radardetector"  -- must match your items.lua entry
```

### Add the item to QB shared items

In `qb-core/shared/items.lua`:

```lua
['radardetector'] = {
  ['name']        = 'radardetector',
  ['label']       = 'Radar Detector',
  ['weight']      = 3000,
  ['type']        = 'item',
  ['image']       = 'radardetector.png',
  ['unique']      = true,
  ['useable']     = true,
  ['shouldClose'] = true,
  ['combinable']  = nil,
  ['description'] = 'We are not liable for your reckless driving.',
},
```

### Add the inventory image

Drop `radardetector.png` into `qb-inventory/html/images/`.

### Restart

```ini
restart tDetector
```

Using the item while in a vehicle toggles the detector on or off — identical to pressing the button in `/tDet`.

## File layout

| Path                     | Purpose                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `data.json`              | Auto-created on first start — stores sound key→file mappings and installed sounds                 |
| `shared/config.lua`      | Radar resource name, default speed unit, access mode, QB item config                              |
| `server/sv_admin.lua`    | Layout discovery, marketplace registration, sounds config persistence, `/tDet` access gate        |
| `server/sv_sync.lua`     | Broadcasts active radar-gun list to all clients every second                                      |
| `server/sv_item.lua`     | QBCore useable item handler (runs when `Config.useAsItem = true` or `Config.accessMode = "item"`) |
| `client/cl_hud.lua`      | NUI toggle, move mode, layout switching, KVP persistence                                          |
| `client/cl_detector.lua` | Detection loop — finds the closest active radar gun each tick                                     |
| `client/cl_settings.lua` | `/tDet` settings dialog                                                                           |
| `client/ui/`             | Built NUI assets (do not edit)                                                                    |
| `client/web/`            | NUI source (SolidJS — build with `bun run build`)                                                 |
| `layouts/`               | HUD layout skins (auto-discovered)                                                                |

  These are built NUI assets. The source lives in `client/web/`. To rebuild after modifying the
  SolidJS source, run `bun run build` from inside `client/web/`.

<!-- llms-full-doc-separator -->

# tAFK Installation (https://timmygstudios.com/docs/tAFK/installation)
How to install tAFK, grant admin access, and confirm the resource is running.

## Prerequisites

- FiveM server with **OneSync** enabled (Infinity or Legacy)
- [tLib](https://github.com/tommy141x/tLib/releases) — install the **release zip**, not the source code (source lacks built files). tAFK depends on it for Discovery, KVP, dialogs, toasts, and admin ACE
- Lua 5.4 (the manifest already declares `lua54 'yes'`)

  tAFK is the successor to the older `tommys-afk` script. If you had that installed, remove it
  before starting tAFK — the resource name, exports, and state-changed event are all different
  (`tafk:stateChanged` instead of `tommys-afk:stateChanged`).

---

## Install

### Extract the resource

Drop the `tAFK` folder into your server's `resources` directory. If you group resources (e.g., `[tScripts]`), place it alongside them.

### Start tLib before tAFK

Order matters — tAFK resolves tLib exports and Discovery at load time.

```ini
title="server.cfg" ensure tLib ensure tAFK
```

### Grant admin access

The editor, global settings, sequence management, and music-track registration all require tLib's admin ACE. Add it to any group that should be able to author sequences or tune server-wide defaults:

```ini
title="server.cfg" add_ace group.admin tlib.admin allow
```

Admins can:

- Open `/tafkedit` (or the **Open Sequence Editor** button in `/tafk`, visible when in a vehicle)
- Manage sequences — list, enable/disable, create, edit, delete — all inside the editor overlay
- Adjust global settings via **Server Defaults** (idle timeout, duration bounds, beat anchor, music defaults)

Non-admins see only the player-facing section of `/tafk` — their own overrides, sequence opt-outs, and a toggle button.

### Start the server

On first run tAFK creates `data.json` at the resource root, seeded with 11 default sequences and 5 bundled music tracks. No further setup is required.

---

## Quick start: see it in action

Goal: get the camera orbiting your vehicle in under a minute.

### Spawn a vehicle

Any vehicle — AFK works on cars, bikes, boats, aircraft.

### Stop moving

Sit still. After 30 seconds of no input (movement, mouse, keys), tAFK fades out and drops into the first sequence.

### Or trigger it manually

Type `/afk` to skip the timer. The same fade → cinematic sequence plays immediately.

### Hit any input to exit

Any key, mouse move, gamepad stick — instant cancel, fade back to gameplay.

From here, see:

- [Usage guide](/docs/tAFK/usage) — all commands, the `/tafk` dialog, state-bag integration
- [Editor guide](/docs/tAFK/editor) — author your own camera sequences in-game
- [Configuration](/docs/tAFK/configuration) — `data.json` schema, per-vehicle packs, admin options

---

## File layout

| Path                      | Purpose                                                                                   |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| `fxmanifest.lua`          | Resource manifest — declares tLib dependency and the `tafk_config` Discovery metadata key |
| `data.json`               | Settings, sequences, music tracks, vehicleConfigs (auto-generated)                        |
| `shared/utils.lua`        | Log helper, camera math, `tafkToVec3` decoder                                             |
| `shared/schema.lua`       | Default settings + sequences + validators                                                 |
| `server/sv_store.lua`     | `data.json` read/write with read-merge-write to coexist with Discovery                    |
| `server/sv_discovery.lua` | tLib Discovery instance for `tafk_config` → `vehicleConfigs` section                      |
| `server/sv_admin.lua`     | ACE-gated event handlers (save, toggle, register track, etc.)                             |
| `client/cl_bridge.lua`    | Receives server config + vehicle configs, exposes merged getters                          |
| `client/cl_camera.lua`    | AFK lifecycle, camera render, state-bag broadcast                                         |
| `client/cl_director.lua`  | Weighted sequence selection with raycast penalties                                        |
| `client/cl_detector.lua`  | Idle detection, exit conditions, auto-AFK timer                                           |
| `client/cl_music.lua`     | NUI music bridge + beat-data callback                                                     |
| `client/cl_editor.lua`    | Orbit-camera keyframe editor + NUI callbacks                                              |
| `client/cl_settings.lua`  | `/tafk` dialog (player prefs + admin sub-dialogs)                                         |
| `client/ui/`              | Built NUI assets (do not edit)                                                            |
| `client/web/`             | NUI source (SolidJS + Vite + UnoCSS)                                                      |
| `audio/`                  | Music tracks (`.ogg`/`.mp3`/`.wav`)                                                       |

  These are built NUI assets. Source for the editor HUD and music player lives in `client/web/`.
  Build with `bun run build` from `client/web/`.

---

## Verifying the install

After starting the server, look for this in the console:

```
[tAFK] loaded: 11 sequences, 5 music tracks discovered, v1
```

(Music-tracks count reflects `.ogg`/`.mp3`/`.wav` files discovered in `tAFK/audio/` — either name-matched by pattern or listed in `audio/manifest.txt`. See [Configuration → Music tracks](/docs/tAFK/configuration#music-tracks).)

On the client, after resource start:

```
[tAFK] cinematic camera system loaded
[tAFK] config received: 11 sequences, 5 tracks
```

If the player has the `tafk:enabled` KVP flag set (from a previous `/tafk` toggle), you'll also see:

```
[tAFK] AFK disabled by player preference
```

That's the normal path for a player who previously opted out.

<!-- llms-full-doc-separator -->

# tels Integrations (https://timmygstudios.com/docs/tels/integrations)
How to configure tELS vehicles to work with third-party scripts.

## ERS (night_ers)

night_ers gates pullover detection on GTA's native emergency-lights flag. Because tELS uses its own rendering pipeline, turning on a tELS stage does **not** automatically set that flag — you need to tell tELS to blip it via the `ers_pullover` trigger action.

### How it works

The `ers_pullover` action fires on the **rising edge** of whichever conditions you attach it to. On that edge it briefly activates GTA's native emergency-lights flag — visually silent (audio muted by tELS) — for long enough that night_ers detects it and allows a pullover. The flag clears itself automatically after the blip window.

No night_ers dependency is created anywhere in tELS. The action works the same whether night_ers is installed or not — it just flips a GTA native flag.

### Setup

### Open the Triggers tab for your vehicle

Run `/telsedit` while seated in the vehicle, then navigate to **Triggers**.

### Add a trigger

Click **Add Trigger**. Set the condition(s) that should allow a pullover — typically `stage_2`, `siren`, or a combination of both.

### Add the ers_pullover action

With the trigger selected, click **Add Action** and choose `ers_pullover`.

### Save

Press **Enter** (or the Save button) to write the config.

### Recommended condition

The most common setup is to fire on `stage_2` — the stage players typically activate when approaching a traffic stop:

`data.json (triggers entry for your vehicle)`

```json
{
  "id": "a1b2c3d4e5f6a7b8",
  "conditions": [
    "stage_2"
  ],
  "negated": [
    false
  ],
  "operator": "and",
  "enabled": true,
  "actions": [
    {
      "type": "ers_pullover"
    }
  ]
}
```

You can attach it to any condition or combination — `siren`, `stage_3`, `main_siren_on`, or a compound rule. Whatever reflects "I intend to stop this vehicle" on your server.

### Blip duration

The blip window defaults to **300 ms** and that is the recommended value — it reliably covers one full enforcement tick (which runs every 200 ms) and is confirmed to work with night_ers. You do not need to change it.

If you want to override it anyway:

```json
{ "type": "ers_pullover", "durationMs": 500 }
```

Do not set `durationMs` below 300 ms. The enforcement loop that applies the GTA flag runs every 200 ms, so a shorter window may expire before the loop fires and night_ers will miss the detection.

### Using a cross-vehicle reference

If you have multiple police vehicles that all need ERS support, configure the trigger once on your primary model (e.g., `police4`) and reference it from the others:

`police5, police6 triggers[]`

```json
{
  "$ref": "police4",
  "triggerId": "a1b2c3d4e5f6a7b8"
}
```

See [Configuration → Cross-vehicle references](/docs/tels/configuration#cross-vehicle-references) for details.

<!-- llms-full-doc-separator -->

# tels LED Naming Convention (https://timmygstudios.com/docs/tels/led-naming)
Standard naming convention for LED groups on tELS vehicles.

## Overview

tELS identifies individual LEDs by internal UUID, but each LED can carry a **name** field that groups it semantically. These names drive HUD display, trigger conditions, and pattern targeting by name.

This page defines the naming standard all vehicle configs should follow.

---

## Format

```
[ZONE][FACE?][SIDE?][NUM]
```

| Part   | Description                                                                                  |
| ------ | -------------------------------------------------------------------------------------------- |
| `ZONE` | 2–4 letter zone code (see tables below)                                                      |
| `FACE` | Optional face direction: `F` (forward) or `R` (rear) — only when the zone has multiple faces |
| `SIDE` | Optional side: `L` (left) or `R` (right) — only for physically separate side-facing units    |
| `NUM`  | Sequential number starting at `1`                                                            |

### Rules

1. **All uppercase**, no spaces, no special characters.
2. **Forward/rearward-facing lights** — use sequential numbers only. No L/R suffix. (`RD1`, `RD2`, `LBF1`, `LBF2`)
3. **Side-facing lights** — use an L/R suffix because they are physically separate units on opposite sides. Add a number after if there are multiple per side. (`MRL`, `MRR`, `SRL1`, `SRL2`) Omit `NUM` when there is only one unit per side — `LBAL` not `LBAL1`, `PIL` not `PIL1`.
4. **Names describe physical location only.** Functions like takedowns, traffic advisor, and alley lights are _pattern behaviors_, not LED names. The same physical LED can act as a takedown in one pattern and a standard flasher in another.
5. Numbers count left to right **from the perspective of an observer standing outside the vehicle, looking directly at that face.** Numbering typically starts at `1`, but starting at `0` is permitted — and encouraged — when a vehicle has more LEDs than the standard cross-vehicle range. For example, a rear lightbar with 8 LEDs should use `LBR0`–`LBR7`: the `LBR1`–`LBR6` core remains the cross-vehicle compatible zone (what patterns and the HUD reliably target), while `LBR0` and `LBR7` are vehicle-specific extensions. Patterns written for the full range silently skip any names that don't exist on a given vehicle, so a pattern targeting `LBR0`–`LBR7` degrades gracefully on a vehicle that only defines `LBR2`–`LBR5`. This means:
   - **Front-facing lights** (`LBF#`, `FG#`, `FB#`, `DS#`, `FV#`, etc.) — `#1` is on the **vehicle's right**, because the observer facing the front sees the vehicle's right on their left.
   - **Rear-facing lights** (`LBR#`, `RD#`, `RV#`, etc.) — `#1` is on the **vehicle's left**, because the observer facing the rear sees the vehicle's left on their left.
   - **Right-side lights** (`SRR#`, `DOR#`, etc.) — `#1` is toward the **vehicle's rear**, because the observer facing the right side sees the rear on their left.
   - **Left-side lights** (`SRL#`, `DOL#`, etc.) — `#1` is toward the **vehicle's front**, because the observer facing the left side sees the front on their left.

---

## Zone Reference

### Roof

| Code   | Description                          | Example                |
| ------ | ------------------------------------ | ---------------------- |
| `LBF#` | Lightbar — front face                | `LBF1`, `LBF2`, `LBF3` |
| `LBR#` | Lightbar — rear face                 | `LBR1`, `LBR2`, `LBR3` |
| `LBAL` | Lightbar — alley left (side-facing)  | `LBAL`                 |
| `LBAR` | Lightbar — alley right (side-facing) | `LBAR`                 |
| `MBF#` | Mini bar — front face                | `MBF1`, `MBF2`         |
| `MBR#` | Mini bar — rear face                 | `MBR1`, `MBR2`         |
| `MBAL` | Mini bar — alley left                | `MBAL`                 |
| `MBAR` | Mini bar — alley right               | `MBAR`                 |
| `BK#`  | Beacon / rotator                     | `BK1`                  |

> **Alley lights:** `LBAL` / `LBAR` are the physically side-facing LED units built into the ends of the lightbar. Whether they illuminate as alley lights, scene lights, or anything else is determined by the pattern — not the name.

### Front Exterior

| Code          | Description                              | Example      |
| ------------- | ---------------------------------------- | ------------ |
| `FG#`         | Front grille                             | `FG1`, `FG2` |
| `FB#`         | Front bumper / push bar (forward-facing) | `FB1`, `FB2` |
| `FBL` / `FBR` | Front bumper side end caps (side-facing) | `FBL`, `FBR` |
| `HD#`         | Hood lights                              | `HD1`, `HD2` |

### Front Interior _(projects forward through windshield)_

| Code  | Description                     | Example      |
| ----- | ------------------------------- | ------------ |
| `DS#` | Dash lights (low mount)         | `DS1`, `DS2` |
| `FV#` | Front visor lights (high mount) | `FV1`, `FV2` |

### Side

| Code            | Description                                         | Example                |
| --------------- | --------------------------------------------------- | ---------------------- |
| `MRL` / `MRR`   | Mirror lights                                       | `MRL`, `MRR`           |
| `SRL#` / `SRR#` | Side runner lights                                  | `SRL1`, `SRL2`, `SRR1` |
| `DOL#` / `DOR#` | Door lights                                         | `DOL1`, `DOR1`         |
| `PIL` / `PIR`   | Pillar light sticks (B/C-pillar directional sticks) | `PIL`, `PIR`           |

### Rear Interior _(projects rearward through rear glass)_

| Code  | Description             | Example             |
| ----- | ----------------------- | ------------------- |
| `RD#` | Rear deck — low mount   | `RD1`, `RD2`, `RD3` |
| `RV#` | Rear visor — high mount | `RV1`, `RV2`        |

### Rear Exterior

| Code          | Description                                 | Example        |
| ------------- | ------------------------------------------- | -------------- |
| `RB#`         | Rear bumper face (exterior, bumper-mounted) | `RB1`, `RB2`   |
| `RR#`         | Rear runner (body/rocker perimeter)         | `RR1`, `RR2`   |
| `RSP#`        | Rear step pad lights                        | `RSP1`, `RSP2` |
| `LPL` / `LPR` | License plate lights                        | `LPL`, `LPR`   |

### Specialty

| Code          | Description                       | Example      |
| ------------- | --------------------------------- | ------------ |
| `SPL` / `SPR` | Spotlight (A-pillar or roof edge) | `SPL`, `SPR` |
| `SC#`         | Scene / work lights               | `SC1`, `SC2` |
| `CAB#`        | Cabin / interior dome lights      | `CAB1`       |

---

## HUD Default LEDs

The tELS HUD displays a row of colored LED indicators. When no layout specifies which LED names to show, tELS automatically resolves the best available set from the vehicle config using this fallback chain:

| Priority | Names checked   | Typical source     |
| -------- | --------------- | ------------------ |
| 1st      | `RD1` – `RD6`   | Rear deck lights   |
| 2nd      | `RV1` – `RV6`   | Rear visor lights  |
| 3rd      | `LBR1` – `LBR6` | Lightbar rear face |

tELS uses whichever group has **at least one matching LED** on the vehicle. Only the LEDs that actually exist in the config are shown — if a vehicle only has `RD1`, `RD2`, and `RD3`, the HUD shows three indicators, not six.

If none of the above names exist on the vehicle, the HUD falls back to showing all LEDs.

Custom HUD layouts can override this entirely by declaring their own `data-hud-led` bindings.

---

## Out of Scope

**Factory light circuits** (headlight flashers, tail light flashers) are not part of this convention. These are native vehicle lights driven by the game engine, not placed LEDs in the tELS config. If tELS ever gains addressable control over factory circuits, they will be assigned their own convention at that time. Do not invent names like `HLF` or `TLF` — there is no placed LED to attach them to.

<!-- llms-full-doc-separator -->

# tDetector Layouts (https://timmygstudios.com/docs/tDetector/layouts)
Build a custom radar detector skin with HTML, CSS, sounds, and the state callback API.

## Overview

A layout is a self-contained folder under `layouts/` containing a `ui.html` entry point plus any icons and sounds it needs. The SolidJS HUD panel fetches the HTML at runtime, injects it into the page, and calls a JavaScript callback every time the radar state changes.

Lua does no presentation logic — the layout decides what to show and when.

Folders in `layouts/` are auto-discovered on server start and appear in the **HUD Layout** selector in `/tDet`.

---

## Folder structure

```
layouts/
  sounds/            shared sound files — available to all layouts
    blip.wav
    gps_connected.wav
    ka_band.wav
  MyLayout/
    ui.html          required — layout entry point
    icons/           PNG / SVG assets
    sounds/          optional layout-specific sound overrides
```

Image and audio `src` attributes in `ui.html` are automatically rewritten to be absolute before injection, so use simple relative paths:

```html
<img src="icons/radar_frame.png" />
```

For sounds, use the injected `window.__tdetSoundsDir` variable (points to the shared `layouts/sounds/` folder) rather than hard-coding a path:

```js
var soundsDir = window.__tdetSoundsDir || "./sounds/";
var blip = new Audio(soundsDir + "blip.ogg");
```

`window.__tdetLayoutDir` is also available and points to the current layout's own folder, for layout-specific assets.

---

## Create a layout

### Create the folder

`layouts/MyLayout/` — the folder name is what players see in the `/tDet` layout selector.

### Add `ui.html`

This is the full layout. It can contain all HTML, CSS, and a single `<script data-layout-script>` block for logic.

### Add assets

Drop icons and sounds into `icons/` and `sounds/`. The script tries `.ogg` for sounds and falls back to `.wav`.

### Restart the resource

```ini
restart tDetector
```

The layout appears in `/tDet → HUD Layout`.

---

## State callback

Register `window.__tdetLayoutUpdate` inside a `<script data-layout-script>` block. It is called after every state update.

```html
<script data-layout-script>
  (function () {
    window.__tdetLayoutUpdate = function (state, root) {
      // state — object with the keys below
      // root  — this layout's container element (use for querySelector)
    };

    // Optional: called when the layout is replaced or the component unmounts.
    // Cancel timers, remove listeners, reset internal variables here.
    window.__tdetLayoutDestroy = function () {};
  })();
</script>
```

  Always wrap layout scripts in an immediately-invoked function expression `(function () { … })()`. Multiple layouts may be injected over a session — an IIFE prevents variable collisions between layout loads.

---

## Available state keys

| Key         | Type    | Description                                                                                       |
| ----------- | ------- | ------------------------------------------------------------------------------------------------- |
| `radarOn`   | boolean | Detector is active. `false` is the reset signal — hide everything and reset timers.               |
| `inVehicle` | boolean | Player is currently in a vehicle                                                                  |
| `distance`  | number  | Distance in metres to the closest active radar gun. `-1` when no radar is within range (≥ 300 m). |
| `speed`     | number  | Player's current speed in the selected unit (rounded integer)                                     |
| `unit`      | string  | `"mph"` or `"kph"`                                                                                |
| `facing`    | string  | `"front"` — radar source is ahead. `"back"` — radar source is behind.                             |

### State lifecycle

- **`radarOn: false`** — sent once when the detector is turned off. Reset all timers, hide all elements, clear any internal state.
- **`radarOn: true, inVehicle: true`** — normal operation. Update the display each call.
- Updates arrive every ~500 ms while the detector is on.

---

## Sounds

Shared sounds live in `layouts/sounds/`. Load them using the injected `window.__tdetSoundsDir` path helper:

```js
var soundsDir = window.__tdetSoundsDir || "./sounds/";

function makeSound(name) {
  var a = new Audio(soundsDir + name + ".ogg");
  a.onerror = function () {
    a.src = soundsDir + name + ".wav";
  }; // wav fallback
  return a;
}

var blip = makeSound("blip");

function play(audio) {
  audio
    .cloneNode()
    .play()
    .catch(function () {});
}
```

Using `cloneNode()` allows the same sound to overlap itself — important for a blip that fires repeatedly at short intervals.

Layout-specific sounds can live in `MyLayout/sounds/` and are accessed via `window.__tdetLayoutDir`:

```js
var mySound = new Audio(window.__tdetLayoutDir + "sounds/custom.ogg");
```

---

## Minimal example

```html
<div>
  <style>
    .det {
      width: 200px;
      padding: 12px;
      background: #111;
      color: #0f0;
      font-family: monospace;
      border-radius: 4px;
    }
    .det-hidden {
      display: none;
    }
  </style>

  <div class="det" id="det-root">
    <div id="det-distance">No signal</div>
    <div id="det-speed"></div>
  </div>
</div>

<script data-layout-script>
  (function () {
    function el(id) {
      return document.getElementById(id);
    }

    window.__tdetLayoutUpdate = function (state) {
      if (!state.radarOn) {
        el("det-distance").textContent = "No signal";
        el("det-speed").textContent = "";
        return;
      }

      var dist = state.distance;
      el("det-distance").textContent =
        dist !== -1
          ? (state.facing === "front" ? "FRONT" : "REAR") + " — " + Math.round(dist) + "m"
          : "Scanning…";
      el("det-speed").textContent = (state.speed || 0) + " " + (state.unit || "mph");
    };
  })();
</script>
```

---

## UI Studio

Build and publish custom layouts with the **[UI Studio](https://timmygstudios.com/marketplace/studio)**. See the [Marketplace docs](/docs/marketplace#ui-studio) for the full walkthrough — creating drafts, design vs HTML mode, lint rules, bundle limits, forking, and publishing.

---

## Default layout reference

The built-in `Youniden7` layout is a direct port of the original Youniden detector display. It uses eight proximity rings, front/rear direction arrows, a speed readout, and a startup boot sequence. The source is at `layouts/Youniden7/ui.html` and is the best starting point for a custom skin.

<!-- llms-full-doc-separator -->

# Marketplace (https://timmygstudios.com/docs/marketplace)
Browse, install, and publish layouts and sound packs for tRadio, tELS, and tDetector.

The tLib marketplace lets you browse, install, and publish layouts and sound packs for tRadio, tELS, and tDetector — no file editing or server restart required.

---

## Browsing and Installing

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">

</div>

Access via the in-game panel for your script (`/tradio`, `/tels`, `/tdet`) → **Marketplace**, or through the tLib web panel. Two tabs:

- **Browse** — search and install available items. Installed items show a checkmark; click **Uninstall** to remove.
- **Installed** — lists every item currently on the server with a remove button for each.

---

## UI Studio

The **UI Studio** is the tool for building and publishing custom layouts for any tScript. Supported product types:

| Script    | Canvas size  |
| --------- | ------------ |
| tRadio    | 300 × 406 px |
| tDetector | 400 × 400 px |
| tELS      | 400 × 120 px |

### Access

Any signed-in account can publish — creator status is granted automatically on your first upload. The only gate is a staff-issued ban, which blocks further uploads and immediately hides your existing published items.

### Creating a layout

1. Go to [Your Creations](/app/marketplace/manage).
2. Click **Create UI**, then pick the target script and start designing.
3. The UI Studio opens with a new draft.

### Editor modes

- **Design mode** — visual canvas; drag to add/position/resize elements. Seven element types: background image, text, LED (boolean toggle), LED-color, icon toggle, icon set, button. Not available for tDetector — see below.
- **HTML mode** — raw code editor; full control over markup and CSS.

Undo/redo (50 states) works in both modes. Design-mode layouts embed the canvas as a `<!-- studio-design:<base64> -->` comment so the studio can round-trip between modes.

Design mode's elements bind to live data via `data-hud-*` attributes — `data-hud-text`,
`data-hud-led`, `data-hud-led-color`, `data-hud-show`/`data-hud-hide`, `data-hud-eq`, and
`data-hud-btn` — these are read and driven live by tRadio's and tELS's shared HUD binder at
runtime, not cosmetic. For tRadio specifically, the canvas size is also written onto the root
element (`data-radio-width`/`data-radio-height`) so the installed layout renders at its intended
size instead of tRadio's default.

**tDetector doesn't use this attribute model at all.** Its runtime expects exactly one
`<script data-layout-script>` block registering `window.__tdetLayoutUpdate(state, root)` —
Design mode can't produce that, so it's disabled for tDetector-targeted items. HTML mode allows
exactly this one script block as the sole exception to the "no scripts" rule below, specifically
for tDetector items — everything else (a second script tag, event handlers, `javascript:` URLs,
etc.) is still rejected.

### Drafts

Drafts are stored in **browser localStorage**, not on the server — clearing your browser's site data permanently deletes all unpublished work. Every new, never-submitted layout gets its own draft slot (not just one shared slot), and they're listed alongside your published items on [Your Creations](/app/marketplace/manage) with a **Draft** badge, so you can jump back into one, or delete it, without ever submitting it for review.

### Validation and size limits

A layout is a single self-contained HTML + CSS document — no separate asset bundle. Images
(background, icons) are embedded inline as `data:` URIs, whether you draw them in Design mode or
paste them into HTML mode. Clicking **Submit for review** validates before saving:

- Bare `<script>` tags and `on*` inline event handlers are rejected — except the single
  `<script data-layout-script>` block tDetector items are allowed (see above)
- `javascript:` URLs, `<iframe>`, `<object>`/`<embed>`, `<meta http-equiv>`, `<base>`, `<link>`,
  and `@import` are rejected
- The document must be under 2 MB total

This is a floor, not a ceiling — every new item and every edit to a published item is also
reviewed by staff before it goes live (see below).

### Forking an existing layout

On any published UI item's page, **Fork** copies its layout into a new local draft (does not count as a download) and opens the studio, with an attribution note linking back to the original. Publishing a fork always creates a new item — it never modifies the original, even if you own it.

### Updating a published item

From [Your Creations](/app/marketplace/manage), items with a saved local draft show an **"Edits pending"** badge. Submit from the studio to push the update to the same item ID — this resets the item to "pending" for re-review.

<!-- llms-full-doc-separator -->

# Syntax Error / Error Parsing (https://timmygstudios.com/docs/faq-syntax-error)
Fixing 'syntax error near <\1>' and 'Error parsing script' errors in FiveM.

## Error Messages

You may see one of these in your server console:

```
syntax error near '<\1>'
```

```
Error parsing script @your_resource/server/file.lua in resource your_resource:
@your_resource/server/file.lua:1: syntax error near '<\1>'
```

```
Failed to load script @your_resource/server/file.lua
```

## Possible Causes

  FileZilla damages escrow-protected files during transfer in its default mode. Use
  [WinSCP](https://winscp.net/eng/download.php) instead, or switch FileZilla to binary transfer
  mode.

  Transferring files one-by-one through RDP also damages them. Upload the `.zip` to the server and
  extract it there.

  Your server must be at least artifacts version **4752**. Older builds can't load modern escrow
  resources.

  The download itself may have been truncated or corrupted. Re-download from the CFX Portal.

  A virus on your server may be modifying script files. This usually manifests as scripts working
  initially and breaking after a few restarts.

---

## Solutions

### Re-upload with WinSCP

Download the script again from the [CFX Portal](https://portal.cfx.re/) and upload using [WinSCP](https://winscp.net/eng/download.php) instead of FileZilla.

  Always upload the `.zip` file to your server first, then extract it there. Never transfer the
  folder file-by-file.

### Or: switch FileZilla to Binary mode

If you must use FileZilla:

1. Open FileZilla
2. Go to **Transfer** → **Transfer Type** → **Binary**
3. Re-upload the entire resource

### Update server artifacts

Run `version` in the server console. If it's below **4752**, update.

    1. Download the latest recommended artifacts from the [Windows artifacts page](https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/)
    2. Stop your server
    3. Remove the old server folder and replace it with the new one
    4. Start the server and run `version` to confirm

    1. Download the latest recommended artifact from the [Linux artifacts page](https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/)
    2. Stop your server
    3. Delete the `cache` and `alpine` folders
    4. Extract with `tar -xf fx.tar.xz`
    5. Start the server and run `version` to confirm

### Clear the server cache

Delete the `cache` folder in your server directory and restart.

### Fresh install

If nothing else works:

1. Delete the resource folder entirely
2. Download a fresh copy from the [CFX Portal](https://portal.cfx.re/)
3. Upload via [WinSCP](https://winscp.net/eng/download.php)
4. Disable any anticheat that dumps or modifies Lua files
5. Restart the server

---

## Related

    Overview of all escrow errors and how to identify which one you're seeing.

  Different error, same root cause as the corrupted-upload fix above.

    If restarts stop loading the script entirely, you may be hitting this instead.

<!-- llms-full-doc-separator -->

# Tommy's Radio (https://timmygstudios.com/docs/tRadio)
A real P25 radio system for FiveM — its own voice server, conventional and trunked channels, a dispatch panel, 911 calls, 3D audio, and station alerting.

<div class="flex items-center gap-4 my-4">

    FiveM Post

    Store Page

</div>

Most FiveM radio scripts add channel routing and an audio filter on top of pma-voice. Tommy's Radio runs its own voice server and encodes speech with P25 IMBE — the same vocoder real public-safety handhelds use. The radio sound is the codec, not an effect painted over your voice.

Channels, trunking, codeplugs, a dispatch panel, 911 calls, 3D audio, station alerting, and GPS all ship in one resource. One port, one config file, nothing external to sign up for.

## Requirements

| Requirement | Detail                                                                                  |
| ----------- | --------------------------------------------------------------------------------------- |
| FiveM       | Artifact **4752 or newer**. Run `version` in your server console                        |
| tLib        | **v0.6+**, free — [download](https://github.com/tommy141x/tLib/releases). No other deps |
| A port      | One free TCP port, default `7777`, reachable from the internet. Not FiveM's 30120       |
| Framework   | Optional. ESX, QBCore, QBX, ND_Core, ox_core, and nat2k15 auto-detect; standalone works |
| Voice       | Runs **alongside** pma-voice or Mumble. It does not replace your proximity voice        |

Opening the port is the step that goes wrong most often, so it has its own section in the [installation guide](/docs/tRadio/installation).

---

## Try it first

All three are live right now, on the same server, and none of them need a purchase.

## Install in five steps

1. **Extract** the resource into your server's `resources` folder
2. **Configure** `config/config.lua` — `serverAddress`, `serverPort`, `authToken`, `adminPassword`, `dispatchNacId`
3. **Open the port** in your firewall or hosting panel
4. **Add** `ensure tRadio` to `server.cfg`, below `ensure tLib`
5. **Restart** — the startup banner's **Status** row should read `Server started successfully`

A new install is not empty. Three zones, twelve channels, a working codeplug, four alerts, and job mappings for `police`, `sheriff`, `ambulance`, and `fire` ship preconfigured, so a patrol officer can key up the moment the port is open.

<div class="mt-4">

    Full Installation Guide

</div>

---

## Features

### Radio that sounds like radio

A WebAssembly build of op25's IMBE encoder — the same codec real public-safety handhelds run. The sender encodes once; every listener decodes locally, whether they are in game, on the dispatch panel, or a bystander standing nearby. Bitrate is roughly 3.7× smaller than Opus.

The voice server runs on a port you pick, completely separate from FiveM and your existing voice stack. Not layered on pma-voice, not piggybacking on a third-party service.

P25 is set per channel, so a digital dispatch channel and an analog tac channel live on the same radio — and an [analog FX chain](/docs/tRadio/configuration#radio-fx) (highpass, lowpass, compression, drive, mid-boost) sits on top of either.

<div class="mx-auto max-w-[300px]">

</div>

### Conventional and trunked channels

Conventional is one shared frequency: everyone connected hears everyone else. Trunked auto-assigns units to sub-frequencies by location, so four units spread across the map stop stepping on each other — and dispatch still reaches all of them on the control frequency.

Patching bridges two or more channels on the fly, and patches survive a restart. A floating channel list shows who is on with you, callsigns, who is transmitting, dispatcher badges, and patch or trunked state. Channels flagged secure show a lock.

### Codeplugs — one radio per department

The same idea real agencies program into their fleets. A codeplug is a radio personality: which channels a unit can transmit on, which it can only scan, which radio models it may carry, what its emergency button does, and whose GPS blips it can see.

Map jobs to codeplugs in one table, optionally per rank, so a sergeant's radio carries channels a patrol officer's does not:

```lua
['police'] = { [0] = 'leo', [3] = 'leo-supervisor', [8] = 'leo-command' }
```

Each codeplug carries named [scan lists](/docs/tRadio/usage#scanning) with priorities, per-context default radio models (on foot, vehicle, boat, aircraft, and per-spawncode overrides), supervisor rights, and cross-agency GPS visibility — so fire can see EMS but not undercover units. Unmapped jobs get no radio at all, by default.

### A dispatch panel that dispatches

A browser panel plus a native Windows app with global push-to-talk and auto-updates. Dispatchers transmit to any channel, patch frequencies, arm announcement groups that broadcast to many channels at once, trigger alerts with tone picks, answer 911 calls, replay buffered transmissions from the log, and assign callsigns. Same vocoder as the in-game radios, so audio is consistent either direction.

### Speakers you can place, tones you can drop

Stand where you want a speaker, run `/_tradio_coords`, and paste the position into [Admin Panel → Speakers](/docs/tRadio/configuration#speakers) with a radius, an optional prop model, and a group name. A dispatcher then picks a tone, presses a speaker or a whole group, and it plays at those coordinates in 3D — station alerting, tone-outs, PA stingers.

Everyone inside the radius hears it from the speaker, positioned. Nobody outside hears anything.

### A working 911 line

  The 911 system works end to end, but it is still settling. It can be switched off entirely in
  **Admin Panel → Settings → General**, and nothing else in tRadio depends on it.

Players dial `/911` — or 911 on their LB Phone — and land in a queue on the dispatch panel with their phone number, unit ID, location, and message. Dispatchers accept, talk, and hang up like a real call.

Callers speak hands-free over voice activation with a phone-to-ear animation, and press ESC to hang up. No radio, codeplug, or channel access is needed to call. If no dispatcher is online, a configurable fallback broadcasts the call to on-duty units instead. Full detail in [Usage](/docs/tRadio/usage#911-calls).

### Radio in 3D space

Players near a talker hear their radio at their position — voice, tones, the siren loop behind them, helicopter rotor, and gunshots fired during a transmission. The earbuds toggle gates your outgoing broadcast, and wearing a configured earpiece item enables it automatically. See [3D audio](/docs/tRadio/usage#3d-audio).

### A radio that's really in the dash

Not a screenshot taped to the dashboard. It is a streamed prop with a live display — zone, channel, signal bars, status LEDs — rendering the same thing the player's own radio shows. Walk away from the car and it takes over as the audio source at extended range.

Placement is per vehicle model and done in game: sit in the car, open `/tradio` → Style → **3D Prop Editor**, and drag it into place with a Three.js gizmo. Save, and it applies to every client immediately. Codeplugs can override the model for a specific vehicle spawncode, or a spawncode and livery combination.

### Coverage you can plan — and lose

[Signal towers](/docs/tRadio/configuration#signal-towers) go in at coordinates you pick, and strength falls off with distance from the nearest one. Turn on degradation and a weak signal audibly chews up the audio, so the edge of the county sounds like the edge of the county. Tune the falloff curve and severity, or flip **Always Full Signal** to keep your tower layout without the consequences.

[Geo zones](/docs/tRadio/configuration#geo-zones) go the other way. Give a centre coordinate and a radius — the mall, the airport, a prison — with optional floor and ceiling heights for stacked interiors. A unit walking in switches to that area's channel automatically and reverts on the way out. Players opt in per zone, so nobody gets yanked off dispatch unexpectedly.

<div class="mx-auto max-w-[320px]">

</div>

### Tune every knob, live

The admin panel covers the analog FX chain, signal coverage, half-duplex "bonking" behaviour, 3D audio ranges, GPS blip rate, man-down timers, 911 cooldowns, keybind defaults, and default radio layouts per vehicle type. Changes broadcast to every connected client instantly — no restart, no file editing.

### Details that sell the illusion

Battery drains on foot and charges in any vehicle, chirping a warning under 50% and cutting out at zero. Man-down monitoring escalates from a warning tone to a full emergency broadcast if a unit stays down. Keying up over another transmission earns a bonk tone, with a double-tap override when it is urgent. Spoken announcements read the zone and channel aloud as you switch.

Every one of these is a toggle, and every player-facing string is translatable.

<div class="mx-auto max-w-[280px]">

</div>

### Built to be customised

[Radio models](/docs/tRadio/usage#radio-models-and-appearance) are HTML and CSS folders in `layouts/` — ten ship, and marketplace installs appear in the Style picker on next open. Twenty-five tone slots remap globally or per radio model, with variants for conventional, trunked, and patched channels.

A complete Lua export surface, a REST API, and a Socket.IO event stream cover anything the UI does not.

### Make the dispatch panel yours

Five [themes](/docs/tRadio/usage#themes) ship built in. Beyond that the panel has a real theming SDK, in four tiers. Recolour it with design tokens. Restyle it with CSS. Replace individual components — a channel card, a unit row, a 911 card — while the panel keeps every feature gate and accessibility guard around them. Or rebuild the console from scratch with a declarative template.

None of those tiers require JavaScript, so they publish to the marketplace without a review queue. A worked dispatch-console rebuild ships as a reference. See [dispatch panel theming](/docs/tRadio/api-reference#dispatch-panel-theming).

### One click, no code, no restart

Radio UIs, dispatch themes, and tones publish to the [tMarketplace](/marketplace). Find one, press install in **Admin Panel → Marketplace**, and it shows up in every player's style picker the next time they open the radio. No file transfer, no `restart tRadio`, no editing anything.

Live today: extra handhelds, a car radio, a tone pack, and a full dispatch-console theme. Because layouts and themes are just HTML and CSS, anyone can build one — and publishing needs no review queue.

<div class="mx-auto max-w-[420px]">

</div>

<div class="my-6">

    Browse the marketplace

</div>

### Drive it from a Stream Deck

An official plugin turns an Elgato Stream Deck into a live radio panel — channel and zone on the key, signal bars, who is talking, panic in red, and the 911 queue count. Push to talk, step channels, scan, adjust volume, or hold one key to transmit on a specific channel without leaving your own.

It drives both the in-game radio and the dispatch panel, and needs no companion app — the plugin talks to them directly over localhost. Free with the resource, and it works with Stream Deck Mobile and OpenDeck. See [Stream Deck](/docs/tRadio/usage#stream-deck).

### Plays well with your stack

Auto-detects ESX, QBCore, Qbox, ND_Core, ox_core, and nat2k15 — job-to-codeplug mapping is one table in an open config file, and access refreshes the moment a job changes. Discord OAuth gates the dispatch and admin panels by role.

Optional [integrations](/docs/tRadio/configuration#integrations) mirror 911 calls into ImperialCAD, hook 911 dialling into LB Phone, and surface radio status in LB Radio. Running more than one FiveM server? [Satellite mode](/docs/tRadio/configuration#multi-server-federation) federates every server onto one shared radio network and dispatch panel.

---

## Specifications

## Questions people actually ask

    Yes. tRadio runs its own voice server inside the FiveM process, and that server needs one TCP
    port reachable from the internet. Most hosting panels expose extra ports on request. The
    [installation guide](/docs/tRadio/installation) covers Windows, Linux, and the common hosts, and
    [troubleshooting](/docs/tRadio/troubleshooting) covers what to do when the port looks open but
    the radio still will not connect.

    No. Radio PTT uses tRadio's own microphone capture on its own server, so your proximity voice
    keeps working exactly as it does now. The only place tRadio touches in-game voice is 911 calls,
    which use voice activation.

    Yes. The resource is escrow-encrypted, but `config/config.lua`, both function-hook files,
    `config/locales.json`, `layouts/`, and `data.json` ship unencrypted and stay yours. Framework
    integration is a Lua function you write. Nearly everything else is a setting in the admin panel,
    applied live.

    Six items: `config/config.lua`, `config/cl_functions.lua`, `config/sv_functions.lua`,
    `config/locales.json`, `data.json`, and `layouts/`. Everything else is replaced. Release notes
    call out any new `config.lua` key, since new keys are not merged into your file automatically —
    see [updating](/docs/tRadio/installation#updating-tradio).

    The 911 system works end to end but is still settling, and can be switched off from the admin
    panel without affecting anything else. Transmission playback and the LB Phone / LB Radio
    integrations are also marked experimental. Trunked channels cannot be patched.

---

## Pages

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">

    Step-by-step setup, port configuration, and getting your server running.

    <div class="mt-4">

        Installation Guide

    </div>

    config.lua reference, zones, channels, codeplugs, access control, speakers, towers, admin panel settings, and framework integration.

    <div class="mt-4">

        Configuration Guide

    </div>

    In-game controls and settings, the dispatch panel, 911 calls, radio models, animations, and the Stream Deck plugin.

    <div class="mt-4">

        Usage Guide

    </div>

    Lua exports, REST endpoints, Socket.IO events, and the full dispatch panel theming reference.

    <div class="mt-4">

        API Reference

    </div>

    Common problems and fixes for connection, audio, codeplug access, and P25 quality.

    <div class="mt-4">

        Troubleshooting

    </div>

</div>

<div class="my-6">

    View Changelog

</div>

<!-- llms-full-doc-separator -->

# tRadio Troubleshooting (https://timmygstudios.com/docs/tRadio/troubleshooting)
Symptom-based fixes for Tommy's Radio — connection failures, audio and microphone problems, access issues, 911 calls, dispatch panel errors, and install mistakes.

## The radio won't connect

### Read the health check first

Every start prints a **Status** row in the tRadio banner. It tells you which of three situations you are in.

| Status                                              | Meaning                                                                                                             | Do this                                                                                                                               |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Green — `Server started successfully`               | Both the public and localhost probes passed                                                                         | Nothing. The port is open                                                                                                             |
| Amber — reachable on localhost, public probe failed | The radio works for players; this host just cannot reach its own public IP (hairpin NAT, CGNAT, or a reverse proxy) | Confirm from [portchecker.co](https://portchecker.co/check-v0) or a phone on mobile data. If players connect, the warning is cosmetic |
| Red — both probes failed                            | Nothing is listening on that port, or something else is                                                             | Follow the port fix below                                                                                                             |

### ECONNREFUSED, closed port, or "Failed to connect to radio server"

**What you see**

```
[Radio-Server] ERROR Health check failed after 4 attempt(s)
[Radio-Server] WARN HTTP endpoint test failed - connect ECONNREFUSED
```

or players get _Failed to connect to radio server_ in-game, or the browser console shows `xhr poll error`.

**Why** — the port is not reachable from the internet.

**Diagnose** — with the resource running, enter your server IP and the port from `config.lua` at [portchecker.co](https://portchecker.co/check-v0). **Closed** confirms it.

**Fix, hosting panel**

1. Confirm the port exists in your panel's Network / Ports / Allocations section
2. Confirm it is not 30120 (FiveM) or 40120 (txAdmin)
3. Make `serverPort` and the port inside `serverAddress` match
4. Restart the **entire server** from the panel, not just the resource
5. Re-test. If it is still closed, open a support ticket — most Pterodactyl hosts block the port at the network level even after you add it

**Fix, VPS**

```bash
sudo ufw allow 7777 && sudo ufw reload                                   # Ubuntu / Debian
sudo firewall-cmd --permanent --add-port=7777/tcp && sudo firewall-cmd --reload  # CentOS / RHEL
```

**Confirmed when** portchecker.co reports **Open** and Status goes green on the next restart.

### "Invalid URL" on startup

`serverAddress` is malformed. Set it to `""` to auto-detect, or use exactly `http://IP:PORT` — the protocol and the port are both required.

### Port is reachable but another service answers

The banner says the port is reachable but a different service is responding. Something else is bound to it. Pick a port nothing else uses and update both `serverPort` and `serverAddress`.

---

## The radio won't open at all

**What you see** — pressing F6 does nothing, and the F8 console shows `radio keybind blocked: server has not granted radio access`.

The server denied access. Work through the chain in order:

1. **Does the player have a codeplug?** Their job must appear in `JOB_CODEPLUG_MAP` in `config/sv_functions.lua`, and the value must match a codeplug's ID in the admin panel exactly. Unmapped jobs get no radio by design
2. **Is a grade threshold excluding them?** If the mapping uses grade thresholds, a player below the lowest threshold gets nothing
3. **Is the item requirement on?** With `Config.inventory.enabled = true`, they must be carrying the item — or hold the `tRadio.access` ACE
4. **Did their job just change?** Call `exports['tRadio']:refreshNacId(source)`, or leave `autoRefreshOnJobChange = true` and let tRadio handle it
5. **Does the codeplug have any allowed models?** A codeplug with none leaves the player with no radio to render

`JOB_CODEPLUG_MAP` changes require `restart tRadio`. Admin panel changes do not.

**Also possible:** `radio keybind blocked: NUI engine not ready yet` simply means the UI is still loading. Wait a few seconds.

---

## No audio

### Nobody can hear me and I can't hear anyone

The player's codeplug does not include the channel. Add the channel under **Channel Access** on their codeplug, or grant `tRadio.connect.{freq}` (drop the decimal: `154.755` → `154755`). Reconnect to the channel afterwards.

### No static, tones, or radio character

Check three settings in **Admin Panel → Settings → Audio & Radio**:

- **Transmission Tones** must be on for `TX_START` / `TX_END`
- **Radio FX** must be on for the analog chain
- **SFX Volume** — both the server default and the player's own setting

### Robotic, warped, or metallic audio on a P25 channel

| What you hear                                    | Why                               | Fix                                                                                                                |
| ------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Robotic or warped at the very start of a session | The WASM vocoder is warming up    | None needed — it resolves after the first transmission                                                             |
| Metallic buzz or warbling throughout             | Microphone input is clipping      | Lower the mic level in Windows Sound settings → Recording → Properties → Levels                                    |
| First syllable cut off                           | Normal codec behaviour            | If severe, raise **PTT Release Delay**                                                                             |
| Dispatch hears clean audio instead of P25        | That channel is not a P25 channel | Set the channel's **Mode** to `P25 Digital` in Zones & Channels. There is no global P25 switch — it is per channel |

### Idle hum, pops, or clicks

Turn **Signal Degradation** off in **Settings → Audio & Radio** and listen again. Degradation deliberately inserts dropouts at low signal; if that removes the artefacts, either lower **Degradation Intensity** or add more [signal towers](/docs/tRadio/configuration#signal-towers) so players are not sitting at the edge of coverage.

Run `/tradio_debug_audio` before and after reproducing the noise and compare the two reports.

### Unwanted bonk tones, or people talking over each other

Both are in **Settings → Audio & Radio → Half-Duplex (Bonking)**. Turn **Play Bonk Tone** off to silence the tone; turn **Block Transmission** on to actually prevent the second transmission.

---

## Microphone not working

### Wrong device

Open the radio → **ST** → **MIC**, or `/tradio` → Audio → Microphone, and pick the right input. The refresh button beside it re-enumerates devices and re-acquires the stream.

### FiveM was denied microphone access

If you clicked _Deny_ on FiveM's permission prompt, no device list appears at all.

1. Close FiveM completely
2. Delete `%localappdata%\FiveM\FiveM.app\cache`
3. Relaunch — the prompt reappears
4. Click **Allow**

### canTalk is returning false

  `Config.canTalk` in `config/cl_functions.lua` blocks transmission whenever it returns `false` —
  the shipped version does so when the player is dead or swimming. If it starts returning `false`
  mid-transmission, the client force-stops PTT and logs `canTalk check failed mid-transmission,
  force-stopping PTT` to the F8 console. Check for that line before suspecting hardware.

### Voice chat works but the radio doesn't (or the reverse)

Expected, and explainable. Radio PTT uses tRadio's own microphone capture. In-game Mumble voice activity detection is used **only** for 911 calls. The two paths are entirely separate, so one working while the other does not is not by itself a bug.

### Diagnostic commands

| Command                           | Shows                                                                                                                                                                  |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/tradio_debug_audio`             | Full F8 report: audio context state, signal degradation parameters, active voice buffers, and `micStreamReady` / `isRecording` — check those two first for mic reports |
| `/tradio_debug_output [deviceId]` | Output-device switching report                                                                                                                                         |
| `/_tradio_diag`                   | Connection diagnostics — socket health and connected endpoint                                                                                                          |
| `/_tradio_tone [TONE]`            | Play a tone by key (default `BEEP`) — tests the tone path independently of PTT                                                                                         |
| `/_tradio_fx [EFFECT]`            | Play a background effect: `transmission`, `gunshot`, `siren`, `heli`, `transEnd`                                                                                       |
| `/_tradio_mute2d`                 | Toggle 2D audio mute, to isolate 3D positional audio while testing                                                                                                     |
| `/_tradio_coords [lua\|json]`     | Copy your position to the clipboard for placing speakers, towers, and geo zones                                                                                        |
| `/_tradio_debug`                  | Toggle the radio UI debug overlay                                                                                                                                      |
| `/tradio_con <url>`               | Override this client's voice server address — useful for testing one player against another endpoint. Run with no argument to clear it. Power-cycle the radio to apply |

---

## Wrong channels, zones, or blips

| Symptom                                                   | Fix                                                                                                                                                                                                                                               |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A channel is missing from the radio                       | Add the channel to the codeplug's **Channel Access**, or grant `tRadio.connect.{freq}`                                                                                                                                                            |
| A channel cannot be scanned                               | Add it to **Scan Access**, or grant `tRadio.scan.{freq}`. Connect-access channels are scannable automatically                                                                                                                                     |
| A zone is missing                                         | Zone access is derived from channels — select at least one of that zone's channels on the codeplug, or grant `tRadio.zone.{N}`                                                                                                                    |
| No GPS blips for other players                            | Check all three: the target codeplug is selected under **GPS Visibility** on the viewer's codeplug, **GPS Blips** is on in that codeplug's Features, and **Radio Blips** is on in Settings → General. The player's own GPS toggle must also be on |
| A zone vanished from the dispatch panel but works in-game | Its **Hide from dispatch** toggle is on. That is display scope only, not access control                                                                                                                                                           |
| Zone ACE grants apply to the wrong zone                   | `tRadio.zone.{N}` is positional. Deleting or reordering zones shifts every later-numbered grant — review `server.cfg`                                                                                                                             |

---

## 911 calls

### /911 says unknown command

Two settings suppress it, both deliberately:

1. **911 Calling** is off in **Settings → General**. Turn it on
2. **LB Phone 911 Dial-In** is on in **Settings → Advanced**. That replaces the command — players dial `911` on the phone instead. Turn it off and restart to get the command back

If the phone integration is on but lb-phone is not installed or started, players have no way to reach 911 at all. tRadio logs a warning about exactly this a few seconds after startup.

### Turning 911 off didn't remove the command

Expected and harmless. FiveM cannot unregister a chat command, so it stays for players already connected — but the server rejects every call and tells them 911 is unavailable. It disappears for anyone who reconnects, and after a resource restart.

### Calls never reach the panel

The call _is_ queued — a dispatcher connecting later will see it. Confirm a dispatcher is actually logged in, and that the sidebar's 911 section is not collapsed or popped out. With nobody on the panel, `call911NoDispatcherFallback` fires instead; by default that chat-broadcasts to everyone with radio access.

### The caller can't be heard after accept

911 calls use **in-game voice activity detection**, not radio PTT. If the player's in-game voice chat is not working, the call carries no audio even though their radio PTT may be fine. See [Voice chat works but the radio doesn't](#voice-chat-works-but-the-radio-doesnt-or-the-reverse).

---

## Dispatch panel

### The desktop app shows someone else's server

It is pointed at the demo endpoint. In the app's settings, set **Endpoint URL** to `http://YOUR_IP:YOUR_PORT/` and reconnect.

### The panel asks for a NAC ID and I don't have one

It is not generated — you define it. Set `dispatchNacId` in `config/config.lua` and restart.

### Microphone doesn't work in the browser

Browsers only expose microphone APIs over HTTPS. Use the desktop app, which has no such requirement, or put a reverse proxy with a valid TLS certificate in front of the radio server.

### "No authentication method configured"

Neither `adminPassword` nor `discord.adminRoles` is set, so nobody can log into the admin panel. Set one in `config/config.lua` and restart. tRadio also prints this as a startup warning.

### Session expired banner

Admin sessions log out after 30 minutes of inactivity, and a resource restart invalidates them. Click **Log in again**. Unsaved changes are lost, so save before stepping away.

---

## Install and config errors

### Syntax error referencing `<\1>`

Two causes:

1. **Corrupted transfer.** FTP clients in ASCII mode (FileZilla's default) and Remote Desktop drag-and-drop corrupt Lua files. Use WinSCP or set binary mode — and always transfer the `.zip` and unzip on the server
2. **Outdated artifact.** Build **4752 or newer** is required. Check with `version` in the console

To update a Linux artifact: download the latest from the [build server](https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/), stop the server, delete the `cache` and `alpine` folders, run `tar -xf fx.tar.xz`, and restart.

### Missing .fxap file

The escrow file is dot-prefixed, so it is hidden on Linux and macOS and commonly dropped by FTP clients set to hide hidden files, or by `.gitignore` rules in a CI pipeline. Enable hidden files and transfer it; make sure `.fxap` is not gitignored in a git-based deploy.

### The SGN button does nothing

The player needs the `tlib.admin` ACE, or **Supervisor Access** enabled on their codeplug. Note that `tlib.admin` grants in-game supervisor features only — it does not unlock the web admin panel, which uses `adminPassword` or Discord.

### Framework failed to initialize

```
[tRadio] ERROR: Framework 'esx' failed to initialize.
```

All players are denied radio access until this is resolved. Confirm the framework resource is running and that `Config.frameworkResources` matches its actual resource name.

### Changes in the admin panel aren't applying

Almost everything applies live. The exceptions are marked **Restart required** in the panel: 911 Calling, the Callsign Command name, and LB Phone 911 Dial-In. Anything edited in `config/config.lua`, `sv_functions.lua`, or `cl_functions.lua` also needs `restart tRadio`.

---

## Getting more detail

Raise **Log Level** in **Admin Panel → Settings → General**. It applies immediately.

| Level | Output                                                             |
| ----- | ------------------------------------------------------------------ |
| 0     | Errors only                                                        |
| 1     | Warnings                                                           |
| 2     | Minimal                                                            |
| 3     | Normal — the production default                                    |
| 4     | Debug — for troubleshooting                                        |
| 5     | Verbose — very noisy, measurable performance cost on a busy server |

Reproduce the problem at level 4 or 5, then look for `[tRadio]`-prefixed lines in the server console. Connection failures appear at startup; audio path problems only appear when someone transmits. Set it back to 3 when you are done.

**Still stuck?** Post in the [FiveM community thread](https://forum.cfx.re/t/tommys-radio/5340987) with the full console error block, your `config.lua` with secrets redacted, the level 4 output captured during the failure, and your framework.

<!-- llms-full-doc-separator -->

# tRadio Usage (https://timmygstudios.com/docs/tRadio/usage)
Using Tommy's Radio — in-game controls and settings, channel features, the dispatch panel, 911 calls, radio models and animations, and the Stream Deck plugin.

## The in-game radio

Press **F6** to open the radio, **B** to transmit. Both are the shipped defaults and both are rebindable by each player in **FiveM → Settings → Key Bindings → FiveM**, or server-wide in **Admin Panel → Settings → Controls**.

### On-radio buttons

The radio is a four-page device driven by the three soft buttons under the display. What each button does depends on the page.

| Page         | Buttons               | What they do                                                        |
| ------------ | --------------------- | ------------------------------------------------------------------- |
| **Main**     | `ZN` · `CH` · `ST`    | Open the zone list, the channel list, or the settings menu          |
| **Zones**    | `SEL`                 | Select the previewed zone                                           |
| **Channels** | `CON` · `DSC` · `SCN` | Connect, disconnect, or add the previewed channel to your scan list |
| **Settings** | varies                | `TGL` toggles, `UP`/`DWN` adjust, `<-`/`->` cycle choices           |

On the Channels page the third button changes with context:

- **`SCN`** normally — toggle scanning on the previewed channel
- **`SGN`** on the channel you are connected to, if you are a supervisor — fire the first configured alert
- **`CT` / `TK`** on a connected trunked channel, if you are a supervisor — switch between the control frequency and a trunked sub-frequency

Supervisor means the `tlib.admin` ACE or a codeplug with **Supervisor Access** enabled.

The connected channel shows `[CON]` after its name; a scanned one shows `[SCN]`. During a transmission the display shows `TX:` for your own, `RX:` for another unit on your channel, and `SC:` for one on a scanned channel, followed by the caller's callsign, name, and agency.

### The ST settings menu

`ST` on the main page cycles through per-player settings on the radio itself. Options appear only when relevant.

| Option      | Buttons             | Notes                                                                     |
| ----------- | ------------------- | ------------------------------------------------------------------------- |
| **GPS**     | `TGL`               | Your blip's visibility. Hidden if the codeplug disables GPS               |
| **Earbuds** | `TGL`               | Only shown when 3D audio is enabled server-side                           |
| **VC Vol**  | `DWN` / `UP`        | Voice volume                                                              |
| **SFX Vol** | `DWN` / `UP`        | Tone volume                                                               |
| **3D Vol**  | `DWN` / `UP`        | Only shown when 3D audio is enabled                                       |
| **Style**   | `<-` / `->`         | Radio model, from your codeplug's allowed models                          |
| **DISP**    | `<-` / `->`         | Auto, Light, or Dark                                                      |
| **Move**    | `CHG` / `RST`       | Reposition the radio, or reset its position                               |
| **MIC**     | `<-` / `->`         | Microphone device                                                         |
| **Anim**    | `<-` / `->`         | Radio animation. Hidden when animations are disabled server-side          |
| **SCL**     | `<-` / `->` / `LOD` | Load a scan list preset. Only shown when your codeplug defines scan lists |

### The /tradio settings dialog

`/tradio` opens the full settings dialog — everything from the ST menu plus options that need more room. It has two tabs, and a third when your codeplug has scan lists.

<video
  class="not-prose my-6 w-full rounded-lg"
  width="1280"
  height="720"
  autoPlay
  muted
  loop
  playsInline
  preload="metadata"
  poster="/assets/tRadio/user-settings-poster.jpg"
>
  <source src="/assets/tRadio/user-settings.webm" type="video/webm" />
  <source src="/assets/tRadio/user-settings.mp4" type="video/mp4" />
</video>

**Audio tab**

| Option                  | Notes                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------- |
| Voice / SFX / 3D Volume | 0–100 sliders                                                                      |
| Earbuds                 | Off, your radio leaks out spatially. On, private earpiece — nobody nearby hears it |
| Voice Announcements     | Speaks the zone and channel name aloud when you switch. Codeplug-gated             |
| Man Down Alarm          | Broadcasts an alert if you stay down too long. Codeplug-gated                      |
| Auto Transmit           | Auto-transmit when you hit the emergency button. Codeplug-gated                    |
| Tone Ducking            | Lowers voice audio while a tone plays so the tone stays audible                    |
| Microphone              | Input device, with a refresh button beside it                                      |
| Animation               | Which radio animation plays                                                        |

**Style tab**

| Option                        | Notes                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Radio Style                   | Radio model for your current context — the model is remembered per context, so on-foot and in-vehicle can differ                                                                |
| Theme                         | Auto, Light, or Dark                                                                                                                                                            |
| GPS Blips                     | Codeplug-gated                                                                                                                                                                  |
| Geo Zones                     | A master **Geo Auto-Switch** toggle plus one checkbox per zone you can reach. Both must be on for a zone to switch you. The whole section is hidden when no zone applies to you |
| Separate On-Foot Focus Layout | Use a different radio skin when the radio is open but unfocused                                                                                                                 |
| Channel List                  | Enable the floating channel-member overlay                                                                                                                                      |
| Active Talkers Only           | Show only transmitting units in that overlay                                                                                                                                    |
| Move Radio / Reset Position   | Drag to reposition, scroll to scale                                                                                                                                             |
| Move Channel List / Reset     | Same, for the overlay                                                                                                                                                           |
| 3D Prop Editor                | Admins only — see [Vehicle radio props](#vehicle-radio-props)                                                                                                                   |

---

## Channel features

### Scanning

Navigate to a channel and press **SCN** to add it to your scan list; press again to remove. Your connected channel always wins transmit priority, and transmitting on it mutes scan traffic until you release PTT.

If your codeplug defines **scan lists**, load a whole preset at once from `/tradio` → Scan Lists, or with the `SCL` option in the ST menu. Each entry carries a priority — 1 High, 2 Normal, 3 Low.

### Channel list overlay

Enable it in `/tradio` → Style → **Channel List**. A floating roster of everyone on your channel, aware of patches, trunking, and scan traffic.

- Callsign badges coloured by the channel's GPS blip colour
- Dispatchers marked with a **DSP** badge; panicking units highlighted red
- Header badges: zone and channel name, frequency, **P** when patched, **T** when trunked, the active alert name, and **PANIC** during an emergency

Drag it anywhere and scroll to scale it, independently of the radio.

### Emergency and panic

Press your emergency keybind or the on-radio emergency button. Your GPS blip flashes for everyone whose codeplug can see your blips, and dispatchers get a panic indicator. Depending on your codeplug, the radio may also switch to a dedicated emergency channel and auto-transmit for a set number of seconds.

Panic clears automatically after 60 seconds by default, or immediately when a dispatcher acknowledges it. A cooldown (15 s by default) prevents repeat triggering.

**Man down** is separate: if enabled, being down or stationary for too long plays a warning tone after 45 seconds and escalates to a full emergency broadcast 20 seconds later. Players toggle it in `/tradio` when their codeplug allows it.

### Callsigns

With the callsign system on, a callsign replaces your character name on radio displays and the dispatch panel.

```
/callsign 2L-319   -- set
/callsign          -- show current
/callsign clear    -- remove
```

The command name is configurable in **Admin Panel → Settings → General**. Callsigns persist client-side, namespaced by your community ID — set `sets tlib_community_id "your-unique-id"` in `server.cfg` so callsigns do not bleed between your test and production servers. Dispatchers can also assign a callsign from the panel.

### Battery and signal

Battery runs 0–100%. By default it charges 0.5%/s in any vehicle — driver or passenger, no dock prop needed — and drains 0.1%/s on foot, so a full charge takes about 3 minutes and a full drain about 17. At 0% the radio powers off. A chirp warns you under 50%, more often under 30%.

Signal bars (1–5) reflect your distance from the nearest [signal tower](/docs/tRadio/configuration#signal-towers). With **Signal Degradation** enabled, low signal audibly degrades voice quality. Both battery drain and signal behaviour are server settings; see [Configuration](/docs/tRadio/configuration#general-tab).

### 3D audio

When 3D audio is enabled server-side, nearby players hear your radio coming from your position — voice, tones, sirens, helicopter, and gunshots.

- **Earbuds off** — your radio leaks out spatially, audible within **35 m** by default
- **Earbuds on** — private earpiece, nothing is emitted
- Wearing a configured earpiece item switches earbuds on automatically

With **Vehicle 3D Audio** on, any vehicle you get into claims your radio as its source. Walk more than 3 m away and the car keeps rebroadcasting your traffic from itself, audible within **60 m** by default, until it despawns or you claim another. One vehicle, one owner at a time — and you never hear your own vehicle, only other players do.

All three distances are server settings.

---

## The dispatch panel

Open `http://your-server-ip:port/` in a browser, or install the desktop app. Log in with the `dispatchNacId` from `config.lua`, or with Discord if that is enabled. Sessions last 24 hours.

### Desktop app or browser

  The panel shows a **Mic denied** warning and voice transmission is unavailable. Use the desktop
  app, which handles mic access automatically, or put an HTTPS reverse proxy in front of the radio
  server. For local testing only, Chrome's
  `chrome://flags/#unsafely-treat-insecure-origin-as-secure` also works.

The desktop app additionally gives you **global push-to-talk** — a browser cannot capture hotkeys while you are alt-tabbed into the game, and this is the main reason the app exists. It also supports native pop-out windows for the TX log and call queue.

Download it from **Settings → Desktop App → Download** inside the panel, or directly from `http://your-server-ip:port/radio/dispatch/installer`. On first launch enter your server URL. It auto-updates whenever the server's version changes — an **Update** button appears in the header.

### Working the board

**Transmitting** — hold **T** (default) or the header PTT button to talk on your monitored channel. Each channel card also has its own hold-to-talk button for cross-channel transmits without leaving your current channel, and each can be given its own PTT key in Settings.

**Units** — drag a user between channels to move them. The menu on each user row can disconnect them, send them a direct alert, or set their callsign.

**Alerts** — trigger any configured alert on any channel from the channel menu, or compose a free-text broadcast with an optional tone from **Broadcast Alert**.

**Frequency patching** — bridge two or more channels so every patched unit hears the others. Create one from the Patches panel in the header: give it a label, pick at least two frequencies, and create. A **P** badge appears on every patched channel, and patches survive a restart. Trunked channels cannot be patched.

<video
  class="not-prose my-6 w-full rounded-2xl"
  width="768"
  height="470"
  autoPlay
  muted
  loop
  playsInline
  preload="metadata"
  poster="/assets/tRadio/patches-poster.jpg"
>
  <source src="/assets/tRadio/patches.webm" type="video/webm" />
  <source src="/assets/tRadio/patches.mp4" type="video/mp4" />
</video>

**Announcement groups** — when at least one group is configured, a **GROUPS** bar appears above the zone list. Click a group to arm it; your next PTT broadcasts to every channel in it at once. Click again to disarm, or give the group its own PTT key in Settings.

**Transmission log** — a running log of transmissions with timestamps, frequencies, and callers. Filter by All, Monitored, or Channel; replay buffered audio with **Play**; collapse it, or pop it out into its own window on the desktop app.

**Speakers (tone board)** — when speakers are configured, a **Speakers** button appears bottom-right. Pick a tone, then press a speaker or speaker group to play it at that world location. See [Speakers](/docs/tRadio/configuration#speakers).

**Settings** — callsign, voice and SFX volume, PTT bindings, theme, transmission log on/off, auto-collapse empty channels, and the desktop app download.

### Themes

Five themes ship built in and are selectable in **Settings → Theme** with no install: Dark Minimal (default), Dark, Dark Blue, Basic, and Basic Dark.

More are installable from **Admin Panel → Marketplace → Themes**. A theme can be anything from a colour swap to a completely custom console. Building one is documented in the [API Reference](/docs/tRadio/api-reference#dispatch-panel-theming).

---

## 911 calls

  The 911 system works end to end, but it is still settling — expect rough edges, and expect
  behavior to change between releases. If you would rather not run it on a live server yet, turn it
  off in **Admin Panel → Settings → General → 911 Calling**. Everything else in tRadio is unaffected
  either way.

Civilians call 911 and land in a queue on the dispatch panel. When a dispatcher accepts, the caller and that dispatcher are placed on a private, temporary voice channel and simply talk. **Anyone can call 911** — no radio, no codeplug, and no channel access required.

```
/911                          -- dial with no details
/911 shots fired at the bank  -- dial with a message for the dispatcher
```

The message is optional and capped at 200 characters. The dispatcher sees it on the call card alongside the caller's phone number, unit ID if they have a codeplug, position, and how long they have waited.

  With [LB Phone 911 Dial-In](/docs/tRadio/configuration#lb-phone-and-lb-radio) enabled, the `/911`
  command is not registered at all — players dial `911` on their in-game phone instead. Both routes
  reach the same queue. Turn it off and restart for the chat command.

**What the caller experiences**

- A ring-out tone plays immediately and keeps ringing until a dispatcher answers
- On answer, the radio powers on by itself and a 911 banner appears at the top of the screen
- Speech is **hands-free** — the call uses in-game voice activity detection, not PTT. Just talk
- Press **ESC** at any time to hang up, or end the call on the phone if dialled that way

**What the dispatcher does.** Accepted calls get the same controls as a real channel:

| Control    | Effect                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------- |
| **Accept** | Puts you on a private voice channel with the caller                                         |
| **Listen** | Adds the call to your scan list so you hear it alongside your channels                      |
| **Talk**   | Press-and-hold cross-channel PTT on the call                                                |
| **Focus**  | Points your main PTT key at this call instead of your channel, for a sustained conversation |
| **End**    | Hangs up. Available to any dispatcher, not only the one who accepted                        |

Like the transmission log, the queue is collapsible and can be popped out on the desktop app. The whole section disappears when 911 Calling is off.

**Timeouts.** An unanswered call expires after **5 minutes**. After a dispatcher accepts, the caller has **20 seconds** to connect. A call whose channel stays empty for 15 seconds is treated as hung up. Players are rate-limited between calls — 30 seconds by default, with a 5-second server-side backstop that always applies.

**When nobody is on the panel**, the call still queues and appears the moment a dispatcher logs in. The `call911NoDispatcherFallback` hook also fires immediately so it is not silently missed — by default it chat-broadcasts to every player with radio access. Replace it with a Discord webhook or your own alerting; see [911 hooks](/docs/tRadio/configuration#911-hooks).

---

## Radio models and appearance

Ten models ship. The radio picks one automatically from your context, and each context remembers its own choice.

| Context            | Default model                                               |
| ------------------ | ----------------------------------------------------------- |
| On foot, focused   | `QRX-720`                                                  |
| On foot, unfocused | `QRX-720H` — only when Separate On-Foot Focus Layout is on |
| Ground vehicle     | `HLX-120`                                                  |
| Watercraft         | `HLX-120G`                                                 |
| Air vehicle        | `KVD-880`                                                 |

The full set, by folder name — use these when picking allowed models on a codeplug:

| Model       | Form factor                                   |
| ----------- | --------------------------------------------- |
| `QRX-720`  | Portable handheld — the on-foot default       |
| `QRX-720H` | Portable handheld — unfocused on-foot variant |
| `QRX-720G` | Portable handheld — alternate body            |
| `QRX-760`  | Portable handheld — modern slim               |
| `DRX-330` | Portable handheld — compact                   |
| `ZTR-540`  | Portable handheld — squared body              |
| `ZTR-540S` | Portable handheld — squared body, slim        |
| `HLX-120`  | Dash-mounted — the in-vehicle default         |
| `HLX-120G` | Dash-mounted — watercraft variant             |
| `KVD-880` | Aviation radio — the in-air default           |

Which models a player may pick, and which one they get first per context, is set on their codeplug under **Allowed Models** and **Default Layouts**. Codeplugs can also override the model for a specific vehicle spawncode, or a specific spawncode and livery combination.

Install more from **Admin Panel → Marketplace → Layouts**. Installed layouts appear immediately in every player's style picker, with no restart.

### Vehicle radio props

Admins with `tlib.admin` can place a dashboard radio prop per vehicle model. Sit in the vehicle you want to edit, then open `/tradio` → Style → **3D Prop Editor**.

<video
  class="not-prose my-6 w-full rounded-2xl"
  width="1280"
  height="720"
  autoPlay
  muted
  loop
  playsInline
  preload="metadata"
  poster="/assets/tRadio/3dpropeditor-poster.jpg"
>
  <source src="/assets/tRadio/3dpropeditor.webm" type="video/webm" />
  <source src="/assets/tRadio/3dpropeditor.mp4" type="video/mp4" />
</video>

| Input                       | Action                       |
| --------------------------- | ---------------------------- |
| Middle mouse + drag         | Orbit                        |
| Shift + middle mouse + drag | Pan                          |
| Scroll wheel                | Zoom                         |
| **W** / **R**               | Translate mode / rotate mode |
| **X**                       | Toggle world and local space |

Drag the coloured arrows to move and the rings to rotate. **Save** applies to every client immediately. **Export Config** copies the placement block for use elsewhere.

<video
  class="not-prose my-6 w-full rounded-2xl"
  width="1280"
  height="716"
  autoPlay
  muted
  loop
  playsInline
  preload="metadata"
  poster="/assets/tRadio/radio-in-car-poster.jpg"
>
  <source src="/assets/tRadio/radio-in-car.webm" type="video/webm" />
  <source src="/assets/tRadio/radio-in-car.mp4" type="video/mp4" />
</video>

---

## Animations

Players pick their radio animation in `/tradio` → Audio → Animation. Four ship, all using native GTA dictionaries with no extra resources:

| Name         | PTT pose                                                  | Radio-open pose                                           |
| ------------ | --------------------------------------------------------- | --------------------------------------------------------- |
| **None**     | —                                                         | —                                                         |
| **Shoulder** | `random@arrests` / `generic_radio_enter`                  | `cellphone@` / `cellphone_call_to_text` + hand radio prop |
| **Handheld** | `cellphone@` / `cellphone_call_to_text` + hand radio prop | same                                                      |
| **Earpiece** | `cellphone@` / `cellphone_call_listen_base`               | —                                                         |

A fifth entry, **Call911**, is used automatically for the caller side of a 911 call — a phone-to-ear pose with a phone prop, since a 911 caller may have no radio at all. It is not meant to be chosen manually.

Animations are suppressed automatically while the player is driving or piloting, or holding a weapon.

### Adding your own

Add entries to `Config.animations` in `config/cl_functions.lua`. Each entry needs a `name`, an `onKeyState(isKeyDown)` handler for the transmitting pose, and an `onRadioFocus(focused)` handler for the idle holding pose. Either may be an empty function.

`MakeAnimHandler(dict, anim, prop)` builds a standard handler — it loads the dictionary without blocking, attaches an optional prop to the right hand, and cleans up on release. It is defined in the same file, above the animation list.

```lua
[6] = {
    name         = "Chest Mic",
    onKeyState   = MakeAnimHandler("random@arrests", "generic_radio_enter", nil),
    onRadioFocus = MakeAnimHandler("cellphone@", "cellphone_call_to_text", "prop_cs_hand_radio"),
},
```

Find prop model names at [forge.plebmasters.de/objects](https://forge.plebmasters.de/objects). Index `[1]` is the fallback used when a player's saved choice no longer exists.

**Using rpemotes.** Servers running [rpemotes](https://github.com/TayMcKenzieNZ/rpemotes) can call an emote instead. Check `ShouldSuppressAnim` first — it is defined alongside `MakeAnimHandler` and returns `true` while driving or armed:

```lua
[6] = {
    name = "Handheld (rpemotes)",
    onKeyState = function(isKeyDown)
        local ped = PlayerPedId()
        if isKeyDown then
            if ShouldSuppressAnim(ped) then return end
            exports["rpemotes"]:EmoteCommandStart("wt4", 0)
        else
            exports["rpemotes"]:EmoteCancel(true)
        end
    end,
    onRadioFocus = function(focused)
        local ped = PlayerPedId()
        if focused then
            if ShouldSuppressAnim(ped) then return end
            exports["rpemotes"]:EmoteCommandStart("wt", 0)
        else
            exports["rpemotes"]:EmoteCancel(true)
        end
    end,
},
```

**Using a custom `.ycd` pack.** Stream the files through rpemotes, register the clip as an emote, then call it exactly as above.

1. Copy the `.ycd` files into a subfolder under `rpemotes/stream/`
2. The `.ycd` filename is the dictionary name. Open it in [OpenIV](https://openiv.com/) or [CodeWalker](https://github.com/dexyfex/CodeWalker) to find the clip name inside
3. Register it in `rpemotes/client/AnimationListCustom.lua` — never edit `AnimationList.lua` directly:

```lua
CustomDP.Emotes = {
    ["radiochest"] = {
        "anim@cop_mic_pose_002", -- dictionary (filename without .ycd)
        "chest_mic",             -- clip inside the dictionary
        "Radio Chest",           -- label in the rpemotes menu
        AnimationOptions = { onFootFlag = AnimFlag.MOVING },
    },
}
```

4. Add a `Config.animations` entry that calls `EmoteCommandStart("radiochest", 0)`
5. Restart rpemotes, then tRadio

---

## Stream Deck

The official plugin turns an [Elgato Stream Deck](https://www.elgato.com/us/en/p/stream-deck) into a live radio panel — change channels, transmit, scan, and adjust volume without touching the keyboard. It works with both the in-game radio and the dispatch panel, and needs no separate desktop app.

The free [Stream Deck Mobile](https://www.elgato.com/us/en/s/stream-deck-mobile) app and the open-source [OpenDeck](https://github.com/ninjadev64/OpenDeck) both work too.

<div class="flex flex-wrap items-center gap-3 my-4">

    Download plugin (.streamDeckPlugin)

</div>

### Setup

### Install the plugin

**Elgato Stream Deck:** double-click `com.timmyg-studios.tradio.streamDeckPlugin`. **OpenDeck:** plugin menu → _install from file_. OpenDeck also needs its Node.js plugin runtime available.

### Add actions to keys

Find **tRadio** in the actions list and drag the actions you want onto keys, or onto dials on a Stream Deck +.

### Pick a target

Each control action has a **Target**: `Radio` (in-game), `Dispatch` (panel), or `Auto` (whichever is connected). Channel actions let you pick a specific channel from a live list.

### Start tRadio

Keys populate and become interactive once their source connects — radio keys need you in-game with tRadio loaded, dispatch keys need the panel open. Until then they show as offline, which is expected.

Everything runs locally: the plugin opens a WebSocket server on `127.0.0.1:21398`, and the game and panel connect out to it. Nothing leaves your PC.

### Actions

| Key                   | Shows or does                                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Radio Status**      | Zone and connected channel, talk/scan status, signal bars, and scan / trunk / patch / GPS / secure indicators. Turns red on panic; shows active alerts |
| **Talk Indicator**    | Amber when you transmit, green when someone on your channel talks, cyan on a scanned-channel hit — with the talker's name                              |
| **Scan Indicator**    | Lit while scanning; flags scanned-channel hits                                                                                                         |
| **Dispatch Activity** | The dispatcher's channel and zone, how many units are keyed up, and TX/RX including cross-channel transmits                                            |
| **911 Queue**         | How many calls are waiting — goes red with the count                                                                                                   |
| **Radio Control**     | One flexible key: PTT, next/previous channel or group, power, toggle or focus the overlay, emergency, volume up/down/mute, and dispatch accept/end 911 |
| **Channel**           | Act on a specific channel: Connect, Toggle Transmit, Talk on Channel (hold), or Toggle Scan. Lights when that channel is active, scanned, or keyed     |
| **Volume dial**       | Rotate for Master / SFX / 3D volume, press to mute. Live level on the touchscreen                                                                      |
| **Channel dial**      | Rotate to step channels or groups, press and hold to transmit                                                                                          |

  Set a **Channel** key to *Talk on Channel*, target **Dispatch**, and pick a channel. Holding it
  transmits on that channel without leaving your current one. Add one per channel for instant
  multi-channel dispatch.

A channel key keeps its selection through disconnects, plugin reloads, and deck restarts — the choice is stored on the key itself, and it reconnects automatically when tRadio comes back.

<!-- llms-full-doc-separator -->

# tels Usage (https://timmygstudios.com/docs/tels/usage)
Keybinds, commands, client settings, stages, modes, and the chirp system.

## Commands

| Command     | Who      | Purpose                                                                          |
| ----------- | -------- | -------------------------------------------------------------------------------- |
| `/tels`     | Everyone | Open the client settings dialog (HUD, display, quality, presence, admin options) |
| `/telsedit` | Admin    | Open the vehicle editor. You must be in a vehicle (any seat).                    |

The `/tels` dialog is context-aware: vehicle-ownership controls appear when you own a tELS vehicle; admin options appear when you hold the `tlib.admin` ACE; the editor button appears when both are true and you're in a vehicle.

---

## Keybinds

All keybinds register through `RegisterKeyMapping` and can be rebound in FiveM's **Keybinds → FiveM** settings.

### Lights

| Key   | Command              | Action                                                                             |
| ----- | -------------------- | ---------------------------------------------------------------------------------- |
| **Q** | `+lbar_toggle`       | Toggle lights on/off, or cycle stages if the vehicle has stage triggers configured |
| **0** | `+lbar_pattern`      | Cycle pattern up (skips `triggerOnly` patterns and patterns hidden by livery)      |
| **9** | `+lbar_pattern_down` | Cycle pattern down                                                                 |

Stage cycling goes `Off → Stage 1 → … → Max Stage → Off`. The max stage is derived automatically from whichever `stage_1` / `stage_2` / `stage_3` conditions appear in the vehicle's triggers.

### Siren

| Key                   | Command            | Action                                                   |
| --------------------- | ------------------ | -------------------------------------------------------- |
| **R**                 | `+lbar_siren`      | Siren burst / tone cycle (see behavior table)            |
| **Alt (LMENU)**       | `+lbar_siren_main` | Toggle main siren on/off (lights must be on)             |
| **Up Arrow**          | `+lbar_siren_aux`  | Toggle aux siren on/off (lights must be on)              |
| **E**                 | `+lbar_horn`       | Horn when lights off, airhorn when lights on             |
| **1 – 8**             | `+lbar_tone1..8`   | Jump to a specific siren tone (see direct-tone behavior) |
| **Right Alt (RMENU)** | `+lbar_rumbler`    | Toggle rumbler variant on the main siren                 |

**R key behavior**

| Current state    | Tap                     | Hold (>400 ms) |
| ---------------- | ----------------------- | -------------- |
| No sirens active | Burst tone 1 while held | —              |
| Main only        | Cycle main tone         | —              |
| Aux only         | Cycle aux tone          | —              |
| Both active      | Cycle main tone         | Cycle aux tone |

**Direct-tone keys (1-8)**

| Light state | Siren state                   | Press                         |
| ----------- | ----------------------------- | ----------------------------- |
| Off         | —                             | Burst that tone while held    |
| On          | No siren                      | Start main siren on that tone |
| On          | Siren running, different tone | Switch to that tone           |
| On          | Siren running, same tone      | Stop the main siren           |

Tones flagged `triggerOnly` in the config are skipped by cycling and direct-tone keys, but can still be started by trigger actions.

### Modes

| Key   | Command          | Action                                                                                                  |
| ----- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| **6** | `+lbar_cruise`   | Toggle cruise                                                                                           |
| **7** | `+lbar_takedown` | Toggle takedown                                                                                         |
| **8** | `+lbar_ta`       | Cycle traffic advisor (Off → Left → Right → Center, limited to directions the vehicle has triggers for) |

### Arges Spotlight

Available only when the vehicle has an Arges spotlight configured.

| Key          | Command                 | Action    |
| ------------ | ----------------------- | --------- |
| **Numpad 8** | `+lbar_arges_aim_up`    | Aim up    |
| **Numpad 5** | `+lbar_arges_aim_down`  | Aim down  |
| **Numpad 4** | `+lbar_arges_aim_left`  | Aim left  |
| **Numpad 6** | `+lbar_arges_aim_right` | Aim right |

### Other

| Key                    | Command           | Action                                                                                                                             |
| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **B** (hold)           | `+lbar_pa`        | PA mic — hold-to-talk public address. Broadcasts your voice to nearby players through a bandpass radio filter. Requires pma-voice. |
| _(unbound by default)_ | `+lbar_cinematic` | Toggle cinematic camera                                                                                                            |

---

## Client settings (`/tels`)

The dialog is built with tLib and applies most changes live as you adjust them.

### HUD

| Field              | Description                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------- |
| **HUD Visible**    | Show or hide the HUD overlay                                                             |
| **HUD Layout**     | Pick from any folder under `layouts/`                                                    |
| **Reposition HUD** | Enter move mode to drag and scale the HUD; Esc or the NUI confirm saves the new position |

### Display

| Field                     | Description                                                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Day/Night Mode**        | `Combined` uses one emissive/bloom setting; `Day & Night` exposes separate values for day and night and switches automatically |
| **Emissive** (10% – 300%) | LED emissive intensity multiplier                                                                                              |
| **Bloom** (10% – 300%)    | Bloom brightness multiplier                                                                                                    |
| **Bloom Size**            | Bloom sprite radius                                                                                                            |
| **Bloom Skew**            | Horizontal stretch for bar-style bloom                                                                                         |

In Day & Night mode, each slider has a `Day` and `Night` variant.

### Quality

| Field                      | Values                        | Description                                                    |
| -------------------------- | ----------------------------- | -------------------------------------------------------------- |
| **Environmental Lighting** | Off, Low, Medium, High, Smart | Controls how LEDs cast light onto the surrounding world        |
| **Lighting Quality**       | Off, Low, Medium, High, Smart | Controls per-LED render pipeline (bloom, coronas, spot lights) |

**Smart** samples frame time at ~90/75 fps thresholds and downgrades between High and Medium automatically to keep the render cost bounded.

### Audio

| Field                   | Description                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Server-sided Sirens** | Use custom server-bundled siren sounds when a tone has a `serverSound` configured. Turn off to force vanilla GTA siren audio. |

### PA Mic

Shown when you own a tELS vehicle and pma-voice is running.

| Field                     | Description                                                                                                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PA Range** (10 – 100 m) | How far your PA voice carries. The server admin sets the default; you can adjust it per-session. pma-voice multiplies this by approximately 3× in native audio mode. |
| **PA Preset**             | Submix effect applied to your PA voice: `police` (radio bandpass), `fire` (similar bandpass), or `clean` (no effect).                                                |

### Vehicle (shown when you own a tELS vehicle)

| Field                         | Description                                                                                                                                                                                                            |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Presence Detection**        | Enable presence mode. When enabled and the vehicle is locked while you're away, other on-foot players near the vehicle satisfy the `presence` / `presence_mode` trigger conditions — used for scene-lighting triggers. |
| **Release Vehicle Ownership** | Release ownership of the current vehicle so another player can control its lights.                                                                                                                                     |

### Admin

| Field                      | Description                                                                                                                                   |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Set as Server Defaults** | Save the current display (emissive, bloom, env quality, lighting quality, HUD visibility, HUD layout) as the server defaults for all players. |
| **Open LED Editor**        | Launch `/telsedit` from the dialog.                                                                                                           |

Settings in KVP under the `tels_*` prefix; server defaults only apply to fields the player hasn't personally changed.

---

## Stages

Stages are driven entirely by triggers. If a vehicle has no `stage_1` / `stage_2` / `stage_3` conditions in any trigger, Q behaves as a simple on/off toggle. Otherwise Q cycles through each configured stage.

| Stage | Meaning                                                                  |
| ----- | ------------------------------------------------------------------------ |
| Off   | Lights fully deactivated                                                 |
| 1–3   | Whatever triggers and pattern overlays are wired to that stage condition |

When lights activate:

- **Cruise** suspends (and restores on deactivate)
- **Takedown** suspends if `lightsSuspendTakedown` is enabled (siren config, default on)
- **Traffic Advisor** suspends if `lightsSuspendTA` is enabled (siren config, default on)

---

## Modes

### Cruise (6)

Steady-speed patrol mode. Typical pattern: a single steady rear pattern via a trigger gated on `cruise`.

### Takedown (7)

Forward scene lights. Trigger conditions can force it on when stationary, or off when moving.

### Traffic Advisor (8)

Directional arrow patterns. The cycle only includes directions the vehicle has `ta_left` / `ta_right` / `ta_center` triggers for — a vehicle with only a left-arrow pattern will cycle `Off ↔ Left`.

### Presence (`/tels` → Vehicle)

Presence detection arms the vehicle. While the owner is away **and** the vehicle is locked, on-foot players who come near satisfy:

- `presence_mode` — true whenever the owner is away and the vehicle is locked
- `presence` — true when an on-foot player (not another tELS owner) enters the detection radius

Use these to automate scene lighting or amber patterns when an officer leaves the vehicle.

### Rumbler (Right Alt)

Toggles the rumbler variant of the main siren when tones have rumbler sounds configured. The aux siren is unaffected.

---

## Horn gestures

The horn key (`E`) emits three trigger conditions usable from the editor:

| Condition         | Fires when                           |
| ----------------- | ------------------------------------ |
| `horn_tap`        | Press + release in under 400 ms      |
| `horn_double_tap` | Two taps within 600 ms of each other |
| `horn_hold`       | Held for more than 500 ms            |

When `hornProgrammable` is enabled on the vehicle's siren config, the default airhorn / vehicle-horn sounds are suppressed and your triggers drive the audio exclusively.

---

## Chirp

A chirp is a short siren burst triggered by the `park_kill` event — when the driver exits the vehicle while sirens are running. It's configured as a trigger action (`park_chirp`) wired to the `park_kill` condition, and fires regardless of vehicle speed. Configure the chirp in the Sirens tab:

- **Chirp Tone** — which tone slot plays
- **Play Full Siren** (`chirpByCode` in the config) — hold the tone for the full chirp duration instead of short blips. Use this when the audio file itself already contains the chirp envelope.

---

## PA Mic

Hold **B** to broadcast your voice through the vehicle's public address system. Requires pma-voice. The audio passes through a bandpass filter to simulate a real PA speaker.

- Only available when you're in the driver seat, own the vehicle, and are not on a call
- PA Range (10–100 m) and Preset (`police` / `fire` / `clean`) are adjustable in `/tels → PA Mic`
- A vehicle's siren config can set `paEnabled: false` to disable the PA mic for that specific model
- The `tels:paActive` state bag and the `IsPaActive()` export reflect the current PA state for external scripts

---

## Sirens

### Burst

Tapping R (or holding a direct-tone key while lights are off) plays a one-shot siren burst without starting the main siren. Burst mode doesn't change `sirenTone` so you stay on whatever tone you had selected.

### Horn interrupt

When `hornInterrupt` is enabled (siren config, default on) the main siren pauses while the airhorn plays and resumes on release.

### Park kill

When the driver exits and `parkKill` is enabled (siren config, default on), all sirens stop and the `park_kill` trigger condition fires. This is what lets a trigger play a short park chirp on driver-exit.

---

## Troubleshooting

  The vehicle has no LEDs configured yet. Every keybind — Q, R, 9/0, 1-8 — requires at least one LED
  on the vehicle. Open `/telsedit` and add LEDs (the **Create from siren bones** button is the
  fastest way).

  You don't have the `tlib.admin` ACE. Add `add_ace group.admin tlib.admin allow` to `server.cfg`
  and reconnect.

  You need to be inside a vehicle (any seat is fine). Passenger works, but you still need admin.

  Patterns marked **Trigger Only** are intentionally hidden from manual cycling — they only play via
  trigger actions. Uncheck **Trigger Only** in the pattern options if you want to cycle to it
  manually.

  Patterns can have a `livery` index that restricts them to a specific vehicle livery. Set `Livery`
  to **Any** in the pattern options, or switch the vehicle to the matching livery.

  Three things must be true: the tone has a `Server Sound` **and** `Server Sound Ref` configured,
  the audio bank is shipped with the resource, and **Server-sided Sirens** is enabled in `/tels`. If
  any of those is missing, tELS falls back to the vanilla `sound` value.

  Another player still holds ownership. Have them release it via `/tels → Release Vehicle
  Ownership`, or drive the vehicle themselves to claim it.

  Client settings in KVP per player — they survive reconnects. **Server defaults** (saved via `/tels
  → Set as Server Defaults`) and **vehicle configs** both live in `data.json` at the tELS resource
  root. Back that file up.

  Make sure you clicked **Save** (or pressed **Enter**). The editor doesn't auto-save; exiting
  without saving discards the work.

<!-- llms-full-doc-separator -->

# tDetector Usage (https://timmygstudios.com/docs/tDetector/usage)
The /tDet settings dialog, toggling the detector, move mode, and per-player preferences.

## Commands

| Command | Purpose                  |
| ------- | ------------------------ |
| `/tDet` | Open the settings dialog |

Depending on your server's `Config.accessMode` (see [Installation](/docs/tDetector/installation#access-control)), `/tDet` may require an ace permission to open at all, or open normally but with its toggle button disabled in favor of a QBCore item. Players denied by the ace check see a chat message and the dialog does not open.

## Settings dialog (`/tDet`)

The dialog handles everything — toggling the detector, tuning display preferences, and repositioning the HUD.

| Field                         | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| **Enable / Disable Detector** | Toggle the radar overlay on or off. Only works while in a vehicle. |
| **Speed Unit**                | `MPH` or `KPH`. Applied immediately and persisted in KVP.          |
| **HUD Layout**                | Pick from any folder under `layouts/`. Changes apply live.         |
| **Reposition HUD**            | Enter move mode (see below).                                       |

Settings are saved per-player in KVP and restored automatically on reconnect.

## Toggling the detector

The **Enable Detector** button in `/tDet` only activates while you are in a vehicle. If you press it on foot, nothing happens.

Once active, the HUD runs a boot animation:

1. Logo flash
2. Self-test (all rings + direction indicator light up briefly)
3. GPS lock animation
4. Steady-state — speed readout and AUTO indicator

If you get out of the vehicle while the detector is on, it switches off automatically and the HUD hides.

## Reading the display

| Element         | Meaning                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| **North arrow** | Radar source is ahead of you                                                                                       |
| **South arrow** | Radar source is behind you                                                                                         |
| **Rings (1–8)** | Proximity. Ring 1 (outermost) appears at 300 m. Each inner ring appears as the gap closes. All 8 lit = under 25 m. |
| **AUTO**        | No active radar gun within 300 m                                                                                   |
| **Speed**       | Your current speed in the selected unit                                                                            |

The blip interval shortens as the gap closes — at 300 m it fires roughly every 1.5 s, at 25 m every 400 ms.

## Move mode

Open `/tDet` and click **Reposition HUD**. The dialog closes and the HUD enters move mode (a dashed outline appears).

| Action           | Effect                                 |
| ---------------- | -------------------------------------- |
| **Drag**         | Move the HUD anywhere on screen        |
| **Scroll wheel** | Scale the HUD up or down (0.3× – 2.0×) |
| **Escape**       | Lock the position and exit move mode   |

Position and scale persist in KVP and restore on every login.

## Troubleshooting

  tDetector only picks up players whose radar resource has the `IsRadarActive` export patched in **and** has an antenna switched on (not just powered — XMIT must be active). Check:

1. At least one entry in `Config.radarResources` matches a running resource (`wk_wars2x` or `seeker_dual`).
2. That resource has the `IsRadarActive` client export added to both its manifest and its client script (see [Installation](/docs/tDetector/installation)).
3. The radar player is in a vehicle with the radar powered on **and** at least one antenna in XMIT mode.

If you're testing solo there will be nothing to detect.

  You must be in a vehicle. Speed is read from the vehicle entity — it reads 0 on foot.

  Layouts are enumerated when the resource starts. Add your layout folder under `layouts/`, then
  restart `tDetector`. It will appear in `/tDet` on next open.

  That's by design — the boot sequence resets each time the detector is enabled. If you want to skip
  it, build a custom layout that skips the sequence in its `__tdetLayoutUpdate` callback.

  Position is saved in KVP, which is tied to your player identifier — it persists across restarts
  and reconnects as long as you connect with the same identifier. If your license/steam ID changed,
  the KVP is for a different player.

<!-- llms-full-doc-separator -->

# tAFK Usage (https://timmygstudios.com/docs/tAFK/usage)
Commands, auto-AFK flow, the /tafk dialog, and state-bag integration.

## How AFK triggers

tAFK watches for input every tick. Three paths fire the cinematic camera:

| Trigger                                               | Gated by                                                      | Notes                                                  |
| ----------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------ |
| **Auto** — `timeoutSeconds` of no input (default 30s) | Must be in a vehicle; system must be enabled (per-player KVP) | Detector fades to black, then opens the first sequence |
| **Manual** — `/afk` command                           | Must be in a vehicle                                          | Same fade → cinematic flow, skips the idle timer       |
| **Manual** — `/tafk` menu → **Enter AFK Mode**        | Same as `/afk`                                                | Closes the dialog first, then triggers                 |

All three trigger on one code path. What counts as input:

- Position delta > `0.05` units
- Heading delta > `0.5°`
- Gameplay cam rotation delta > `0.001` rad (very sensitive — any mouse movement exits)
- Any of 12 monitored controls (movement, look, aim, attack, sprint, jump, crouch)

---

## Commands

| Command     | Access               | Effect                                                           |
| ----------- | -------------------- | ---------------------------------------------------------------- |
| `/afk`      | Anyone               | Toggle AFK cinematic on/off (fastest path)                       |
| `/tafk`     | Anyone               | Open the settings dialog — player overrides, admin panels if ACE |
| `/tafkedit` | Admin (`tlib.admin`) | Open the free-cam keyframe editor (must be in a vehicle)         |

  `/afk` is the single-press toggle. `/tafk` opens the dialog where players set persistent
  preferences — they're different surfaces for different needs.

---

## The `/tafk` dialog

### Player section (always visible)

- **Enter AFK Mode / Exit AFK Mode** — live toggle, disabled when the system is off for this player
- **AFK System** — persistent master switch. Stored as `tafk:playerDisabled` KVP. When off, even `/afk` and the detector are silenced for this player
- **Play Music During AFK** — two-state checkbox. On/off; overrides the server default for this player
- **Music Volume** — 0–100 (%) slider, step 1. Stored as 0.0–1.0 after division by 100
- **Hide HUD While AFK** — if on, `DisplayRadar(false)` and `DisplayHud(false)` fire on AFK start, reversed on exit. Backed by the `hideHudInAFK` setting
- **My Sequence Preferences** — sub-dialog listing every loaded sequence with a checkbox. Uncheck to opt this player out of that sequence. Server-disabled sequences are read-only
- **Reset My Settings** — clears all KVP for this player, falls back to server defaults

### Admin section (requires `tlib.admin`)

Two buttons, both open sub-dialogs or the editor:

- **Server Defaults** — idle timeout (seconds), min/max sequence duration (seconds), beat anchor (ms), and server-wide fallback values for music / volume / hide-HUD. Players with their own override still win; these are just the defaults for players who haven't chosen.
- **Open Sequence Editor** — launches the free-cam editor overlay. Shown only when the admin is in a vehicle; otherwise the button is disabled with the label **Get in a vehicle to open the editor**. All sequence management — list, enable/disable, create, edit, delete — happens inside the editor overlay. There's no separate "Manage Sequences" sub-dialog. See [Editor guide](/docs/tAFK/editor).

All changes apply live — sliders and checkboxes push to server or KVP on every change. No save button.

  There's no music-track management UI. Drop `.ogg` / `.mp3` / `.wav` files into `tAFK/audio/` and
  restart the resource. Filenames matching `bg1.ogg`, `track2.ogg`, `afk3.ogg`, `music4.ogg`, or
  `cinematic5.wav` (1–99) are picked up automatically; any other filename works too if you list it
  in `audio/manifest.txt`. See [Configuration → Music
  tracks](/docs/tAFK/configuration#music-tracks).

---

## Exit conditions

Once AFK, the detector exits the cinematic immediately when any of these become true:

- Any input from the [input list above](#how-afk-triggers)
- Player exits the vehicle
- Vehicle entity no longer exists (despawn, destroy)
- `IsCutsceneActive()` or `IsPlayerSwitchInProgress()` returns true

Fade-out during entry is also cancellable — hit any key mid-fade and the whole thing aborts cleanly without ever rendering the cinematic camera.

---

## State bag integration

Every AFK enter/exit sets a replicated state bag on the local player:

```lua
LocalPlayer.state:set('afk', true, true)   -- on enter
LocalPlayer.state:set('afk', false, true)  -- on exit (also set to false at resource start)
```

Other scripts read this without any handshake:

```lua
-- Server-side
local isAfk = Player(playerId).state.afk   -- true | false | nil

-- Client-side, from another resource
local peer = GetPlayerFromServerId(targetId)
local isAfk = Player(peer).state.afk
```

  - Radio scripts can mute transmit for AFK players
  - Scoreboard / F8 overlays can mark AFK names
  - Dispatch panels can filter busy units
  - Economy scripts can pause paycheque timers

None of this requires integration with tAFK beyond the state bag read.

---

## The `tafk:stateChanged` event

For same-client listeners that need to know the moment state changes (e.g., muting a different NUI, pausing a minigame), a local event fires in parallel with the state-bag write:

```lua
AddEventHandler('tafk:stateChanged', function(isAfk)
  if isAfk then
    -- entering AFK — freeze your own HUD, pause timers
  else
    -- leaving AFK — unfreeze
  end
end)
```

The event is client-local only. For cross-player awareness use the state bag.

---

## Exports

See the [API Reference](/docs/tAFK/api-reference) for full signatures. Quick summary:

```lua
exports['tAFK']:IsAFK()                -- this client, right now
exports['tAFK']:IsAFKEnabled()         -- session switch (/tafk master toggle)
exports['tAFK']:StartAFK()             -- manual enter (still needs vehicle)
exports['tAFK']:StopAFK()              -- exit now
exports['tAFK']:ToggleAFK()
exports['tAFK']:SetAFKEnabled(bool)
```

---

## Disabling temporarily

If you need to suppress tAFK during a specific scene (a race, a cutscene, a minigame in your own resource), call:

```lua
exports['tAFK']:SetAFKEnabled(false)
-- ... your scene ...
exports['tAFK']:SetAFKEnabled(true)
```

`SetAFKEnabled(false)` also stops an in-progress cinematic immediately. The setting is session-only — it doesn't to KVP unless you also write `tafk:playerDisabled`.

<!-- llms-full-doc-separator -->

# You Lack the Required Entitlement (https://timmygstudios.com/docs/faq-entitlement-error)
Fixing the "You lack the required entitlement" error for FiveM escrow scripts.

## Error Message

```
You lack the required entitlement to use script_name
```

## Why This Happens

All FiveM escrow-protected scripts are linked to your FiveM account (the account you used on Tebex). The script requires a server key generated by the **same FiveM account** that purchased the script.

## What is a Server Key?

- A server key is generated at the [CFX Portal](https://portal.cfx.re/)
- It is **not** a script key
- A FiveM server can only use **one** server key
- It's set in your `server.cfg`:

```ini
sv_licenseKey "YOUR_SERVER_KEY_HERE"
```

---

## How to Fix

### Restart your server

Sometimes a simple restart resolves the issue. Fully restart — don't just `ensure` the resource.

### Verify your server key

Run this in your FiveM server console:

```
sv_licenseKey
```

This shows which server key your server is currently using. Note it down for the next step.

### Verify key ownership

1. Go to the [CFX Portal](https://portal.cfx.re/)
2. Check the **Purchased Assets** tab — verify the script appears under this account
3. Check the **Server Keys** section — verify the key from the previous step was generated by this same account

If the script isn't listed under your purchased assets, you used a different FiveM account on Tebex, or the script was transferred to another account.

### Check system time

Your server's operating system clock must be accurate. If it's more than one minute off:

1. Check at [time.is](https://time.is/)
2. Select your server's location
3. If the time is off, sync it — [watch this guide](https://www.youtube.com/watch?v=cLJGy4-sMZg)

### Transfer the script (if keys and purchase don't match)

If your server key belongs to a different account than the one that purchased the script, either:

- **Generate a new server key** from the account that owns the script, or
- **Transfer the script** to the account that owns the server key (see below)

---

## How to Transfer a Script

  Scripts can only be transferred **once**. You will not be able to transfer it again after this.

### Find the server owner

You need the FiveM username of the account you're transferring to:

1. Go to the [FiveM Server List](https://servers.fivem.net/servers)
2. Find your server and check the **Owner** field
3. Alternatively, check the server console for the nucleus auth ID, then visit `https://servers.fivem.net/servers/detail/YOUR_ID`

### Transfer steps

### Log in to the CFX Portal

Open the [CFX Portal](https://portal.cfx.re/) and sign in with the account that currently owns the script.

### Open Purchased Assets

Go to the **Purchased Assets** tab and find the script.

### Click Transfer

Click **Transfer to another account** on the script's row.

### Enter the target username

Type the username of the destination FiveM account and confirm. The transfer is immediate and final.

---

## ZAP-Hosting Users

If you're using ZAP-Hosting, you do **not** enter your server key in `server.cfg`. Instead, set it directly in the ZAP-Hosting web panel.

See the [official ZAP-Hosting guide](https://zap-hosting.com/guides/docs/en/fivem_licensekey/) for instructions.

---

## Related

    Overview of all escrow errors and how to identify which one you're seeing.

  The other common escrow symptom — usually a bad upload.

    If you're seeing this error alongside entitlement issues, start here.

<!-- llms-full-doc-separator -->

# tAFK (https://timmygstudios.com/docs/tAFK)
Cinematic AFK camera for FiveM — beat-synced cuts, per-vehicle sequence packs, authored in-game not in a file.

<div class="flex items-center gap-4 my-4">

    FiveM Post

    Store Page

</div>

AFK systems in FiveM have always been disciplinary — a timer, a warning, a kick. tAFK is the opposite. When a player goes idle in a vehicle, their camera breaks out into a cinematic orbit of the car: depth of field, cuts that land on the beat, music underneath. Presence without interaction.

Any input at all puts them straight back in control.

  tAFK never kicks, warns, or punishes idle players. It is a camera system that triggers on idle
  input. If you need session-timeout enforcement, combine tAFK with a separate kick script that
  reads `Player(src).state.afk`.

## Requirements

| Requirement | Detail                                                                                                    |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| OneSync     | Required — Infinity or Legacy                                                                             |
| tLib        | **v0.4+**, free — [download](https://github.com/tommy141x/tLib/releases). The release zip, not the source |
| Framework   | None. There is no framework code in tAFK, and none is needed                                              |
| Ports       | None. No external services                                                                                |
| Scope       | Vehicles only — car, bike, boat, or aircraft. There is no on-foot camera                                  |
| Lua         | 5.4, handled by the manifest                                                                              |

---

## Try it first

## Quick start

1. **Extract** the resource to your server's `resources` folder
2. **Start** tLib before tAFK — `ensure tLib` then `ensure tAFK` in `server.cfg`
3. **Grant** the `tlib.admin` ACE to whoever should author shots
4. **Drop** your own music into `audio/` if you want beat-synced cuts — any filename, any of `.ogg` / `.mp3` / `.wav`
5. **Restart** your server

<div class="mt-4">

    Full Installation Guide

</div>

---

## Features

### Eleven shots, shared by everyone

Eleven shots ship: low ground pans, headlight and taillight wipes, wheel-to-door tracks, grille-to-hood pushes, and rear-bumper detail tilts. Each is a pair of camera keyframes stored as offsets relative to the vehicle, so the same shot works on a Bati and a Phantom.

Server-authored shots live in `data.json` and stream to every client on boot; the cinematic itself renders on the player's own machine.

### The director picks the shot, not a shuffle

Before every cut, each candidate is raycast — along its path and at both ends. Angles that clip the vehicle or its trailer, sit too close, repeat one of the last three shots, or start far from where the previous shot ended all lose points. Whatever survives goes into a weighted draw.

Offsets also scale to the vehicle, 0.8× to 2.5× of its bounding box, so one shot frames a motorbike and an articulated truck without being re-authored. Every run looks different; none of them look broken.

### Authored in the vehicle, not in a file

`/tafkedit` (admin-gated) drops you into a free-fly camera around your car. MMB drag orbits, Shift+MMB pans, RMB looks around, the wheel adjusts FOV. WASD flies; Space and Ctrl are up and down; Shift for 3×, Alt for 0.3× fine-tune.

**1** captures the start, reposition, **2** captures the end, **3** previews, **4** saves. Scope the shot globally or lock it to the current model. Naming, per-shot toggles, and depth-of-field live in the same overlay — no config files to edit.

### Cuts on the beat

Drop any `.ogg`, `.mp3`, or `.wav` into `audio/` and restart — any filename works. The server enumerates the folder on boot and adds every audio file it finds to the rotation. No naming convention, no manifest.

When a track plays, the interface analyses its tempo and offset in-browser and hands the timing back to Lua; cuts align to the next beat within the shot's min/max duration, with a configurable anticipation offset so the hit lands _with_ the beat, not after.

No beat data? Durations fall back to random within range — the system still works, just without the sync.

  Tempo data from the interface has not arrived yet when the first shot is chosen, so shot one uses
  a plain random duration and ignores your configured bounds. Sync begins from the second shot
  onward.

### Per-vehicle sequence packs

Vehicle resources can ship their own shots:

```lua
title="fxmanifest.lua" tafk_config 'tafk.json'
```

```json
title="tafk.json" { "bati801": { "sequences": [ { "id": "bati_low_pass", "name": "Low Pass", "start": {...}, "end": {...} } ] } }
```

tLib's Discovery module scans every running resource on server start, merges matching-model shots into each client's lookup, and re-broadcasts when packs start or stop. Server-side admin edits always take priority, so pack shots act as defaults you can override.

### Integrates through state bags

The moment a player enters or leaves AFK, tAFK sets `LocalPlayer.state.afk` and replicates it server-wide:

```lua
local afk = Player(playerId).state.afk   -- true | false | nil
```

No exports, no events, no polling. Radio, scoreboard, dispatch panels — anything that needs to know who is cinema-idle reads the state bag. Exports (`IsAFK`, `StartAFK`, `StopAFK`, `ToggleAFK`, `IsAFKEnabled`, `SetAFKEnabled`) cover local-client queries and programmatic toggles.

### Players control their own experience

`/tafk` opens a settings dialog with master enable/disable, music override, volume override, HUD-hide toggle, and per-shot opt-outs — all persisted via tLib KVP, all surviving relogs. Server defaults inform the starting values; a player's override wins for their own client.

Admins see the same dialog plus global settings (timeout, duration bounds, beat anchor, music defaults) and an editor launch button when in a vehicle.

---

## Questions people actually ask

    No — there is no timer, no warning, and no kick anywhere in it. It only changes the camera. For
    session enforcement, run a kick script alongside it that reads `Player(src).state.afk`.

    No. Vehicles only. A player outside a vehicle who runs `/afk` is told to get in one.

    By design, and the sensitivity is deliberately high — even a small mouse movement counts as
    input, including during the fade in. That is what makes it safe to leave enabled for everyone.

    No. Shots are captured in `/tafkedit` and saved from that overlay, which pushes them live.
    `data.json` is only read at start, so hand-edits need a `restart tAFK`. See
    [Editor](/docs/tAFK/editor).

    No. Cutscenes, player switches, and a ragdolled ped all block it, and two of those also end a
    cinematic already in progress. For your own scripts, use `exports['tAFK']:SetAFKEnabled(false)`.

---

## Pages

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">

    Dependencies, server.cfg setup, admin ACE, first-run behaviour.

    <div class="mt-4">

        Installation Guide

    </div>

    Commands, auto-AFK flow, player settings, state-bag integration.

    <div class="mt-4">

        Usage Guide

    </div>

    Orbit controls, keyframe capture, preview, save scope.

    <div class="mt-4">

        Editor Guide

    </div>

    The `data.json` schema, per-vehicle packs, admin settings.

    <div class="mt-4">

        Configuration Guide

    </div>

    Exports, events, state bags, admin server events.

    <div class="mt-4">

        API Reference

    </div>

</div>

<!-- llms-full-doc-separator -->

# tDetector (https://timmygstudios.com/docs/tDetector)
Radar detector for FiveM. Detects nearby police radar guns and displays distance, direction, and speed on a draggable HUD overlay.

---

## Know before they know you're speeding

tDetector listens for players running a Wraith ARS 2X radar gun. The moment someone switches an antenna on, the overlay wakes up — a boot animation, a GPS lock, then the live display: proximity rings that contract as the radar car closes in, a direction arrow showing whether the gun is ahead of you or behind you, and your current speed.

---

## Proximity rings

The display shows up to eight concentric rings. Rings appear from the outside in as the radar car gets closer.

---

## Boot sequence

When the detector switches on it runs a self-test: the logo, a test pattern across all rings, a GPS-lock animation, then steady-state. The display only goes active after the lock completes.

---

## Draggable and scalable

The overlay uses tLib's move mode. Open `/tDet`, click **Reposition HUD**, then drag it anywhere on screen. Scroll to scale it up or down. Press **Escape** to lock the new position. Position and scale across sessions.

---

## Layouts

The default skin replicates the original Youniden radar detector display. Anything in `layouts/` is auto-discovered and appears in the `/tDet` selector — the same marketplace pattern as tELS and tRadio.

---

## Requirements

- FiveM server with OneSync
- [tLib](https://github.com/tommy141x/tLib)
- [Wraith ARS 2X](https://github.com/WolfKnight98/wk_wars2x) (`wk_wars2x`) — provides radar gun detection

---

## Start here

    Dependencies, server.cfg order, and the Wraith ARS 2X patch.

  The `/tDet` settings dialog, how to toggle the detector, move mode, and per-player preferences.

    Build a custom detector skin — HTML, CSS, sounds, and the state callback API.

<!-- llms-full-doc-separator -->

# tELS (https://timmygstudios.com/docs/tels)
Emergency lighting for FiveM. Configured in the vehicle, not in a file.

<div class="flex items-center gap-4 my-4">

    Store Page

</div>

Emergency lighting in FiveM has always meant patterns compiled into a vehicle resource. Every flash-rate change, every LED nudge, every siren swap — edit the file, reupload the resource, restart the server.

tELS throws that pipeline out. You sit in the vehicle, run `/telsedit`, place LEDs on the 3D model with a gizmo, paint patterns on a grid, and wire up triggers. Save, and every connected client picks up the change.

  tELS is not a drop-in replacement for ELS or non-ELS vehicle packs. Their pattern files do not
  migrate — the data model is different. You configure each vehicle in-game, import its
  `carcols.meta`, or use a vehicle that ships a bundled `tels.json`.

## Requirements

| Requirement | Detail                                                                   |
| ----------- | ------------------------------------------------------------------------ |
| OneSync     | Required — Infinity or Legacy                                            |
| tLib        | **v0.6+**, free — [download](https://github.com/tommy141x/tLib/releases) |
| Framework   | None. There is no framework code in tELS, and none is needed             |
| pma-voice   | Optional, and only for the PA microphone                                 |
| Lua         | 5.4, handled by the manifest                                             |

---

## In-game editor

Position and rotate each LED on the vehicle with a live gizmo. Attach to bones so LEDs follow doors, the hood, the trunk. Group them by location. Click **Create from siren bones** and tELS auto-generates a starter bar from the vehicle's `siren1`…`sirenN` bones in one click.

Multi-select, duplicate, mirror across the centerline. Every LED carries a stable UUID, so renaming or reordering never breaks a saved pattern.

Up to **64 LEDs are rendered at once** per vehicle. That covers a full lightbar build comfortably; a very heavily-lit apparatus can reach it.

---

## Import an existing carcols

Copy a vehicle's `carcols.meta`, paste it into the importer, and pick a siren set. tELS converts its sequences, flash rate, phase offsets, and per-head colours into a native tELS pattern — optionally split into separate patterns per `lightGroup` — which you then edit like anything else.

It does not make tELS a drop-in for ELS packs, but it does mean a vanilla-style lightbar is a paste away rather than a rebuild.

---

## Patterns, not presets

LEDs run across the top as columns, frames down the side as rows. Any colour on any LED at any frame. Per-pattern colour palettes, per-pattern frame rate, and per-frame durations. Cells marked dimmable interpolate their colour into the next frame instead of snapping.

The pattern previews on the actual vehicle as you edit. What you see in the editor is the pixel output in-game.

Per-pattern flags decide whether it cycles manually, plays only from triggers, holds the GTA emergency-lights flag, holds high beams, restricts to a specific livery, or syncs across every client from a shared network clock.

---

## Triggers that match the real problem

**73 vehicle-state conditions**, written as compound AND/OR rules with per-condition negation, driving **16 kinds of action**. Not a token list — the actual inputs emergency lighting needs:

| Category          | Conditions                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **Speed**         | `stationary`, `speed_15`, `speed_30`, `speed_60`, `speed_90`                                  |
| **Controls**      | `brake`, `handbrake`, `reverse`, `turn_left`, `turn_right`, `hazards`                         |
| **Horn gestures** | `horn_tap`, `horn_hold`, `horn_double_tap`                                                    |
| **Doors**         | `door_fl/fr/rl/rr`, `hood`, `trunk`, `any_door_open`, `locked`                                |
| **Occupancy**     | `driver_in_veh`, `passenger_front`, `passenger_rear`, `presence`, `presence_mode`             |
| **Audio state**   | `siren`, `main_siren_on`, `aux_siren_on`, `rumbler`, `airhorn`, `siren_tone_1`…`siren_tone_8` |
| **Modes**         | `cruise`, `takedown`, `ta_left/right/center`                                                  |

Actions overlay a pattern, set the base pattern, change stages, cycle sirens, play the airhorn, or fire a park chirp.

> **Example:** `brake` AND `speed_30` AND `lights_on` → overlay the rear warning pattern. Built in-game in two clicks.

<div class="mx-auto max-w-[560px]">

</div>

---

## Audio that matches the lights

Eight tone slots per vehicle. Main and aux channels. Airhorn. Rumbler variants. Each tone holds a vanilla GTA sound and an optional server-sided one — players toggle between them in `/tels`. Twelve custom tones ship, alongside fourteen vanilla game sounds, and sound packs map to the same slots; switching packs is a config change, not a code change.

Horn gestures become trigger conditions. With `hornProgrammable` on, the default horn steps out of the way and your triggers drive the audio exclusively.

---

## Runs under load

Built for scenes with several emergency vehicles on screen, not just one:

- Vehicles beyond **500 m** are skipped entirely; ones behind the camera are culled past 20 m.
- Environmental lighting steps down with distance, with a far band at 200 m.
- Pre-allocated render buffers — zero per-tick allocation.
- Trigger evaluation is native-gated: expensive door, lock, and occupancy natives run only for vehicles whose rules reference them.
- **Smart environmental lighting** samples frame time and scales between Medium and High, upgrading at 90 fps and dropping back at 75 so it settles rather than oscillates.
- **Smart lighting quality** is a separate setting: it drops _other_ players' vehicles to Low below 85 fps and always leaves your own vehicle at full quality.
- Pattern sync rides a shared server clock — every client derives the same frame without per-client coordination.

  Everything above is a mechanism, not a measurement. There is no official ms-per-frame or fps
  figure for tELS, and any number you see quoted for it did not come from us.

---

## Share once, deploy everywhere

```json
{ "$ref": "police4", "$all": true }
```

Configure `police4` once. Reference its patterns, triggers, and siren from `police5`, `police6`, `police7`. Edit the source and every referencing vehicle updates. Orphans clean up automatically.

Two things to know: references do not chain — a `$ref` pointing at another `$ref` will not resolve — and editing a referenced pattern edits the **source** vehicle, not the one you are sitting in.

Vehicle packs can ship a `tels.json` inside their resource — tLib's Discovery module picks it up on server start. Server-owner edits always take priority, so customizations survive pack updates.

---

## Integrates through state bags

Every lighting and siren field mirrors to a `tels:*` state bag. Any script on any client reads current state without a server round-trip:

```lua
local on   = Entity(veh).state['tels:active']
local tone = Entity(veh).state['tels:sirenTone']
local ta   = Entity(veh).state['tels:taMode']
```

Two exports (`IsSirenActive`, `AreLightsActive`) cover the common "is this a tELS vehicle" gate for integrations like radio scripts.

---

## Questions people actually ask

    The vehicle has no LEDs yet. Every keybind — Q, R, 9/0, 1-8 — needs at least one configured LED.
    Open `/telsedit` and click **Create from siren bones**.

    You need tLib's admin ACE. Add `add_ace group.admin tlib.admin allow` to `server.cfg` and
    reconnect.

    Three things all have to be true: the tone has both a Server Sound and a Server Sound Ref, the
    audio bank ships with the resource, and **Server-sided Sirens** is on in `/tels`. Miss any one
    and it falls back to the vanilla sound silently.

    Ownership is per vehicle. They release it from `/tels` → **Release Vehicle Ownership**, or you
    drive the vehicle yourself to claim it.

    The editor does not auto-save. Press Enter or click Save — exiting discards your changes. Undo
    history is also cleared once you save.

    It is either flagged **Trigger Only**, which deliberately hides it from manual cycling, or it is
    restricted to a livery index that isn't currently active.

---

## Start here

    Dependencies, server.cfg setup, admin access, and a two-minute quick start from install to lights-on.

  Configure any vehicle: LEDs, patterns, triggers, sirens.

  Every keybind, the `/tels` settings dialog, stages, modes, and troubleshooting for the questions
  you can't Google.

  The `data.json` schema, vehicle-developer bundling, cross-vehicle references, and server defaults.

  Build custom HUD overlays with declarative `data-hud-*` bindings.

  The naming standard that makes patterns and HUD layouts portable between vehicles.

    Exports, state bags, and network events for external scripts.

    Working alongside other resources, including night_ers pullover detection.

## Support

- [Changelog](/changelog) — what shipped in each release
- [FAQ](/docs/faq-general-issues) — questions that come up before you buy
- [Discord](https://timmygstudios.com/discord) — bring your console error, load order, and tELS + tLib versions

<!-- llms-full-doc-separator -->

# tLib (https://timmygstudios.com/docs/tlib)
Shared UI and utility library for FiveM and Helix resources.

<div class="flex items-center gap-4 my-4">

    GitHub

    Download

</div>

## What is tLib?

tLib is a shared utility library for FiveM and Helix resources. It provides UI components (menus, dialogs, toasts, themes), reusable Lua import modules (settings, KVP, coords, layouts, move mode), and TypeScript/NUI utilities for resource developers.

It has no configuration — just install it and use it as a dependency.

---

## Features

### UI Component Suite

Full NUI-based menu system with submenus and dynamic updates, modal form dialogs with multiple field types, stackable toast notifications, and a CSS variable-based theme system.

### Import Modules

Lightweight Lua modules that load on demand — typed KVP storage, settings stores with persistence, vehicle coordinate math, layout discovery, and drag-to-reposition for HUDs.

### TypeScript / NUI Utilities

Shared TypeScript packages (`@tlib/shared`) including a Three.js-based 3D gizmo, undo/redo system, coordinate conversion helpers, and a framework-agnostic drag handler.

### Platform Abstraction

Works on both FiveM and Helix through an adapter layer — write once, run on either platform.

---

## Pages

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">

    Download and set up tLib on your server.

    <div class="mt-4">

        Installation Guide

    </div>

    Menu, Dialog, Toast, Theme, Logger, HTTP, and Permission exports.

    <div class="mt-4">

        Exports Reference

    </div>

    Lightweight Lua modules: coords, kvp, settings, and layouts.

    <div class="mt-4">

        Import Modules

    </div>

</div>