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.
Server exports
Section titled “Server exports”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 deliverylocal function payoutDelivery(src) -- your own payout code here exports['kivo-battlepass']:AddXp(src, 250, 'delivery job')endSetPremium
Section titled “SetPremium”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') endend, true)IsPremium
Section titled “IsPremium”local isPremium = exports['kivo-battlepass']:IsPremium(source)Returns true when the player has Premium and false otherwise.
GetProgress
Section titled “GetProgress”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.
OpenUi and CloseUi
Section titled “OpenUi and CloseUi”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.
AddMissionProgress
Section titled “AddMissionProgress”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)Client export
Section titled “Client export”exports['kivo-battlepass']:OpenUi()Opens the Battle Pass window for the local player. It takes no arguments.
Editing bridge and open files
Section titled “Editing bridge and open files”- Keep every function name, parameter list and return type. The rest of the resource calls them.
- The functions live on the
KivoBPtable. That table is only shared inside this resource, so other scripts cannot callKivoBPfunctions. 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. |
bridge/framework.lua
Section titled “bridge/framework.lua”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.
Support another framework
Section titled “Support another framework”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 nilend
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) == trueend
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'endAfter this change:
bridge/garage.luaonly knows the names'qbox','qbcore'and'esx'. For a different name, adapt the garage bridge too (seebridge/garage.lua). Otherwise vehicle rewards only work throughqbx_vehiclesor theSpawnVehicleOnGrantfallback.- The inventory bridge only falls back to the ESX inventory when the name is
'esx'. SetConfig.Inventoryto 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.endThen 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.
Change who counts as an admin
Section titled “Change who counts as an admin”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)endbridge/inventory.lua
Section titled “bridge/inventory.lua”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.
Support another inventory
Section titled “Support another inventory”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 endIn 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 endAddWeapon 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.
bridge/garage.lua
Section titled “bridge/garage.lua”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.
Support another garage script
Section titled “Support another garage script”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 endIf 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.
bridge/notify.lua
Section titled “bridge/notify.lua”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.
Use another notification system
Section titled “Use another notification system”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)endAfter this change, Config.MissionGuidance.NotificationMode no longer has an effect, because every message goes to your system.
open/rewards_custom.lua
Section titled “open/rewards_custom.lua”This file holds two functions that run on the server.
KivoBP.GrantCustom(source, grant)
Section titled “KivoBP.GrantCustom(source, grant)”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 falseendThe 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'))endopen/redeem.lua
Section titled “open/redeem.lua”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.
Add another payment provider
Section titled “Add another payment provider”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', payloadendThen add a branch at the start of verifyProvider:
if code:sub(1, 5) == 'shop-' then local status, payload = verifyMyStore(code) return status, payload, 'mystore' endAdd the secret to server.cfg with set my_store_secret "...".
open/admin.lua and open/admin_client.lua
Section titled “open/admin.lua and open/admin_client.lua”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.
