Leaderboards Interface

借助 排行榜接口（Leaderboards Interface），使用 Epic在线服务 （EOS）的开发人员能够对整个玩家群的分数进行排名，以便玩家可以与朋友或全球其他玩家竞争最高分。每款游戏可以支持创建多个排行榜，从不同来源收集分数，并以不同的评分模式进行排名。

要访问排行榜接口，请通过平台接口函数 EOS_Platform_GetLeaderboardsInterface 获取 EOS_HLeaderboards 句柄。所有排行榜接口函数都需要将此句柄作为第一个参数。你必须确保 EOS_HPlatform 句柄正在更新函数，以便在操作完成时触发相应的回调。

在你能够访问游戏排行榜前，你必须使用开发人员门户设置排行榜将跟踪的统计数据（有关更多信息，参见统计数据接口），并定义排行榜本身。定义排行榜涉及指定以下内容：

• 排行榜跟踪的统计数据（或分数）

• 排行榜用于进行玩家排名的方法

• 排行榜总生命周期的起止时间

设置统计数据和排行榜后，可以通过EOS SDK访问。

EOS排行榜由我们的EOS统计数据系统驱动。每个排行榜将特定数据用作其跟踪的分数。详见统计数据接口。

EOS排行榜接口支持查询全球排名数据和未排名朋友数据。我们系统中的任何统计数据都可以用作好友、战队或其他基于组的排行榜，只需查询单个玩家的统计数据即可查看。另一方面，全球排行榜需要进行特定配置。出于可延展性原因，我们限制了你可以拥有的全球排行榜数量以及我们跟踪的排行榜的实际条目数量。我们不跟踪整个全球排行榜，而是只跟踪排名前1000（+1000溢出）的分数。我们保留了额外的1000个条目，因为开发人员可能会（出于作弊、代练、隐私性选择退出或任何其他原因）选择从排行榜中删除某些条目，因此我们保留额外的值，以便在删除后填补前1000个条目。虽然只跟踪前1000名条目的决定意味着，大多数玩家不会在排行榜上看到自己，但我们认为这是好事，因为全球排行榜只提供顶级玩家的数值。好友排行榜和其他小型封闭群组为玩家提供了更多互动性和价值，让他们能够通过有意义的反馈实现合理的目标。

每个排行榜都引用了许多统计数据里程碑，以便对准确计算排行榜状态所需的统计数据聚合进行分类。单个用户可以拥有的排行榜数量取决于给定用户账号允许包含多少统计数据里程碑。下表描述了每个排行榜类型的这种关系（目前仅支持一种类型）：

创建排行榜时，会相对于用户自己定义/为用户定义的现有里程碑集引用（读取：复用）或创建里程碑。例如，一个单例排行榜定义为在10月31日08:00 - 16:00之间对玩家就 stat total_apples_collected （SUM）进行排名。创建此排行榜时，假定当前不存在里程碑，将创建以下里程碑：

使用08:00到16:00之间的时间戳为 total_apples_collected 生成的统计数据将被聚合为每个playerId的单个总和值。然后，所有玩家的这些值将在我们定义的单例排行榜中排名。

为了突显里程碑复用，接下来假定我们有另一个统计数据 total_pumpkins_collected，我们希望在同一时间段内有第二个单例排行榜。 创建此新排行榜将引用/复用为 total_apples_collected 创建的相同里程碑，而不会进一步减少可用里程碑的数量。

当没有排行榜引用里程碑时，系统会自动删除里程碑。

汇总：

• 全球总排行榜：受可用里程碑的限制（参见上文）

• 里程碑数量上限（默认）：100

• 全球排行榜条目总数：1000（+1000溢出）

排行榜接口提供多种评分方法，以便适应不同类型的游戏或排名系统。你的排行榜可以根据 分数聚合类型 计算分数并进行排名。你为排行榜使用的聚合类型，必须与指定给它的统计数据使用的聚合类型相同。可用分数聚合类型如下：

此外，你需要提供统计数据的名称，供排行榜用作分数值。

要访问排行榜信息，你将需要排行榜ID。你可以从开发人员门户获取这些信息，并将它们直接添加到游戏，也可以查询EOS SDK，了解与游戏关联的所有排行榜列表。为此，请使用通过以下信息初始化的 EOS_Leaderboards_QueryLeaderboardDefinitionsOptions 结构体调用 EOS_Leaderboards_QueryLeaderboardDefinitions：

此操作完成后，类型为 EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallback 的回调将使用指示成功或失败的 EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallbackInfo 结构运行。成功后，本地缓存将包含符合标准的排行榜列表。然后，你可以使用 EOS_Leaderboards_GetLeaderboardDefinitionCount 了解系统找到多少排行榜定义，并调用 EOS_Leaderboards_CopyLeaderboardDefinitionByIndex，以便获取每个排行榜的副本。如果你已知预期的特定排行榜的ID在列表中，你可以调用 EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId 获取排行榜定义的副本。

调用 EOS_Leaderboards_CopyLeaderboardDefinitionByIndex 时，传入按如下方式初始化的 EOS_Leaderboards_CopyLeaderboardDefinitionByIndexOptions 的结构：

调用 EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId 时，传入按如下方式初始化的 EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardIdOptions 结构：

无论是哪种情况，你将收到定义排行榜的信息副本（类型EOS_Leaderboards_Definition）不再需要此信息时，调用 EOS_Leaderboards_LeaderboardDefinition_Release 来释放它。

通常，玩家想要查看整个世界或其好友的排行榜数据。排行榜接口提供单独的查询方法来支持通过这两种方式检索数据。

要查看排行榜的全球排名，调用结构为 EOS_Leaderboards_QueryLeaderboardRanksOptions 的 EOS_Leaderboards_QueryLeaderboardRanks。按如下方式初始化结构：

操作完成后，类型为 EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallback 的调用将使用指示成功或失败的 EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallbackInfo 数据结构运行。成功后，EOS SDK缓存将包含你请求的数据。你可以通过调用 EOS_Leaderboards_GetLeaderboardRecordCount 找到记录数量，并使用 EOS_Leaderboards_CopyLeaderboardRecordByIndex 获取单独记录的副本。如果你想要特定用户的记录，并且你有该用户的ID，你可以调用 EOS_Leaderboards_CopyLeaderboardRecordByUserId。这些函数均以EOS_Leaderboards_LeaderboardRecord形式返回缓存记录的副本。不再需要副本后，使用 EOS_Leaderboards_LeaderboardRecord_Release 来释放它们。

如果你要向玩家展示好友的分数记录，请使用 EOS_Leaderboards_QueryLeaderboardUserScores。使用按如下方式初始化的 EOS_Leaderboards_QueryLeaderboardUserScoresOptions 结构调用此函数：

操作完成后，类型为 EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallback 的回调将使用指示成功或失败的 EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallbackInfo 数据结构运行。如果调用成功，缓存将包含你朋友分数的排序记录。你可以使用 EOS_Leaderboards_GetLeaderboardUserScoreCount 函数获取可用的记录数量，并使用 EOS_Leaderboards_CopyLeaderboardUserScoreByIndex 按索引检索分数，或使用 EOS_Leaderboards_CopyLeaderboardUserScoreByUserId 按用户ID检索。无论是哪种情况，你将收到相应 EOS_Leaderboards_LeaderboardUserScore 数据的副本。不再需要此数据时，使用 EOS_Leaderboards_LeaderboardUserScore_Release 来释放它。

借助排行榜接口，使用（EOS）的开发人员能够对整个玩家群的分数进行排名，以便玩家可以与他们的朋友或全球其他玩家竞争最高分。每款游戏可以支持创建多个排行榜，从不同来源收集分数，并以不同的评分模式进行排名。

有关节流、用量配额和最佳实践的一般信息，请参见服务使用限制。

以下限制适用于一个部署的整体排行榜使用：

此外还有按用户或按部署应用的使用率限制。按用户限制适用于玩游戏和查看现有排行榜的单个用户，而按部署限制适用于创建或删除这些排行榜的调用。