How to add a leaderboard to a JavaScript game

01A leaderboard needs a player, not an account

Scores attach to a durable player id, which every visitor gets automatically on first join. No signup, no login screen, nothing for the player to do.

They can claim a username later to carry that record to another device, and the score history follows them. Asking for the signup first is how you lose them before they have played.

02Submit, then read

Pick a mode when you submit. Use max for a high score, inc for a running total like lifetime kills, and set when the newest value replaces the old one.

Every read gives you the top entries, the player's own rank and the size of the whole board, so a line like "rank 7 of 412" comes from one call rather than three.

const board = player.leaderboard("high-scores");

await board.submit(score, { mode: "max" });   // keeps the best

const { entries, me, total } = await board.top(10);

render(entries);                               // the top ten
show(`rank ${me.rank} of ${total}`);           // this player's standing

03Make it mean something

Everything above is submitted by the browser, which means a determined player can submit anything. For a personal-best counter that is fine. For a public ranking it is not, and the first person to open the console will prove it.

When the ranking matters, move scoring into server logic. The client sends inputs, the server decides the score and submits it, and the browser never gets to name a number.

04Design notes that save a rewrite

• Use one board per thing being ranked, named plainly, rather than one board with mixed units.
• Scores are scoped to your studio by default, so a player is one person across your games. Switch a game to its own player pool before launch if you want it isolated, since that choice locks once real players exist.
• Show the player their own rank even when they are nowhere near the top. It is the number they came for.
• Decide early whether the board is all-time or seasonal. Starting a fresh board later is easy; splitting one that already mixed both is not.

Common questions