Skip to content

Exports and integration

The kivo-inv-bridge resource exposes a small set of read-only exports. The Kivo inventory interface uses the same data, and any other script on your server can read it too. There are client exports and server exports.

All examples use the resource name kivo-inv-bridge. If the resource is not started when you call an export, FiveM prints an error such as No such export GetPlayerBalances in resource kivo-inv-bridge. See Guard your calls.

Two table shapes are used by several exports:

Name Shape Notes
Balances { cash = number, bank = number } Both fields are always present. They are 0 when nothing is known.
Player info { name = string, id = number } name is the RP name when the framework provides one, otherwise the FiveM name. id is the character ID when the framework provides one, otherwise the server ID.

See Configuration for what each framework supplies.

Call these from client scripts. Functions that ask the server wait for the answer, so call them from a thread or an event, not in a loop that runs every frame.

Export Parameters Returns What it does
GetPlayerBalances() None Balances Asks the server for the current cash and bank. Returns { cash = 0, bank = 0 } if the server gives no answer. Also refreshes the value returned by GetCachedBalances.
GetCachedBalances() None Balances or nil The last result of GetPlayerBalances. nil if it was never called. Instant, no server request.
GetPlayerAvatar() None URL string or nil The player’s avatar URL. Returns the value already known on the client, or asks the server for the one it has stored. Never starts a new lookup. nil if there is no avatar (yet).
GetCachedAvatar() None URL string or nil The avatar URL already known on the client. Instant, no server request.
IsAvatarLoaded() None boolean true once the avatar lookup has finished for this player, even if no avatar was found.
GetPlayerInfo() None Player info Asks the server for the player’s name and ID. Returns { name = 'Unknown', id = 0 } if the server gives no answer. Also refreshes GetCachedPlayerInfo.
GetCachedPlayerInfo() None Player info or nil The last result of GetPlayerInfo. nil if it was never called. Instant, no server request.

Client example, a small HUD thread that shows the cash amount:

CreateThread(function()
while true do
local balances = exports['kivo-inv-bridge']:GetPlayerBalances()
SendNUIMessage({ action = 'setCash', cash = balances.cash })
Wait(5000)
end
end)

Client example, wait for the avatar and use it:

CreateThread(function()
local tries = 0
while not exports['kivo-inv-bridge']:IsAvatarLoaded() and tries < 20 do
Wait(500)
tries += 1
end
local avatar = exports['kivo-inv-bridge']:GetCachedAvatar()
print(avatar or 'No avatar, use your own default picture')
end)

Call these from server scripts. source is the player’s server ID (a number).

Export Parameters Returns What it does
GetPlayerBalances(source) source (number) Balances Current cash and bank of the player. { cash = 0, bank = 0 } if the player is not loaded or no framework was detected.
GetPlayerInfo(source) source (number) Player info RP name and ID of the player. Falls back to the FiveM name and the server ID.
GetPlayerAvatar(source) source (number) URL string or nil The avatar URL stored for the player. It never starts a lookup. nil while the lookup is still running, or if no avatar was found.
GetFramework() None 'esx', 'qbx', 'qb', 'ox' or nil The framework the bridge detected. nil if none was found, or if you call it in the first moments after the bridge starts.

Server example, print a summary for a player:

RegisterCommand('myinfo', function(source)
if source == 0 then return end
local info = exports['kivo-inv-bridge']:GetPlayerInfo(source)
local money = exports['kivo-inv-bridge']:GetPlayerBalances(source)
print(('%s (ID %s) has $%s cash and $%s in the bank'):format(
info.name, info.id, money.cash, money.bank
))
end, false)

Server example, send a Discord webhook message with the RP name and the avatar:

local WEBHOOK_URL = 'https://discord.com/api/webhooks/your-webhook'
local function sendLog(source, message)
local info = exports['kivo-inv-bridge']:GetPlayerInfo(source)
local avatar = exports['kivo-inv-bridge']:GetPlayerAvatar(source)
PerformHttpRequest(WEBHOOK_URL, function() end, 'POST', json.encode({
embeds = {{
title = info.name,
description = message,
thumbnail = avatar and { url = avatar } or nil,
}}
}), { ['Content-Type'] = 'application/json' })
end

Server example, branch on the detected framework:

local framework = exports['kivo-inv-bridge']:GetFramework()
if framework == 'esx' then
-- ESX only code
elseif framework == 'qbx' or framework == 'qb' then
-- QB-Core or QBX code
elseif framework == 'ox' then
-- OX Core code
end

Start the bridge before any script that calls it, and check that it is running before you call it. This keeps your script from throwing errors when the bridge is stopped or restarted:

local function bridgeStarted()
return GetResourceState('kivo-inv-bridge') == 'started'
end
local function getCash(source)
if not bridgeStarted() then return 0 end
local ok, balances = pcall(function()
return exports['kivo-inv-bridge']:GetPlayerBalances(source)
end)
return ok and balances and balances.cash or 0
end

If your resource cannot work without the bridge, you can also add it to your own fxmanifest.lua:

dependency 'kivo-inv-bridge'

Feed the interface from another framework or script

Section titled “Feed the interface from another framework or script”

The interface does not read your framework directly. It asks ox_inventory for three things through callbacks in ox_inventory/client.lua, and each callback asks the bridge. You can change where one of them gets its answer, for example to read money from a custom economy or to support a framework that the bridge does not know.

Callback in ox_inventory/client.lua Calls this bridge export The interface expects Sent when the bridge gives nothing
getBalances GetPlayerBalances() { cash = number, bank = number } { cash = 0, bank = 0 }
getPlayerInfo GetPlayerInfo() { name = string, id = number } false. The interface then shows the inventory label and the server ID.
getAvatar GetPlayerAvatar() An image URL string nil. The interface then shows the default picture.

The file also contains a fourth callback that the interface needs when it starts. Leave it exactly as it is.

If the bridge detects no framework, balances show 0, the name is the FiveM name and the ID is the server ID. Avatars still work. To show the real values, re-point the callbacks as shown below.

Example: read balances from a custom economy

Section titled “Example: read balances from a custom economy”

Say your own resource my_economy knows each player’s cash and bank. First give it a server callback and a client export that return the two numbers. The resource must load @ox_lib/init.lua as a shared script.

-- my_economy/server.lua
lib.callback.register('my_economy:getBalances', function(source)
-- Replace these two lines with your own lookups.
local cash = MyEconomy.GetCash(source)
local bank = MyEconomy.GetBank(source)
return { cash = cash, bank = bank }
end)
-- my_economy/client.lua
exports('GetBalances', function()
return lib.callback.await('my_economy:getBalances', false)
end)

Then open ox_inventory/client.lua and replace the existing getBalances callback (the block that starts with RegisterNUICallback('getBalances') with this one. Do not register the same callback twice.

RegisterNUICallback('getBalances', function(_, cb)
local ok, result = pcall(function()
return exports['my_economy']:GetBalances()
end)
if ok and type(result) == 'table' then
cb({ cash = result.cash or 0, bank = result.bank or 0 })
else
cb({ cash = 0, bank = 0 })
end
end)

Restart ox_inventory. The inventory now shows the numbers from my_economy. The interface shows amounts with a $ prefix. To change the symbol, see Rebuilding the interface.

Example: show the name and ID from a character script

Section titled “Example: show the name and ID from a character script”

Replace the getPlayerInfo callback the same way. Return false when you have nothing, so the interface falls back to the inventory label and the server ID.

RegisterNUICallback('getPlayerInfo', function(_, cb)
local ok, character = pcall(function()
return exports['my_characters']:GetActiveCharacter()
end)
if ok and character then
cb({
name = ('%s %s'):format(character.firstName, character.lastName),
id = character.id,
})
else
cb(false)
end
end)

Replace the getAvatar callback and return a full image URL, or nil for the default picture.

RegisterNUICallback('getAvatar', function(_, cb)
local ok, url = pcall(function()
return exports['my_profiles']:GetPictureUrl()
end)
cb(ok and url or nil)
end)

The player’s PC loads the picture, so the URL must be reachable from the internet and point straight to an image.

A new Kivo release replaces ox_inventory/client.lua. Keep a copy of your changed callbacks and paste them in again after you update. See Updating to a new Kivo release.