SDK

Leaderboards

Smaz Games keeps leaderboards for your game: fastest times, high scores, or both. You don't need your own server. Players don't need an account: guests are ranked per browser, and signed-in players are ranked once across all their devices.

1. Set up your boards

Open Leaderboards on your game in the developer desk and add a board for each ranking:

Scores sent to a board you haven't set up are refused, so set the boards up before you upload the build that uses them.

2. Send scores and show boards

With the SDK:

// A stage finished in 83.456 seconds.
const result = await OpenArcade.leaderboards.submit('stage-alps-3', 83456, { bike: 'red' });
if (result) showRank(result.rank, result.isBest);

const top = await OpenArcade.leaderboards.get('stage-alps-3', { range: 'week', limit: 10 });
if (top) drawTable(top.entries, top.me);

Without the SDK, include the small leaderboards file instead. Download smaz-leaderboards.js, put it in your ZIP and load it before your game:

<script src="./smaz-leaderboards.js"></script>

await SmazLeaderboards.submitScore('high-score', 12850);
const board = await SmazLeaderboards.getBoard('high-score', { range: 'all', limit: 10 });

Both work the same way and never throw. Outside Smaz Games, offline, in a private preview, or when a score is refused, they resolve to null and the game carries on. In debug mode (?smazDebug=1) the reason is logged to the console.

submit(board, value, meta)

• board: the board ID.
• value: whole milliseconds for time boards, whole points for score boards.
• meta: optional JSON object, 1KB at most, kept with the player's best entry and returned with it. Use it for details such as the vehicle or splits. No personal data.

Resolves to:

{ board: 'stage-alps-3', value: 83456, best: 81020, rank: 4, total: 212, isBest: false, name: 'Neon Comet 42' }

best and rank are the player's all-time best and rank on that board. isBest is true when this score beat their previous best.

get(board, { range, limit })

• range: 'all' (default), 'week' (since Monday, UTC) or 'day' (today, UTC).
• limit: 1–100 entries, default 10.

Resolves to:

{
  board: { id: 'stage-alps-3', title: 'Stage time · stage-alps-3', sort: 'asc', unit: 'ms' },
  range: 'week',
  total: 57,
  entries: [ { rank: 1, entry: 'k3J9…', name: 'speedy_pete', value: 79870, at: '2026-10-25T09:12:44.120Z', meta: { bike: 'blue' }, me: false } ],
  me: { rank: 4, name: 'Neon Comet 42', value: 81020, … } // or null
}

Equal values share a rank. Between equal values, whoever got there first is listed first.

How players are ranked and named

• Each player has one entry per board: their best. Daily and weekly boards use their best that day or week.
• Signed-in players count once across all their devices. Scores they made as a guest in a browser move to their account when they play signed in there.
• Adults appear under their username. Guests, teens and accounts without an age appear under a generated name such as "Neon Comet 42", and so do usernames that don't pass the word filter. Games can't set names.
• The game page shows your boards once they have scores. Players can remove their own scores there at any time. Deleting an account removes its scores.

Cheating

Scores are only accepted from a game being played on Smaz Games: the site adds the current play, and the server takes the game and the player from it, never from your code. The server also refuses:

• values outside the board's range, or not whole numbers;
• times longer than the play has lasted so far, unless the board's times span many sessions;
• points faster than the board's points-per-second limit;
• more than 10 scores a minute from one player on one board, or 30 a minute from one play.

A determined player can still send a fake score from their browser, as on any web leaderboard. Keep the range tight. Open Entries on a board in the developer desk to remove an impossible score.

Test before you upload

In local test mode (see Install the SDK), OpenArcade.leaderboards keeps the best score for each board in your browser as "Test player", so you can test your code. Add ?smazLeaderboardOrder=asc for time boards. smaz-leaderboards.js resolves to null outside Smaz Games. In a private preview on the site, submit resolves to null, and get reads the boards of the published game if there is one.