概览

Steam 支持自动排序并持续更新的排行榜。 这些排行榜可以用来在您的游戏和您的社区网页上显示全球及好友排行榜。 每个 Steamworks 游戏最多可以创建 10,000 个排行榜，并且在玩家分数提交后，可以立即检索对应的排行榜。

每位玩家在每个排行榜上可有一个条目。 每个排行榜玩家人数不限。 每个条目都包含排行榜的分数（int32）和最多可达 64 个 int32 的关联数据（可选）。 这些关联数据可用于储存与用户产生排行榜条目时的游戏会话有关的具体信息。 Steam 不会对此数据进行排序或解析。当用户创建了新的排行榜条目后，旧的数据就会被替换。

ISteamUserGameStats.h 包含所有排行榜函数。Steamworks 示例中也展示了两个样本排行榜。 您可在 Steamworks 游戏管理员中查阅并管理您的排行榜。

准备事项

所有异步排行榜函数都会返回一个指向 Steam API 调用结果的句柄。 请参见“入门指南”文档中的调用结果部分，了解有关如何获取这些结果的更多信息。

创建排行榜

排行榜专属于各个应用程序，必须使用 Steamworks 合作伙伴站点的游戏管理员页面或通过 API 进行设置。

通过网页创建

您可以在 Steamworks 应用管理员页面中，前往统计&成就->排行榜，为您的 app ID 创建和管理排行榜。


要定义排行榜，必须填写以下字段：

• 名称：内部开发可用的合理名称。
  
• 社区名称：如要在社区中心显示此排行榜，在此设置公开显示的名称。 如未输入名称，则该排行榜将不会显示。
  
• 排序方式：设置排行榜的排列顺序。 对于基于排位的排行榜，请使用升序。 对于高分排行榜，请使用降序。
  
• 显示类型：决定排行榜显示的数据类型。 可选择数字、秒或毫秒。
  
• 写入：如果此项设置为“可信任”，则排行榜分数不能由客户端设置，只能通过 SetLeaderboardScore WebAPI 来设置。 默认为 false。
  
• 读取：如设置为“好友”，则游戏只能读取该用户好友的排行榜分数（但 WebAPI 始终可以读取所有分数）。 默认为 false。

通过 API 创建

您可以通过 Steamworks 应用管理员创建您游戏的排行榜，或者也可以通过调用 ISteamUserStats::FindOrCreateLeaderboard 以编程方式创建。 在 Steam 中，每款 Steamworks 游戏的各排行榜均通过一个唯一名称进行识别。 排行榜名称仅在 Steamworks API 中起识别作用，不会在 Steam 社区向用户显示。 创建排行榜时，您需要选择：

• 排序方式：k_ELeaderboardSortMethodAscending （排名第一的是分数最低的用户）或 k_ELeaderboardSortMethodDescending（排名第一的是分数最高的用户）。
  
• 显示类型：ELeaderboardDisplayType 用来说明排行榜分数代表的意义，且仅被社区用于编排排行榜分数的显示格式。

如选择仅通过应用管理员来创建排行榜，则可使用 ISteamUserStats::FindLeaderboard 来获取排行榜句柄。 FindLeaderboard 与 FindOrCreateLeaderboard 均为异步方法，并通过 ISteamUserStats::LeaderboardFindResult_t 调用结果为特定排行榜返回句柄。

创建排行榜后，您可以通过游戏管理员修改排行榜的排序方式和显示类型。 当对已存在排行榜调用 FindOrCreateLeaderboard 时，排序方法和显示类型参数将被忽略。

上传分数

如要上传分数至排行榜，只需调用 ISteamUserStats::UploadLeaderboardScore 传入目标排行榜句柄（通过 FindLeaderboard 获取）、用户分数，以及在设置新分数时产生的关联数据（可选）。 用户排行榜分数更新完毕后，传入 ISteamUserStats::UploadLeaderboardScore 的关联数据将替换掉之前存储的任何数据。 上传用户排行榜分数时，有两种更新方式可选择：

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest：Steam 会将用户的新分数与其在排行榜中已存储的分数进行比较，并保留用户的最佳分数（对于升序排序的排行榜，保留最低分；对于降序排序的排行榜，保留最高分）。
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate：Steam 始终会以新分数替换排行榜中原有分数。
  
• ISteamUserStats::UploadLeaderboardScore 为异步调用，在 LeaderboardScoreUploaded_t 调用结果中返回上传结果。 该结果对已更改的用户分数进行标示，并包含用户的新旧全球排名。 上传后，Steamworks 排行榜将立刻更新以反映新分数，新的条目顺序可通过 DownloadLeaderboardEntries 获得。

附加用户生成内容

分数上传后，您可选择是否为该条目附加用户生成内容， 只须调用 ISteamUserStats::AttachLeaderboardUGC 即可。该内容可为用户取得成绩时的回放，或是可以与之比赛的幽灵记录。 当条目被成功检索时，其关联的句柄将变为可用状态，并可被其他用户下载。 如需创建和下载用户生成内容，请见 Steam 云的相关文献。

内容一经添加后，即使基础云文件有更改或被用户删除，内容仍将可用。

获取排行榜条目

ISteamUserStats::DownloadLeaderboardEntries 用于通过 ISteamUserStats::FindLeaderboard 获取到的排行榜句柄来检索排行榜条目。

您通过 GetDownloadedLeaderboardEntry 检索所有已下载的条目后，这些条目的数据就会被释放，而 LeaderboardScoresDownloaded_t 中的 SteamLeaderboardEntries_t 也将不再有效。

获取排行榜信息

您可用 FindLeaderboard 返回的排行榜句柄通过以下 API 获取排行榜信息：

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType