# PlayDrop 게임의 업적

catalogue.json에 아이콘이 있는 일반 업적과 누적 업적을 선언하고, sdk.achievements로 잠금 해제하고 진행 상황을 기록하세요.

Source: https://www.playdrop.ai/ko/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/ko/create/learn/leaderboards) 키와 같은 형식을 따릅니다.
- `kind`는 `STANDARD`(한 번 잠금 해제) 또는 `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이므로 직접 만든 알림을 한 번만 보여 줄 수 있습니다.
- `list({ includeHiddenDefinitions: true, includeRetired: true })`는 숨김 업적과 종료된 업적의 정의도 포함합니다.

잠금 해제는 실제 플레이 중에만 하고, 미리 보기나 캡처 중에는 절대 하지 마세요. 플레이어 세션이 전혀 없으면 호출은 완료되지만 저장되지 않습니다.

## 좋은 업적 만들기

게임을 익히게 해 주는 초반 업적과 장기 목표를 섞으세요. 보상이 아니라 행동을 이름으로 붙이세요. "피해를 입지 않고 승리하기"는 무엇을 해야 하는지 알려 줍니다. 잘 고민한 업적 10여 개가 사소한 업적 100개보다 낫습니다.

## 관련 가이드

- [순위표](https://www.playdrop.ai/ko/create/learn/leaderboards): catalogue.json에 순위표를 선언하고, sdk.leaderboards로 점수를 제출하고, 상위 순위와 플레이어 주변 순위를 보여 주세요. 점수 유형, 제한, 업데이트 규칙도 담았습니다.
- [클라우드 저장](https://www.playdrop.ai/ko/create/learn/cloud-saves): sdk.me.appData와 sdk.me.updateAppData로 게스트와 로그인한 플레이어의 진행 상황을 저장하고 불러오세요. 쓰기, 미리 보기, 오프라인 플레이 규칙도 담았습니다.
- [catalogue.json](https://www.playdrop.ai/ko/create/learn/catalogue-json): PlayDrop 게임이 쓰는 catalogue.json 필드: 식별 정보, 등록 정보, 플레이 방식, 화면, 로그인, 인스턴트, 미리 로드, 미디어, 번역, 점수, 서버.