Configuration

Where each setting lives#

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#

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

Discord authentication#

Optional OAuth for the dispatch panel and the admin panel. Create an application at the Discord Developer Portal, 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

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

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#

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

'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#

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

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

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:

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)

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:

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.

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.

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:

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.

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.

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.

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.

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#

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.

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.

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.

Codeplug sections#

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.

ACE permissions#

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

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

server.cfg

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

Server settings#

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

General tab#

Audio & Radio tab#

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

PTT & Transmission

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

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

Signal Coverage

Degradation does nothing until towers exist — see Signal towers.

Dispatch Scanning

Radio Audio Effects — see 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).

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.

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

ImperialCAD Integration — see 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.

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:

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:

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.

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:

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.

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

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.

Grab coordinates in-game with /_tradio_coords. Dispatchers use them from the Speakers button in the dispatch panel; see Usage.

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.

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.

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

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.

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.

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

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:

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
}

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.