Configuration Guide

All of zerio-radio’s settings are Lua files in the configs/ folder. This guide explains every option and its default. Restart zerio-radio after you change a config file.

Channels, towers, signal zones, speakers and patches are not in the config files. They are stored in the database and managed in the in-game admin menu (/radioadmin).

Configuration Files Overview

Main Settings (configs/main.lua)

Language

Config.Locale = "en"

The language for notifications and command help. It must match a file in locales/. zerio-radio ships with en (English) and sv (Swedish). See Translations.

Radio Behaviour

Commands

Config.ChangeRadioChannelCommand = "changeradio"

The command that joins a frequency without opening the radio, for example /changeradio 911. Set it to nil or remove the line to remove the command.

Callsigns

Config.AllowCallSigns = true
Config.CallsignCommand = "callsign"

• AllowCallSigns: Lets players set a callsign that shows next to their name.
• CallsignCommand: The command to set a callsign, for example /callsign 1-ADAM-12. Set it to nil to remove the command. Players can still set a callsign in the radio.

Defaults for New Players

Config.DefaultTheme = "orange"
Config.DefaultSkin = "default"

• DefaultTheme: The theme new players start with. Must match an id in configs/themes.lua. If you remove it, the first theme in the list is used.
• DefaultSkin: The radio skin new players start with: "default", "sharp" or "rounded".

Players can change both in the radio’s settings.

Debug

Config.Debug = false
Config.DebugClient = false

• Debug: Prints server-side debug output to the server console.
• DebugClient: Always prints client-side debug output in every player’s F8 console. When false, a player can still turn it on for themselves in the radio’s settings.
• DebugMute: A list of debug areas to keep quiet while debug is on, for example "Signal" or "Weather".

Leave both false on a live server.

Voice Server (configs/voice.lua)

Config.VoiceServer = {
    Enabled = true,
    Domain = "eu.radio.zerio-scripts.com",
    ServerId = "my-rp-server",
    PortalUrl = "https://portal.radio.zerio-scripts.com",
}

The admin token is not in this file. It goes in server.cfg, with set and never setr:

set zerio_voice_admin_token "your-token-from-the-setup-wizard"

See Set Up the Voice Server for where to get these values.

Per-Environment Voice Server

If you run several environments (for example local, test and live) from the same files, set the voice server in each environment’s server.cfg instead of editing configs/voice.lua. The convars win over the config:

# Overrides Domain. Use setr: players' games need it to connect.
setr zerio_voice_domain "radio.example.com"

# Optional, server only. Sends zerio-radio's admin calls straight to the voice
# server instead of through Domain, for example when a reverse proxy only
# exposes the voice connection.
set zerio_voice_admin_url "http://127.0.0.1:30130"

ServerId still comes from configs/voice.lua and is added to both addresses.

Voice Server Version

zerio-radio checks the voice server’s version, and whether the voice server still supports your version of zerio-radio, on start and every few seconds after that. When either is too old, radio voice turns off and the console shows a red box until it is fixed. Admins also get a notice in game. When your version is being phased out, you get a yellow warning with the date it stops working. See Troubleshooting.

zerio-voice 1.1.0 or newer gives the clearest radio audio. With an older voice server, zerio-radio switches to a lower-quality audio mode by itself.

Themes (configs/themes.lua)

Config.Themes is the list of color themes players can pick in the radio’s settings. zerio-radio ships with eight: orange, midnight, emerald, slate, mono, gold, rose and teal. Remove the ones you don’t want, or add your own.

Colors are HSL values without the hsl() wrapper, for example "271 81% 56%". Only id, label and primary are required. Anything you leave out uses the built-in default. Here is a list with one custom theme; to keep the shipped themes, add your entry to the existing list instead:

Config.Themes = {
    {
        id = "purple",
        label = "Purple",
        primary = "271 81% 56%",
        primaryDark = "271 85% 64%",
        backgroundDark = "271 20% 7%",
        cardDark = "271 16% 11%",
    },
}

Gameplay (configs/gameplay.lua)

The two keybind options only set the default key for players who haven’t bound the keybind yet. Players change their keys in Settings → Key Bindings → FiveM.

Framework (configs/framework.lua)

This file detects your framework when the resource starts. You don’t need to edit it.

• qb-core or qbx_core running: QBCore mode (Qbox runs through its QBCore compatibility).
• es_extended running: ESX mode.
• Neither: standalone mode.

Admin Menu (configs/admin.lua)

Config.Admin = {
    command = "radioadmin",
    acePermission = "zerio.admin",
    qbcoreGroup = "admin",
    esxGroup = "admin",
    additionalCheck = nil,
}

A player is an admin when they have the ace in acePermission, the command ace (server owners usually have it), or the framework permission:

To give the ace, add it in server.cfg:

add_ace group.admin zerio.admin allow

Use additionalCheck to add your own condition on top, for example a staff duty or opt-in system:

additionalCheck = function(source)
    return exports.qbx_core:IsOptin(source)
end,

It applies to everyone who passes the permission check, including players with the ace.

Players who are not admins but have patch access (see Channel Patches) can also open the admin menu. They only see the Patches page.

Opening the Radio (configs/opentype.lua)

Open Types

Config.OpenType.Value = { "item" }
Config.OpenType.Keybind = "f5"
Config.OpenType.Command = "radio"

Config.OpenType.Value is a list of ways players can open the radio:

"command", "keybind" and "custom" can be combined, for example { "command", "keybind" }. "item" can’t be combined with anything: if you list "item" with other types, the others are ignored and a warning is printed. That keeps players from getting around the item requirement.

Radio Items and Codeplug Radios

Config.OpenType.Items lists every item that works as a radio. It is only used in item mode.

Config.OpenType.Items = {
    ["radio"] = {},
 
    ["police_radio"] = {
        label = "Police Radio",
        codeplug = {
            allowOtherChannels = false,
            channels = {
                { frequency = 911, label = "Police - Main" },
                { frequency = 921, label = "Police - Tactical" },
            },
        },
    },
}

Each key is an item name. Each item is its own radio: carrying an item does nothing until the player uses it. A player can have several radios open at once and hears all of them. Dropping one radio only disconnects the channels that radio joined.

A codeplug turns an item into a locked radio, like a department radio:

• A player using that item can only join the channels in its channels list.
• Those channels can only be joined by players using that item. The channel’s normal access rules (jobs and so on) are ignored for them.
• A plain radio can’t tune to those channels.
• Anyone who uses the item gets access, whatever their job. Only using the item counts, not carrying it.

Every item here must also exist in your inventory. See Add the Items.

Ambient Sound Capture (configs/audio/ambient.lua)

Nearby gunshots and aircraft are mixed into a player’s transmission while they talk.

All options are in Config.AmbientCapture.

Push-to-Talk Sounds (configs/audio/micclicks.lua)

Config.PTTAudioCues controls the clicks and squelch sounds around a transmission.

You can pick a different sound set per channel in /radioadmin (channel editor, “Mic Click Sound”).

Two more settings sit above Config.PTTAudioCues and apply to listen-only channels (channels you hear but can’t talk on):

Custom Sound Sets

Each sound set names four sounds. A sound name is a file in html/sounds/ without .ogg.

{
    id = "radio2",
    label = "Radio 2",
    txStart = "radio2_tx_start", -- you start transmitting
    txEnd = "radio2_tx_end",     -- you stop transmitting
    rxOpen = "radio2_rx_open",   -- someone else starts talking
    rxClose = nil,               -- someone else stops talking (nil = no sound)
}

To add one:

1. Put your .ogg files in html/sounds/, for example html/sounds/radio2_tx_start.ogg. The fxmanifest.lua already includes every .ogg in that folder.
2. Add the set to soundSets.
3. Restart zerio-radio and pick the set as defaultSoundSet or per channel.

Signal Quality (configs/audio/submix.lua)

These settings decide how a weak signal sounds. The signal itself comes from towers, jammers and the other features below.

General

Signal Degradation

Config.SignalDegradation:

breakingUp makes audio drop out in short bursts when signal is very low:

staticBurst plays a sound when a talker’s signal drops to zero (sound, default "static_burst") and when it comes back (reconnectSound, default "reconnect_click"). Set enabled = false to turn it off.

Quality Tiers

Config.SubmixTiers defines how the audio sounds at each signal level. This is advanced tuning; most servers leave it alone.

The default tiers are Excellent (0.80 and up), Good (0.60), Fair (0.40), Poor (0.20) and Dead (0.00).

Radio Towers (configs/features/towers.lua)

Towers give radio coverage. Each tower has a position, a range, a power and the frequencies it serves. You create towers in /radioadmin (Towers page), and sql/!data.sql adds nine examples. Channels with no tower nearby get defaultSignal.

Coverage

Destructible Towers

health lets players shoot or blow up tower masts. A damaged tower gives weaker signal, and a destroyed one gives none until it is repaired.

This only applies to towers that have their own prop and don’t use a world prop (the “world prop” option in the tower editor points at a mast that is already part of the map). Towers using a world prop can’t be destroyed.

In-Game Repair

health.repair lets a player walk up to a destroyed mast and repair it.

Panic Button (configs/features/panic.lua)

Config.EnablePanicButton = true
Config.PanicButtonCooldown = 5
 
Config.PanicAlertReceive = {
    Notify = true,
}

Players who receive a panic alert hear html/sounds/panic_alert.ogg and see a screen effect. Players can turn the screen effect off with the “Emergency Alerts” setting in the radio. To use your own sound, replace that file with your own .ogg file of the same name.

When unit GPS is on for the channel, the player’s blip also flashes (see FlashOnPanic in Unit GPS).

Every panic alert also shows up in the dispatch console (Coming in full release). To send it to zerio-dispatch, ps-dispatch or lb-tablet as well, see Dispatch Scripts.

Dispatch Scripts (configs/features/dispatch.lua)

Panic and man-down alerts always reach the dispatch console (Coming in full release). These settings also send them to a third-party dispatch script.

Config.DispatchAlerts = {
    Script = "auto",
    Jobs = { "police" },
    Alerts = {
        panic   = { Enabled = true, Code = "10-33" },
        mandown = { Enabled = false, Code = "10-99" },
    },
}

The alert is only sent once the server has accepted it, so the panic cooldown also applies to the dispatch script.

To support another dispatch script, edit Functions.SendDispatchAlert in server/functions.lua (for scripts that take alerts on the server) and client/functions.lua (for scripts that take alerts from the player’s client). Or listen to the dispatchAlert event from your own resource.

Radio Scanner (configs/features/scanner.lua)

The scanner lists active channels near the player and lets them lock on to listen.

Config.Scanner = {
    OpenType = "command",
    Item = "radio_scanner",
    Keybind = "f6",
    Command = "radioscanner",
    -- ...
}

Animations and Props (configs/features/animation.lua)

Config.Animation sets the radio prop in the player’s hand and the animations for opening the radio and talking.

Config.Animation = {
    OpenProp = {
        Model = GetHashKey("zerio_radio"),
        Bone = 28422,
        Offset = vector3(0.0, 0.0, 0.0),
        Rotation = vector3(90.0, 90.0, 0.0),
    },
 
    TalkProp = {
        Model = GetHashKey("zerio_radio"),
        Bone = 60309,
        Offset = vector3(0.05, 0.0, 0.015),
        Rotation = vector3(0.0, 90.0, -45.0),
    },
 
    OpenAnimation = {
        Normal = { Dictionary = "cellphone@", Name = "cellphone_text_in" },
        InCar = { Dictionary = "cellphone@in_car@ds", Name = "cellphone_text_in" },
    },
 
    TalkAnimation = {
        Name = "generic_radio_chatter",
        Dictionary = "random@arrests",
        StopSpeed = 1.0,
    },
 
    ClothingAnimations = {},
}

Remove a block (or set it to nil) to turn it off. The zerio_radio model comes from the zerio-radio-prop resource. Bone IDs are listed on the RAGE:MP wiki.

See Animations & Props in the FAQ for examples, including clothing-based animations.

Audio Leak (configs/features/audio-leak.lua)

Players standing near someone on the radio hear that radio’s audio from the world, unless the radio user wears an earpiece. All options are in Config.RadioLeak.

Earpieces

earpiece turns the leak off for players wearing an earpiece. Set earpiece.enabled = false to ignore earpieces.

• props: Earpiece props, as { component = 2, index = 2 }. component is the prop slot and index the prop drawable.
• drawables: Earpiece clothing, as { component = 8, drawable = 15 }.

Both accept an optional texture to match only one texture. Add the IDs of the earpieces on your server’s clothing packs.

Proximity Pickup

proximityPickup mixes the voices of nearby players into your transmission while you talk, so people around you can be heard on the radio.

Jammers (configs/features/jammers.lua)

Jammers lower or remove signal in an area. Ground jammers are placed in the world. Personal jammers are worn on the player’s back and move with them.

Ground Jammers

groundTypes is a list of ground jammer types. Using the item starts placement mode: a preview follows your crosshair and you confirm the spot. Add more entries for more tiers; each id must be unique.

Personal Jammers

personalTypes is a list of personal jammer types. Using the item turns it on or off.

A player can’t place a jammer while they have a repeater placed or are placing one, and the other way around.

Repeaters (configs/features/repeaters.lua)

Repeaters extend tower coverage. A repeater only works if it is placed somewhere that already has tower signal. Once active, it gives full signal at its position, fading out to its range. Players get whichever is stronger: the repeater or their own tower signal. Underground signal loss does not apply to repeater signal.

types is a list of repeater types:

Signal Zones (configs/features/cutoffzones.lua)

Config.CutoffZones = {
    enabled = true,
}

Signal zones are 3D areas that force the signal inside them to a set level, from 0% (tunnels, bunkers) to 100% (for example a building with its own coverage). The zone’s level replaces tower coverage, underground loss, repeaters and weather. Jammers and low battery still apply. When zones overlap, the smallest one wins.

You draw zones in /radioadmin on the Signal Zones page. They are saved in the database. enabled = false turns the feature off.

Underground Signal Loss (configs/features/occlusion.lua)

Lowers signal when the player is underground, for example in sewers, mines and tunnels. Ground-level interiors like police stations are not affected. All options are in Config.TerrainOcclusion.

It is checked again with every signal update (checkInterval in configs/features/towers.lua).

Weather (configs/features/weather.lua)

Lowers signal in bad weather. All options are in Config.WeatherEffects.

Default penalties: RAIN 0.08, THUNDER 0.28, BLIZZARD 0.18, SNOW 0.05, XMAS 0.05, SNOWLIGHT 0.03, SMOG 0.02, FOGGY 0.02, OVERCAST 0.01, and 0.0 for clear weather and HALLOWEEN.

Battery (configs/features/battery.lua)

The battery system is off by default. When on, radios drain while in use, and players swap batteries or charge at charging stations. A dead battery can’t open the radio, join channels or transmit.

Where the charge is stored:

• ox_inventory or QBCore, with the radio as an item: on the radio item. The charge stays with the item and shows on ox_inventory’s tooltip.
• ESX’s built-in inventory: in server memory for the session. Not shown on the item.
• Command, keybind or custom open type: one battery per player, in server memory.

If you use ox_inventory, add the radio_battery item with its server.export when you turn this on (see Add the Items).

Drain

Low Battery Signal Penalty

SignalPenalty weakens the signal as the battery runs low.

Between the two thresholds the multiplier goes linearly from LowMultiplier to CriticalMultiplier.

Charging Stations

Stations are places where players charge their radio. Players press E (or use the target option) to start charging, stay within the radius, and press E again or walk away to stop.

Locations = {
    { coords = vector3(441.5, -982.0, 30.7), radius = 2.0 },
    { coords = vector3(831.4, -1289.7, 27.9), radius = 3.0, chargePerSecond = 5.0 },
},

Channel Patches (configs/features/patches.lua)

A patch links two or more channels so players on one channel hear the others. Admins manage patches in /radioadmin on the Patches page. Patches made in the web dispatch panel (Coming in full release) are synced to the game when PortalUrl is set in configs/voice.lua.

Players allowed by DispatchJobs or AcePermissions open /radioadmin and only see the Patches page.

Man-Down (configs/features/mandown.lua)

When a player stays down while on a channel, the radio counts down on their screen and then sends an emergency alert to their channels. Other players see a banner and a flashing area on the map until the player recovers, leaves, or someone clears the alert.

Trigger values:

• "ragdoll": The player is ragdolled. Death systems that keep the player in a “downed” animation (like qb-ambulancejob or esx_ambulancejob) don’t count.
• "dead": The player is dead or in last stand according to the framework (QBCore last stand or dead, ESX dead), or dead by game natives on standalone.
• "either": Ragdolled or dead. The default.
• "stationary": The player hasn’t moved for the whole countdown.

Blip is the map marker other players see:

Unit GPS (configs/features/gps.lua)

Shows live map blips for the other players on your channels. Blips change shape by vehicle type and can flash on sirens and panic.

Speakers (configs/features/speakers.lua)

Speakers are PA speakers placed in the world. Admins place them in /radioadmin on the Speakers page and group them into stations. Speakers need OneSync.

Groups (configs/features/groups.lua)

Groups split the people on a channel into named groups, for example “SWAT”, “Traffic” or “Unit 4”. They are only for organising: the member list overlay shows them as headers (or as badges when it only shows who is talking), and the radio’s members page has a group picker. Groups never change who hears whom.

• A group belongs to one channel, and a player is in at most one group per channel.
• Groups last for the server session and are removed once their last member is gone.
• A group a player picked themselves is dropped when they leave the channel. A group a script assigned with SetPlayerGroup stays for the session, so the player is back in it when they rejoin.
• Scripts can lock a player in a group, so they can’t change it themselves, and give a group a colour with SetGroupColor, for example to use groups as statuses.
• Players can hide groups with the “Show Groups” setting in the radio.

Each channel also has a Player Groups setting in /radioadmin (channel editor):

Translations (locales/)

Texts are in locales/en.json and locales/sv.json. Config.Locale in configs/main.lua picks the file.

• The top-level keys in the JSON file are the in-game notifications and command help. You can edit them, and they change after a restart.
• The ui section is the text inside the radio itself. That text is built into the radio’s interface, so editing it in the JSON file changes nothing.

To add a language, copy en.json to a new file such as de.json, translate it and set Config.Locale = "de". Notifications and command help then use your file. The radio’s interface only has English and Swedish built in and shows English for other languages. Contact support if you want your translation added to the radio’s interface.