# PlayDrop 게임의 순위표

catalogue.json에 순위표를 선언하고, sdk.leaderboards로 점수를 제출하고, 상위 순위와 플레이어 주변 순위를 보여 주세요. 점수 유형, 제한, 업데이트 규칙도 담았습니다.

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

순위표는 플레이어에게 다시 플레이할 이유와 공유할 순위를 줍니다. PlayDrop은 순위표마다 플레이어별 최고 점수를 저장하고 게임에 표시합니다.

## 순위표 선언하기

[catalogue.json](https://www.playdrop.ai/ko/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`는 두 가지 조합만 있습니다. `INTEGER`와 `DESC`(높을수록 승리, 0 이상의 점수) 또는 `TIME_MS`와 `ASC`(낮을수록 승리, 양의 밀리초).
- `unitLabel`은 선택 사항인 표시 텍스트입니다.

한 번 게시한 키는 삭제할 수 없으며 `scoreType`과 `sort`도 바꿀 수 없습니다. 더 이상 쓰지 않으려면 `"status": "RETIRED"`로 종료하세요. 순위표에는 [패키지](https://www.playdrop.ai/ko/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/ko/create/learn/achievements), [클라우드 저장](https://www.playdrop.ai/ko/create/learn/cloud-saves), [점수 공유하기](https://www.playdrop.ai/ko/create/learn/social).

## 관련 가이드

- [업적](https://www.playdrop.ai/ko/create/learn/achievements): catalogue.json에 아이콘이 있는 일반 업적과 누적 업적을 선언하고, sdk.achievements로 잠금 해제하고 진행 상황을 기록하세요.
- [클라우드 저장](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 필드: 식별 정보, 등록 정보, 플레이 방식, 화면, 로그인, 인스턴트, 미리 로드, 미디어, 번역, 점수, 서버.