游戏内排行榜：排名、回合和奖励

玩家看到什么

• 以标签页呈现的榜单：每个都有一张卡片，显示玩家的分数、名次和本回合结束倒计时。
• 排名靠前的玩家，玩家自己会被高亮，前三名有奖牌。
• 弹窗中的名次奖励和积分奖励；积分奖励可以当场领取。
• 上一回合奖励的弹窗：回合结束时自动出现，带“领取”按钮。
• 如果游戏有赚取积分的模式，卡片上会有**“开始”按钮**。
• 有奖励待领取时，标签页上的徽标。

榜单的结构

• 回合。 榜单按周期重复（例如每周），按计划运行，或作为一串回合运行。
• 分数的计算方式。 所有结果之和、最好成绩、最快时间或最后一次的值。
• 名次奖励：回合结束时按名次区间发放：第 1 名、第 2 至 3 名、第 4 至 10 名等等。
• 积分奖励：回合内的里程碑：“本周赚到 1000 积分”。

积分从哪里来

积分来自榜单上设置的来源：

• 游戏提交的结果（ClientScore）。游戏发送一个数字，例如一局跑酷的分数。⚠ 请为这个来源设置限制：单次提交上限、每日上限和两次提交之间的间隔。没有这个来源，榜单根本不接收游戏发来的任何数字。
• 服务器自己统计的事件，例如购买或完成的任务。这些无法在游戏中伪造。

开发者须知

排行榜通过 @idosgames/core 中的 client.leaderboard 工作。

// 提交结果：服务器应用计分规则和限制
const sub = await client.leaderboard.submitScore('weekly_score', 150)
if (!sub.ok) return showError(sub.error)
sub.data.NewScore // 计算后的分数

// 有多个榜单的界面：一次请求获取排名列表和玩家进度
const overview = await client.leaderboard.getOverviewBatch(['weekly_score', 'season_pvp'])

// 领取所有待领奖励：名次奖励和积分奖励
await client.leaderboard.claimAllRewardsBatch(['weekly_score', 'season_pvp'])

• SDK 会直接拒绝零或负数的分数，不发送请求。
• 新分数请从响应中的 NewScore 读取：在“最好成绩”规则下，较差的结果不会改变分数。
• 好友排名是 getFriendsLeaderboard(leaderboardID)。

每个字段都在技能 leaderboard-system 中有说明，由 SDK 的 MCP 服务器提供。