Developer Documentation

Everything other resources can use from zerio-radio: exports, the server events it triggers, and the commands it registers.

Frequencies are numbers, such as 100 or 100.5. Exports that take a frequency also accept it as a string.

Server-Side Exports

Players and Channels

GetPlayerChannels

local channels = exports["zerio-radio"]:GetPlayerChannels(source)
-- { active = 911, listening = { 100, 911 } }

Returns the channels a player is on. active is the channel they talk on, or 0 when they’re on none. listening lists every channel they’re on, including the active one.

GetChannelMembers

local members = exports["zerio-radio"]:GetChannelMembers(frequency)

Returns the server ids of everyone on a channel. Players who only listen in through a scanner lock-on aren’t members, so they’re left out.

IsPlayerTransmitting

local talking = exports["zerio-radio"]:IsPlayerTransmitting(source)

Returns true while the player is talking on their radio. To react the moment it changes, listen to playerStartedTransmitting and playerStoppedTransmitting instead.

GetPlayerSignalStrength

local signal = exports["zerio-radio"]:GetPlayerSignalStrength(source)
local signal = exports["zerio-radio"]:GetPlayerSignalStrength(source, frequency)

Returns the player’s signal on a channel, from 0.0 (no signal) to 1.0 (full signal), in steps of 0.05. Without a frequency it uses the channel they talk on. Returns nil when they aren’t on that channel.

Signal depends on towers, terrain, weather, jammers, repeaters, signal zones and battery. With all of those turned off, it’s always 1.0.

ForceJoinChannel

local joined = exports["zerio-radio"]:ForceJoinChannel(source, frequency, setActive)

Adds a player to a channel without checking their access (jobs, codeplug radios and so on), like the admin menu’s force join. Returns whether they were added.

It still won’t add a player to a channel an admin has locked, when their battery is dead or when they’re already on Config.MaxChannels channels. The channel becomes the one they talk on when setActive is true, or when they weren’t talking on any channel.

ForceLeaveChannel

local left = exports["zerio-radio"]:ForceLeaveChannel(source, frequency)
local left = exports["zerio-radio"]:ForceLeaveChannel(source)

Removes a player from a channel, or from every channel when you leave out the frequency. Returns false when they weren’t on it.

HasAccess

local access = exports["zerio-radio"]:HasAccess(frequency, source)

Returns whether a player may join a channel, going by the channel’s access rules and admin lock. Note that the frequency comes first. A frequency without a channel set up is open to everyone, so it returns true.

Channel Management

Channels are created and edited in the admin menu (/radioadmin) and stored in the database. The exports below only change the running server: the change is gone after a restart, and players already on a channel aren’t checked again.

DoesChannelExist

local exists = exports["zerio-radio"]:DoesChannelExist(frequency)

Returns whether a channel is set up on that frequency.

CreateChannel

local created = exports["zerio-radio"]:CreateChannel(frequency, {
  label = "SWAT",
  jobs = { "police" },
  noTalkOver = true,
})

Sets up a channel until the next restart. Returns false when the frequency already has a channel or label is missing.

RemoveChannel

local removed = exports["zerio-radio"]:RemoveChannel(frequency)

Removes a channel until the next restart, which leaves the frequency open to everyone.

UpdateChannelLabel

local updated = exports["zerio-radio"]:UpdateChannelLabel(frequency, label)

Renames a channel until the next restart. Players on it see the new name straight away.

GiveAccessToChannel

local success = exports["zerio-radio"]:GiveAccessToChannel(frequency, accessType, value)

Adds a value to one of a channel’s access rules, for example GiveAccessToChannel(911, "jobs", "sheriff").

The access types are jobs, gangs, rcoreGangs, opCrimeGangs, discordRoles, acePermissions and whitelisted.

RemoveAccessFromChannel

local success = exports["zerio-radio"]:RemoveAccessFromChannel(frequency, accessType, value)

Removes a value from one of a channel’s access rules. Returns false only when the channel doesn’t exist.

Callsigns and Settings

GetCallsign

local callsign = exports["zerio-radio"]:GetCallsign(source)
local callsign = exports["zerio-radio"]:GetCallsign(identifier)

Returns a player’s callsign, from their server id or their identifier. Returns an empty string when they have none.

SetCallsign

exports["zerio-radio"]:SetCallsign(source, callsign)
exports["zerio-radio"]:SetCallsign(identifier, callsign)

Sets a player’s callsign and saves it. Players on the same channels see the new callsign straight away.

UpdateSetting

exports["zerio-radio"]:UpdateSetting(source, key, value)
exports["zerio-radio"]:UpdateSetting(identifier, key, value)

Changes one of a player’s radio settings and saves it. The keys are:

• General: volume, callsign, theme, colorTheme, radioSkin, streamerMode, anonymous, pttEnabled, debugMode
• Layout: radioPositionX, radioPositionY, radioScale, memberList, memberListShowAll, memberListShowGroups, memberListPositionX, memberListPositionY, memberListScale, channelHudPositionX, channelHudPositionY, channelHudScale
• Notifications: messageNotifications, notificationSound, emergencyAlerts, joinLeaveAlerts
• Audio: clickVolume, staticNoise, memberJoinSound, memberLeaveSound

The zerio_radio_settings table shows the possible values.

Codeplug Radios

Codeplug radios are radio items locked to preset channels, set up in Config.OpenType.Items (configs/opentype.lua).

GetPlayerCodeplug

local codeplug = exports["zerio-radio"]:GetPlayerCodeplug(source)

Returns the codeplug radio the player is using, or nil when the radio they’re using isn’t one. The table has itemName, label, channels (the preset channels) and allowOtherChannels.

PlayerCodeplugCoversFrequency

local covered = exports["zerio-radio"]:PlayerCodeplugCoversFrequency(source, frequency)

Returns whether any codeplug radio the player has open has that frequency as a preset.

CheckAccessOnInventoryChange

exports["zerio-radio"]:CheckAccessOnInventoryChange(source)

Checks the player’s access to every channel they’re on again, and removes them from the ones they’ve lost access to. zerio-radio already does this for job changes, duty changes and radio items, so you only need it when your own script changes what a player can access.

Groups

Groups organise the members of a channel, for example “SWAT” or “Traffic”. They only change how the member list looks, never who hears whom. See Groups for how players use them.

Groups are kept in memory for the server session. The exports below take the player as a server id or a character identifier (QBCore citizen ID, ESX identifier), so you can also assign players who are offline. Group names are unique per channel, ignoring case.

SetPlayerGroup

local success = exports["zerio-radio"]:SetPlayerGroup(source, frequency, "SWAT")
local success = exports["zerio-radio"]:SetPlayerGroup(source, frequency, "SWAT", true) -- locked
local success = exports["zerio-radio"]:SetPlayerGroup(source, frequency, nil) -- no group

Puts a player in a group on a channel, and creates the group if it doesn’t exist. With nil as the name, it takes them out of their group. Returns false when groups are turned off or the name is shorter than Config.Groups.MinNameLength or longer than MaxNameLength. BlockedNames isn’t checked.

• The player doesn’t have to be on the channel yet. The group applies once they join.
• A group set by this export stays for the session, even when the player leaves and rejoins the channel.
• With locked set to true, the player can’t change or leave the group themselves. The radio shows “Assigned by dispatch”.
• It works whatever the channel’s Player Groups setting is, including “Off”.

GetPlayerGroup

local group, locked = exports["zerio-radio"]:GetPlayerGroup(source, frequency)

Returns the name of the player’s group on a channel and whether they’re locked in it, or nil when they’re in no group there.

SetPlayerGroupLocked

local success = exports["zerio-radio"]:SetPlayerGroupLocked(source, frequency, locked)

Locks or unlocks a player in the group they’re in on a channel. A locked group counts as set by a script, so it stays when they leave the channel. Returns false when they’re in no group there.

GetChannelGroups

local groups = exports["zerio-radio"]:GetChannelGroups(frequency)
-- { ["SWAT"] = { members = { 12, 31 }, identifiers = { "ABC12345", "XYZ67890" } } }

Returns the groups on a channel, keyed by group name. members are the server ids of the group’s members who are online. identifiers lists every member, including players set by a script who are offline or off the channel.

SetGroupColor

local success = exports["zerio-radio"]:SetGroupColor(frequency, "Busy", "red")
local success = exports["zerio-radio"]:SetGroupColor(frequency, "Busy", nil) -- default colour

Sets the colour of a group’s tag on a channel, in the member list, the overlay and the group picker. Use it to turn groups into statuses, for example “Available” in green and “Busy” in red. The colour is green, red, yellow, orange, blue, purple, gray, white or a hex colour such as "#ff8800". nil or "" goes back to the default colour.

The group doesn’t have to exist yet. The colour applies whenever a group with that name is on the channel, until the server restarts.

GetGroupColor

local color = exports["zerio-radio"]:GetGroupColor(frequency, "Busy")

Returns the colour set for a group on a channel, or nil when none is set.

Towers

These exports only change the running server. Use the admin menu for permanent changes.

AddTower

local id = exports["zerio-radio"]:AddTower({
  id = "event_relay",
  label = "Event relay truck",
  position = vector3(215.0, -810.0, 30.7),
  range = 800.0,
  power = 1.0,
})

Adds a tower until the next restart, for example a relay truck during an event. Returns its id, or nil when id or position is missing or the id is taken.

RemoveTower

local removed = exports["zerio-radio"]:RemoveTower(towerId)

Removes a tower until the next restart. It stays in the database.

SetTowerEnabled

local changed = exports["zerio-radio"]:SetTowerEnabled(towerId, enabled)

Turns a tower on or off until the next restart. A destroyed tower stays off until it’s repaired.

RepairTower

local repaired = exports["zerio-radio"]:RepairTower(towerId)

Restores a damaged or destroyed tower to full health.

GetTowers

local towers = exports["zerio-radio"]:GetTowers()

Returns every tower with id, label, position, range, power, frequencies, enabled, destructible, health, maxHealth and destroyed.

Jammers

PlaceJammer

-- A ground jammer
local id = exports["zerio-radio"]:PlaceJammer({
  position = vector3(215.0, -810.0, 30.7),
  jammerTypeId = "standard",
})
 
-- A personal jammer, which follows the player
local id = exports["zerio-radio"]:PlaceJammer({
  type = "personal",
  serverId = source,
})

Places a jammer and returns its id, or nil when it couldn’t, for example because Config.Jammers.maxActive jammers are already placed.

A player can carry one personal jammer at a time.

RemoveJammer

local removed = exports["zerio-radio"]:RemoveJammer(jammerId)

GetJammers

local jammers = exports["zerio-radio"]:GetJammers()

Returns every jammer with id, type, jammerTypeId, radius, power, frequencies and placedBy, plus position for ground jammers and serverId for personal ones.

PlayerHasActiveJammer

local hasJammer = exports["zerio-radio"]:PlayerHasActiveJammer(source)

Returns whether the player has placed a ground jammer or is carrying a personal one.

Repeaters

PlaceRepeater

local id = exports["zerio-radio"]:PlaceRepeater({
  position = vector3(215.0, -810.0, 30.7),
  typeId = "standard",
  range = 300.0,
})

Places a repeater and returns its id, or nil when it couldn’t. A repeater only works within the coverage of a tower.

RemoveRepeater

local removed = exports["zerio-radio"]:RemoveRepeater(repeaterId)

GetRepeaters

local repeaters = exports["zerio-radio"]:GetRepeaters()

Returns every repeater with id, repeaterTypeId, label, position, range, falloff, frequencies and placedBy.

PlayerHasActiveRepeater

local hasRepeater = exports["zerio-radio"]:PlayerHasActiveRepeater(source)

Battery

Battery exports need Config.Battery.Enabled, which is off by default.

GetPlayerBattery

local battery = exports["zerio-radio"]:GetPlayerBattery(source)

Returns the battery level of the player’s radio as a whole percentage from 0 to 100, or nil for a player who isn’t online. GetBattery(source) returns the same without rounding.

SetBattery

exports["zerio-radio"]:SetBattery(source, level)

Sets the battery level of the player’s radio, from 0 to 100. At 0 the player is removed from every channel, like with a dead battery.

Unit GPS

GPS only covers channels that have GPS turned on in the admin menu.

GetUnitPositions

local units = exports["zerio-radio"]:GetUnitPositions(frequency)

Returns the position of every member of a channel, for a map in an MDT or CAD. Each entry has:

Passengers aren’t listed separately: the driver’s position stands in for everyone in the vehicle.

GetUnitPosition

local unit = exports["zerio-radio"]:GetUnitPosition(source)

Returns the same entry for one player, or nil when they’re on no channel with GPS or haven’t reported a position yet.

Dispatch Console

These send to the hosted dispatch console. They need the voice server set up in configs/voice.lua and zerio_voice_admin_token set in your server.cfg.

DispatchNotify

exports["zerio-radio"]:DispatchNotify({
  title = "911 Call",
  body = "Shots fired at Grove Street",
  priority = "high",
  unit = "1-ADAM-12",
  channel = "911",
})

Shows a notification to every dispatcher. priority is "low", "medium" (default), "high" or "critical". "high" and "critical" play a sound. unit and channel are optional.

DispatchManDownStart

exports["zerio-radio"]:DispatchManDownStart({
  playerId = source,
  name = "John Doe",
  channel = "911",
  channelLabel = "Police",
  x = 215.0, y = -810.0, z = 30.7,
})

Shows a man-down alert to the dispatchers monitoring the channel, with a marker on their map. It stays until DispatchManDownClear clears it. zerio-radio’s own man-down feature already calls these.

DispatchManDownClear

exports["zerio-radio"]:DispatchManDownClear({ playerId = source })

Signal 100

While Signal 100 is active on a channel, players can’t talk on it and only dispatchers can. Players who press push-to-talk hear the busy tone, and anyone talking when it starts is cut off. Dispatchers start it from the dispatch console (Coming in full release); these exports start it from your own scripts. The channel needs Signal 100 turned on in the admin menu.

StartSignal100

local started, reason = exports["zerio-radio"]:StartSignal100(frequency, activatedBy)

Starts Signal 100 on a channel. activatedBy is the name players and dispatchers see, and defaults to "Dispatch".

Returns true, or false and a reason: "not_enabled" when the channel doesn’t allow Signal 100, "active_by_dispatch" when a dispatcher already started it, or "not_supported" when the voice server is too old for Signal 100. It waits for the voice server, so call it from a thread or an event handler.

While a script holds Signal 100, every dispatcher monitoring the channel can talk on it and end it.

EndSignal100

local ended = exports["zerio-radio"]:EndSignal100(frequency)

Ends Signal 100 on a channel, whoever started it. Returns true when it was active.

IsSignal100Active

local active = exports["zerio-radio"]:IsSignal100Active(frequency)

Returns whether Signal 100 is active on a channel. When a dispatcher starts or ends it, this can take up to 5 seconds to catch up.

Client-Side Exports

Open

exports["zerio-radio"]:Open()

Opens the radio. ox_inventory calls it as zerio-radio.Open when a radio item is used, passing the slot and the item so zerio-radio knows which radio was used.

OpenScanner

exports["zerio-radio"]:OpenScanner()

Opens the radio scanner.

HasAccess

local access = exports["zerio-radio"]:HasAccess(frequency)

Returns whether the local player may join a channel. It asks the server, so call it from a thread.

ChangeChannel

local changed = exports["zerio-radio"]:ChangeChannel(frequency)

Joins a channel and makes it the one the player talks on. Returns false for an invalid frequency or a dead player. The server still checks access, and shows the player an error when they don’t have it.

GetCallsign

local callsign = exports["zerio-radio"]:GetCallsign()

Returns the local player’s callsign, or an empty string when they have none.

SetCallsign

exports["zerio-radio"]:SetCallsign(callsign)

Sets the local player’s callsign and saves it. Players on the same channels see the new callsign straight away.

GetSignalStrength

local signal = exports["zerio-radio"]:GetSignalStrength()

Returns the local player’s best signal across the channels they’re on, from 0.0 to 1.0.

GetUnitBlips

local blips = exports["zerio-radio"]:GetUnitBlips()

Returns the GPS blips zerio-radio shows the local player, as { [serverId] = blip }.

Event List

Server

zerio-radio triggers these events on the server so your own resources can react to what happens on the radio. Listen to them with AddEventHandler:

AddEventHandler("zerio-radio:server:panicButtonPressed", function(source, frequency, coords)
  print(("%s pressed panic on %s at %s"):format(GetPlayerName(source), frequency, coords))
end)

When an event is about a player, they’re the first argument. Use it instead of the global source, which isn’t set for events triggered by the server.

playerJoinedChannel

AddEventHandler("zerio-radio:server:playerJoinedChannel", function(source, frequency, channelLabel) end)

Triggered when a player joins a channel, whether from the radio, through an export or when their channels are restored after a restart. Players can be on several channels at once, so you get one event per channel.

Locking onto a channel with the scanner doesn’t trigger it.

playerLeftChannel

AddEventHandler("zerio-radio:server:playerLeftChannel", function(source, frequency) end)

Triggered when a player leaves a channel. This includes leaving from the radio, turning the radio off, a dead battery, losing access to the channel and disconnecting. When a player leaves all their channels at once, you get one event per channel.

playerStartedTransmitting

AddEventHandler("zerio-radio:server:playerStartedTransmitting", function(source, frequency) end)

Triggered when a player starts talking on a channel. It’s only triggered once the server has accepted the transmission, so a player blocked by no-talk-over, Signal 100, a dead battery or missing access doesn’t trigger it.

playerStoppedTransmitting

AddEventHandler("zerio-radio:server:playerStoppedTransmitting", function(source, frequency) end)

Triggered when a player stops talking. If they leave the channel or disconnect mid-transmission, it’s triggered just before playerLeftChannel.

Each playerStartedTransmitting is followed by one playerStoppedTransmitting for the same frequency, even if the player switches channel while talking.

groupChanged

AddEventHandler("zerio-radio:server:groupChanged", function(source, frequency, newGroup, oldGroup) end)

Triggered when a player’s group on a channel changes, whether they picked it on the radio or a script set it with SetPlayerGroup. Also triggered when a group the player picked is dropped because they left the channel. Locking or unlocking a player without changing their group doesn’t trigger it.

panicButtonPressed

AddEventHandler("zerio-radio:server:panicButtonPressed", function(source, frequency, coords) end)

Triggered when a player presses the panic button on their radio. Presses within Config.PanicButtonCooldown are ignored, and nothing is triggered when Config.EnablePanicButton is false. When players open the radio with an item, they need a radio open to press it.

coords is read by the server, so the player can’t fake it.

dispatchAlert

AddEventHandler("zerio-radio:server:dispatchAlert", function(alert)
  print(alert.type, alert.source, alert.coords)
end)

One event for every alert a dispatch script should know about: a panic button press, or a man-down alert once the countdown runs out. Use it to connect a dispatch script zerio-radio doesn’t support out of the box.

The settings in configs/features/dispatch.lua decide which alerts also go to zerio-dispatch, ps-dispatch or lb-tablet. To send them to another script, edit Functions.SendDispatchAlert in server/functions.lua and client/functions.lua.

signalLost

AddEventHandler("zerio-radio:server:signalLost", function(source, frequency) end)

Triggered when a player’s signal on a channel drops to zero. With no signal they can’t transmit on the channel or hear it. Signal depends on towers, terrain, weather, jammers, repeaters, signal zones and battery, so this event never triggers when all of those features are turned off.

Triggered once per drop, and again only after the signal has come back.

signalRestored

AddEventHandler("zerio-radio:server:signalRestored", function(source, frequency) end)

Triggered when signal comes back on a channel after signalLost. If the player leaves the channel before it comes back, you get playerLeftChannel instead.

signal100Started

AddEventHandler("zerio-radio:server:signal100Started", function(frequency, activatedBy) end)

Triggered when Signal 100 starts on a channel, from the dispatch console (Coming in full release) or StartSignal100. When a dispatcher starts it, the event can arrive up to 5 seconds later.

signal100Ended

AddEventHandler("zerio-radio:server:signal100Ended", function(frequency) end)

Triggered when Signal 100 ends on a channel.

jammerPlaced

AddEventHandler("zerio-radio:server:jammerPlaced", function(source, position, jammer) end)

Triggered when a jammer is placed or a personal jammer is turned on, by a player, an admin or the PlaceJammer export.

The jammer table contains:

jammerRemoved

AddEventHandler("zerio-radio:server:jammerRemoved", function(id) end)

Triggered when a jammer is removed, whether it was picked up, destroyed, turned off, removed by an admin or the RemoveJammer export, or its owner disconnected.

repeaterPlaced

AddEventHandler("zerio-radio:server:repeaterPlaced", function(source, position, repeater) end)

repeaterRemoved

AddEventHandler("zerio-radio:server:repeaterRemoved", function(id) end)

Triggered when a repeater is removed, whether it was picked up, removed by an admin or the RemoveRepeater export, or its owner disconnected. id matches the one in repeaterPlaced.

Commands

The command names for opening the radio, the scanner, changing channel, callsigns and the admin menu can be changed in the config. See the Configuration Guide.