一起玩

PlayDrop 游戏的排行榜

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

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

声明排行榜

把它添加到 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"。排行榜需要使用包。

提交和读取分数

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 不提供地区、定时重置、赛季或每周自动发奖。如果想做每周排行榜，请把“周”纳入你自己的设计，例如在新版本中为每个赛季声明一个新键。

相关内容：成就、云存档、分享分数。

一起玩