排行榜接口

处理在线排行榜的接口

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

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

排行榜接口可以设置和管理排行榜,但不会用分数数据填充排行榜。相反,排行榜会提取数据统计接口创建和维护的数据。

创建排行榜

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

  • 排行榜跟踪的统计数据(或分数)

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

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

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

统计数据和里程碑

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

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

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

排行榜类型

说明

里程碑引用数量

单例排行榜

由单个聚合窗口定义的排行榜(开始/结束时间戳对)。

2

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

Leaderboards_Milestones.png

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

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

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

汇总:

  • 全球总排行榜:受可用里程碑的限制(参见上文)

  • 里程碑数量上限(默认):100

  • 全球排行榜条目总数:1000(+1000溢出)

评分方法

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

分数聚合类型(Score Aggregation Type)

排行榜行为

EOS_LSA_Min

此排行榜将使用玩家的最低报告分数。分数最低的玩家排在第一。

EOS_LSA_Max

此排行榜将使用玩家的最高报告分数。分数最高的玩家排在第一。

EOS_LSA_Sum

此排行榜会将每个玩家报告的每个分数相加。总分数最高的玩家排在第一。

EOS_LSA_Latest

此排行榜将使用玩家最近报告的分数。分数最高的玩家排在第一。

EOS_LSA_Latest 用于排行榜可能会导致排行榜条目不稳定。例如,最新 统计数据会跟踪为某个关卡收集的物品数量。在前一轮中,玩家的表现足以出现在此统计数据的排行榜。随后玩家在该关卡中的表现可能会变差,导致玩家被移出排行榜。一般来说,我们不鼓励使用由 EOS_LSA_Latest 定义状态的排行榜,除非用它来直接控制其统计值/聚合。 例如,包含玩家自定义计算ELO的排行榜。 使用最新排行榜时,需要注意以下内容:

  1. 排行榜只保留前2000个条目的聚合,并且只允许查看前1000个排名。 系统不会保留排名在2001及更靠后玩家的数值。 为了让这类玩家出现在排行榜上,我们必须发出(或发送)该用户的统计数据。

    1. 相对于(1)而言,每次发送后,最新统计数据值存在很大差异,这会导致玩家体验较差。 理想的统计数据是随着时间的推移每个玩家的值无变化。

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

访问排行傍信息

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

属性

数值

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDDEFINITIONS_API_LATEST

StartTime

排行榜起始时间的可选POSIX时间戳,或 EOS_LEADERBOARDS_TIME_UNDEFINED

EndTime

排行榜终止时间的可选POSIX时间戳,或 EOS_LEADERBOARDS_TIME_UNDEFINED

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

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

属性

数值

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYINDEX_API_LATEST

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

属性

数值

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYLEADERBOARDID_API_LATEST

LeaderboardId

你要检索信息的排行榜的ID

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

检索排行榜数据

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

检索已排名全球数据

要查看排行榜的全球排名,调用结构为 EOS_Leaderboards_QueryLeaderboardRanksOptionsEOS_Leaderboards_QueryLeaderboardRanks。按如下方式初始化结构:

属性

数值

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDRANKS_API_LATEST

LeaderboardId

你要检索信息的排行榜的ID

操作完成后,类型为 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 结构调用此函数:

属性

数值

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDUSERSCORES_API_LATEST

UserIds

一组 EOS_ProductUserId 值,用于指示你要检索其分数的用户

UserIdsCount

UserIds 参数中包含的ID数量

StatInfo

要收集的统计数据和决定每种统计数据排名顺序时要使用的排序方法

StatInfoCount

StatInfo 数组中元素的数量

StartTime

可选POSIX时间戳或 EOS_LEADERBOARDS_TIME_UNDEFINED,结果将仅包括此时间之后的分数

EndTime

可选POSIX时间戳或 EOS_LEADERBOARDS_TIME_UNDEFINED,结果将仅包括此时间之前的分数

你以这种方式收集的分数将根据你的具体要求进行排序,但不会取自排行榜或也不需要排行榜。这些分数没有全球排名。StatInfo 字段包括你希望比较的统计数据以及你希望使用的相对于查询中检索到的其他用户分数的排名方法。

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

使用限制

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

有关节流、用量配额和最佳实践的一般信息,请参见

[服务使用限制](Overview#ServiceUsageLimitations)

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

功能

限制

全球排行榜的数量

受可用里程碑的限制 - 参见排行榜接口

全球排行榜总条目

1000(+1000溢出 - 参见排行榜接口

好友排行榜数量

无限制,有关更多详情,参见数据统计

好友排行榜通过直接查询统计数据而创建;不受全球排行榜限制的影响。

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

功能

按用户限制

按部署限制

获取单个排行榜值

每分钟100个请求

获取所有排行榜值

每分钟10个请求

创建排行榜

每分钟100个请求

删除排行榜

每分钟100个请求