Add a leaderboard

You submit a player’s best score to a named board and show the top entries with the player’s rank.

Before you start

The SDK installed and started, from Connect the SDK.
A private preview to check hosted scores. The quickstart covers deploying one.

Declare the board

Boards live in opengame.json, up to 10 a game:

opengame.json

{
  "leaderboards": [
    {
      "key": "rounds",
      "order": "desc",
      "label": "Rounds survived",
      "min": 0,
      "max": 500
    },
    {
      "key": "fastest_lap",
      "order": "asc",
      "label": "Fastest lap (ms)",
      "min": 20000
    }
  ]
}

Field	Meaning
`key`	Lowercase letters, digits and underscores, starting with a letter. Up to 48 characters.
`order`	`desc` when higher is better, `asc` when lower is better.
`label`	The heading shown above the scores.
`min`, `max`	Optional. The range a real score falls in.

A score outside min or max is stored at that limit and marked clamped. A score is rejected instead when it is more than max times 10, or less than min divided by 10. With min at 0, that means any negative score. Only a score stored as submitted, marked ok, appears on the board.

Submit a score

import { og } from "@opengamehq/sdk";

await og.init();
const board = og.leaderboard("rounds");

const saved = await board.submit(14, {
  mode: "coop",
});
if (!saved.ok) {
  console.warn(saved.reason ?? saved.error);
} else {
  const { best, state, score } = saved.value;
  if (best && state === "ok") showNewBest(score);
}

saved.value.state is ok, clamped or rejected, and saved.value.best is true when the score replaced the player’s best. To call the game API without the SDK, read the API reference. The SDK handles the session, the request deadline and the local mock for you.

Show the board

const top = await board.top({ limit: 10 });

// value is null until the player has an
// accepted score.
const mine = await board.me();

// A hosted top() never marks the
// player's row, so match the rank
// that me() returns.
const myRank = mine.ok
  ? mine.value?.rank
  : undefined;

if (top.ok) {
  for (const entry of top.value.entries) {
    const name = entry.name ?? "Guest";
    const { rank, score } = entry;
    const isMine = rank === myRank;
    addRow(rank, name, score, isMine);
  }
}

// The entries either side of the player.
const nearby = await board.around();

top() returns up to 100 entries. around() returns 10 entries either side of the player. Each entry has these fields:

Field	Meaning
`name`	The player’s handle, or a guest name. See below.
`score`	The stored score.
`meta`	The metadata submitted with it.
`createdAt`	When it was stored.
`rank`	The entry’s place on the board.
`isMe`	`true` on the player’s entry from `me()` and `around()`. `false` from a hosted `top()`.

name is the player’s handle when they have turned on profile sharing. In a published game, any other player, guest or signed in, is Guest and the first four characters of their og.player.id, for example Guest 3f9a. Some signed-in players’ entries saved before each game gave its players a separate ID have null. Show your own fallback for them. The game cannot set name. In a multiplayer private preview the room ID can differ from the score identity, so display the entry’s name, not one built from og.player.id.

Know what a board stores

One best score per player per board. A new submission replaces it only when it is better.
Scores are the game’s claim. Anyone with a browser console can submit any number. The declared bounds keep wild numbers off the board, but forged scores inside them still appear. A board shows what the game reported, and prizes are judged on other criteria.
meta is small, and typed. It takes only label, mode, level and character as strings, and duration_ms, accuracy and combo as numbers. A number where a string belongs, such as a numeric level, fails with invalid_meta. Strings run to 24 characters and 384 bytes in all. A string that looks like an email address or a long number fails with invalid_meta. Use it for game context, such as a mode or a level.
Reads are cached. top() results are cached for 30 seconds, so a new best can take that long to appear there.

Test a board

Outside OpenGame, scores are kept in localStorage per folder and board, using the boards in ./opengame.json. If your build moves that file, pass the manifest yourself with og.init({ manifest }). Locally a board holds only your best score, so top() returns one entry, with isMe set to true and name set to "dev". Changing a board’s bounds or order starts it fresh. In your private preview, scores go to a separate board that only that preview can read. They are not shown publicly, and they stop being readable when the preview expires. A hosted failure does not fall back to local scores. Before you release:

Submit a score within the board’s bounds. Check saved.ok before reading saved.value, and expect saved.value.state to be ok.
Read me() to confirm the player’s result.
Submit a worse score and confirm the best one stays.
Check names with a player who shares their profile and one who does not.
In a private preview, confirm the scores stay on that preview’s board.

Fix a problem

Leaderboard methods return a result instead of throwing, even on a network failure. When ok is false, the operation failed. The result includes an error code and a reason for you to log. Tell the player in plain words, such as “Score not saved. Keep playing.”, and let them carry on. Never show them the code.

Fix by error code

Code	What to do
`invalid_board`	Use a key declared in `opengame.json`.
`board_unavailable`	Declare the board in `opengame.json`, or deploy a release that has it.
`invalid_score`	Submit a finite number.
`invalid_meta`	Send only `label`, `mode`, `level` and `character` as strings, and `duration_ms`, `accuracy` and `combo` as numbers. Keep strings short; the result’s `reason` names the field.
`invalid_limit`	Pass a positive whole number to `top()`.
`invalid_manifest`	Fix the `leaderboards` list in `opengame.json`.
`rate_limited`	The session sent more than 60 scores in a minute, or the player or their address went over theirs, so this score was not saved. Submit it again after a minute, or submit only each round’s best.
`invalid_request`	The API could not read the request, so nothing was saved. Check the arguments against the SDK reference.
`unavailable`	This page does not offer leaderboards, or the request did not reach OpenGame, so nothing was saved. Check `og.capabilities` before you show a board.

Fix by symptom

A new best is missing from the board

Only scores marked ok appear on the board. Check saved.value.state: a clamped score is stored at the limit and does not appear. top() results are cached, so an ok score can take 30 seconds to show there.

A player shows as Guest

Their handle appears only when they have turned on profile sharing. Until then the board shows Guest and the first four characters of their og.player.id. The game cannot set name.

Preview scores are missing from the published board

A private preview writes to a separate board that only that preview can read. Those scores do not appear on the published board.

Start

Guides

Reference

Add a leaderboard

Before you start

Declare the board

Submit a score

Show the board

Know what a board stores

Test a board

Fix a problem

Fix by error code

Fix by symptom

Where next

Update a live game

Read the SDK reference

​Before you start

​Declare the board

​Submit a score

​Show the board

​Know what a board stores

​Test a board

​Fix a problem

​Fix by error code

​Fix by symptom

​Where next

Update a live game

Read the SDK reference

Before you start

Declare the board

Submit a score

Show the board

Know what a board stores

Test a board

Fix a problem

Fix by error code

Fix by symptom

Where next