# PlayDrop 遊戲的成就

在 catalogue.json 中宣告附圖示的標準成就與累進成就，並用 sdk.achievements 解鎖成就及回報進度。

Source: https://www.playdrop.ai/zh-hant/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/zh-hant/create/learn/leaderboards)的鍵相同。
- `kind` 為 `STANDARD`（解鎖一次）或 `INCREMENTAL`（進度達到 `maxProgress` 時解鎖，`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，讓你自己的提示通知只顯示一次。
- `list({ includeHiddenDefinitions: true, includeRetired: true })` 會包含隱藏與已停用的定義。

只在真正遊玩時解鎖，絕不要在預覽或擷取時解鎖。完全沒有玩家工作階段時，呼叫會正常完成，但不會儲存。

## 好的成就

混合教玩家熟悉遊戲的早期成就與長期目標。用動作命名，而不是用獎勵命名：「無傷獲勝」直接說明要做什麼。十來個用心設計的成就，勝過一百個瑣碎的成就。

## 相關指南

- [排行榜](https://www.playdrop.ai/zh-hant/create/learn/leaderboards): 在 catalogue.json 中宣告排行榜，用 sdk.leaderboards 提交分數，並顯示前幾名與玩家周邊的排名。包含分數類型、限制與更新規則。
- [雲端存檔](https://www.playdrop.ai/zh-hant/create/learn/cloud-saves): 用 sdk.me.appData 與 sdk.me.updateAppData 儲存及載入玩家進度，適用於訪客與已登入玩家，並說明寫入、預覽與離線遊玩的規則。
- [catalogue.json](https://www.playdrop.ai/zh-hant/create/learn/catalogue-json): PlayDrop 遊戲使用的 catalogue.json 欄位：身分、上架資訊、遊玩方式、顯示環境、登入、即玩、預先載入、媒體、翻譯、分數與伺服器。