In-game leaderboard: ranking, rounds and rewards

What the player sees

• Boards as tabs: each with a card showing the player's score, rank and the countdown to the end of the round.
• The top players, with the player highlighted and medals for the top three.
• Rank rewards and points rewards in popups; points rewards are claimed right there.
• A popup with the reward of the last round: it appears by itself when a round ends, with a "Claim" button.
• A "Play" button on the card if the game has a mode where points are earned.
• A badge on the tab when a reward is waiting.

How a board is built

• Rounds. A board repeats in cycles (for example every week), runs on a schedule or as a chain of rounds.
• How the score is counted. The sum of all results, the best result, the best time or the last value.
• Rank rewards - by ranges of places at the end of a round: 1st place, 2nd to 3rd, 4th to 10th and so on.
• Points rewards - milestones inside a round: "earn 1000 points this week".

Where points come from

Points come from the sources set on the board:

• A result from the game (ClientScore). The game sends a number, for example the score of a run. ⚠ Set limits on the source: a maximum per submission, per day and a pause between submissions. Without this source the board takes no number from the game at all.
• Events the server counts by itself, for example purchases or finished quests. These cannot be faked from the game.

For developers

The leaderboard works through client.leaderboard in @idosgames/core.

// Submit a result: the server applies the counting rule and the limits
const sub = await client.leaderboard.submitScore('weekly_score', 150)
if (!sub.ok) return showError(sub.error)
sub.data.NewScore // the score after counting

// A screen with several boards: top lists and the player's progress in one request
const overview = await client.leaderboard.getOverviewBatch(['weekly_score', 'season_pvp'])

// Claim everything waiting: rank rewards and points rewards
await client.leaderboard.claimAllRewardsBatch(['weekly_score', 'season_pvp'])

• The SDK rejects a score of zero or less by itself, without a request.
• Take the new score from NewScore in the response: with "best result" a worse result does not change the score.
• The friends ranking is getFriendsLeaderboard(leaderboardID).

Every field is described in the leaderboard-system skill, served by the SDK MCP server.