Achievements and leaderboards
Achievements players collect and leaderboards they climb, without a server of your own. The store shows them on your game's page and in the player's library.
1. Define them in the console
Open your game in the developer console and choose the Achievements tab. Each achievement has an id (what your code uses), a name, a description, an optional https:// icon (a square picture, 64 px or more) and whether it is hidden: a hidden achievement reads “Hidden achievement” in the store until the player has it. Each leaderboard has an id, a name, what is best and how scores read.
| Leaderboard setting | Values |
|---|---|
| What is best | desc: higher (points). asc: lower (a time). Fixed once there are scores. |
| Format | number: 12,345. time: milliseconds, shown as 1:02.345. decimal: hundredths, shown as 123.45. |
2. Unlock and submit from the game
const { newly } = await playium.achievements.unlock('first-win'); // fine to call again
const mine = await playium.achievements.list(); // with unlocked_at
const result = await playium.leaderboards.submit('high-score', 12345);
result.improved; // the player's best went up (or this was their first)
result.best; // { rank, display_name, score, achieved_at, me }
const top = await playium.leaderboards.top('high-score', { limit: 10 });
const near = await playium.leaderboards.aroundMe('high-score', { range: 3 });
top.entries; top.me; top.total;Scores are whole numbers. Each player keeps their best; equal scores share a rank, the earlier one first. Entries carry the player's public display name only, never their id.
What players see
The game's store page lists the achievements with the share of players who have each, and the top of every leaderboard with a filter for the player's friends. The library page of the game shows which ones the player has. New unlocks reach the player as one notification per game, gathered until they read it.
Testing
In the store preview and with a dev key, unlocks and scores go to a test store apart from players': nothing shows in the store, and the console counts them separately. Clear test data in the tab empties it. In Node, createFakeStore({ achievements: [{ id: 'first-win' }], leaderboards: [{ id: 'high-score' }] }) answers these calls offline.
Limits and errors
| Limit | Value |
|---|---|
| Achievements per game | 200 |
| Leaderboards per game | 50 |
| Ids | A-Z a-z 0-9 _ . -, 1 to 64 characters |
| Entries from top() | 1 to 100 |
| Entries each way from aroundMe() | 1 to 25 |
| Unlocks and submissions | Counted with cloud save writes: 60 a minute per player |
Errors: achievement_not_found and leaderboard_not_found (an id the console does not know), account_suspended (a suspended player cannot unlock or submit; carry on without it), invalid_request.
From your server
GET https://platformbackend-production-e04dbbd2.up.railway.app/v1/achievements Authorization: Bearer <play token>
POST https://platformbackend-production-e04dbbd2.up.railway.app/v1/achievements/:id/unlock
POST https://platformbackend-production-e04dbbd2.up.railway.app/v1/leaderboards/:id/scores { "score": 12345 }
GET https://platformbackend-production-e04dbbd2.up.railway.app/v1/leaderboards/:id/top?limit=10
GET https://platformbackend-production-e04dbbd2.up.railway.app/v1/leaderboards/:id/around-me?range=5Next: Players on your server