A quest's leaderboard ranks the players who finished it. A built leaderboard ranks everyone who takes part, all the time, by a score you choose. You build it on the same canvas as quests: Score → Who → Appearance → When → Leagues → Rewards.
The score
The score adds up parts, each times a weight:
- A metric: its total in the scoring window, added up the metric's own way (a sum, a count, distinct values, the highest).
- Points earned: points of one kind earned in the window.
- Badges earned: all badges, or one badge.
Spend + 2 × coins earned is one score. Points and badges paid by leaderboards never count, so prizes don't snowball.
Permanent, or in seasons
- Permanent leaderboards run from a start date with no end. They can have payouts, weekly on chosen days or every N days, that pay the top places. A payout can flush: scores start again from zero, and players keep their order until someone out-scores someone above them.
- Seasons have a start and an end, once or repeating every week or every N days. Places are paid when each season ends.
Global leagues
One ranking cut into tiers: League 1 is the top 100, League 2 the next 100, and the last league holds everyone else. Moving between leagues works one of two ways:
- Automatically: your league is your rank. Out-score someone above you and you swap places.
- Players decide: everyone starts in the last league and moves up when they choose to, if the league above has room or they beat its lowest score. The player they replace moves down.
A danger zone warns players who may lose their place: the last N places of each league, and, when players decide, anyone whom a player in the league below out-scores.
Seasonal leagues
At the start of each season, players are split into groups of a fixed size, like 30. Groups can be random, or ranked by a pre-ranking (the strongest players together), and you choose who enters: everyone who joined, or only players who were active recently. Players who join mid-season wait for the next one.
Rewards for places
Points, badges and perks go to places, like 1–3 or 4–10, in every league or group, or in one league only (a crown for the winner of Gold).
Your site reads a leaderboard with one call: the standings of the player's league, their place and score, and whether they're in the danger zone or can move up. Read the API docs.