Skip to content

Seasons and rewards

This page covers config/seasons.lua and config/rewards.lua.

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. startsAt means 00:00:00 UTC on that day. endsAt means 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.

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.

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.

To start a new season:

  1. Add a new entry at the end of Config.Seasons with a new id and its dates.
  2. 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.
  3. 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.

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.

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.

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.

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.

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.

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 lets a player keep rewards they earned but did not claim in an earlier season.

  • A carryover entry is saved in the kivo_bp_carryover table 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.lua later 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.