# PlayDrop 游戏的成就

在 catalogue.json 中声明带图标的普通成就和累进成就，并用 sdk.achievements 解锁成就、上报进度。

Source: https://www.playdrop.ai/zh-hans/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-hans/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-hans/create/learn/leaderboards): 在 catalogue.json 中声明排行榜，用 sdk.leaderboards 提交分数，并显示前几名和玩家附近的排名。包括分数类型、限制和更新规则。
- [云存档](https://www.playdrop.ai/zh-hans/create/learn/cloud-saves): 用 sdk.me.appData 和 sdk.me.updateAppData 保存和读取玩家进度，适用于访客和已登录玩家，并了解写入、预览和离线游玩的规则。
- [catalogue.json](https://www.playdrop.ai/zh-hans/create/learn/catalogue-json): PlayDrop 游戏使用的 catalogue.json 字段：标识、商店页面、游玩方式、显示形态、登录、即玩、预加载、媒体、翻译、分数和服务器。