Skip to content

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 settingValues
What is bestdesc: higher (points). asc: lower (a time). Fixed once there are scores.
Formatnumber: 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

LimitValue
Achievements per game200
Leaderboards per game50
IdsA-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 submissionsCounted 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

HTTP
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=5
Anyone who holds a play token can submit any score for that player, so a score the game computes in the browser can be faked. For a leaderboard that matters, check the score on your server and submit it from there with the token the game sends you.

Next: Players on your server