Battle Pass

The battle pass is a seasonal reward track. Players earn XP from contests and claim rewards from the Battle Pass page of the tablet. Clans have their own XP track that unlocks extra member slots.

Season settings

Config.BattlePass = {
    Enabled = true,
    SeasonId = 'contest_season_2',
    SeasonName = 'Contest Season 2',
    EndsAt = 0,
    ImageBase = 'auto',
    MinParticipationSeconds = 120,
    PositionSampleSeconds = 2,
    RequestCacheSeconds = 2,
    ClaimCooldownSeconds = 2,
    RequestTimeoutSeconds = 15,
    ClaimTimeoutSeconds = 30,
    -- XP, ClanSlots, Tiers ...
}

Option	Description
Enabled	Turns the battle pass on or off.
SeasonId	Unique season key stored with all progress and claims.
SeasonName	Name shown in the UI.
EndsAt	Unix timestamp when the season ends. 0 means no end date.
ImageBase	Where reward images come from. 'auto' uses your inventory's image folder.
MinParticipationSeconds	Time a player must spend in the zone to count as a participant.
PositionSampleSeconds	How often the server checks player positions for participation.
RequestCacheSeconds	Caches battle pass data requests.
ClaimCooldownSeconds	Cooldown between reward claims.
RequestTimeoutSeconds / ClaimTimeoutSeconds	UI timeouts for requests and claims.

Starting a new season

1. Change SeasonId to a new value, for example 'contest_season_3'.
2. Update SeasonName, and optionally EndsAt.
3. Restart the resource.

Progress is stored per SeasonId, so everyone starts the new season at 0 XP. Old season data stays in the database.

TIP

Get a Unix timestamp for EndsAt from unixtimestamp.com. For example, 1798761600 is 1 January 2027, 00:00 UTC.

Earning XP

XP = {
    ContestParticipation = 100, -- for taking part in a contest
    ContestWinBonus = 250,      -- extra for the winning clan
    ContestKill = 5,            -- per kill
},

Developers can also grant XP with the AddBattlePassXP and AddClanBattlePassXP exports.

Clan slots

A clan starts with Base member slots and unlocks more as its clan battle pass level rises, up to Maximum.

ClanSlots = {
    Base = 6,
    Maximum = 15,
    Unlocks = {
        { level = 1,  slots = 7 },
        { level = 4,  slots = 8 },
        { level = 7,  slots = 9 },
        { level = 10, slots = 10 },
        { level = 13, slots = 11 },
        { level = 16, slots = 12 },
        { level = 19, slots = 13 },
        { level = 22, slots = 14 },
        { level = 25, slots = 15 },
    },
},

Config.MaxClanMembers is still the hard cap.

Reward tiers

Each tier needs a total XP amount and gives one reward.

Tiers = {
    {
        id = 1,
        requiredXP = 1000,
        reward = { type = 'money', account = 'cash', amount = 5000, label = 'Cash', image = 'money.png' },
    },
    {
        id = 2,
        requiredXP = 2000,
        reward = { type = 'item', item = 'pistol_ammo', amount = 40, label = 'Pistol Ammo', image = 'pistol_ammo.png' },
    },
    -- ...
},

Field	Description
id	Unique tier number. Do not reuse IDs within a season.
requiredXP	Total XP needed to unlock the tier.
reward.type	'money' or 'item'.
reward.account	For money: cash or bank.
reward.item	For items: the item name in your inventory.
reward.amount	Amount of money or items.
reward.label	Name shown in the UI.
reward.image	Image file name in your inventory's image folder.

Default rewards

Tier	XP	Reward
1	1,000	$5,000 cash
2	2,000	40× Pistol Ammo
3	3,000	1× Armor
4	4,000	2× Thermite
5	5,000	SNS Pistol
6	6,000	$10,000 cash
7	7,000	80× Pistol Ammo
8	8,000	2× Armor
9	9,000	Security Card A
10	10,000	Pistol P220
11	11,000	$20,000 cash
12	12,000	120× Pistol Ammo
13	13,000	2× Thermite
14	14,000	3× Armor
15	15,000	Pistol Mk II
16	16,000	$30,000 cash
17	17,000	180× Pistol Ammo
18	18,000	2× Security Card A
19	19,000	3× Thermite
20	20,000	Heavy Pistol
21	21,000	$50,000 cash
22	22,000	250× Pistol Ammo
23	23,000	5× Armor
24	24,000	Pistol .50
25	25,000	$75,000 cash

WARNING

Every item in the rewards (for example weapon_p220 or security_card_01) must exist in your inventory, or the claim will fail.