# PlayDrop ゲームの実績

catalogue.json でアイコン付きの通常実績と段階実績を宣言し、sdk.achievements で実績の解除と進行状況の報告を行います。

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

実績はゲーム内の目標を示すもので、プレイヤーが PlayDrop で目にするアイコンと説明が付きます。ゲストにも、サインイン中のプレイヤーにも使えます。

## 実績を宣言する

```json
{
  "achievements": [
    { "key": "first-win", "displayName": "First flag", "description": "Reach the flag once",
      "kind": "STANDARD", "icon": "achievements/first-win.png" },
    { "key": "collector", "displayName": "Collector", "description": "Collect 100 stars",
      "kind": "INCREMENTAL", "maxProgress": 100, "icon": "achievements/collector.png" },
    { "key": "secret-room", "displayName": "Secret room", "description": "Find the hidden room",
      "kind": "STANDARD", "hidden": true, "icon": "achievements/secret-room.png" }
  ]
}
```

- `key` は[ランキング](https://www.playdrop.ai/ja/create/learn/leaderboards)のキーと同じ形式です。
- `kind` は `STANDARD`（1回で解除）または `INCREMENTAL`（進行状況が正の整数 `maxProgress` に達すると解除）です。
- `icon` はパッケージ内の PNG です。小さく表示しても見分けやすい、はっきりした正方形の画像を使いましょう。
- `hidden: true` にすると、解除されるまで名前と説明を秘密にできます。

公開済みのキーは削除できず、`kind`、`maxProgress`、`hidden` も変更できません。実績を終了するには `"status": "RETIRED"` を指定します。

## 解除と進行状況の報告

```js
await sdk.achievements.unlock("first-win");
await sdk.achievements.setProgressAtLeast("collector", starsCollected);

const { achievements } = await sdk.achievements.list();
const { achievement } = await sdk.achievements.get("collector");
```

- `setProgressAtLeast` には、その時点までの合計値を渡します。差分は絶対に渡しません。進行状況は増えるだけで、`maxProgress` が上限となり、そこに達すると解除されます。
- どちらの呼び出しも `{ accepted, changed, unlocked, progress, unlockedAt, achievement }` を返します。新しく何も起きなかったときは `changed` が false になるので、独自の通知を1回だけ表示できます。
- `list({ includeHiddenDefinitions: true, includeRetired: true })` は、隠し実績と終了した実績の定義も含めて返します。

解除は実際のプレイ中だけに行い、プレビューやキャプチャでは絶対に行わないでください。プレイヤーセッションがまったくない場合、呼び出しは保存されないまま正常終了します。

## 良い実績とは

ゲームの遊び方を教える序盤の実績と、長期的な目標を組み合わせましょう。名前には報酬ではなく行動を入れます。「ノーダメージで勝利する」なら、何をすればよいかが伝わります。よく考えた十数個の実績は、ありきたりな100個に勝ります。

## 関連ガイド

- [ランキング](https://www.playdrop.ai/ja/create/learn/leaderboards): catalogue.json でランキングを宣言し、sdk.leaderboards でスコアを送信して、上位とプレイヤー周辺の順位を表示します。スコアの種類、制限、更新のルールも説明します。
- [クラウドセーブ](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 のフィールド：識別情報、掲載情報、遊び方、表示環境、サインイン、インスタント、事前読み込み、メディア、翻訳、スコア、サーバー。