PlayDrop ゲームのランキング

catalogue.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〜64文字で、英小文字で始まり、そのあとに英小文字、数字、_、.、- が続きます。
• scoreType と sort の組み合わせは2通りです。INTEGER と DESC（大きいほうが勝ち、スコアは0以上）、または TIME_MS と ASC（小さいほうが勝ち、正のミリ秒）。
• unitLabel は任意の表示用テキストです。

公開後は、キーを削除できず、scoreType と sort も変更できません。使うのをやめるには "status": "RETIRED" を指定します。ランキングにはパッケージが必要です。

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();

• スコアは安全な整数です。自己ベストを置き換えるのは、より良いスコアだけです。
• top は1〜100件、aroundMe はプレイヤーの前後それぞれ1〜20件を指定できます。
• list({ includeRetired: true }) は終了したランキングも返します。

スコアは毎フレームではなくプレイの終わりに、play フェーズでだけ送信してください。拒否された呼び出しはほかのネットワーク呼び出しと同じように処理し、ゲームを遊べる状態に保ちましょう。

サインインを確認せずにスコアを送信できます。プレイヤーセッションがまったくない場合、送信は保存されないまま正常終了します。オフライン対応の PlayDrop アプリなど、デバイスデータへの対応を示すホストは、オフラインで出したスコアを保存し、あとで同期します。こうしたホストでのオフライン時の読み取りでは、プレイヤー自身の自己ベストだけが表示され、順位は表示されません。それ以外の環境では、送信にネットワーク接続が必要です。

SDK には、地域、定期リセット、シーズン、週間賞品の自動付与はありません。週間ランキングにしたい場合は、たとえばシーズンごとに新しいバージョンで新しいキーを宣言するなど、週の区切りを自分で設計に組み込んでください。

関連：実績、クラウドセーブ、スコアの共有。