---
name: ineed-leaderboards
description: 将真实游戏开局和结算接入 iNeed 世界、省、市排行榜，支持平台界面、自绘榜单、成绩冻结及重试。
---
# 排行榜

先确定真实开局、结算和评分代码，再接入。模拟数值只用于隔离测试，不写入正式榜单。

## 确认榜单规则

必填：boardKey、名称、分数公式与单位、升序/降序、合法分数范围、合法耗时、真实开局及结算事件。可选：世界/省/市、同分规则、赛季和重置要求。平台不支持的配置标记待办，不能在游戏里悄悄替换排序或修改已发布规则。

## 数据流

1. leaderboards.list 得到 value.boards 和 profile，确认目标 boardKey 存在。不要拿商品 key 当榜单 key。
2. 真正开始一局时生成唯一 runId，并保存身份、开始时间和规则版本；暂停计时是否计入按确认规则处理，不能临时重算。
3. 结束一次冻结 boardKey/runId/score/durationMs，可选 endedAt/stats。需要登录时保存该结算，登录后仍提交原数据，不生成新成绩。
4. leaderboards.submit 成功读取 value.receipt，显示个人最佳和排名。网络失败后复用冻结数据重试；身份已换则停止旧局提交到新账号。
5. 展示自绘榜单用 leaderboards.get，平台榜单用 open_leaderboard；详情见[接口手册](../../../guides/integration/api.md)。

## 自绘与平台界面

自绘时显示榜单标题、世界/省/市切换、名次、昵称、成绩、自己的最好成绩及分页。昵称与头像使用返回资料并提供空值占位，字体覆盖动态中文。地区缺失时提示选择或显示世界榜，不能静默把城市榜换成另一个地区。

平台 UI 接收 boardKey/scope，负责现成列表；真实成绩提交仍需游戏代码。leaderboards.profile 返回档案；leaderboards.region 使用合法地区代码更新地区。v1 Godot 未提供地区目录查询包装，不虚构接口；自绘地区选择需平台确认可用代码来源。

## 失败与反作弊边界

未登录、榜单不存在、范围错误、成绩/耗时不合法、地区修改限制、账号变化均显示实际失败，不能声称“上传成功”。保留冻结结算供符合条件时重试，不循环刷榜。客户端提交分数不是防作弊证明；高价值竞技需要额外的服务端玩法验证，不能承诺 SDK 自动防改分。

## 验收

同一 runId 重试不产生新局次；篡改同一 runId 的数据被拒绝；真实耗时和分数符合配置；切账号后不串数据；空榜、分页、世界/省/市和中文昵称正常；平台 UI 与自绘 UI 看到同一配置。交付真实入口、计分说明、请求/回执及未验证项。