Skip to content

Configuration

Kivo Battlepass is configured with plain Lua files. Edit them in any text editor and run restart kivo-battlepass to apply the changes.

File What it holds
config/config.lua General options, mission guidance, sounds, the premium purchase window, webhooks and convar names. Described on this page.
config/seasons.lua Season list. See Seasons and rewards.
config/rewards.lua The free and premium reward for each tier. See Seasons and rewards.
config/rewards_types.lua The names of the reward types. Leave this file unchanged.
config/quests.lua The built-in daily and weekly missions. See Missions.
locales/en.lua, locales/de.lua, locales/locale.lua Text shown to players and admins. See Locales.
sql/install.sql Database tables. See Installation.
bridge/*.lua Adapters for the framework, inventory, garage and notifications. See Exports and bridge files.
open/*.lua Custom reward code, purchase code checks and admin tools. See Exports and bridge files.

All options below are in config/config.lua.

Option Default Description
Debug false Prints extra diagnostic lines to the server console, for example when a custom reward is granted or a qbx_vehicles grant fails.
Locale 'en' Language of script messages. 'en' and 'de' are included. See Locales.
Command 'battlepass' Chat command that opens the Battle Pass, written without the slash.
Keybind 'F7' Default key that opens the Battle Pass.
OpenOnJoin false When true, the Battle Pass opens automatically for a player after they join.
Framework 'auto' Framework to use. See Framework.
Inventory 'auto' Inventory to use. See Inventory.
Identifier 'citizenid' Which player identifier progress is stored under. See Identifier.
TimezoneOffsetHours 0 Hours added to UTC when working out the daily and weekly mission reset. For example 2 for UTC+2 or -5 for UTC-5. See Time zone.
ClaimAllPopupEnabled true Turns the Claim All popup on or off. Admins can flip it while the server runs with /kivobppopup. The change lasts until the resource restarts, then this value applies again.
PlayTimeMinutes 10 Minutes of active play that count as one progress step for Play Time missions. A mission can set its own value with minutesPerTick.
AfkTimeoutMs 120000 Milliseconds without movement before a player counts as AFK. AFK time does not count toward Play Time missions.
MaxRedeemLength 64 Longest purchase code a player may enter. Longer input is refused with “That code is too long.”
RedeemCooldownMs 2500 Minimum time in milliseconds between two code redemption attempts from the same player.
ClaimCooldownMs 750 Minimum time in milliseconds between two reward claims from the same player. Faster clicks show “You are claiming too quickly.”
MugshotEnabled false When true, the Battle Pass tries to show a mugshot of the player’s character as the avatar. When false, the default avatar is used.
DefaultAvatarUrl 'nui://kivo-battlepass/web/images/avatar.png' Avatar shown when no other avatar is available.
ImagesBaseUrl 'nui://kivo-battlepass/web/images/' Base URL for reward images. The image file name of each reward is added to this URL.
ObjectStreamDistance 80.0 Distance in meters at which mission objects (Object Hunt, Peyote Time and Yoga props) appear for the player.
ObjectSearchRadius 90.0 Radius in meters of the search area shown on the map after a player pins an Object Hunt mission. The object itself only appears when the player is close enough to find it.
PeyoteSearchRadius 70.0 Radius in meters of the search area shown on the map for Peyote Time missions.
ObjectRevealDistance 35.0 Distance in meters at which the exact marker of an Object Hunt item appears.
SpawnVehicleOnGrant false Fallback for vehicle rewards. See Vehicle rewards.
DefaultGarage 'pillboxgarage' Garage name used when a vehicle reward is saved for QBCore or QBox. See Vehicle rewards.
AdminAce 'kivo.battlepass.admin' ACE permission that admin commands and the admin menu check. See Admin tools.
Value Meaning
'auto' Uses the first running resource from this list: qbx_core, qb-core, es_extended.
'qbox' Forces QBox (qbx_core).
'qbcore' Forces QBCore (qb-core).
'esx' Forces ESX (es_extended).

Any other value is treated like 'auto'. Only force a framework that is installed and running. If the forced framework is not running, players cannot be loaded and see “Your character is not loaded yet.”

Value Meaning
'auto' Uses the first running resource from this list: ox_inventory, qb-inventory, ps-inventory, qs-inventory. If none runs and the framework is ESX, the ESX built-in inventory is used.
'ox_inventory' Forces ox_inventory.
'qb-inventory' Forces qb-inventory.
'ps-inventory' Forces ps-inventory.
'qs-inventory' Forces qs-inventory.
'esx' Uses the ESX built-in inventory functions.

If you enter a name the script does not know, item rewards fall back to the add item function of your framework, without a capacity check. To support another inventory properly, see Exports and bridge files.

Progress, claims and missions are saved under one identifier per player.

Value Meaning
'citizenid' QBCore and QBox: the character’s citizenid. Every character has separate progress.
'license2' QBCore and QBox: the account’s license2. All characters of one account share progress.
'license' QBCore and QBox: the account’s license. All characters of one account share progress.

On ESX the identifier that ESX returns for the player is always used, whatever this option says. If no identifier can be found, the script falls back to the player’s license2, then license.

TimezoneOffsetHours moves the moment when missions reset. Daily missions reset at midnight and weekly missions at midnight at the start of Monday, in the time zone you set. Season start and end dates are not affected: they are always read as UTC (see Seasons).

When a player claims a vehicle reward, the script tries these options in order and stops at the first that works:

  1. If qbx_vehicles is running, the vehicle is created with it in the garage named by DefaultGarage.
  2. On QBCore and QBox, a row is added to the player_vehicles table, using DefaultGarage as the garage.
  3. On ESX, a row is added to the owned_vehicles table. DefaultGarage is not used on ESX.
  4. If none of the above worked and SpawnVehicleOnGrant is true, the vehicle is spawned next to the player with the same plate. It is not saved to a garage.

If every option fails, the claim fails and the reward stays unclaimed. Plates start with KIVO followed by four random letters or digits. To save vehicles through another garage script, see Exports and bridge files.

The key is registered as a FiveM key mapping. FiveM only uses Keybind as the default for players who have not set a key yet. Players who already have a key can change it in the GTA settings under Key Bindings, FiveM. Changing Keybind later does not move their existing key.

Settings in the MissionGuidance block control how mission messages appear. Mission messages replace the current Battle Pass message instead of stacking.

Option Default Description
NotificationMode 'kivo' 'kivo' uses the built-in Kivo toast. 'ox' uses an ox_lib notification. 'auto' uses ox_lib when it is available.
NotificationDuration 4500 How long normal mission messages stay on screen, in milliseconds.
InstructionNotificationDuration 9000 How long the “how it works” message stays on screen when a mission starts, in milliseconds.
ProgressNotificationMode 'milestones' 'off' shows no progress messages. 'milestones' shows a message at the first progress and at the halfway point. 'all' shows a message after every progress step.
ShowStartInstructions true Shows the “how it works” message when a player starts a mission.
AllowMultipleTrackedMissions false When false, a player can track one mission at a time. When true, several missions can be tracked together.

Settings in the UiFeedback block control the sounds in the Battle Pass window.

Option Default Description
SoundVolume 0.42 Volume of the interface sounds, from 0.0 (silent) to 1.0 (full volume).
Sounds.LevelUp 'sounds/lvbel-c5-sezen-aksu.mp3' Sound played when a player reaches a new tier.
Sounds.MissionClaim 'sounds/universfield-level-up-05-326133.mp3' Sound played when a player claims mission XP.

The sound paths are relative to web/index.html, so the default files live in the web/sounds folder. To use your own sound, copy an audio file into that folder and enter its path, for example 'sounds/my-level-up.mp3'. No interface changes are needed.

Settings in the PremiumPurchase block control the upgrade window. Every label can be rewritten or translated.

Option Default Description
Url 'https://your-store.example.com/battlepass' Page that the Buy now button opens in the player’s default browser. Replace the example URL.
Title 'Unlock Premium' Heading of the window.
Description 'Get the Premium Battle Pass and earn rewards from both tracks.' Text under the heading.
BuyNowLabel 'Buy now' Label of the Buy now button.
ExistingPurchaseLabel 'Already bought Premium?' Label for players who already bought Premium and want to enter their code.
CodeLabel 'Enter your purchase code' Label of the code field.
CodePlaceholder 'Paste your transaction ID' Placeholder text inside the code field.
RedeemLabel 'Activate' Label of the button that submits the code.
CodeHint 'Paste the purchase code you received after checkout.' Hint text for the code field.
  1. The player buys Premium in your store and pastes their transaction id into the code field.
  2. The script checks whether the code was already used. A used code is refused with “This code has already been redeemed.”
  3. The script asks the payment provider whether the payment exists and is complete.
  4. If it is, the script stores a hash of the code together with the provider and the player identifier, and grants Premium.

Which provider is asked depends on the code:

Code starts with Provider
tbx- Tebex
cs_ or pi_ Stripe (checkout session or payment intent)
Anything else Tebex first. Stripe is tried when the Tebex secret is not set, or when Tebex does not know the code and a Stripe secret is set.

If the matching secret is not set, the player sees “Payment provider is not configured on this server.” If the provider cannot be reached, the player sees “Redemption service is unavailable. Try again later.” The messages can be changed in the locale files.

To use a different payment provider, see Exports and bridge files.

Secrets and webhook addresses are read from convars in server.cfg, never from the config file. Config.Convars holds the convar names:

Config key Convar Purpose
Config.Convars.TebexSecret kivo_battlepass:tebex_secret Tebex plugin secret used to check Tebex payments.
Config.Convars.StripeSecret kivo_battlepass:stripe_secret Stripe secret used to check Stripe payments.
Config.Convars.DiscordBotToken kivo_battlepass:discord_bot_token Optional Discord bot token used to load Discord profile pictures.
set kivo_battlepass:tebex_secret "your-tebex-plugin-secret"
set kivo_battlepass:stripe_secret "your-stripe-secret"
set kivo_battlepass:discord_bot_token "your-discord-bot-token"

You only need to rename a convar by editing Config.Convars if the default name clashes with something else on your server.

Config.Webhooks maps each log channel to the name of a convar. The value in the config is the convar name, not the webhook address. Set the address in server.cfg. A channel with no convar value sends nothing.

Config key Convar Sent when
Redeem kivo_battlepass:webhook_redeem A player redeems a purchase code.
Claim kivo_battlepass:webhook_claim Reward claim log.
Admin kivo_battlepass:webhook_admin An admin gives XP from the admin menu, or Premium is switched on or off.
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/..."

All text that the script sends to players and admins comes from the locale files in locales/. English (en.lua) and German (de.lua) are included. Set the language with Config.Locale.

If a key is missing in the chosen language, the English text is used. If it is missing in English too, the key itself is shown.

Prefix Used for
ui. Short labels such as Start Mission, Stop and Show GPS, and the frozen season message.
claim. Results and errors when claiming rewards, such as “Your inventory cannot hold this reward.”
mission. Mission results, and the instruction, hint and objective texts for each mission type.
redeem. Results of premium code redemption.
notify. Notifications, including mission messages (races, yoga, peyote, object pickups, waypoints) and feedback for admin commands.
admin. Entries of the admin menu.

Some texts contain placeholders in curly braces. Keep them exactly as written in your translation. They are replaced with live values.

Placeholder Replaced with
{name} Name of the claimed reward.
{count}, {total} Number of rewards claimed, and number that could be claimed.
{xp} XP given by a mission.
{title} Mission title.
{current}, {required} Mission progress and target.
{amount} Amount of XP granted by an admin.
{tier} Tier set by an admin.
{remaining} Objects, checkpoints, mats, emotes or races still to do.
  1. Copy locales/en.lua to a new file, for example locales/fr.lua.

  2. In the new file, change Locales.en = { to Locales.fr = { and translate the text on the right side of each line. Do not change the keys on the left.

  3. Add the file to fxmanifest.lua, in the shared_scripts list next to the other locale files:

    shared_scripts {
    -- other entries stay as they are
    'locales/en.lua',
    'locales/de.lua',
    'locales/fr.lua',
    'locales/locale.lua',
    }
  4. Set Locale = 'fr' in config/config.lua and restart the resource.

The mission titles and descriptions come from config/quests.lua, and the purchase window texts come from Config.PremiumPurchase. Translate those in the config files.

Next: Seasons and rewards.