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.
Return values
Section titled “Return values”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.
Client exports
Section titled “Client exports”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) endend)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)Server exports
Section titled “Server exports”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' })endServer example, branch on the detected framework:
local framework = exports['kivo-inv-bridge']:GetFramework()
if framework == 'esx' then -- ESX only codeelseif framework == 'qbx' or framework == 'qb' then -- QB-Core or QBX codeelseif framework == 'ox' then -- OX Core codeendGuard your calls
Section titled “Guard your calls”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 0endIf 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.
What happens on an unsupported framework
Section titled “What happens on an unsupported framework”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.lualib.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.luaexports('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 }) endend)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) endend)Example: use your own profile pictures
Section titled “Example: use your own profile pictures”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.
Keep your changes
Section titled “Keep your changes”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.
