Asobiai SDK

Leaderboards

Call submitScore once when a play ends and a leaderboard appears on the game page. No server or login system to build.

v2.7.0Check it from your game with window.AIGame?.version.Changelog

The shortest version

js
// Once, on game over (or clear / time up)
function onGameOver() {
  window.AIGame?.submitScore(score);
}
  • If your game has a score, a time or a move count, add one. Leaderboards make people come back.
  • Each logged-in player's personal best is kept (one per player per board, replaced only when it improves).
  • The score is a number (integer or decimal). Very large numbers are shown with units, like 56.95T.

When and how often

  • Once at the end of a play (game over, clear, time up). In a stage-based game, on each stage clear is fine too.
  • Don't send every frame or on every point. Too many in a short time get refused (rate_limited).
  • Scores sent within 3 seconds of starting to play on the game page are refused (too_fast).

Options (order, label, board, note)

js
// Points (higher is better). This is the default order
window.AIGame?.submitScore(1200, { label: "pts" });

// Times and move counts (lower is better): order: "asc"
window.AIGame?.submitScore(42.5, { order: "asc", label: "sec" });

// Separate boards per difficulty (board is the leaderboard's name; up to 5 per game)
window.AIGame?.submitScore(score, { board: "hard", label: "pts" });

// Attach a short note to the score (shown next to the number on the leaderboard)
window.AIGame?.submitScore(score, { note: "B23F" });

// Use the result
const result = await window.AIGame?.submitScore(score);
if (result?.ok) {
  showMessage(`Rank #${result.rank}! Best: ${result.best}`);
} else if (result?.reason === "login_required") {
  showMessage("Log in to get on the leaderboard");
}
  • order: "desc" (higher is better; the default) or "asc" (lower is better: times, moves, misses).
  • label: the unit shown after the number ("pts", "sec", "moves", … up to 32 characters).
  • board: the leaderboard's name ("default" if omitted). Use it to split by difficulty or mode. Up to 5 per game, 32 characters (no @).
  • note: a short note for the score (the floor reached "B23F", a level "Lv12", the stage cleared, … up to 24 characters). It shows next to the number on the leaderboard. The note kept is the one from the personal-best play; it doesn't change when the score doesn't improve.

order and label are fixed when the first score reaches that board; changing them later has no effect. If they're wrong, delete the board in the Leaderboards tab of your game's edit page. It is recreated with the new order and label when the next score arrives.

The result

submitScore returns a result: { ok: true, rank, best } when recorded (rank = current position, best = personal best), or { ok: false, reason }.

reasonMeaning
login_requiredNot logged in. The score is kept in the browser and sent after the player logs in (the game page shows a prompt)
rate_limitedToo many scores in a short time (every frame, every point, …)
too_fastSent within 3 seconds of starting to play
season_resetThe creator started a new season during this play
too_many_boardsMore than 5 boards
online_offSent in an online room while the creator chose “don't record”
preview / testA preview of an unreleased version or an automated test (not recorded)
replayA leaderboard replay is playing (not recorded)
unavailable / network / timeoutOpened outside Asobiai, or the request failed

Where the leaderboard shows

  • Below the game on the game page. There's no function to read the list from inside the game right now, so don't build your own ranking in the game (one in localStorage can't show anyone else's scores).
  • Showing “#3!” or “New personal best” in the game from the returned rank and best is fine.
  • If you spot a fake score, delete it from the Leaderboards tab of your game's edit page.

Common mistakes

js
// ✗ Sending every frame or on every point (refused with rate_limited)
function update() { window.AIGame?.submitScore(score); }

// ✗ A time without order (creates a higher-is-better board)
window.AIGame?.submitScore(seconds);

// ✗ Building your own ranking in localStorage (nobody else's scores show up)
localStorage.setItem("ranking", JSON.stringify(myScores));

// ✓ Once per play. Times use order: "asc"
function onClear() { window.AIGame?.submitScore(seconds, { order: "asc", label: "sec" }); }

Seasons (resetting the leaderboard)

When you change difficulty or rules so old scores are no longer comparable, start a new season (the Leaderboards tab of the edit page, “Reset the leaderboard” on a new version, or reset_ranking in update_game via MCP / the API). Previous seasons are kept on the game page. Scores from plays started before the new season are not recorded (season_reset).

Scores from online play

Scores sent while the player is in an online room (joinRoom) are detected by the SDK and go to a separate "Online" leaderboard (no code changes). Choose "separate", "same" or "don't record" in the Leaderboards tab of the edit page (online_scores in MCP / the API). Pass-and-play on one screen can't be detected, so split it with board.

Replays (watch from the leaderboard)

Pass replay (a record of the inputs) to submitScore. When it's a personal best in the top 20, it's kept and a ▶ appears on that leaderboard entry. Anyone can press it to watch the play on the game page. It's not a video: the game rebuilds the same play from the record.

js
// Recording: keep each step's input (and the seed)
const log = [];
function step() {
  const input = readInput();      // keys, touch position, …
  log.push(input);
  world.update(input);            // a fixed number of steps per second, e.g. 60
}
function onGameOver() {
  window.AIGame?.submitScore(score, { replay: { seed, log } });
}

// Playback: when opened from ▶ on the leaderboard
if (window.AIGame?.replaying) {
  const r = await window.AIGame.getReplay();
  if (r) {
    // r.score points by r.player.name
    startWorld(r.data.seed);
    for (const input of r.data.log) world.update(input); // in practice one per step
  }
}
  • The game must play out the same way for the same inputs. Step a fixed number of times per second (not per screen refresh), use a seeded random generator and put the seed in the record (keep purely visual randomness separate), and don't use the clock (Date.now, …) for gameplay. Math.sin and friends can differ in the last digit between browsers, so long plays are safest with your own implementations.
  • Opening from ▶ loads the version the play was recorded on and sets AIGame.replaying to true. AIGame.getReplay() returns { data, score, board, version, player: { name, handle } } (data is what you passed to submitScore).
  • While replaying, submitScore, unlockAchievement, tally and save record nothing, and anything the game writes to localStorage stays inside that page; the viewer's data is untouched.
  • Up to 512 KB as JSON. The result's replay says "saved", "rank" (below 20th) or "too_large". Not available for scores from online rooms or guest scores sent after logging in.

Checking it works

  • After publishing, play while logged in. If your score shows in the leaderboard below the game after game over, it works.
  • check_game (with steps) and test_multiplayer via MCP list the scores the game sent (scores from automated tests are not recorded).
  • For games made with Godot or Unity, see calling the SDK from an engine.
What to tell your AI

The game has a score or time, so add an Asobiai leaderboard. When a play ends (game over, clear, time up) call window.AIGame?.submitScore(score, { label: "pts" }) exactly once (use ?. so it doesn't fail where AIGame is missing). For things where lower is better, like times or move counts, pass { order: "asc", label: "sec" } (order and label are fixed by the first score, so get them right from the start). Don't send every frame or on every point. The leaderboard appears on the game page, so don't build your own ranking inside the game; you may show "#n" or "personal best" from the returned { ok, rank, best }.