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.
What needs what
Section titled “What needs what”| 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. |
Supported frameworks
Section titled “Supported frameworks”| 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.
Supported inventories
Section titled “Supported inventories”| 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".
Which setup needs what
Section titled “Which setup needs what”| 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 |
Overriding detection
Section titled “Overriding detection”Edit config/items.lua, then restart kivo-radio.
-- use ESX even if another framework resource is also runningConfig.Framework = "esx";
-- store the earpiece per player, even though ox_inventory is runningConfig.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.Frameworkto the one you actually use. ox_inventorystarts after Kivo Radio and you cannot change the order. SetConfig.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.
Unsupported framework
Section titled “Unsupported framework”If you run a custom framework or no framework:
- Leave
Config.Framework = "auto". The earpiece stays unavailable. - Set
Config.Items.enabled = falseso the setup is explicit and the earpiece is not offered. - Players can open the radio with
/radioor/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:
- Leave
Config.Inventory = "auto". Kivo Radio uses the per player mode. - Add both items to your inventory under the names in
Config.Items. Both must be usable, and they should not stack. - 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.
Using other item names
Section titled “Using other item names”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.
Other scripts that give or take radios
Section titled “Other scripts that give or take radios”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.
pma-voice
Section titled “pma-voice”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.
