Installation
Follow these steps in order. Check the requirements first.
1. Copy the resource
Section titled “1. Copy the resource”-
Copy the resource folder into your server’s
resourcesdirectory. -
Make sure the folder is named exactly
kivo-battlepassand thatfxmanifest.luasits directly inside it:resources/[kivo]/kivo-battlepass/fxmanifest.lua
The name is fixed. The exports, the default image paths and the examples in these docs all use kivo-battlepass.
2. Prepare the database
Section titled “2. Prepare the database”Kivo Battlepass stores everything in MySQL through oxmysql. Make sure oxmysql is installed and its connection string is set in server.cfg:
set mysql_connection_string "mysql://user:password@localhost/database"The resource creates its tables automatically the first time it starts. You do not need to import anything.
If you prefer to create the tables yourself, import the SQL file shipped with the resource, sql/install.sql, into your database. It is safe to run more than once because every statement uses CREATE TABLE IF NOT EXISTS.
Contents of sql/install.sql
CREATE TABLE IF NOT EXISTS `kivo_bp_players` ( `identifier` VARCHAR(64) NOT NULL, `season_id` VARCHAR(64) NOT NULL, `tier` INT NOT NULL DEFAULT 0, `xp` INT NOT NULL DEFAULT 0, `total_xp` INT NOT NULL DEFAULT 0, `is_premium` TINYINT(1) NOT NULL DEFAULT 0, `playtime_seconds` INT NOT NULL DEFAULT 0, `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`identifier`, `season_id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE IF NOT EXISTS `kivo_bp_claims` ( `identifier` VARCHAR(64) NOT NULL, `season_id` VARCHAR(64) NOT NULL, `reward_id` VARCHAR(64) NOT NULL, `claimed_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`identifier`, `season_id`, `reward_id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE IF NOT EXISTS `kivo_bp_mission_progress` ( `identifier` VARCHAR(64) NOT NULL, `season_id` VARCHAR(64) NOT NULL, `mission_id` VARCHAR(64) NOT NULL, `period_key` VARCHAR(64) NOT NULL, `current` INT NOT NULL DEFAULT 0, `claimed` TINYINT(1) NOT NULL DEFAULT 0, `resets_at` BIGINT NOT NULL DEFAULT 0, PRIMARY KEY (`identifier`, `season_id`, `mission_id`, `period_key`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE IF NOT EXISTS `kivo_bp_carryover` ( `id` INT NOT NULL AUTO_INCREMENT, `identifier` VARCHAR(64) NOT NULL, `from_season` VARCHAR(64) NOT NULL, `reward_id` VARCHAR(64) NOT NULL, `grant_json` LONGTEXT NOT NULL, `claimed` TINYINT(1) NOT NULL DEFAULT 0, PRIMARY KEY (`id`), UNIQUE KEY `uniq_carryover` (`identifier`, `from_season`, `reward_id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE IF NOT EXISTS `kivo_bp_redeems` ( `code_hash` CHAR(64) NOT NULL, `provider` VARCHAR(16) NOT NULL, `identifier` VARCHAR(64) NOT NULL, `payload_json` LONGTEXT NULL, `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`code_hash`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE IF NOT EXISTS `kivo_bp_custom_quests` ( `id` INT NOT NULL AUTO_INCREMENT, `quest_id` VARCHAR(64) NOT NULL, `period` VARCHAR(16) NOT NULL, `quest_type` VARCHAR(32) NOT NULL, `title` VARCHAR(128) NOT NULL, `description` VARCHAR(512) NOT NULL, `required` INT NOT NULL DEFAULT 1, `xp_reward` INT NOT NULL DEFAULT 0, `params_json` LONGTEXT NOT NULL, `enabled` TINYINT(1) NOT NULL DEFAULT 1, `created_by` VARCHAR(64) NULL, `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uniq_custom_quest` (`quest_id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;What each table stores
Section titled “What each table stores”| Table | Contents |
|---|---|
kivo_bp_players |
One row per player and season: tier, current XP, total XP, premium flag and play time in seconds. |
kivo_bp_claims |
The tier rewards a player has claimed, per season. |
kivo_bp_mission_progress |
Mission progress per player, season, mission and day or week. Includes the claimed flag and the reset time in milliseconds. |
kivo_bp_carryover |
Rewards saved from an earlier season so the player can still claim them. See Seasons and rewards. |
kivo_bp_redeems |
Redeemed purchase codes. The code is stored as a hash, together with the provider and the player identifier. |
kivo_bp_custom_quests |
Missions created with the in-game quest creator. See Missions. |
Players are identified by the value that Config.Identifier selects (see Configuration). The identifier columns hold up to 64 characters.
3. Add the resource to server.cfg
Section titled “3. Add the resource to server.cfg”Start ox_lib and oxmysql first, then your framework and inventory, then the Battle Pass:
ensure ox_libensure oxmysqlensure qbx_core # or qb-core / es_extendedensure ox_inventory # or your inventoryensure kivo-battlepass4. Give admins permission
Section titled “4. Give admins permission”Admin commands and the admin menu use the ACE permission kivo.battlepass.admin. The name can be changed with Config.AdminAce. Add these lines to server.cfg (replace group.admin with your own group if needed):
add_ace group.admin kivo.battlepass.admin allowadd_principal group.admin kivo.battlepass.adminThe first line lets the group pass the admin check inside the script. The second line lets the group run the chat commands, which are registered through ox_lib with this ACE as their restriction.
The admin menu also accepts players who have the general command permission, QBCore and QBox players in the admin or god group, and ESX players in the admin or superadmin group. See Admin tools for all commands.
5. Set up premium purchases (optional)
Section titled “5. Set up premium purchases (optional)”Skip this step if you only grant premium by hand with /kivobppremium or from another script.
-
Open
config/config.luaand replaceConfig.PremiumPurchase.Urlwith the checkout page of your store. The Buy now button opens this page in the player’s default browser. -
Add the secret of the provider you use to
server.cfg. Add only the lines you need:set kivo_battlepass:tebex_secret "your-tebex-plugin-secret"set kivo_battlepass:stripe_secret "your-stripe-secret" -
Optionally add Discord webhooks for log messages:
set kivo_battlepass:webhook_redeem "https://discord.com/api/webhooks/..."set kivo_battlepass:webhook_claim "https://discord.com/api/webhooks/..."set kivo_battlepass:webhook_admin "https://discord.com/api/webhooks/..." -
Optionally add a Discord bot token to show Discord profile pictures:
set kivo_battlepass:discord_bot_token "your-discord-bot-token"
6. Adjust the config
Section titled “6. Adjust the config”At a minimum, check these before opening the server to players:
- Season dates. The example season in
config/seasons.luaruns from01.09.2026to28.09.2026. Change the dates to the period you want. Outside every season window the Battle Pass opens frozen and players cannot claim current rewards. See Seasons and rewards. - Reward items. Every item named in
config/rewards.luamust exist in your inventory. Remove or replace the ones that do not. See Examples and troubleshooting for the list used by the default rewards. - Purchase URL. Replace the example store URL.
- Language. Set
Config.Localeto'en'or'de'. - Framework and inventory. Leave both on
'auto'unless detection picks the wrong resource.
7. Restart and test
Section titled “7. Restart and test”- Restart the server, or run
ensure kivo-battlepassin the server console. - Check the console. When the resource is ready it prints a line that shows the detected framework and inventory, for example
qbox / ox_inventory. It showsnonefor anything it could not find. - Join the server, choose a character and press
F7or type/battlepass. - As an admin, run
/kivobpxp <your id> 500(use your own server id) to give yourself some XP and check that the tier bar moves. - Claim a free reward and check that it arrives in your inventory.
- Start a daily mission, finish it and claim its XP.
- If you sell premium, redeem a test purchase in the upgrade window.
Updating
Section titled “Updating”Config changes only take effect after restart kivo-battlepass. When you install a newer version of the resource, copy your edited files back into the new folder: config/, locales/, bridge/ and open/. Database tables are kept because the table statements only create missing tables.
Continue with Configuration.
