# PlayDrop ゲームのランキング

catalogue.json でランキングを宣言し、sdk.leaderboards でスコアを送信して、上位とプレイヤー周辺の順位を表示します。スコアの種類、制限、更新のルールも説明します。

Source: https://www.playdrop.ai/ja/create/learn/leaderboards

ランキングは、プレイヤーにもう一度遊ぶ理由と、共有したくなる順位を与えます。PlayDrop はランキングごとに各プレイヤーの自己ベストを保存し、ゲーム上に表示します。

## ランキングを宣言する

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

公開後は、キーを削除できず、`scoreType` と `sort` も変更できません。使うのをやめるには `"status": "RETIRED"` を指定します。ランキングには[パッケージ](https://www.playdrop.ai/ja/create/learn/packaging)が必要です。

## スコアの送信と読み取り

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

関連：[実績](https://www.playdrop.ai/ja/create/learn/achievements)、[クラウドセーブ](https://www.playdrop.ai/ja/create/learn/cloud-saves)、[スコアの共有](https://www.playdrop.ai/ja/create/learn/social)。

## 関連ガイド

- [実績](https://www.playdrop.ai/ja/create/learn/achievements): catalogue.json でアイコン付きの通常実績と段階実績を宣言し、sdk.achievements で実績の解除と進行状況の報告を行います。
- [クラウドセーブ](https://www.playdrop.ai/ja/create/learn/cloud-saves): sdk.me.appData と sdk.me.updateAppData でプレイヤーの進行状況を保存・読み込みます。ゲストとサインイン中のプレイヤーへの対応、書き込み、プレビュー、オフラインのルールも説明します。
- [catalogue.json](https://www.playdrop.ai/ja/create/learn/catalogue-json): PlayDrop ゲームが使う catalogue.json のフィールド：識別情報、掲載情報、遊び方、表示環境、サインイン、インスタント、事前読み込み、メディア、翻訳、スコア、サーバー。