Season Track

A season track is a ladder of reward tiers that fills with experience during a limited season. A free lane pays everyone, and a paid lane pays extra. Tiers are claimed one by one in any order. When the season ends, earning stops, and a short window remains for claiming what was earned.

Also called: Battle pass, Season pass, Reward track, Tier ladder.

A stout otter in a patchwork cloak climbs a zig-zag stair of cubes around a floating mountain and opens a glowing chest on the newest step, while a violet side stair carries bigger chests and a moon with a shrinking ring hangs above. — Pebblewick Ascent, an invented stair-climbing adventure. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Season Track" to my game.

What it should do: A season gives playing a clear shape: a visible ladder to climb, a deadline that makes today matter, and a reason to come back until the end.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> running
  running: Season running
  top: Top reached
  claiming: Claim window
  closed: Closed
  running --> top: reaches the top tier
  running --> claiming: season ends
  running --> closed: window passes unseen
  top --> claiming: season ends
  top --> closed: window passes unseen
  claiming --> closed: window ends
  closed --> [*]
```

Use these starting values:
- tiers: 30 tiers
- xpPerTier: 1000 xp
- seasonLength: 56 days
- claimGraceDays: 7 days
- rewardPerTier: 50 coins
- premiumMultiplier: 2 x

Watch out for these common mistakes:
- One big gain crosses many tiers: Tell your AI: never store the tier. Keep the experience and work out the tier from it every time it is needed.
- Buying the paid lane late: Tell your AI: when the paid lane is bought, every tier already reached becomes claimable on it at once.
- Claiming only in order: Tell your AI: keep one taken-flag per tier and lane, and allow any reached tier in any order.
- The last-day rush: Tell your AI: stop earning at the end, but keep claiming open for a few more days.
- Rewards that overflow: Tell your AI: cap the experience at the top of the ladder, and refuse any tier number outside 1 to the last tier.
- Bad numbers and double taps: Tell your AI: accept only finite experience above zero, and mark the reward as taken in the same step that pays it.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

A season gives playing a clear shape: a visible ladder to climb, a deadline that makes today matter, and a reason to come back until the end.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Season running → Top reached: reaches the top tier
Season running → Claim window: season ends
Season running → Closed: window passes unseen
Top reached → Claim window: season ends
Top reached → Closed: window passes unseen
Claim window → Closed: window ends

Good starting values

Value	Start with	What it changes
tiers	30 tiers	How many rungs the ladder has. Too few and each one feels like a big jump, too many and the top is out of sight.
xpPerTier	1000 xp	How much experience one tier costs. With a season of 56 days, the default means the top is reached by playing a bit more than half an hour a day.
seasonLength	56 days	How long earning is possible. Eight weeks is long enough to relax and short enough to feel urgent.
claimGraceDays	7 days	How many days after the season ends the player can still take what they earned. It spares people who were away on the last day.
rewardPerTier	50 coins	What a free reward pays. It is the same on every tier here, so the ladder is easy to read. Make tiers differ in your game by giving some an item instead.
premiumMultiplier	2 x	How many times more a paid reward pays than a free one. The paid lane must feel clearly better, but the free lane must still feel worth playing.

What usually goes wrong

One big gain crosses many tiers

A bonus event gives 7,300 experience at once. Code that unlocks only the next tier leaves the player stuck on tier 1 with six rewards missing.

Fix: Tell your AI: never store the tier. Keep the experience and work out the tier from it every time it is needed.

Buying the paid lane late

A player buys the paid lane on tier 12. If only the tiers from now on pay extra, they feel cheated, and support gets the complaints.

Fix: Tell your AI: when the paid lane is bought, every tier already reached becomes claimable on it at once.

Claiming only in order

The code lets the player take tier 5 only after tiers 1 to 4. One reward that is hard to show, or one skipped on purpose, blocks the whole ladder.

Fix: Tell your AI: keep one taken-flag per tier and lane, and allow any reached tier in any order.

The last-day rush

A player earns the last tiers a minute before the season ends and then cannot take them, because the claim closed with the season.

Fix: Tell your AI: stop earning at the end, but keep claiming open for a few more days.

Rewards that overflow

A player keeps earning experience at the top. If the number grows without limit, the next tier is worked out past the end of the ladder and reads a reward that does not exist.

Fix: Tell your AI: cap the experience at the top of the ladder, and refuse any tier number outside 1 to the last tier.

Bad numbers and double taps

An award of minus 50 or of a missing value, or a double tap on claim, takes experience away or pays a reward twice.

Fix: Tell your AI: accept only finite experience above zero, and mark the reward as taken in the same step that pays it.

How to check it works

A new season with 1,000 experience per tier. the player earns 2,500: tier 2 is reached and 500 is on the way to tier 3.
A new season. the player earns 7,300 in one go: tier 7 is reached, and tier 3 can be claimed at once.
A ladder of 30 tiers. the player earns 100,000: the experience stops at 30,000 and the tier is 30.
Tier 1 is reached. the player claims its free reward twice: the first pays 50 coins and the second pays nothing.
The player is on tier 2. they claim tier 3, or tier 0, or tier 31: nothing is paid.
Tier 4 is reached and the paid lane is not owned. the player claims the paid reward of tier 2: nothing is paid.
Tier 5 is reached. the player buys the paid lane and claims the paid reward of tier 2: they get 100 coins.
Tier 6 is reached. the player claims tier 5, then tier 1, then tier 3: each pays 50 coins, 150 in all.
The season is 56 days long. the player earns experience on day 56: the experience does not change.
The season ended and the player reached tier 3. they claim on day 62, and another reward on day 63: day 62 pays, and day 63 pays nothing because the window closed on day 63.
The season has ended. the player tries to buy the paid lane: it is refused.
A player with 1,500 experience. the game awards -50, 0 or a value that is not a number: the experience stays 1,500.

Works well with

Experience and Levels: A player level lasts for the whole game, while the season ladder starts again each season. Feed both from the same events, but never share one number between them. Keep the two ladders apart.
Daily Rewards: Both depend on the day. Use the same trusted day number for both, so they cannot disagree about whether it is the same day. Give both their own clock check.
Currency Wallet: The wallet owns the balance. The track only decides whether and how much to pay, and remembers what was taken. Pay into the wallet when a claim is accepted.

Common questions

how does a battle pass work in a game

Playing earns experience, and each full block of experience unlocks the next tier. Every tier holds a reward on a free lane and often a better one on a paid lane, until the season ends.

how long should a game season be

Eight weeks is a good start. Shorter seasons feel like a chore to keep up with, and longer ones lose the sense that today matters.

what happens to the paid lane when a player buys it late

Everything they have already reached unlocks on the paid lane at once. Otherwise buying late feels like a trap, and people stop buying.

what do i tell my ai to add a season pass

Paste this: Add a season track with 30 tiers, 1,000 experience per tier, a free lane and a paid lane that pays double. Work out the tier from the experience, allow claiming in any order, unlock old tiers on the paid lane when it is bought, stop earning after 56 days and keep claiming open for 7 more.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

19 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it