Seasons and rewards
This page covers config/seasons.lua and config/rewards.lua.
Seasons
Section titled “Seasons”Seasons are listed in Config.Seasons in config/seasons.lua. Only edit the entries in that list. The date conversion code above and below it must stay in place.
Config.Seasons = { { id = 'season-1', name = 'Season 1', title = 'BATTLE PASS', description = 'Complete missions, climb the road, and claim free or premium rewards before the season ends.', startsAt = '01.09.2026', endsAt = '28.09.2026', maxTier = 50, xpPerTier = 2000, },}| Field | Type | Description |
|---|---|---|
id |
string | Unique id of the season, up to 64 characters. Progress, claims and mission progress are saved under this id. Use a new id for every season. |
name |
string | Season name shown in the Battle Pass window. |
title |
string | Title text shown in the Battle Pass window. |
description |
string | Description text shown in the Battle Pass window. |
startsAt |
string or number | First moment of the season. See Dates. |
endsAt |
string or number | Last moment of the season. See Dates. |
maxTier |
number | Highest tier a player can reach. |
xpPerTier |
number | XP a player needs for each tier. The value is the same for every tier. |
startsAt and endsAt accept two formats:
- A date string written as
DD.MM.YYYY, for example'01.10.2026'. Day and month may have one digit.startsAtmeans 00:00:00 UTC on that day.endsAtmeans 23:59:59 UTC on that day, so the end date itself is still part of the season. - A Unix timestamp in seconds, for example
1790812800. The number is used exactly as written. Use this when you need an exact start or end time in your own time zone.
Dates are always read as UTC. Config.TimezoneOffsetHours does not change them.
If a date string is not written as DD.MM.YYYY, the config stops with the error Season date "..." must be DD.MM.YYYY in the server console.
Several seasons
Section titled “Several seasons”Add one entry per season, in date order with the oldest first. Give each a different id.
Config.Seasons = { { id = 'season-1', name = 'Season 1', title = 'BATTLE PASS', description = 'The first season.', startsAt = '01.09.2026', endsAt = '30.09.2026', maxTier = 50, xpPerTier = 2000, }, { id = 'season-2', name = 'Season 2', title = 'BATTLE PASS', description = 'The second season.', startsAt = 1790812800, -- 01.10.2026 00:00:00 UTC endsAt = 1793491199, -- 31.10.2026 23:59:59 UTC maxTier = 50, xpPerTier = 2500, },}Keep finished seasons in the list. Their id and maxTier are still needed when rewards are carried over.
When no season is running
Section titled “When no season is running”Before the first season starts and after the last one ends, the Battle Pass is frozen. Players who open it see “This season is frozen. You can still claim leftover rewards.” Claiming a current reward is refused with “The season is frozen. Current rewards cannot be claimed.” Add a new season to config/seasons.lua and restart the resource to reopen the Battle Pass.
The example season in the shipped config ends on 28.09.2026. Change the dates before you go live.
Season rollover
Section titled “Season rollover”To start a new season:
- Add a new entry at the end of
Config.Seasonswith a newidand its dates. - Check
config/rewards.lua. The reward table is shared by all seasons, so a changed reward applies to the current season and to carryover that has not yet been saved. - Restart the resource before the new season starts. Config files are read when the resource starts.
Players start the new season with a fresh tier, XP and mission progress, because everything is stored per season id. Old rows stay in the database. Rewards that players reached but did not claim can be kept as carryover.
Rewards
Section titled “Rewards”config/rewards.lua holds two tables, FREE_GRANTS and PREMIUM_GRANTS. Each table has one entry per tier, from 1 to 50. Premium players can claim both tracks. Players without Premium can only claim the free track.
[1] = { type = 'account', account = 'cash', amount = 2500, name = 'Street Cash', image = 'money.png' },[2] = { type = 'item', item = 'water', amount = 5, name = 'Bottled Water', image = 'water.png' },The file builds the reward list from these tables with a loop that runs from tier 1 to tier 50. Every fifth tier is marked as a featured reward automatically. Each reward gets the id free-<tier> or premium-<tier>, for example free-12 or premium-12. Claims are saved under these ids, so keep the id format as it is.
Reward fields
Section titled “Reward fields”| Field | Used by | Description |
|---|---|---|
type |
all | The reward type. Required. See Reward types. |
name |
all | Name shown to the player. Required. |
image |
all | Image file name. It is added to Config.ImagesBaseUrl. Required, because an entry without an image stops the config from loading. |
amount |
most types | How many items, how much money or how much XP. Defaults to 1 when left out. |
item |
item, metadata_item, weapon, custom |
Item name, weapon name, or the identifier your custom code needs. |
account |
account |
'cash' or 'bank'. |
model |
vehicle |
Vehicle spawn name. |
metadata |
item, metadata_item, weapon, custom |
Table of item metadata, passed to your inventory. |
Fields not listed here are dropped when the reward list is built, so they never reach your code.
Reward types
Section titled “Reward types”type |
Fields | What the player gets |
|---|---|---|
account |
account, amount |
Money. 'bank' adds to the bank account. Any other value, including 'cash', adds cash. |
item |
item, amount, optional metadata |
An item, if the inventory has room. |
metadata_item |
item, amount, metadata |
An item with metadata, if the inventory has room. |
weapon |
item (weapon name), amount, optional metadata |
A weapon, if the inventory has room. |
vehicle |
model |
A vehicle saved to the player’s garage. amount is not used. See Vehicle rewards. |
xp |
amount |
Bonus XP for the player. |
premium |
none | Unlocks Premium for the player. |
custom |
item, amount, optional metadata |
Whatever your code in open/rewards_custom.lua does. See Exports and bridge files. |
If a reward cannot be delivered, the claim fails and the reward is not marked as claimed. The player sees “Your inventory cannot hold this reward.” when the inventory is full, or “The reward could not be delivered. It was not marked claimed.” for any other failure. The player can try again later.
Reward images
Section titled “Reward images”Images come from Config.ImagesBaseUrl. By default this points to the images folder of the resource, and the reward entries use the file names found there, for example money.png or WEAPON_BAT.png. File names are case sensitive.
To use your own image, copy it into that folder and enter its file name in the image field. To load images from another resource, change Config.ImagesBaseUrl to its NUI address, for example nui://my-inventory/web/images/. That resource must list the image files in the files section of its own fxmanifest.lua.
Examples
Section titled “Examples”Replace the free reward of tier 5 with an item that has metadata:
[5] = { type = 'metadata_item', item = 'phone', amount = 1, metadata = { label = 'Battle Pass Phone' }, name = 'Battle Pass Phone', image = 'phone.png',},Give 5000 bank money at tier 20 of the premium track:
[20] = { type = 'account', account = 'bank', amount = 5000, name = 'Bank Transfer', image = 'moneybag.png' },Give Premium itself as a free reward at tier 30:
[30] = { type = 'premium', name = 'Premium Pass', image = 'certificate.png' },The metadata fields that work depend on your inventory. Check its documentation.
Default reward track
Section titled “Default reward track”The shipped file fills all 50 tiers on both tracks. A few examples:
| Tier | Free track | Premium track |
|---|---|---|
| 1 | 2,500 cash | 12,500 bank |
| 5 | 3 lockpicks | 3 advanced repair kits |
| 10 | 1 body armor | 3 body armor |
| 40 | 2,000 bonus XP | Sultan RS vehicle |
| 43 | Sultan vehicle | Combat Pistol |
| 45 | Gold bar | 8,000 black_money item |
| 50 | Luxury watch | Carbine Rifle |
Check that the items, weapons and vehicles exist on your server. See Examples and troubleshooting.
Carryover
Section titled “Carryover”Carryover lets a player keep rewards they earned but did not claim in an earlier season.
- A carryover entry is saved in the
kivo_bp_carryovertable for each reward the player had reached in that season but had not claimed. Premium track rewards are only saved for players who had Premium. - Entries are stored together with the reward definition, so changing
config/rewards.lualater does not change an entry that was already saved. - Players see carryover rewards as leftover rewards and can claim them like any other reward.
- Admins can create the entries for one player at once with
/kivobproll [id]or with Force season rollover in the admin menu. See Admin tools.
Next: Missions.
