Leaderboard API for games
Boards a designer adds without code. A board keeps the best score of each player: the highest, or the lowest for a time. It may start again every day, week or month. Scores come from the client, or only from the game server.
await rudder.leaderboards.submit({ board: 'arena', score: 1200 });Catalog: Leaderboards
Section titled “Catalog: Leaderboards”Engagement → Leaderboards.
| Field | Meaning |
|---|---|
key, name | The board. |
period | never, day, week or month: how often the board starts again, from the day start of the project. |
order | desc, the highest score first, or asc, the lowest first, such as the time of a race. |
client | Whether the game client sends its own scores. Otherwise only the game server reports them. |
A board whose period or order changes starts again empty. Its old scores stay under the old
rules.
Functions
Section titled “Functions”| Function | Kind | Caller | Arguments | Result |
|---|---|---|---|---|
submit | mutation | client | {board, score} | {place, score, players} |
report | mutation | server | {board, score} | {place, score, players} |
top | query | client | {board, count?} | {places: [{place, player, score, nickname, avatar}], players} |
me | query | client | {board} | {place, score, players} |
submitsends a score of the player of the call to a board withclient; another board answersserver_only.reportis the game server reporting for the player it names, on any board.topreturns the firstcountplaces (10 by default, at most 100) with the nickname and avatar of each player, and the number of players on the board.mereturns the place and score of the player (place 0 when it is not on the board) and the number of players.- Players with equal scores share a place (1, 1, 3) and are listed by player id.
- A place is read a moment after the scores it counts: a score another player sent a few milliseconds ago may not be in it yet. The best score itself is never lost.
Errors
Section titled “Errors”| Code | When |
|---|---|
unknown_board | There is no such board. |
server_only | The client submitted to a board without client. |
invalid_score | A score below 0 or above 2^53. |
invalid_count | count is not from 1 to 100. |
In the Dashboard
Section titled “In the Dashboard”- Engagement → Leaderboards. The page of a board shows its standings in the current and the previous period, with a search by player id or nickname, in the environment chosen in the header.
- Engagement → Calendar: the starts of each board’s periods.
Limits
Section titled “Limits”- The best score only: no sum and no last score.
- No prizes for places. A module of your game reads the previous period and lets each player claim its prize.
- Only the current and the previous period of a board can be read.