Achievements Interface

用于检查和解锁不同用户的Epic在线服务成就的接口。

阅读时间17分钟

使用 成就接口 来执行以下操作:

  • 获取某个玩家的成就数据。
  • 通过函数调用解锁成就。
  • 获取某个应用的所有成就数据。

请参见API参考文档了解详情:EOS成就接口API参考文档

你通过成就接口定义的成就都统称为“Epic在线服务成就”。你可以将其添加到你的产品中,无论产品使用何种平台或商城。

从EOS SDK 1.8开始,我们更新了对成就图标的处理方式。尽管从1.7升级到1.8时,你可能不会遇到任何中断,但你的一些图标可能会恢复到默认状态。如果你遇到这种情况,请联系你的技术客户经理以获得支持。

如果你在Epic游戏商城中发布了你的 产品,你可以通过EGS成就系统进一步加强你的产品的游戏体验。EGS成就扩展了EOS成就。它们会为你的用户的Epic玩家账户提供经验点(XP)和其他奖励。更多信息请参见Epic游戏商城成就

访问成就接口

要访问成就接口,需要调用 EOS_Platform_GetAchievementsInterface 函数获取一个 EOS_HAchievements 柄。与所有其他接口类似,EOS_HPlatform 柄必须tick,确保请求完成时触发正确的回调。

EOS成就定义

在EOS成就定义中,我们不再支持LATEST类型的集合(aggregation)。这样可能会产生如下影响:

  • 你仍然可以创建使用LATEST集合类型的统计数据
  • 不过,你无法创建一个引用了LATEST集合类型的统计数据的EOS成就
  • 如果某个EOS成就已经存在,并且引用了LATEST集合类型的成就,编辑仍然是可行的

获取某个EOS成就定义的数据时,其将包含在结构体 EOS_Achievements_DefinitionV2 中。此结构体含以下参数:

EOS_Achievements_DefinitionV2:
参数 说明
ApiVersion EOS_ACHIEVEMENTS_DEFINITIONV2_API_LATEST
AchievementId 可以用于识别成就的独有成就ID。
UnlockedDisplayName 解锁时显示的本地化成就名称。
UnlockedDescription 解锁时显示的本地化成就说明。
LockedDisplayName 未解锁时显示的本地化成就名称。
LockedDescription 未解锁时显示的本地化成就说明。
FlavorText 本地化的额外文字,可以在游戏中任意使用。如果开发者门户中没有设置数据,该项可以为null。
UnlockedIconURL 解锁时成就显示图标的URL。如果开发者门户中没有设置数据,该项为null,并且社交覆层中会使用一个默认图片。
LockedIconURL 解锁时成就或者成就隐藏时显示图标的URL。如果开发者门户中没有设置数据,该项为null,并且社交覆层中会使用一个默认图片。
bIsHidden 如果成就被隐藏,那么设为 EOS_TRUE ;否则为 EOS_FALSE 。设置为 EOS_TRUE 时,如果成就未解锁,社交覆层 会将成就名显示为 "隐藏成就",并且说明文本为空字符串。不过,该结构中 LockedDisplayNameLockedDescription 的数值不会改变。
StatThresholdsCount 用于监视该成就进度的统计数据阈值的数量。
StatThresholds 包含 EOS_Achievements_StatThresholds 的数组,必须满足这些条件才能解锁该Epic在线服务成就。包含名称和阈值数值。

查询EOS成就定义

函数 EOS_Achievements_QueryDefinitions 可用于获取在开发者门户上为你应用程序创建的所有EOS成就定义的一个数组。

查询完成后,EOS成就定义将被本地缓存,而非通过函数返回。使用 EOS_Achievements_CopyAchievementDefinitionV2ByIndexEOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 来获取 EOS_Achievements_DefinitionV2 的一个副本,即可访问定义。必须使用 EOS_Achievements_DefinitionV2_Release 来释放用于保存这些定义副本的内存。欲知复制EOS成就的更多详情,请参加下方复制缓存成就定义

EOS_Achievements_QueryDefinitions 采用以下参数:

EOS_Achievements_QueryDefinitions:
参数 说明
Handle 一个有效的 EOS_HAchievements 句柄。
Options 包含用于获取本地化文本的数据的 EOS_Achievements_QueryDefinitionsOptions 结构,其中还包含要返回哪种数据类型的选项。
ClientData CompletionDelegate 中返回的任意数据。
CompletionDelegate 操作完成时调用的函数,使用与 EOS_Achievements_OnQueryDefinitionsCompleteCallback 一致的签名。
EOS_Achievements_QueryDefinitionsOptions:
Parameter Description
ApiVersion 设为 EOS_ACHIEVEMENTS_QUERYDEFINITIONS_API_LATEST
LocalUserId 检索定义的用户的产品用户ID。
EpicUserId 已弃用,必须设为null。
HiddenAchievementIds 已弃用,必须设为null。
HiddenAchievementsCount 已弃用,必须设为0。

如查询成功,此函数将返回 EOS_Success 的一个 EOS_EResult 值。其他结果代表错误或不正确参数。

查询使用 LocalUserIdEpicUserId 来确定用户的 地区,其用于返回本地化文本(假如用户有一个绑定了的Epic在线服务账号ID)。你也可以调用 EOS_Platform_SetOverrideLocaleCode 来强制系统使用你选择的地区来获取EOS成就信息。

查询定义完成回调

查询定义操作已完成时,回调函数 EOS_Achievements_OnQueryDefinitionsCompleteCallback 将被调用,其将返回一个 EOS_Achievements_OnQueryDefinitionsCompleteCallbackInfo 结构。回调信息将包含一个 ResultCode,以及使用 ClientData 参数在 EOS_Achievements_QueryDefinitionsOptions 中设置的任意客户端数据。

复制缓存的EOS成就定义

EOS_Achievements_QueryDefinitions 操作完成后,EOS成就定义将被本地缓存。之后你可以使用 EOS_Achievements_CopyAchievementDefinitionV2ByIndexEOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 来获取 EOS_Achievements_DefinitionV2 的一个副本。

获取缓存EOS成就的数量

可以使用函数 GetAchievementDefinitionCount 来获取可用的缓存的EOS成就数量。此函数将数量返回为一个整数,并将一个 EOS_Achievements_GetAchievementDefinitionCountOptions 结构体用作参数。

EOS_Achievements_GetAchievementDefinitionCountOptions 结构自身只接受一个 ApiVersion 参数,此参数应被设为 EOS_ACHIEVEMENTS_GETACHIEVEMENTDEFINITIONCOUNT_API_LATEST 的值。

按索引复制EOS成就定义