API Reference

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#

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

Alerts and panic#

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

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#

User information#

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#

getSubscriberInfo returns:

{
    codeplugId         = "leo",
    unitId             = "1041",
    nac                = "141",
    allowedModels      = { "ATX-8000", "AFX-1500" },
    defaultLayouts     = { Handheld = "ATX-8000", Vehicle = "AFX-1500" },
    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.

Audio#

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

Tone keys come from the tone catalog.

Client exports#

Radio control#

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#

Radio state#

Volume and audio#

Appearance and settings#

Alerts and panic#

Player and system information#

Web API#

Authenticating#

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

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

{
  "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#

Public endpoints#

Status and config#

Broadcasts and tones#

Alerts#

Channels and units#

Patches#

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"}'

Error responses#

All errors are application/json.

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.

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#

Listen — server to client#

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.

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).

Themes are installed from Admin Panel → Marketplace → Themes. Building and publishing one is covered in Publishing a theme below.

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):

--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): @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), bound by the same binder and the same action allow-list. 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:

{
  "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.

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:

{ "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 — 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 — 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#

Theme JavaScript receives three injected globals:

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 for full autocomplete while authoring.

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.

Zone shape:

{
  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:

{
  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.

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

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

Actions#

Channel:

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

PTT:

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

Announcement groups:

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

Alerts:

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:

// 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:

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.

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.

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.

No-JS template themes#

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

{
  "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.

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: "",
  }),
});

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.

// 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:

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

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):

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:

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:

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,
);

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.

<!-- 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>

Publishing a theme#

Themes are authored and submitted in the theme editor — tgstudios → Marketplace → Themes → Create Theme. Build against your own live panel first (see 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.

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.

What happens on submit

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#