# PlayDrop 游戏的排行榜

在 catalogue.json 中声明排行榜，用 sdk.leaderboards 提交分数，并显示前几名和玩家附近的排名。包括分数类型、限制和更新规则。

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

排行榜让玩家有理由再玩一次，也有排名可以分享。PlayDrop 会为每个排行榜保存每位玩家的最佳分数，并在游戏中显示。

## 声明排行榜

把它添加到 [catalogue.json](https://www.playdrop.ai/zh-hans/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-hans/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/zh-hans/create/learn/achievements)、[云存档](https://www.playdrop.ai/zh-hans/create/learn/cloud-saves)、[分享分数](https://www.playdrop.ai/zh-hans/create/learn/social)。

## 相关指南

- [成就](https://www.playdrop.ai/zh-hans/create/learn/achievements): 在 catalogue.json 中声明带图标的普通成就和累进成就，并用 sdk.achievements 解锁成就、上报进度。
- [云存档](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 字段：标识、商店页面、游玩方式、显示形态、登录、即玩、预加载、媒体、翻译、分数和服务器。