Skip to content

Exports and bridge files

Kivo Battlepass offers three ways to connect it to the rest of your server:

  • Exports let other scripts add XP, grant Premium, add mission progress and open the Battle Pass.
  • Bridge files in bridge/ connect the Battle Pass to your framework, inventory, garage and notification system. Edit them to support something that is not built in.
  • Open files in open/ hold the custom reward code, the purchase code checks and the admin tools.

Call these from server scripts. source is always the player’s server id.

Export Returns
AddXp(source, amount, reason) true or false
SetPremium(source, isPremium, reason) true or false
IsPremium(source) true or false
GetProgress(source) table or nil
OpenUi(source) nothing
CloseUi(source) nothing
AddMissionProgress(source, questTypeOrId, amount) true or false
exports['kivo-battlepass']:AddXp(source, amount, reason)
Parameter Type Description
source number Player server id.
amount number XP to add. Must be a positive number. Decimals are rounded down.
reason string, optional Short text that says why the XP was given. It appears in the console when Config.Debug is on.

Returns true when the XP was added. Returns false when amount is not a positive number, or when the player’s Battle Pass data could not be loaded. XP can raise the player’s tier.

-- In another server script, after you paid out a delivery
local function payoutDelivery(src)
-- your own payout code here
exports['kivo-battlepass']:AddXp(src, 250, 'delivery job')
end
exports['kivo-battlepass']:SetPremium(source, isPremium, reason)
Parameter Type Description
source number Player server id.
isPremium boolean true gives Premium. Anything else removes it.
reason string, optional Short text that says why the change was made.

Returns true when the change was saved, false when the player’s data could not be loaded.

You can use this from your own store script. For example, a console-only command that a store package can run after a purchase:

RegisterCommand('givebattlepasspremium', function(source, args)
if source ~= 0 then
return
end
local target = tonumber(args[1])
if target then
exports['kivo-battlepass']:SetPremium(target, true, 'store')
end
end, true)
local isPremium = exports['kivo-battlepass']:IsPremium(source)

Returns true when the player has Premium and false otherwise.

local progress = exports['kivo-battlepass']:GetProgress(source)

Returns a table that describes the player’s current progress, or nil when the player’s data could not be loaded. Check for nil before you use it.

exports['kivo-battlepass']:OpenUi(source)
exports['kivo-battlepass']:CloseUi(source)

Opens or closes the Battle Pass window for one player. Use OpenUi to add a Battle Pass button to your own menu, phone or pause menu.

exports['kivo-battlepass']:AddMissionProgress(source, questTypeOrId, amount)
Parameter Type Description
source number Player server id.
questTypeOrId string A mission type such as 'playTime', or a mission id such as 'daily-1'.
amount number, optional Progress to add. Defaults to 1.

Returns true when at least one mission advanced and false otherwise.

Only missions that the player has started and not yet claimed advance. Progress never goes above the mission’s required value. Completing a mission shows the usual completion message.

exports['kivo-battlepass']:AddMissionProgress(source, 'playTime', 1)
exports['kivo-battlepass']:OpenUi()

Opens the Battle Pass window for the local player. It takes no arguments.

  • Keep every function name, parameter list and return type. The rest of the resource calls them.
  • The functions live on the KivoBP table. That table is only shared inside this resource, so other scripts cannot call KivoBP functions. They use the exports above.
  • Restart the resource after every change: restart kivo-battlepass.
  • Test with one reward of each type you use.
File Side Purpose
bridge/framework.lua server Player lookup, identifier, name, money and admin check.
bridge/inventory.lua server Carry check, add item and add weapon.
bridge/garage.lua server Saving vehicle rewards.
bridge/notify.lua client and server Notifications.
open/rewards_custom.lua server Code for custom rewards, and a hook for Peyote Time.
open/redeem.lua server Purchase code checks with Tebex and Stripe.
open/admin.lua server Admin commands and callbacks. See Admin tools.
open/admin_client.lua client The admin menu. See Admin tools.

Supports QBox, QBCore and ESX. It is loaded on the server only.

Function Returns Description
KivoBP.GetPlayer(source) player object or nil The framework’s own player object. Also used by the inventory and garage bridges.
KivoBP.GetIdentifier(source) string or nil The identifier progress is saved under. Follows Config.Identifier.
KivoBP.GetCitizenId(source) string or nil The citizenid on QBCore and QBox. Otherwise the same as GetIdentifier.
KivoBP.GetName(source) string The character name on QBCore, QBox and ESX. Otherwise the FiveM player name.
KivoBP.AddMoney(source, account, amount) boolean Adds money. account is 'cash' or 'bank'. Returns true when the money was added.
KivoBP.IsAdmin(source) boolean Whether the player may use the admin tools. See Admin tools.
KivoBP.GetFrameworkName() string or nil 'qbox', 'qbcore', 'esx', or nil when nothing was detected.

Detection uses Config.Framework. With 'auto' it picks the first running resource of qbx_core, qb-core, es_extended, in that order.

Replace the contents of bridge/framework.lua with versions of the seven functions that call your framework. This example uses a made-up framework called my_framework. Replace the export names with the ones your framework provides.

KivoBP = KivoBP or {}
function KivoBP.GetPlayer(source)
return exports['my_framework']:GetPlayer(source)
end
function KivoBP.GetIdentifier(source)
local player = KivoBP.GetPlayer(source)
return player and player.identifier or nil
end
function KivoBP.GetCitizenId(source)
return KivoBP.GetIdentifier(source)
end
function KivoBP.GetName(source)
local player = KivoBP.GetPlayer(source)
return player and player.name or GetPlayerName(source) or 'Player'
end
function KivoBP.AddMoney(source, account, amount)
if type(amount) ~= 'number' or amount <= 0 then
return false
end
local moneyType = account == 'bank' and 'bank' or 'cash'
return exports['my_framework']:AddMoney(source, moneyType, amount) == true
end
function KivoBP.IsAdmin(source)
if not source or source < 1 then
return false
end
return IsPlayerAceAllowed(source, Config.AdminAce) or IsPlayerAceAllowed(source, 'command')
end
function KivoBP.GetFrameworkName()
return 'my_framework'
end

After this change:

  • bridge/garage.lua only knows the names 'qbox', 'qbcore' and 'esx'. For a different name, adapt the garage bridge too (see bridge/garage.lua). Otherwise vehicle rewards only work through qbx_vehicles or the SpawnVehicleOnGrant fallback.
  • The inventory bridge only falls back to the ESX inventory when the name is 'esx'. Set Config.Inventory to your inventory instead of 'auto'.

Pay money through a banking script or add a currency

Section titled “Pay money through a banking script or add a currency”

AddMoney receives the account value from the reward. The shipped code treats 'bank' as bank money and every other value as cash. To send bank rewards to a banking script, or to add a new currency, add a branch at the start of the function, right after the amount check. Leave the rest of the function as it is.

function KivoBP.AddMoney(source, account, amount)
if type(amount) ~= 'number' or amount <= 0 then
return false
end
-- New: a custom currency called 'coins'
if account == 'coins' then
local ok, result = pcall(function()
return exports['your-coins']:AddCoins(source, amount)
end)
return ok and result == true
end
-- New: send bank rewards to a banking script
if account == 'bank' and GetResourceState('your-banking') == 'started' then
local ok = pcall(function()
exports['your-banking']:AddBankMoney(source, amount, 'kivo-battlepass')
end)
return ok
end
-- The original code for cash and bank continues here.
end

Then use the new account name in config/rewards.lua:

[10] = { type = 'account', account = 'coins', amount = 500, name = 'Coins', image = 'money.png' },

The export names above are placeholders. Use the names from your coins or banking script.

Edit KivoBP.IsAdmin. For example, to accept only the ACE and nothing else:

function KivoBP.IsAdmin(source)
if not source or source < 1 then
return false
end
return IsPlayerAceAllowed(source, Config.AdminAce)
end

Supports ox_inventory, qb-inventory, ps-inventory, qs-inventory and the ESX built-in inventory. It is loaded on the server only.

Function Returns Description
KivoBP.CanCarryItem(source, item, amount, metadata) boolean Whether the player has room for the item.
KivoBP.AddItem(source, item, amount, metadata) boolean Adds an item. It checks CanCarryItem first and returns false when the item does not fit.
KivoBP.AddWeapon(source, weapon, amount, metadata) boolean Adds a weapon. It tries AddItem with the weapon name first. On ESX it then falls back to the framework’s addWeapon with 30 rounds.
KivoBP.GetInventoryName() string or nil The inventory in use.

The built-in inventories are called like this:

Inventory Carry check Add item
ox_inventory CanCarryItem(source, item, count, metadata) AddItem(source, item, count, metadata)
qb-inventory CanAddItem(source, item, count) AddItem(source, item, count, false, metadata, 'kivo-battlepass')
ps-inventory CanAddItem(source, item, count) AddItem(source, item, count, false, metadata, 'kivo-battlepass')
qs-inventory CanCarryItem(source, item, count) AddItem(source, item, count, nil, metadata)
esx the player’s canCarryItem(item, count) the player’s addInventoryItem(item, count)

Detection uses Config.Inventory. With 'auto' it picks the first running resource of ox_inventory, qb-inventory, ps-inventory, qs-inventory, in that order, and then falls back to the ESX inventory on ESX servers.

Add a block for your inventory to CanCarryItem and to AddItem. Place each block next to the blocks of the built-in inventories, before the fallback code at the end of the function. Then set Config.Inventory = 'your-inventory' so the bridge uses it. The export names below are placeholders. Use the names from your inventory’s documentation.

In KivoBP.CanCarryItem:

if inventory == 'your-inventory' then
local ok, canAdd = pcall(function()
return exports['your-inventory']:CanCarry(source, item, count)
end)
return ok and canAdd == true
end

In KivoBP.AddItem:

if inventory == 'your-inventory' then
local ok, success = pcall(function()
return exports['your-inventory']:GiveItem(source, item, count, metadata)
end)
return ok and success == true
end

AddWeapon needs no change if your inventory treats weapons as items. If it does not, add a block to AddWeapon that calls your inventory’s weapon function and returns true on success.

If you do not add a block and Config.Inventory names an unknown inventory, item rewards fall back to the add item function of your framework, without a carry check.

Saves vehicle rewards. It is loaded on the server only.

Function Returns Description
KivoBP.GrantVehicle(source, model) true, plate or false Saves a vehicle with the given spawn name for the player. Returns true and the plate on success.

The shipped bridge tries qbx_vehicles, then the player_vehicles table (QBCore and QBox), then the owned_vehicles table (ESX), and finally spawns the vehicle when Config.SpawnVehicleOnGrant is true. See Vehicle rewards.

Add a block inside KivoBP.GrantVehicle, right after the plate and garage variables are set and before the qbx_vehicles check. It must return true, plate when the vehicle was saved, so that the claim counts. The export name is a placeholder.

if GetResourceState('your-garage') == 'started' then
local ok, saved = pcall(function()
return exports['your-garage']:AddVehicleToGarage(source, model, plate, garage)
end)
if ok and saved then
return true, plate
end
end

If this block returns nothing, the shipped options run next. If you want to use only your garage script, return false at the end of the block when the save failed.

Sends notifications. It is loaded on both the client and the server.

Function Side Description
KivoBP.Notify(source, message, nType) both Shows a message. On the server it sends the message to the player source. On the client source is ignored. nType is 'info', 'success' or 'error' and defaults to 'info'.
KivoBP.MissionNotify(source, payload) both Shows a mission message. payload is a table with message (required), title, type and duration in milliseconds.

The file also registers two client events that the server uses to reach the player: kivo-battlepass:client:notify with (message, nType), and kivo-battlepass:client:missionNotify with (payload).

The general notification uses ox_lib when it is running, and the GTA feed otherwise. Mission messages follow Config.MissionGuidance.NotificationMode.

Replace the body of the two local functions near the top of the file. Keep their names. The export name is a placeholder.

local function notifyClient(message, nType)
exports['your-notify']:Notify(message, nType or 'info')
end
local function missionNotifyClient(payload)
exports['your-notify']:Notify(payload.message, payload.type or 'info', payload.duration)
end

After this change, Config.MissionGuidance.NotificationMode no longer has an effect, because every message goes to your system.

This file holds two functions that run on the server.

Runs when a player claims a reward with type = 'custom'. Return true when the reward was delivered, and false when it was not. A false result keeps the reward unclaimed so the player can try again.

grant is the reward entry. It has the fields id (for example 'free-7'), level, track ('free' or 'premium'), name, image, isFeatured, type, amount, item, account, model and metadata. Fields you add to a reward entry in config/rewards.lua that are not in this list do not reach the function. Put your identifier into item.

The shipped version tries to add grant.item as a normal item and then returns true in every case. That means a custom reward counts as claimed even when the item could not be added. Return false when delivery fails.

Example: a custom reward that gives a housing voucher through another script, and falls back to a normal item for every other custom reward. The export name is a placeholder.

function KivoBP.GrantCustom(source, grant)
if grant.item == 'house_voucher' then
local ok, result = pcall(function()
return exports['your-housing']:GiveVoucher(source, grant.amount or 1)
end)
return ok and result == true
end
if grant.item and grant.item ~= '' then
return KivoBP.AddItem(source, grant.item, grant.amount or 1, grant.metadata)
end
return false
end

The matching entry in config/rewards.lua:

[15] = { type = 'custom', item = 'house_voucher', amount = 1, name = 'House Voucher', image = 'certificate.png' },

KivoBP.OnPeyoteTransformed(source, animal)

Section titled “KivoBP.OnPeyoteTransformed(source, animal)”

A hook that is called on the server when a player is turned into an animal during the Peyote Time mission. source is the player’s server id and animal is the name of the ped model. The shipped version only prints a debug line. Add your own code to it, for example to apply an effect or to log the event.

function KivoBP.OnPeyoteTransformed(source, animal)
print(('Player %s became %s'):format(source, animal or 'an animal'))
end

Checks purchase codes with Tebex and Stripe. See How code redemption works for the player side.

The file defines these helper functions near the top, which you can use in your own checks:

Helper Description
getConvarSecret(name) Returns the value of a convar, or nil when it is empty.
httpGet(url, headers) Sends a GET request and returns a table with status and body.
parseJson(body) Decodes a JSON string and returns a table, or nil when it cannot be decoded.

Each provider check returns up to two values:

First value Meaning
'success' The payment exists and is complete. The second value is the provider’s response table.
'invalid' The code is not a completed payment. The player sees “Invalid code or payment id.”
'error' The check could not be done. With the second value 'missing_secret' the player sees “Payment provider is not configured on this server.” Any other second value shows “Redemption service is unavailable. Try again later.”

verifyProvider(code) chooses the provider and returns three values: the status, the second value, and a provider name. The provider name is stored in the kivo_bp_redeems table and can be at most 16 characters.

Codes are converted to lowercase before they reach these functions, so compare against lowercase prefixes.

Write a check function that follows the same return values, and call it from verifyProvider. This example uses a made-up store API. Replace the URL, the convar name and the response fields with those of your provider.

Add the check function above verifyProvider:

local function verifyMyStore(code)
local secret = getConvarSecret('my_store_secret')
if not secret then
return 'error', 'missing_secret'
end
local response = httpGet(('https://store.example.com/api/orders/%s'):format(code), {
['Authorization'] = 'Bearer ' .. secret,
})
if not response or response.status == 0 then
return 'error', 'http'
end
if response.status == 404 then
return 'invalid', 'not_found'
end
if response.status ~= 200 then
return 'error', 'http'
end
local payload = parseJson(response.body)
if not payload then
return 'error', 'decode'
end
if payload.status ~= 'paid' then
return 'invalid', payload.status
end
return 'success', payload
end

Then add a branch at the start of verifyProvider:

if code:sub(1, 5) == 'shop-' then
local status, payload = verifyMyStore(code)
return status, payload, 'mystore'
end

Add the secret to server.cfg with set my_store_secret "...".

These two files hold the admin commands, the admin menu and the two callbacks behind it. They are described on the Admin tools page, including how to call the callbacks from your own admin menu.

Next: Examples and troubleshooting.