Examples and troubleshooting
Config examples
Section titled “Config examples”All of these go into config/config.lua. Change only the lines shown and keep the rest of the file as it is.
QBox with ox_inventory
Section titled “QBox with ox_inventory” Framework = 'qbox', Inventory = 'ox_inventory', Identifier = 'citizenid',Leaving both on 'auto' gives the same result when qbx_core and ox_inventory are running. Forcing them is useful when more than one framework or inventory resource is installed.
ESX with the ESX built-in inventory
Section titled “ESX with the ESX built-in inventory” Framework = 'esx', Inventory = 'esx',On ESX the identifier comes from ESX itself, so Identifier has no effect.
Shared progress for all characters of one account
Section titled “Shared progress for all characters of one account”On QBCore or QBox, progress is saved per character by default. To save it per account instead:
Identifier = 'license2',Choose this before launch. Changing it later makes players start again from zero.
Resets in your own time zone
Section titled “Resets in your own time zone”For a server in UTC+2, daily missions reset at 00:00 local time and weekly missions at 00:00 local time on Monday:
TimezoneOffsetHours = 2,Season dates are not affected. They stay in UTC, so use Unix timestamps in config/seasons.lua when you need exact local start and end times.
Quieter mission messages
Section titled “Quieter mission messages”Use ox_lib notifications, show no progress messages and no start instructions:
MissionGuidance = { NotificationMode = 'ox', NotificationDuration = 4500, InstructionNotificationDuration = 9000, ProgressNotificationMode = 'off', ShowStartInstructions = false, AllowMultipleTrackedMissions = false, },Let players track several missions
Section titled “Let players track several missions” MissionGuidance = { NotificationMode = 'kivo', NotificationDuration = 4500, InstructionNotificationDuration = 9000, ProgressNotificationMode = 'milestones', ShowStartInstructions = true, AllowMultipleTrackedMissions = true, },Store page and wording
Section titled “Store page and wording” PremiumPurchase = { Url = 'https://store.myserver.example/battlepass', Title = 'Go Premium', Description = 'Unlock the premium track and every reward on it.', BuyNowLabel = 'Open store', ExistingPurchaseLabel = 'Already paid?', CodeLabel = 'Transaction ID', CodePlaceholder = 'tbx-...', RedeemLabel = 'Activate', CodeHint = 'You find the transaction ID in your confirmation email.', },Vehicles on a server without a supported garage
Section titled “Vehicles on a server without a supported garage”If your garage script is not supported and you have not adapted the bridge, you can at least let players receive the vehicle in the world:
SpawnVehicleOnGrant = true,The vehicle spawns next to the player and is not saved to a garage. For a saved vehicle, see bridge/garage.lua.
Items used by the default rewards
Section titled “Items used by the default rewards”Every item named in config/rewards.lua must exist in your inventory. These are the item names, weapon names and vehicle models used by the shipped rewards. Check each against your inventory’s item list, and edit config/rewards.lua where a name differs on your server.
Free track items:
advancedlockpick, ammo-45, ammo-9, ammo-rifle, ammo-shotgun, armour, bandage,beer, binoculars, cleaningkit, coffee, copper, cryptostick, diamond_ring,diving_gear, drill, electronickit, firework1, firstaid, goldbar, goldchain,harness, ifaks, jerry_can, lighter, lockpick, medikit, nitrous, painkillers,parachute, phone, radio, repairkit, rolex, sandwich, screwdriverset,security_card_01, thermite, waterFree track weapons and vehicle:
WEAPON_BAT, WEAPON_CROWBAR, WEAPON_FIREEXTINGUISHER, WEAPON_FLASHLIGHT,WEAPON_HAMMER, WEAPON_KNIFE, WEAPON_PISTOL, WEAPON_WRENCHsultan (vehicle)Premium track items:
advancedrepairkit, aluminum, ammo-38, ammo-44, ammo-rifle2, ammo-sniper, armour,at_barrel, at_clip_drum_smg, at_clip_extended_pistol, at_clip_extended_rifle,at_flashlight, at_grip, at_muzzle_tactical, at_scope_holo, at_scope_medium,at_scope_nv, at_suppressor_heavy, black_money, burger, diving_fill, firework2,firework4, grapejuice, jammer, lawyerpass, radiocell, security_card_02, sprunk,trojan_usb, vodka, weaponlicense, whiskey, winePremium track weapons and vehicle:
WEAPON_CARBINERIFLE, WEAPON_COMBATPISTOL, WEAPON_FLAREGUN, WEAPON_HEAVYPISTOL,WEAPON_KNUCKLE, WEAPON_MACHETE, WEAPON_MICROSMG, WEAPON_PETROLCAN,WEAPON_PISTOL_MK2, WEAPON_PUMPSHOTGUN, WEAPON_REVOLVER, WEAPON_SNSPISTOL,WEAPON_SWITCHBLADE, WEAPON_VINTAGEPISTOLsultanrs (vehicle)Money rewards use the accounts cash (free tier 1) and bank (premium tier 1). The premium reward at tier 45 gives black_money as an item. If dirty money on your server is an account and not an item, replace that reward.
Common tasks
Section titled “Common tasks”Give Premium to a player without a purchase
Section titled “Give Premium to a player without a purchase”Run /kivobppremium 12 (player id 12), or use the Grant premium entry in /kivobpadmin. From your own script, use SetPremium.
Reward players from another script
Section titled “Reward players from another script”-- Server side, in your own resourceexports['kivo-battlepass']:AddXp(source, 100, 'heist finished')exports['kivo-battlepass']:AddMissionProgress(source, 'playTime', 1)See Exports and bridge files for what each call needs.
Open the Battle Pass from your own menu
Section titled “Open the Battle Pass from your own menu”-- Client sideexports['kivo-battlepass']:OpenUi()
-- Server sideexports['kivo-battlepass']:OpenUi(source)Look at the data
Section titled “Look at the data”These queries only read data. Run them in your database tool.
-- Premium players of a seasonSELECT identifier, tier, total_xpFROM kivo_bp_playersWHERE season_id = 'season-1' AND is_premium = 1;
-- Rewards one player has claimed in a seasonSELECT reward_id, claimed_atFROM kivo_bp_claimsWHERE identifier = 'ABC12345' AND season_id = 'season-1';
-- The latest redeemed purchase codes (codes are stored as hashes)SELECT provider, identifier, created_atFROM kivo_bp_redeemsORDER BY created_at DESCLIMIT 20;
-- Missions created with the quest creatorSELECT quest_id, period, quest_type, title, enabledFROM kivo_bp_custom_quests;Edge cases
Section titled “Edge cases”The season has ended or has not started
Section titled “The season has ended or has not started”Outside every season window the Battle Pass is frozen. Players see “This season is frozen. You can still claim leftover rewards.” and cannot claim current rewards. Add a new season in config/seasons.lua and restart the resource. See Seasons and rewards.
The shipped example season ends on 28.09.2026. A server that goes live after that date shows the frozen Battle Pass until the dates are updated.
A new season starts
Section titled “A new season starts”Add the new season at the end of Config.Seasons with a new id and restart before it starts. Player progress is stored per season id, so players begin the new season at tier 0. Unclaimed rewards of the old season can be kept as carryover. See Season rollover.
You change a reward after players claimed it
Section titled “You change a reward after players claimed it”Claims are saved under the reward id, for example free-12. Players who already claimed free-12 keep that claim, even when you change what tier 12 gives. They do not get the new reward. Players who have not claimed it get the new reward.
A reward item does not exist
Section titled “A reward item does not exist”The inventory refuses the item, so the claim fails and the reward is not marked as claimed. The player sees “Your inventory cannot hold this reward.” or “The reward could not be delivered. It was not marked claimed.” Fix the item name in config/rewards.lua, or add the item to your inventory. The player can then claim again. With Config.Debug = true, extra lines appear in the console.
The player’s inventory is full
Section titled “The player’s inventory is full”The claim is refused with “Your inventory cannot hold this reward.” and the reward stays unclaimed. The player frees space and claims again. When a player uses Claim All and only some rewards could be delivered, the player sees a message such as “Claimed 4 of 6 rewards.” and the rest stay open.
Framework mismatch
Section titled “Framework mismatch”- Auto detection finds nothing. The ready line in the console shows
noneas the framework, and players see “Your character is not loaded yet.” Start your framework beforekivo-battlepass. - You forced a framework that is not installed. The Battle Pass cannot read players from it. Set
Framework = 'auto'or the name of the framework you really run. - Two frameworks are installed. With
'auto',qbx_corewins overqb-core, andqb-corewins overes_extended. Force the one you want. - A framework that is not supported. Adapt
bridge/framework.lua. See Exports and bridge files.
Inventory mismatch
Section titled “Inventory mismatch”- If
Inventory = 'auto'picks the wrong resource, set the name yourself. - If you use an inventory that is not supported and name it in
Config.Inventory, item rewards go through your framework’s own add item function without a carry check. Adaptbridge/inventory.luafor a proper integration. See Support another inventory.
You change the identifier setting
Section titled “You change the identifier setting”Progress is stored under the identifier that Config.Identifier selected when the player first used the Battle Pass. Switching to another value makes the script look under the new identifier, so players start again from zero. The old rows stay in the database. Switch back to see the old progress again.
You rename a mission id
Section titled “You rename a mission id”Mission progress is stored under the mission id. After a rename, players lose their progress on that mission for the current day or week. Add a new mission instead of renaming one that players are working on.
You set maxTier above 50
Section titled “You set maxTier above 50”The shipped reward tables define tiers 1 to 50. Tiers above 50 have no reward until you extend the two tables and the loop at the bottom of config/rewards.lua.
Troubleshooting
Section titled “Troubleshooting”| Problem | Likely cause | What to do |
|---|---|---|
Nothing happens on F7 or /battlepass. |
The resource did not start, or the key is used by another script. | Read the console for errors on start. Check that ox_lib and oxmysql start first. Players can change the key in the GTA settings under Key Bindings, FiveM. |
| A change in the config has no effect. | Config files are read when the resource starts. | Run restart kivo-battlepass. |
| “Your character is not loaded yet.” | No framework was detected, or the player has no identifier. | Check the ready line in the console. See Framework mismatch. |
| “Your inventory cannot hold this reward.” | The inventory is full or the item does not exist. | Free space, or fix the item name in config/rewards.lua. |
| “The reward could not be delivered. It was not marked claimed.” | The money, item or vehicle could not be given. | Check the item or vehicle name, the Inventory setting and the garage table. Turn on Config.Debug. |
| Reward images are missing. | The file name is wrong, or ImagesBaseUrl points to the wrong place. |
File names are case sensitive. Check image and Config.ImagesBaseUrl. |
| A vehicle reward does not appear in the garage. | None of the garage options worked, or the garage script is not supported. | See Vehicle rewards. Adapt bridge/garage.lua for your garage script. |
| “Payment provider is not configured on this server.” | The secret convar for the provider is missing. | Add the set kivo_battlepass:tebex_secret ... or set kivo_battlepass:stripe_secret ... line to server.cfg and restart the server. |
| “Invalid code or payment id.” | The code is not a completed payment, or the secret belongs to another store. | Check that the payment is complete and that the secret matches the store that took the payment. |
| “Redemption service is unavailable. Try again later.” | The server could not reach the provider, or the answer could not be read. | Check that your server can make outgoing web requests, and try again. |
| “This code has already been redeemed.” | The code was used before. | Each code works once. Grant Premium by hand with /kivobppremium if needed. |
| “You do not have permission to do that.” | The player is not accepted as admin. | See Admin tools. |
| An admin command does nothing and the server console logs “Access denied for command”. | The player’s group is not a member of the admin permission. | Add add_principal group.admin kivo.battlepass.admin to server.cfg, using your own group. |
| Webhook messages do not arrive. | The convar is empty, or the address is wrong. | Set the convar in server.cfg. The values in Config.Webhooks must stay convar names, not web addresses. |
| Daily missions reset at the wrong hour. | TimezoneOffsetHours is not set for your time zone. |
Set it to your offset from UTC. |
| Play Time progress does not move. | The mission was not started, the player is AFK, or one step takes long. | Start the mission in the Battle Pass window. Keep moving. One step takes PlayTimeMinutes minutes unless the mission sets minutesPerTick. |
AddMissionProgress returns false. |
The player has not started a matching mission, or it is already claimed. | Only started missions that are not yet claimed advance. |
| Drunk Activities cannot be completed. | Your server has no drunk walking style effect. | See the note in Missions. |
| A new language does not show. | The locale file is not in fxmanifest.lua, or Config.Locale is wrong. |
See Add a language. |
The config stops with Season date "..." must be DD.MM.YYYY. |
A date string has the wrong format. | Write dates as DD.MM.YYYY, or use Unix timestamps. |
| The Battle Pass says the season is frozen. | No season window covers the current time. | Update config/seasons.lua and restart. |
