Skip to content

Frameworks and inventories

Kivo Radio needs only pma-voice to run. Your framework and your inventory matter for one feature: the radio earpiece. This page explains what is supported and what you can change.

The integration points described here are the config switches and the two item names in config/items.lua, and the two item button lines in the ox_inventory item entries on the Installation page.

Feature Needs
Radio interface, channels, job channels, locking, personalisation pma-voice
Proximity radio hearing pma-voice. No framework and no items.
Radio earpiece pma-voice, a supported framework, and the two items set up in your inventory.
Framework Resource Config.Framework value
QBX qbx_core "qbx"
QBCore qb-core "qb"
ESX es_extended "esx"

With Config.Framework = "auto" (the default) Kivo Radio checks for qbx_core first, then qb-core, then es_extended, and uses the first one that is running. Start your framework before Kivo Radio.

If no supported framework is found, the earpiece is not available. Everything else keeps working.

Inventory Mode Where the earpiece lives
ox_inventory (and Kivo Inventory, which is built on it) ox In the metadata of the radio item. One specific radio.
qb-inventory, qs-inventory, the default ESX inventory and similar fallback A saved flag for the player.

With Config.Inventory = "auto" (the default) Kivo Radio uses ox when ox_inventory is running and fallback otherwise. Start your inventory before Kivo Radio. If ox_inventory starts later, Kivo Radio uses the fallback until you set Config.Inventory = "ox".

Your setup Config.Framework Config.Inventory Add the items in
QBCore with qb-inventory "auto" "auto" qb-core/shared/items.lua
QBCore with ox_inventory "auto" "auto" ox_inventory/data/items.lua
QBX with ox_inventory "auto" "auto" ox_inventory/data/items.lua
ESX with the default inventory "auto" "auto" SQL items table
ESX with ox_inventory "auto" "auto" ox_inventory/data/items.lua
Any framework with qs-inventory or similar "auto" "auto" The item list of that inventory
No supported framework n/a n/a Earpiece not available

Edit config/items.lua, then restart kivo-radio.

-- use ESX even if another framework resource is also running
Config.Framework = "esx";
-- store the earpiece per player, even though ox_inventory is running
Config.Inventory = "fallback";

Typical reasons to override:

  • A compatibility layer makes two framework resources run at the same time, and detection picks the wrong one. Set Config.Framework to the one you actually use.
  • ox_inventory starts after Kivo Radio and you cannot change the order. Set Config.Inventory = "ox".
  • You prefer one earpiece per player instead of one per radio. Set Config.Inventory = "fallback".

Valid values are "auto", "qbx", "qb", "esx" for the framework and "auto", "ox", "fallback" for the inventory.

If you run a custom framework or no framework:

  1. Leave Config.Framework = "auto". The earpiece stays unavailable.
  2. Set Config.Items.enabled = false so the setup is explicit and the earpiece is not offered.
  3. Players can open the radio with /radio or /r, unless you turned those commands off (see Server convars).

Proximity hearing keeps working. Every radio can be overheard, because there is no earpiece to silence it. If you do not want that, set Config.RadioProximity.enabled = false as well.

Unsupported inventory on a supported framework

Section titled “Unsupported inventory on a supported framework”

If your framework is supported but your inventory is not named above:

  1. Leave Config.Inventory = "auto". Kivo Radio uses the per player mode.
  2. Add both items to your inventory under the names in Config.Items. Both must be usable, and they should not stack.
  3. Test with a player: give the player a radio and an earpiece, then use the earpiece item. The player should see a notification and the Earpiece row in the radio’s Settings tab should read FITTED.

If step 3 fails, check that both items are usable in your inventory and that the item names match config/items.lua. If it still fails, set Config.Items.enabled = false until your inventory is supported.

If your server already uses other names, for example handheld_radio, change the config and the inventory entries together.

Config.Items = {
enabled = true,
radio = "handheld_radio",
earpiece = "radio_earpiece",
openRadioOnUse = true,
cacheTtlMs = 10000,
};

Then rename the radio entry in your inventory to handheld_radio. The two TriggerServerEvent lines in the ox_inventory item buttons stay as they are. They do not contain the item name.

Shops, crafting and job scripts can give the radio and radio_earpiece items like any other item. Changes made by another script are noticed within Config.Items.cacheTtlMs (10 seconds by default). Lower that value if the delay matters on your server.

Kivo Radio uses pma-voice for the actual voice. Keep pma-voice up to date and start it before Kivo Radio. Proximity hearing uses the same mumble voice target as pma-voice for radio, which is 1 in an unmodified pma-voice. Only change voiceTargetId in config/proximity.lua if you run a modified pma-voice that uses a different target.