成就接口

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

阅读时间17分钟

成就接口(Achievements Interface) 可用于完成以下操作:

  • 检索特定玩家的成就状态数据。
  • 通过调用手动解锁成就。
  • 检索某个应用的所有成就数据。

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

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

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

如果你在Epic Games商城发布 产品 ,你可以通过Epic Games商城成就进一步提升你的产品的用户体验。Epic Games商城成就就是Epic在线服务成就的延伸。它们会为你的用户的Epic玩家账号带来经验值奖励(XP)和其他好处。欲了解更多信息,请参阅Epic Games商城成就文档。

成就的视频介绍

在youtube.com上观看介绍视频:成就介绍

视频:访问成就接口

访问成就接口

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

Epic在线服务成就定义

在Epic在线服务成就定义中,我们不再支持LATEST聚合类型。影响:

  • 你仍然可以创建使用LATEST聚合类型的统计数据
  • 不过,若统计数据使用了LATEST聚合类型,你将无法创建引用该统计数据的Epic在线服务成就
  • 如果Epic在线服务成就已经存在,并且引用了使用LATEST聚合类型的统计数据,则仍然可以编辑。

检索Epic在线服务成就定义的数据时,其将包含在 EOS_Achievements_DefinitionV2 结构体中,该结构体含以下参数:

EOS_Achievements_DefinitionV2:
参数说明
ApiVersionEOS_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在线服务成就。包含名称和阈值数值。

查询Epic在线服务成就定义

函数 EOS_Achievements_QueryDefinitions 可用于检索你在开发人员门户上为你的应用程序创建的所有Epic在线服务成就定义的一个数组。

查询完成后,Epic在线服务成就定义会缓存到本地,而非通过函数返回。之后使用 EOS_Achievements_CopyAchievementDefinitionV2ByIndexEOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 获取 EOS_Achievements_DefinitionV2 的副本,即可访问定义。必须使用 EOS_Achievements_DefinitionV2_Release 释放用于存储这些定义副本的内存。欲知复制Epic在线服务成就的更多详情,请参见下文复制缓存成就定义

EOS_Achievements_QueryDefinitions 采用以下参数:

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

若用户有绑定的Epic在线服务账号ID,查询使用 LocalUserId 来确定用户的 语言区域(locale) ,用于返回本地化文本。我也可调用 EOS_Platform_SetOverrideLocaleCode 以强制系统使用你选择的语言区域,来检索Epic在线服务成就信息。

查询定义完成回调

查询定义操作完成时,系统将调用回调函数 EOS_Achievements_OnQueryDefinitionsCompleteCallback ,并返回 EOS_Achievements_OnQueryDefinitionsCompleteCallbackInfo 结构。回调信息将包含 ResultCode 和使用 ClientData 参数在 EOS_Achievements_QueryDefinitionsOptions 中设置的任意客户端数据。

复制缓存的Epic在线服务成就定义

EOS_Achievements_QueryDefinitions 操作完成后,Epic在线服务成就定义将被缓存到本地。你可使用 EOS_Achievements_CopyAchievementDefinitionV2ByIndexEOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 来检索 EOS_Achievements_DefinitionV2 的副本。

获取缓存的Epic在线服务成就数量

可使用函数 GetAchievementDefinitionCount 获取可用的已缓存Epic在线服务成就的数量。此函数返回的计数是整数,并将一个 EOS_Achievements_GetAchievementDefinitionCountOptions 结构体用作参数。

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

按索引复制Epic在线服务成就定义

函数 EOS_Achievements_CopyAchievementDefinitionV2ByIndex 使用缓存的Epic在线服务成就列表中的索引值来检索 EOS_Achievements_DefinitionV2 的副本,然后通过输出参数 OutDefinition 输出该副本。此函数接受以下参数:

EOS_Achievements_CopyAchievementDefinitionV2ByIndex:
参数说明
Handle一个有效的 EOS_HAchievements 句柄。
Options一个 EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions 结构,包含要从缓存中请求复制的索引。
OutDefinition一个输出 参数 ,包含请求的 EOS_Achievements_DefinitionV2 的副本。若 OutDefinition 包含有效数据,则必须对该数据调用 EOS_Achievements_DefinitionV2_Release ,将它从内存中释放。
EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions:
参数说明
ApiVersionEOS_ACHIEVEMENTS_COPYDEFINITIONV2BYINDEX_API_LATEST
AchievementIndex要从缓存中检索的成就定义的索引。

若信息可用并传出到 OutDefinition 中,则此函数将返回一个值为 EOS_SuccessEOS_EResult 。若为输出参数传递空指针,则将返回 EOS_InvalidParameters 。若未找到请求的成就定义,将返回 EOS_NotFound

按ID复制成就定义

函数 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 在成就缓存中搜索与给定 AchievementId 匹配的成就,然后通过输出参数 OutDefinition 输出其数据副本。此函数接受以下参数:

EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId:
参数说明
Handle一个有效的 EOS_HAchievements 句柄。
Options一个 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementIdOptions 结构,包含要在缓存中搜索的成就ID。
OutDefinition一个输出参数,包含请求的 EOS_Achievements_DefinitionV2 的副本。若 OutDefinition 包含有效数据,则必须对该数据调用 EOS_Achievements_DefinitionV2_Release ,将它从内存中释放。
CopyAchievementDefinitionV2ByAchievementIdOptions:
参数说明
ApiVersion设为 EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYACHIEVEMENTID_API_LATEST
AchievementId从缓存中复制定义时,要查找的成就ID。

若信息可用并传出到 OutDefinition 中,则此函数将返回一个值为 EOS_SuccessEOS_EResult 。若为输出参数传递空指针,则将返回 EOS_InvalidParameters 。若未找到请求的成就定义,将返回 EOS_NotFound

从复制的成就定义释放内存

使用 EOS_Achievements_CopyAchievementDefinitionV2ByIndexEOS_Achievements_CopyAchievementDefinitionV2ByAchievementIdOutDefinition 复制的信息必须通过函数 EOS_Achievements_DefinitionV2_Release 从内存中释放出来。此函数接受指向名为 AchievementDefinition 的单一 EOS_Achievements_DefinitionV2 的指针。

玩家成就进度数据

玩家成就进度数据包含在名为 EOS_Achievements_PlayerAchievement 的结构中。EOS_Achievements_AchievementDefinition 包含后端中有关Epic在线服务成就的整体信息, EOS_Achievements_PlayerAchievement 则追踪特定玩家解锁Epic在线服务成就的进度、解锁时间(若已经解锁),以及解锁成就的相关统计信息。

EOS_Achievements_PlayerAchievement 的参数如下:

EOS_Achievements_PlayerAchievement:
参数说明
ApiVersion设为 EOS_ACHIEVEMENTS_PLAYERACHIEVEMENT_API_LATEST
AchievementId用于标别成就的独有标识符。
Progress成就进度的百分比。
EOS_Achievements_QueryPlayerAchievements 成功时以及成就解锁时,当前进度就会更新。
UnlockTime成就解锁的POSIX时间戳。若成就尚未解锁,此值将是EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED。
StatInfoCount与此成就相关的玩家统计信息条目的数量。
StatInfoEOS_Achievements_PlayerStatInfo 结构的数组,包含要解锁成就所需要的统计数据阈值以及玩家当前这些数据的数值。
DisplayName本地化的成就显示名称,基于特定玩家当前的成就进度。
DisplayName 会一直在SDK缓存中为空,直至成功调用 EOS_Achievements_QueryDefinitions
Description本地化的成就 说明 ,基于特定玩家当前的成就进度。
EOS_Achievements_QueryPlayerAchievements 成功时以及成就解锁时,当前进度就会更新。
IconURL成就显示图标的URL,基于特定玩家当前的成就进度。如果开发人员门户中没有配置数据,该项可以为null。
IconURL 会一直在SDK缓存中为空,直至成功调用 EOS_Achievements_QueryDefinitions
FlavorText本地化的额外文字,可以在游戏中任意使用。如果开发人员门户中没有配置数据,该项可以为null。
FlavorText 会一直在SDK缓存中为空,直至成功调用 EOS_Achievements_QueryDefinitions
EOS_Achievements_PlayerStatInfo:
参数说明
ApiVersion设为 EOS_ACHIEVEMENTS_PLAYERSTATINFO_API_LATEST
Name统计数据的名称。
CurrentValue统计数据的当前值。
ThresholdValue统计数据的阈值。

欲知玩家统计数据的更多信息,参见统计数据接口页面。

查询玩家成就进度

异步函数 EOS_Achievements_QueryPlayerAchievements 可用于检索玩家的成就进度数据。查询完成后,其将把请求的数据存储到本地缓存的列表中。要访问这些数据,可以使用 EOS_Achievements_CopyPlayerAchievementByIndexEOS_Achievements_CopyPlayerAchievementByAchievementId 获取所需数据的副本。之后必须调用 EOS_Achievements_PlayerAchievement_Release 从内存中释放复制的信息。

EOS_Achievements_QueryPlayerAchievements 的参数如下:

EOS_Achievements_QueryPlayerAchievements:
参数说明
Handle一个有效的 EOS_HAchievements 句柄。
Options一种 EOS_Achievements_QueryPlayerAchievementsOptions 结构,包含查询的目标玩家的 UserId
ClientDataCompletionDelegate 中返回的任意数据。
CompletionDelegate操作完成时调用的函数,使用与 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback 一致的签名。
EOS_Achievements_QueryPlayerAchievementsOptions
参数说明
ApiVersion设为 EOS_ACHIEVEMENTS_QUERYPLAYERACHIEVEMENTS_API_LATEST
UserId正在检索其成就进度数据的目标的账号ID。

查询玩家成就已完成回调

查询玩家成就操作完成时,系统将调用回调函数 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback ,并返回 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallbackInfo 结构。回调信息将包含一个 ResultCode ,以及在 EOS_Achievements_QueryPlayerAchievementsOptions 中设置的客户端数据以及拥有这些数据的玩家的用户ID。

复制玩家成就进度

玩家成就数据将缓存在本地。可以使用 EOS_Achievements_GetPlayerAchievementCount 检索缓存的Epic在线服务成就的数量。

函数 EOS_Achievements_CopyPlayerAchievementByIndexEOS_Achievements_CopyPlayerAchievementByAchievementId 可用于获取 EOS_Achievements_PlayerAchievement 的副本。必须使用 EOS_Achievements_PlayerAchievement_Release 释与复制数据关联的内存。

按索引复制玩家成就

函数 EOS_Achievements_CopyPlayerAchievementByIndex 使用缓存成就列表中的索引值从本地缓存中检索 EOS_Achievements_PlayerAchievement 结构的副本,然后通过输出参数 OutAchievement 输出该副本。此函数接受以下参数:

EOS_Achievements_CopyPlayerAchievementByIndex:
参数说明
Handle一个有效的 EOS_HAchievements 句柄。
OptionsEOS_Achievements_CopyPlayerAchievementByIndexOptions 结构,包含要从缓存中请求复制的索引。
OutAchievement一个输出 参数 ,包含请求的 EOS_Achievements_PlayerAchievement 的副本。若 OutAchievement 包含有效数据,则必须对该数据调用 EOS_Achievements_PlayerAchievement_Release ,将它从内存中释放。
EOS_Achievements_CopyPlayerAchievementByIndexOptions:
参数说明
ApiVersion设为 EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYINDEX_API_LATEST
UserId一个有效的 EOS_ProductUserId ,表示正在复制成就的用户的账号ID。
AchievementIndex要从缓存中检索的玩家成就数据的索引。

若请求的信息可用并传出到 OutAchievement 中,则此函数将返回一个值为 EOS_SuccessEOS_EResult 。若通过输出参数传递空指针,则将返回 EOS_InvalidParameters 。若未找到请求的玩家成就,将返回 EOS_NotFound

按ID复制玩家成就

函数 EOS_Achievements_CopyPlayerAchievementByAchievementId 将在本地玩家成就缓存中搜索与给定 AchievementId 匹配的成就,然后通过输出参数 OutAchievement 输出其数据副本。此函数接受以下参数:

EOS_Achievements_CopyPlayerAchievementByAchievementId:
参数说明
Handle一个有效的 EOS_HAchievements 句柄。
Options一个 EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions 结构,包含要在缓存中搜索的成就ID。
OutAchievement一个输出参数,包含请求的 EOS_Achievements_PlayerAchievement 的副本。若 OutAchievement 包含有效数据,则必须对该数据调用 EOS_Achievements_PlayerAchievement_Release ,将它从内存中释放。
EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions:
参数说明
ApiVersion设为 EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYACHIEVEMENTID_API_LATEST
UserId一个有效的 EOS_ProductUserId ,表示正在复制成就的用户的账号ID。
AchievementId从缓存中复制定义时,要查找的成就ID。

若请求的信息可用并传出到 OutAchievement 中,则此函数将返回一个值为 EOS_SuccessEOS_EResult 。若通过输出参数传递空指针,则将返回 EOS_InvalidParameters 。若未找到请求的玩家成就,将返回 EOS_NotFound

从复制的玩家成就释放内存

使用 EOS_Achievements_CopyPlayerAchievementByIndexEOS_Achievements_CopyPlayerAchievementByAchievementIdOutAchievement 复制的信息必须通过函数 EOS_Achievements_PlayerAchievement_Release 从内存中释放出来。此函数接受指向名为 Achievement 的单一 EOS_Achievements_PlayerAchievement 的指针。

解锁Epic在线服务成就

绑定到Epic在线服务成就的 统计数据 被摄取时,Epic在线服务成就可自动解锁,也可以通过调用 EOS_Achievements_UnlockAchievements 函数手动解锁。

通过统计数据解锁Epic在线服务成就

Epic在线服务成就由一组统计阈值定义,阈值由统计数据的名称以及解锁Epic在线服务成就所需的统计数据数量组成。所有必要阈值都满足后,成就将解锁, 进度(Progress) 将设为1.0。

欲详细了解如何使用 统计数据摄取 操作来更新统计数据,请参见统计数据接口页面。

手动解锁Epic在线服务成就

函数 EOS_Achievements_UnlockAchievements 可以解锁一个用户的一个或多个Epic在线服务成就。此函数的参数如下:

EOS_Achievements_UnlockAchievements:
参数说明
Handle一个有效的 EOS_HAchievements 句柄。
Options一个 EOS_Achievements_UnlockAchievementsOptions 结构,包含我们正在解锁其Epic在线服务成就的玩家的信息,以及我们想要解锁的Epic在线服务成就。
ClientDataCompletionDelegate 中返回的任意数据。
CompletionDelegate操作完成时调用的函数,使用与 EOS_Achievements_OnUnlockAchievementsCompleteCallback 一致的签名。
EOS_Achievements_UnlockAchievementsOptions:
参数说明
ApiVersion设为 EOS_ACHIEVEMENTS_UNLOCKACHIEVEMENTS_API_LATEST
UserIdEOS_ProductUserId ,表示要解锁成就的用户的账号ID。
AchievementIds要解锁的成就ID的列表。
AchievementsCount要解锁的成就的数量。

回调函数 EOS_Achievements_OnUnlockAchievementsCompleteCallback 会在 EOS_Achievements_UnlockAchievements 操作完成时运行。此函数负责从操作返回数据。其参数如下:

EOS_Achievements_OnUnlockAchievementsCompleteCallback:
参数说明
ResultCode一个 EOS_EResult ,表示操作的状态。若结果为 EOS_Success ,意味着操作成功完成。任何其他结果都意味着发生错误。
ClientData 传入 EOS_Achievements_UnlockAchievements 的上下文。
UserIdEOS_ProductUserId ,表示发起此请求的用户的账号ID。
AchievementsCount要解锁的成就的数量。

请注意,SDK不会以本地或离线形式存储成就状态。为了解决服务中断期间未解锁Epic在线服务成就无法得到统计服务支持的问题,请考虑采用以下方法:

  1. 登录时始终下载用户成就状态。

  2. 将解锁状态与你的后台统计/数据进行对比,如果满足条件,则解锁成就

此流程也适用于完成了更新后新出的Epic在线服务成就的用户。

可以多次调用 EOS_Achievements_UnlockAchievements ,甚至每次启动时都可以调用,只要它满足合适的重试频率,并等待完成状态返回后再尝试。

Epic在线服务成就通知

通知(Notifications) 将在Epic在线服务成就解锁时发生。摄取统计数据或手动解锁成就均可触发成就通知。

Epic在线服务成就成功解锁时,函数 EOS_Achievements_AddNotifyAchievementsUnlockedV2 可以订阅通知。它将接受一个使用 EOS_Achievements_AddNotifyAchievementsUnlockedV2Options 结构的选项(Options)参数,以及对一个函数的引用,该函数的签名与 EOS_Achievements_OnAchievementsUnlockedCallbackV2 一致。之后,每当有成就解锁时,就会调用该回调函数。 回调发生时,可以使用 ClientData 将任意上下文数据传递到该回调。

EOS_Achievements_AddNotifyAchievementsUnlockedV2Options 结构包括 ApiVersion ,后者应设为 EOS_ACHIEVEMENTS_ADDNOTIFYACHIEVEMENTSUNLOCKEDV2_API_LATEST

回调函数 EOS_Achievements_OnAchievementsUnlockedCallbackV2 将返回一个 EOS_Achievements_OnAchievementsUnlockedCallbackV2Info 结构。回调信息将包含已解锁成就的 AchievementIdUnlockTime 。它还会包含通过 EOS_Achievements_AddNotifyAchievementsUnlockedV2 传入的 ClientData 和Epic在线服务成就所属用户的 UserId

RemoveNotifyAchievementsUnlocked 可用于取消通知订阅。

使用限制

成就接口可供开发人员检索玩家的Epic在线服务成就数据,为该玩家解锁Epic在线服务成就,并检索所有属于某应用程序的Epic在线服务成就数据。有关节流、用量配额和最佳实践的一般信息,请参见服务使用限制

以下限制适用于部署的所有Epic在线服务成就:

功能限制
成就总数1000
单个成就的统计数据数量3
成就ID长度256个字符
单个成就的本地化文本变体22.
覆层支持16种语言。
本地化文本长度256个字符
成就图标文件大小1.02 MB
成就图标分辨率1024x1024像素
成就图标文件类型PNG、JPG、BMP和GIF(无动画)

定义Epic在线服务成就时,不得在 EOS_Achievements_DefinitionV2AchievementId 参数中使用以下符号:

, { ^ } % ` ] > [ ~ < # | & $ @ = ; : + ? ! \ ( ) * /

导入或导出定义时,这些符号可能会导致问题。

此外,还存在使用频率限制,具体要按用户或 部署 的情况而定。用户相关的限制所适用的情况包括用户玩游戏、用户和现有成就交互。部署相关的限制所适用的情况包括那些与设置成就供玩家查看和解锁有关的调用。

功能按用户限制按部署限制
获取所有成就定义每分钟10次请求-
获取单个成就定义每分钟100次请求-
获取单个玩家成就每分钟100次请求-
解锁成就每分钟100次请求-
创建成就-每分钟100次请求
删除成就-每分钟100次请求

测试你的Epic在线服务成就

你可以在测试沙盒的部署中测试Epic在线服务成就。你应该在部署到现实环境之前进行测试,以便检查成就定义中的错误,确保玩家可以成功解锁Epic在线服务成就。 有关为 产品 创建测试 沙盒 的更多信息,请参阅产品、沙盒和部署ID