Play together

Leaderboards for PlayDrop games

Declare leaderboards in catalogue.json, submit scores with sdk.leaderboards and show top ranks and the player's neighbors. Score types, limits and update rules.

Leaderboards give players a reason to replay and a rank to share. PlayDrop stores each player's best score per leaderboard and shows it on the game.

Declare a leaderboard

Add it to the app in catalogue.json:

json

{
  "leaderboards": [
    { "key": "high-score", "displayName": "High score", "description": "Most points in one run",
      "scoreType": "INTEGER", "sort": "DESC", "unitLabel": "pts" },
    { "key": "best-time", "displayName": "Fastest run", "description": "Time to reach the flag",
      "scoreType": "TIME_MS", "sort": "ASC" }
  ]
}

key: 3 to 64 characters, starting with a lowercase letter, then lowercase letters, digits, _, . or -.
scoreType and sort come in two pairs: INTEGER with DESC (higher wins, scores of 0 or more) or TIME_MS with ASC (lower wins, positive milliseconds).
unitLabel is optional display text.

Once published, a key cannot be removed and its scoreType and sort cannot change. Stop using one with "status": "RETIRED". Leaderboards need a package.

Submit and read scores

const result = await sdk.leaderboards.submitScore("high-score", 1200);
// { accepted, improved, previousBestScore, bestScore, rank, previousRank, bestScoreAt, leaderboard }
if (result.improved) showNewBest(result.bestScore, result.rank);

const { leaderboard } = await sdk.leaderboards.get("high-score", { top: 10, aroundMe: 3 });
// leaderboard: { definition, top, player, playerEntry, aroundPlayer }

const { leaderboards } = await sdk.leaderboards.list();

Scores are safe integers. Only a better score replaces the best.
top accepts 1 to 100 entries and aroundMe 1 to 20 on each side of the player.
list({ includeRetired: true }) also returns retired boards.

Submit at the end of a run, not every frame, and only in the play phase. Handle rejected calls like any network call; keep the game playable.

Guests and offline

You can submit without checking sign-in. With no player session at all, a submission resolves without being stored. Hosts that advertise device-data support, such as offline-capable PlayDrop apps, keep a score made offline and sync it later; their offline reads show only the player's own best, with no rank. Elsewhere a submission needs a connection.

What leaderboards do not do

There are no regions, scheduled resets, seasons or automatic weekly prizes in the SDK. For a weekly board, include the week in your own design, for example a new key per season declared in a new version.