Steamworks 文献库
Steam 排行榜

概览

Steam 支持按条目自动排序并永久保留的排行榜。 这些排行榜可以用来在您的游戏和您的社区网页上显示全球及好友排行榜。 每款 Steamworks 产品可创建多达 1 万个排行榜,且均可在新插入玩家分数后立即获取。

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

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

准备事项

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

创建排行榜

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

在网页创建

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

要定义排行榜,必须填写以下字段:
  • 名称:内部开发可用的合理名称。
  • 社区名称:如要在社区中心显示此排行榜,在此设置公开显示的名称。 如未输入名称,则该排行榜将不会显示。
  • 排序方式:设置排行榜的排列顺序。 按名次的排行榜请使用升序。 高分榜请使用降序。
  • 显示类型:决定排行榜显示的数据类型。 可选择数字、秒或毫秒。
  • 写入:如设置为“可信任”,客户端便无法设置排行榜分数,只能通过 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::AttachLeaderboardUGC 即可。该内容可为用户取得成绩时的回放,或是可以与之比赛的过程记录。 获取条目时也可获得附加的句柄,其他用户也可下载该句柄。 如需创建和下载用户生成内容,请见 Steam 云的相关文献。

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

获取排行榜条目

可使用通过 ISteamUserStats::FindLeaderboard 获得的排行榜句柄在 ISteamUserStats::DownloadLeaderboardEntries 中获取排行榜条目。

获取来自 GetDownloadedLeaderboardEntry 的所有条目后,条目数据将会释放,而 LeaderboardScoresDownloaded_t 内的 SteamLeaderboardEntries_t 将失效。

获取排行榜信息

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

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