The Levels Ladder

The whole system in six points.

1. Every settled bet gets converted into XP. The rate depends on which currency the bet was placed in.
2. That XP lands in two separate counters. Total XP is a lifetime figure. Period XP resets on a schedule you set.
3. A player's level is whichever rung on the ladder has the highest XP threshold their Total XP has passed.
4. Each level also carries a Maintenance XP figure. That is the Period XP a player needs to keep the level when the period closes.
5. When a period closes, one of two things happens. Either their Period XP resets and they keep their level, or they drop one rung and their Period XP resets.
6. Levels carry bonuses. Reaching a level makes its bonuses claimable, and leaving it makes them unclaimable again.

Four things are involved. You build three of them and the system writes the fourth.

XP comes from bet stakes and nothing else. Deposits, logins and wins earn none of it. When a bet finishes, its stake gets converted to XP and added to both counters. It makes no difference whether the bet won or lost, so a 10 SC losing spin and a 10 SC jackpot spin earn the same XP.

The conversion rates

Those examples use the reference multipliers in the platform config, 0.85 for SC and 0.0001 for GC. Both are per brand settings and both have to sit between 0 and 1. You can slow XP earning down, but you cannot push an SC or GC multiplier above face value.

Which bets count

• Any settled bet with a stake amount recorded against it, in any game and any currency.
• Bets with no stake amount earn nothing and get skipped quietly. Free spin rounds fall into this group unless a stake value was recorded.
• XP is calculated on the stake and never on the win. Nothing is layered on top of the currency rate.

One rule decides a player's level, and it gets applied fresh every time.

Three things follow from that rule, and they matter more than they look at first.

• Total XP never gets spent. Reaching a level consumes nothing. Play only ever pushes the number up. The one thing that pulls it down is a downgrade at period close.
• A single bet can clear several rungs. A big enough wager takes the player straight to whichever level their new Total XP lands in, however many thresholds sit in between.
• The top rung has nothing above it. A player who reaches it keeps accumulating Total XP, but there is no next threshold to measure against, so their progress bar reads "Max" and stays there.

The period is what turns the ladder into a retention mechanic, and it is the only part of the system that can take a level away.

When it fires

• A job wakes at midnight on the server clock every day and checks one thing: does today fall on a period boundary, according to your brand's schedule?
• The reference schedule is 0 0 1 * *, which means the 1st of every month. Change the expression and you change the rhythm to weekly, fortnightly or quarterly.
• Only the day part of the schedule gets used. The time of day is ignored, and a boundary always gets processed on the daily midnight run.
• Two switches gate the whole thing. Levels have to be enabled for the brand and periods have to be enabled. Turn periods off and nobody is ever reset or downgraded.

What happens to each player

How the run behaves

The run sweeps every registered player, so it is built for safety ahead of speed.

• Players get walked in pages of 1,000, and each one becomes its own small job. Nothing runs inside a single long transaction.
• A lock stops two servers starting the same run, and every player gets marked off as processed, so a retry or a deploy partway through cannot process anybody twice.
• The run takes a while to drain. On the morning a period closes, expect level changes and their emails to arrive spread across a window rather than all at once.

A downgrade keeps a player's progress percentage and re-projects it onto the band underneath. Someone 40% of the way through Silver I lands 40% of the way through Bronze II, so they do not fall to the bottom of the rung below.

Three cases behave differently

The only functional reward attached to a level is its list of bonuses. Whenever a player's level changes, the system reconciles their level bonuses against the new level in a single pass.

Two things follow from that, and both are deliberate.

• A level bonus only ever gets granted once per player. Bouncing between two rungs across periods switches the same bonus back on each time instead of issuing a new one, so nobody can farm rewards by hovering around a threshold.
• A bonus attached to several levels survives moves between them. If Gold I, II and III all carry the same weekly cashback, a player moving among those three keeps it live throughout. That is the usual way to make a reward stick from a given rank upward.

Six paths, which between them cover about every state a player can be in. They all assume the reference ladder: Bronze I at 0, Bronze II at 5,000, Silver I at 15,000 and Gold I at 40,000, with Silver I asking for 8,000 Period XP to hold.

In the admin

The ladder itself lives under Platform Setup › Level Management, split into a Levels tab and a Ranks tab. Level grants live somewhere else, on the player's own page. Every create, edit and delete gets recorded in the audit log against the admin who did it.

Granting a level

You can put an individual player on a specific level without waiting for them to earn it. It is the only manual lever in the system, and it works differently from how most people assume.

What it does, in order:

1. Works out the gap between the player's current Total XP and the target level's XP Threshold.
2. Awards exactly that much XP, so their Total XP permanently becomes the threshold figure.
3. Runs the same level up path a real bet would, which grants the target level's bonuses and marks the player immune to downgrade for the rest of the period.
4. Sends the level change email and the in-app level up notification, exactly as an earned level up would.
5. Writes a grant record naming the admin, the player and the level, so it shows up alongside cash and package grants in the player's history and in the audit log.

The one button that matters: Reset levels

Here is what it actually does to each player:

1. Takes their existing, untouched Total XP and looks up which level that XP now corresponds to.
2. Writes a new level record if their level changed, or if any of the three cached XP figures changed.
3. Reconciles their level bonuses against wherever they ended up.

Each player's record carries a copy of the XP figures that were in force when it was written, and those copies are what the system checks on each bet. A ladder edit does reach existing players on its own eventually, but only in pieces: they pick up the new shape when they next cross a threshold, and a period close refreshes their cached figures without moving them. Recalculating is how you apply an edit to everyone at once, on purpose, at a moment you choose.

The ladder edit playbook

1. Make all your edits first. Add, re-price and delete every rung you mean to change before you touch Reset levels. One recalculation covers the whole batch, and one batch means one email per affected player instead of several.
2. Think about the send before you press it. Every player whose level actually moves gets a level change email. Re-pricing a busy band can turn into a mass send.
3. Press Reset levels and confirm. The run gets queued and drains in the background. The toast tells you it started, not that it finished.
4. Spot check a few players under User Administration, Engagement, to confirm they landed where you expected.

In the brand config, with engineering

These are deploy time settings per brand rather than admin toggles, so changing any of them is an engineering request. Check your brand's live values before you plan around them. The example configs in the repo have levels switched off for some brands.

Half the job of designing a ladder is knowing which mistakes the system will catch for you and which ones it will wave straight through.

Behaviour that is correct but surprising. These are the ones that generate questions in a room.

What the platform sends on its own, with no CRM campaign attached. The two blanks are the interesting part.

The level change email carries the new level name, its rank name and the XP threshold. It only goes out if the player has an email address on file and they landed on a level that still has a rank attached, so a player who ends up on no level hears nothing at all. One template covers both directions, so the same email announces a promotion and a demotion.

The mechanics are settled. These are the calls that belong to you, and the questions worth taking into the room.

Questions for engineering

• Can the Reset levels button be renamed and its warning corrected? It currently describes something the system does not do.
• Can the level change email be split into separate promotion and demotion templates?
• Should the in-app notification fire on a downgrade too, or is email only deliberate?
• Should a granted level really send the same celebratory notification as an earned one?
• Can a level grant be reversed, or the XP it awarded be adjusted, when someone gets it wrong?
• Is a dry run possible, showing how many players a ladder edit would move before we commit?
• Should crypto and fiat bets get an XP multiplier so all rails earn at the same rate?
• What are our brand's live values for the levels switch, the multipliers and the period schedule?
• What timezone do the servers run in, so we know what hour a period actually closes?
• Has the level grant feature shipped to our brand yet, or is it still on its way?