# PlayDrop 遊戲的排行榜

在 catalogue.json 中宣告排行榜，用 sdk.leaderboards 提交分數，並顯示前幾名與玩家周邊的排名。包含分數類型、限制與更新規則。

Source: https://www.playdrop.ai/zh-hant/create/learn/leaderboards

排行榜讓玩家有理由重玩，也有排名可以分享。PlayDrop 會儲存每位玩家在每個排行榜上的最佳分數，並顯示在遊戲上。

## 宣告排行榜

將它加入 [catalogue.json](https://www.playdrop.ai/zh-hant/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/zh-hant/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 App）會保留離線時取得的分數，並在之後同步；它們的離線讀取只會顯示玩家自己的最佳成績，沒有排名。在其他地方，提交需要網路連線。

## 排行榜不做的事

SDK 中沒有地區、定時重設、賽季或自動發放的每週獎品。若要每週排行榜，請在你自己的設計中納入週次，例如每個賽季在新版本中宣告一個新的鍵。

相關：[成就](https://www.playdrop.ai/zh-hant/create/learn/achievements)、[雲端存檔](https://www.playdrop.ai/zh-hant/create/learn/cloud-saves)、[分享分數](https://www.playdrop.ai/zh-hant/create/learn/social)。

## 相關指南

- [成就](https://www.playdrop.ai/zh-hant/create/learn/achievements): 在 catalogue.json 中宣告附圖示的標準成就與累進成就，並用 sdk.achievements 解鎖成就及回報進度。
- [雲端存檔](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 欄位：身分、上架資訊、遊玩方式、顯示環境、登入、即玩、預先載入、媒體、翻譯、分數與伺服器。