Asobiai SDK

ランキング

1回のプレイが終わったときに submitScore を1回呼ぶだけで、ゲームページにランキングが出ます。サーバーやログインの仕組みを作る必要はありません。

v2.4.0ゲームの中からは window.AIGame?.version で確認できます。更新履歴

いちばん短い使い方

// ゲームオーバー (またはクリア・時間切れ) のときに、1回だけ
function onGameOver() {
  window.AIGame?.submitScore(score);
}

スコア・タイム・手数のどれかがあるゲームなら、付けておくのがおすすめです。ランキングがあると、くり返し遊ばれやすくなります。
記録されるのは、ログインしている人の自己ベストです（ランキングごとに1人1つ。良くなったときだけ上書き）。
スコアは数（整数でも小数でもよい）。とても大きな数は「56.95兆」のように単位を付けて表示します。

いつ・何回呼ぶか

1回のプレイの終わり（ゲームオーバー・クリア・時間切れ）に1回。ステージ制なら、ステージをクリアしたときでもかまいません。
毎フレームや、点が入るたびには送らないでください。短い時間にたくさん送ると断られます（rate_limited）。
ゲームのページで遊び始めてから3秒たたないうちに送ったスコアは受け付けません（too_fast）。

オプション（order・label・board）

// 点数 (大きいほど上位)。order を省くとこれ
window.AIGame?.submitScore(1200, { label: "点" });

// タイム・手数 (小さいほど上位) は order: "asc"
window.AIGame?.submitScore(42.5, { order: "asc", label: "秒" });

// 難易度ごとに分ける (board はランキングの名前。1ゲーム5つまで)
window.AIGame?.submitScore(score, { board: "hard", label: "点" });

// 結果を受け取る
const result = await window.AIGame?.submitScore(score);
if (result?.ok) {
  showMessage(`${result.rank}位！ 自己ベスト ${result.best}`);
} else if (result?.reason === "login_required") {
  showMessage("ログインするとランキングに載ります");
}

order: "desc"（大きいほど上位。省いたときはこれ）か "asc"（小さいほど上位。タイム・手数・ミスの数など）。
label: 数のうしろに出す単位（"点"・"秒"・"手" など。32文字まで）。
board: ランキングの名前（省くと "default"）。難易度やモードごとに分けたいときに使います。1ゲーム5つまで、32文字まで（@ は使えません）。

order と label は、そのランキングに最初のスコアが入ったときに決まり、あとから送るときに変えても変わりません。間違えたときは、ゲームの編集画面の「ランキング」タブで、そのランキングを削除してください。次にスコアが届いたときに、新しい order と label で作り直されます。

結果（返ってくるもの）

submitScore は結果を返します。記録できたら { ok: true, rank, best }（rank は今の順位、best は自己ベスト）、できなかったら { ok: false, reason } です。

reason	わけ
login_required	ログインしていない。スコアはブラウザに預かり、ログインしたあとにランキングへ送ります（ゲームのページに案内が出ます）
rate_limited	短い時間にたくさん送った（毎フレーム・点が入るたびなど）
too_fast	遊び始めてから3秒たたないうちに送った
season_reset	このプレイのあいだに、作者がランキングを新しいシーズンにした
too_many_boards	board が5つをこえた
online_off	オンラインの部屋で出したスコアで、作者が「記録しない」にしている
preview / test	公開前のバージョンのプレビュー・自動テスト（記録しない）
unavailable / network / timeout	Asobiai の外で開いている・通信できなかった

よくある間違い

// × 毎フレームや、点が入るたびに送る (rate_limited で断られる)
function update() { window.AIGame?.submitScore(score); }

// × タイムなのに order を付けない (大きいほど上位のランキングができてしまう)
window.AIGame?.submitScore(seconds);

// × 自分で localStorage にランキングを作る (ほかの人の記録が見えない)
localStorage.setItem("ranking", JSON.stringify(myScores));

// ○ 区切りで1回。タイムは order: "asc"
function onClear() { window.AIGame?.submitScore(seconds, { order: "asc", label: "秒" }); }

シーズン（ランキングのリセット）

難易度やルールを変えて前の記録と比べられなくなったときは、ランキングを新しいシーズンにできます（編集画面の「ランキング」タブ、新しいバージョンの「ランキングをリセットする」、MCP / API の update_game の reset_ranking）。前のシーズンの記録は消えずに、ゲームページの「前のシーズンのランキング」に残ります。新しいシーズンになる前に始めたプレイのスコアは記録されません（season_reset）。

オンライン対戦のスコア

オンラインの部屋（joinRoom）に入っているあいだに送ったスコアは、SDK が自動で見分けて、ひとりで遊んだときとは別の「オンライン」のランキングに入ります（ゲームのコードはそのまま）。編集画面の「ランキング」（MCP / API の online_scores）で「別々にする」「同じにする」「記録しない」を選べます。1台の画面を何人かで回すような遊び方は見分けられないので、board で分けてください。

確かめ方

公開してから、ログインした状態で遊んでみてください。ゲームオーバーのあとに、ゲームの下のランキングに自分のスコアが出れば動いています。
MCP の check_game（遊ぶ手順つき）や test_multiplayer の結果には、送ったスコアが出ます（自動テストのスコアはランキングに入りません）。
Godot や Unity で作ったゲームは、ゲームエンジンから呼ぶ方法を見てください。

AIに伝えるときの文面

スコアやタイムがあるゲームなので、Asobiai のランキングを付けてください。1回のプレイが終わったとき（ゲームオーバー・クリア・時間切れ）に、window.AIGame?.submitScore(スコア, { label: "点" }) を1回だけ呼んでください（AIGame が無い環境でもエラーにならないよう ?. を付ける）。タイムや手数のように小さいほど良いものは { order: "asc", label: "秒" } を付けてください（order と label は最初の1回で決まるので、最初から正しく付ける）。毎フレームや点が入るたびには送らないでください。ランキングはゲームページに出るので、ゲームの中に自分でランキングを作る必要はありません。返ってくる { ok, rank, best } を使って「○位」「自己ベスト」を出すのはかまいません。

いちばん短い使い方

いつ・何回呼ぶか

オプション（order・label・board）

結果（返ってくるもの）