Skip to content

Installation

Follow these steps in order. Check the requirements first.

  1. Copy the resource folder into your server’s resources directory.

  2. Make sure the folder is named exactly kivo-battlepass and that fxmanifest.lua sits 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.

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;
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.

Start ox_lib and oxmysql first, then your framework and inventory, then the Battle Pass:

ensure ox_lib
ensure oxmysql
ensure qbx_core # or qb-core / es_extended
ensure ox_inventory # or your inventory
ensure kivo-battlepass

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 allow
add_principal group.admin kivo.battlepass.admin

The 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.

Skip this step if you only grant premium by hand with /kivobppremium or from another script.

  1. Open config/config.lua and replace Config.PremiumPurchase.Url with the checkout page of your store. The Buy now button opens this page in the player’s default browser.

  2. 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"
  3. 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/..."
  4. Optionally add a Discord bot token to show Discord profile pictures:

    set kivo_battlepass:discord_bot_token "your-discord-bot-token"

At a minimum, check these before opening the server to players:

  • Season dates. The example season in config/seasons.lua runs from 01.09.2026 to 28.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.lua must 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.Locale to 'en' or 'de'.
  • Framework and inventory. Leave both on 'auto' unless detection picks the wrong resource.
  1. Restart the server, or run ensure kivo-battlepass in the server console.
  2. 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 shows none for anything it could not find.
  3. Join the server, choose a character and press F7 or type /battlepass.
  4. 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.
  5. Claim a free reward and check that it arrives in your inventory.
  6. Start a daily mission, finish it and claim its XP.
  7. If you sell premium, redeem a test purchase in the upgrade window.

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.