Installation Guide

This guide walks you through installing zerio-radio v3 on your FiveM server. If you are coming from v2, read Migrating from v2 first.

Prerequisites

Before installing, make sure you have:

• OneSync enabled
• oxmysql and ox_lib installed and started
• QBCore, Qbox or ESX, or no framework (standalone)
• If you use ox_inventory: version 2.47.0 or newer
• A voice server. During the beta you run it yourself: see Self-Hosting. You need the transaction ID and email of your zerio-radio purchase to get your licence.

Installation Steps

resources/
  └── [zerio]/
      ├── zerio-radio/
      └── zerio-radio-prop/

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

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

return {
    -- your existing items ...
 
    ['radio'] = {
        label = 'Radio',
        weight = 1000,
        stack = false,
        allowArmed = true,
        consume = 0,
        client = {
            export = 'zerio-radio.Open',
        }
    },
 
    ['radio_scanner'] = {
        label = 'Radio Scanner',
        weight = 1000,
        stack = false,
        close = true,
    },
 
    ['radio_jammer'] = {
        label = 'Radio Jammer',
        weight = 1000,
        stack = false,
        close = true,
    },
 
    ['mobile_radio_jammer'] = {
        label = 'Mobile Radio Jammer',
        weight = 1000,
        stack = false,
        close = true,
    },
 
    ['radio_repeater'] = {
        label = 'Radio Repeater',
        weight = 1000,
        stack = false,
        close = true,
    },
 
    ['radio_repair_kit'] = {
        label = 'Radio Repair Kit',
        weight = 500,
        stack = true,
        close = true,
    },
}

return {
    ['radio_battery'] = {
        label = 'Radio Battery',
        weight = 100,
        stack = false,
        close = true,
        consume = 0,
        server = {
            export = 'zerio-radio.UseBatteryItem',
        }
    },
}

QBShared.Items = {
    -- your existing items ...
 
    radio = {
        name = 'radio',
        label = 'Radio',
        weight = 1000,
        type = 'item',
        image = 'radio.png',
        unique = true,
        useable = true,
        shouldClose = false,
        description = 'A portable radio.'
    },
 
    radio_battery = {
        name = 'radio_battery',
        label = 'Radio Battery',
        weight = 100,
        type = 'item',
        image = 'radio_battery.png',
        unique = true,
        useable = true,
        shouldClose = true,
        description = 'Replacement battery for the radio.'
    },
 
    radio_scanner = {
        name = 'radio_scanner',
        label = 'Radio Scanner',
        weight = 1000,
        type = 'item',
        image = 'radio_scanner.png',
        unique = false,
        useable = true,
        shouldClose = true,
        description = 'Picks up nearby radio transmissions.'
    },
 
    radio_jammer = {
        name = 'radio_jammer',
        label = 'Radio Jammer',
        weight = 1000,
        type = 'item',
        image = 'radio_jammer.png',
        unique = false,
        useable = true,
        shouldClose = true,
        description = 'Disrupts radio signals in the area.'
    },
 
    mobile_radio_jammer = {
        name = 'mobile_radio_jammer',
        label = 'Mobile Radio Jammer',
        weight = 1000,
        type = 'item',
        image = 'mobile_radio_jammer.png',
        unique = false,
        useable = true,
        shouldClose = true,
        description = 'Portable radio jammer.'
    },
 
    radio_repeater = {
        name = 'radio_repeater',
        label = 'Radio Repeater',
        weight = 1000,
        type = 'item',
        image = 'radio_repeater.png',
        unique = false,
        useable = true,
        shouldClose = true,
        description = 'Boosts radio signal coverage in an area.'
    },
 
    radio_repair_kit = {
        name = 'radio_repair_kit',
        label = 'Radio Repair Kit',
        weight = 500,
        type = 'item',
        image = 'radio_repair_kit.png',
        unique = false,
        useable = false,
        shouldClose = true,
        description = 'Tools and parts to repair a radio tower.'
    },
}

INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
('radio',               'Radio',               1000, 0, 1),
('radio_battery',       'Radio Battery',        100, 0, 1),
('radio_scanner',       'Radio Scanner',       1000, 0, 1),
('radio_jammer',        'Radio Jammer',        1000, 0, 1),
('mobile_radio_jammer', 'Mobile Radio Jammer', 1000, 0, 1),
('radio_repeater',      'Radio Repeater',      1000, 0, 1),
('radio_repair_kit',    'Radio Repair Kit',     500, 0, 1);

Config.OpenType.Value = { "command", "keybind" }

add_ace group.admin zerio.admin allow
add_ace group.admin zerio.jammer allow
add_ace group.admin zerio.repeater allow

# Voice server token (set, not setr)
set zerio_voice_admin_token "your-token-from-the-setup-wizard"

# Dependencies
ensure oxmysql
ensure ox_lib

# Framework and inventory
ensure qb-core
ensure ox_inventory

# Optional
ensure ox_target

# Zerio Radio
ensure zerio-radio-prop
ensure zerio-radio

[zerio-radio:voice] loaded — voice server at https://eu.radio.zerio-scripts.com/s/my-rp-server

Commands and Keybinds

Commands

The command names for /radio, /radioscanner, /changeradio, /callsign and /radioadmin can be changed in the config. The jammer and repeater commands work on every framework, not only standalone.

Keybinds

Players can change every keybind in Settings → Key Bindings → FiveM. The default keys only apply to players who haven’t bound the keybind yet.

Upgrading from v2

Coming from v2? Your database upgrades itself on the first start, but your config has to be copied over by hand. Follow Migrating from v2.

Troubleshooting

Red “admin token missing” box in the console

Cause: The zerio_voice_admin_token convar is not set, is empty, or is still CHANGE_ME.

Solution:

• Add set zerio_voice_admin_token "<token>" to server.cfg, above ensure zerio-radio.
• Restart the server. Radio voice and dispatch stay off until the token is set.
• If you lost the token, sign in at portal.radio.zerio-scripts.com with your Server ID and portal email, and use Reset admin token in the account settings. Then put the new token in server.cfg.

Red “admin token REJECTED” box in the console

Cause: The voice server does not accept the token.

Solution:

• Check that you copied the whole token, inside the quotes.
• Check that you used set, not setr.
• Check that Domain and ServerId in configs/voice.lua belong to the same server the token was made for.
• Restart zerio-radio after changing server.cfg.

Red “voice admin API unreachable” box in the console

Cause: zerio-radio can’t reach the voice server at the address built from configs/voice.lua.

Solution:

• Check Domain: only the host, like eu.radio.zerio-scripts.com, with no https:// and no trailing slash.
• Check ServerId: it must match the Server ID you entered in the setup wizard.
• Check that your host’s firewall allows outgoing HTTPS connections.

Red “voice server is too old” or “this zerio-radio is unsupported” box in the console

Cause: zerio-radio checks the voice server’s version on start and every few seconds after that. “Voice server is too old” means the voice server is older than zerio-voice 1.0.0. “This zerio-radio is unsupported” means the voice server no longer supports your version of zerio-radio. Radio voice is off in both cases, and admins see a notice in game.

Solution:

• “Unsupported”: update zerio-radio to the version the box names, or newer.
• “Too old”: update the voice server. Hosted voice servers are kept up to date by Zerio, so contact support if you see this on a hosted region.
• Voice comes back on by itself once the check passes. The console then prints “Voice server version check passed, voice is back on”.

Yellow “stops working with the voice server on …” line in the console

Cause: Your version of zerio-radio is being phased out. It keeps working until the date in the message. Admins also see the notice in game, when it first appears and when they open /radioadmin.

Solution: Update zerio-radio to the version in the message, or newer, before that date.

Red “voice server licence not valid” box in the console

Cause: Only for a zerio-voice server you run yourself. The voice server has no valid licence, so it refuses radio voice. Channels, dispatch and everything else keep working. The box and the in-game notice to admins give the reason, for example no licence key set, an expired or revoked licence, or the licence already in use on the maximum number of servers.

Solution: Fix the licence key in the voice server’s config.json. Voice comes back on by itself once the licence is valid. Hosted regions never need a licence.

”Radio not connected — reconnecting” when pressing push-to-talk

Cause: The player’s connection to the voice server dropped. Pressing push-to-talk makes the radio reconnect straight away.

Solution: Wait a moment and try again. If it keeps happening for everyone, check the server console for one of the red boxes above.

”Radio audio isn’t working” when pressing push-to-talk

Cause: The radio’s audio engine didn’t start in the player’s game, so they can neither talk nor hear.

Solution: Have the player rejoin the server. If it keeps happening, contact support.

”Could not find dependency zerio-radio-prop”

Cause: zerio-radio-prop is missing, still inside the zerio-radio folder, or not started.

Solution:

• Move zerio-radio-prop out so it sits next to zerio-radio.
• Add ensure zerio-radio-prop above ensure zerio-radio.

”No signal — cannot transmit”

Cause: The player’s signal on the active channel is zero. Most often towers are enabled but there are no towers in the database. A jammer, a 0% signal zone or a dead battery also cause it.

Solution: See Why do players have no signal?

Using the radio item does nothing

Cause: The open type or the item definition doesn’t match your setup.

Solution:

• Check that Config.OpenType.Value in configs/opentype.lua is { "item" }.
• ox_inventory: check that the item has client = { export = 'zerio-radio.Open' }.
• QBCore: check that the item has useable = true.
• Check that the item name is a key in Config.OpenType.Items.

Players can’t hear each other

Cause: Voice is not connected, or the player’s microphone is not the one the radio uses.

Solution: See Players can’t hear each other on the radio.

”ox_inventory … has no post-hook events” warning

Cause: Your ox_inventory is older than 2.47.0.

Solution: Update ox_inventory. On older versions every copy of a radio item acts as one radio, and drops and gives are noticed late.

Need Help?

If you’re still having issues, join our community server and create a support ticket.