成就接口(Achievements Interface) 让开发者能够获取玩家EOS成就相关的数据、为该玩家解锁成就,并获取应用程序中所有成就的相关数据。
从EOS SDK 1.8开始,我们更新了对成就图标的处理方式。尽管从1.7升级到1.8时,你可能不会遇到任何中断,但你的一些图标可能会恢复到默认状态。如果你遇到这种情况,请联系你的技术客户经理以获得支持。
访问成就接口
要访问成就接口,需要调用 EOS_Platform_GetAchievementsInterface
函数获取一个 EOS_HAchievements
柄。与所有其他接口类似,EOS_HPlatform
柄必须tick,确保请求完成时触发正确的回调。
EOS成就定义
如需检索EOS成就数据或手动解锁它们,你必须首先在 开发者门户 中定义EOS成就。
在EOS成就定义中,我们不再支持LATEST类型的集合(aggregation)。这样可能会产生如下影响:
你仍然可以创建使用LATEST集合类型的统计数据
不过,你无法创建一个引用了LATEST集合类型的统计数据的EOS成就
如果某个EOS成就已经存在,并且引用了LATEST集合类型的成就,编辑仍然是可行的
获取某个EOS成就定义的数据时,其将包含在结构体 EOS_Achievements_DefinitionV2
中。此结构体含以下参数:
|
|
---|---|
参数 |
说明 |
|
|
|
用于独立识别成就的成就ID。 |
|
成就被解锁时显示的本地化显示名。 |
|
成就被解锁时显示的本地化描述。 |
|
成就锁定时显示的本地化名称。 |
|
成就锁定时显示的本地化描述。 |
|
能以任意方式被游戏使用的本地化风味文本。如开发者门户中未配置数据,则此文本可为空。 |
|
成就解锁时显示图标的URL。如开发者门户中未配置数据,则此数值可为空,并且社交覆层会使用一张默认的图片。 |
|
成就锁定或隐藏时显示图标的URL。如开发者门户中未配置数据,则此数值可为空,并且社交覆层会使用一张默认的图片。 |
|
如成就为隐藏,则为 |
|
用于监控此成就解锁进度的统计数据阈值的数量。 |
|
需要满足才能解锁此成就的 |
查询EOS成就定义
函数 EOS_Achievements_QueryDefinitions
可用于获取在开发者门户上为你应用程序创建的所有EOS成就定义的一个数组。
如需检索EOS成就数据或手动解锁它们,你必须首先在 开发者门户 中定义EOS成就。
查询完成后,EOS成就定义将被本地缓存,而非通过函数返回。使用 EOS_Achievements_CopyAchievementDefinitionV2ByIndex
或 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId
来获取 EOS_Achievements_DefinitionV2
的一个副本,即可访问定义。必须使用 EOS_Achievements_DefinitionV2_Release
来释放用于保存这些定义副本的内存。欲知复制EOS成就的更多详情,请参加下方复制缓存成就定义。
EOS_Achievements_QueryDefinitions
采用以下参数:
|
||
---|---|---|
参数 |
说明 |
|
|
一个有效 |
|
|
一个 |
|
|
传回 |
|
|
操作完成时调用的函数,使用与 |
|
|
||
|
设为 |
|
|
正在查询定义的用户的产品用户ID。 |
|
|
已废弃。必须设为空。 |
|
|
已废弃。必须设为空。 |
|
|
已废弃。必须设为零。 |
如查询成功,此函数将返回 EOS_Success
的一个 EOS_EResult
值。其他结果代表错误或不正确参数。
查询使用 LocalUserId
和 EpicUserId
来确定用户的 地区,其用于返回本地化文本(假如用户有一个绑定了的Epic在线服务账号ID)。你也可以调用 EOS_Platform_SetOverrideLocaleCode
来强制系统使用你选择的地区来获取EOS成就信息。
查询定义完成回调
查询定义操作已完成时,回调函数 EOS_Achievements_OnQueryDefinitionsCompleteCallback
将被调用,其将返回一个 EOS_Achievements_OnQueryDefinitionsCompleteCallbackInfo
结构。回调信息将包含一个 ResultCode
,以及使用 ClientData
参数在 EOS_Achievements_QueryDefinitionsOptions
中设置的任意客户端数据。
复制缓存的EOS成就定义
EOS_Achievements_QueryDefinitions
操作完成后,EOS成就定义将被本地缓存。之后你可以使用 EOS_Achievements_CopyAchievementDefinitionV2ByIndex
或 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId
来获取 EOS_Achievements_DefinitionV2
的一个副本。
获取缓存EOS成就的数量
可以使用函数 GetAchievementDefinitionCount
来获取可用的缓存的EOS成就数量。此函数将数量返回为一个整数,并将一个 EOS_Achievements_GetAchievementDefinitionCountOptions
结构体用作参数。
EOS_Achievements_GetAchievementDefinitionCountOptions
结构自身只接受一个 ApiVersion
参数,此参数应被设为 EOS_ACHIEVEMENTS_GETACHIEVEMENTDEFINITIONCOUNT_API_LATEST
的值。
按索引复制EOS成就定义
函数 EOS_Achievements_CopyAchievementDefinitionV2ByIndex
使用缓存成就列表中的一个索引值来获取 EOS_Achievements_DefinitionV2
的一个副本,然后通过输出参数 OutDefinition
来输出副本。此函数接受以下参数:
|
||
---|---|---|
参数 |
说明 |
|
|
一个有效 |
|
|
一个 |
|
|
一个输出参数,包含请求 |
|
|
||
|
|
|
|
从缓存获取的成就定义的索引。 |
如信息可用且传出到 OutDefinition
中,此函数将返回一个 EOS_EResult
,带一个 EOS_Success
的值。如传递输出参数的一个空指针,则其将返回 EOS_InvalidParameters
。如未找到请求的成就定义,则其将返回 EOS_NotFound
。
按ID复制成就定义
函数 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId
在成就缓存中搜索匹配给定 AchievementId
的成就,然后通过输出参数 OutDefinition
输出其数据的一个副本。此函数接受以下参数:
|
||
---|---|---|
参数 |
说明 |
|
|
一个有效 |
|
|
一个 |
|
|
一个输出参数,包含请求 |
|
|
||
|
设为 |
|
|
从缓存复制定义时要查找的成就ID。 |
如信息可用且传出到 OutDefinition
中,此函数将返回一个 EOS_EResult
,带一个 EOS_Success
的值。如传递输出参数的一个空指针,则其将返回 EOS_InvalidParameters
。如未找到请求的成就定义,则其将返回 EOS_NotFound
。
从复制的成就定义释放内存
以 EOS_Achievements_CopyAchievementDefinitionV2ByIndex
或 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId
OutDefinition
复制的信息必须使用函数 EOS_Achievements_DefinitionV2_Release
从内存中释放。此函数接受指向名为 AchievementDefinition
的单一 EOS_Achievements_DefinitionV2
的指针。
玩家成就进度数据
玩家成就进度数据包含在一个名为 EOS_Achievements_PlayerAchievement
的结构中。EOS_Achievements_AchievementDefinition
包含后端中EOS成就的整体信息,EOS_Achievements_PlayerAchievement
则追踪特定用户解锁EOS成就的进度、其解锁的时间(如已解锁),以及解锁成就的相关数据信息。EOS_Achievements_PlayerAchievement
的参数如下:
|
||
---|---|---|
参数 |
说明 |
|
|
|
|
|
用于识别成就的独立辨识符。 |
|
|
此成就的完成进度,以百分比显示。 |
|
|
成就被解锁的POSIX时间戳。如成就被解锁,此值将为 EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED。 |
|
|
与此成就相关的玩家数据信息条目数量。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
能以任意方式被游戏使用的本地化风味文本。如开发者门户中未配置数据,则此文本可为空。 |
|
|
||
|
设为 |
|
|
统计数据的名称。 |
|
|
统计数据的当前值。 |
|
|
统计数据的阈值。 |
欲知玩家数据的更多信息,请参见统计数据接口页面。
查询玩家成就进度
如需检索EOS成就数据或手动解锁它们,你必须首先在 开发者门户(Developer Portal) 中定义EOS成就。
异步函数 EOS_Achievements_QueryPlayerAchievements
可用于获取玩家的成就进度数据。查询完成后,其将把请求的数据保存在本地缓存的一个列表中。可使用 EOS_Achievements_CopyPlayerAchievementByIndex
或 EOS_Achievements_CopyPlayerAchievementByAchievementId
进行访问,获取所需数据的副本。在此操作完成后,必须调用 EOS_Achievements_PlayerAchievement_Release
从内容中释放复制的信息。
EOS_Achievements_QueryPlayerAchievements
的参数如下:
|
||
---|---|---|
参数 |
说明 |
|
|
一个有效 |
|
|
一个 |
|
|
传回 |
|
|
操作完成时调用的函数,使用与 |
|
|
||
|
设为 |
|
|
正在获取其成就进度数据的用户的帐户ID。 |
查询玩家成就已完成回调
查询玩家成就操作已完成时,回调函数 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback
将被调用,将返回一个 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallbackInfo
结构。回调信息将包含一个 ResultCode
,以及在 EOS_Achievements_QueryDefinitionsOptions
中设置的客户端数据和拥有数据的玩家的用户ID。
复制玩家成就进度
玩家成就数据将缓存在本地。可以使用 EOS_Achievements_GetPlayerAchievementCount
来获取缓存的EOS成就的数量。
函数 EOS_Achievements_CopyPlayerAchievementByIndex
和 EOS_Achievements_CopyPlayerAchievementByAchievementId
可用于获取 EOS_Achievements_PlayerAchievement
的副本。必须使用 EOS_Achievements_PlayerAchievement_Release
来释放此复制数据相关的内存。
按索引复制玩家成就
函数 EOS_Achievements_CopyPlayerAchievementByIndex
使用缓存成就列表中的一个索引值从本地缓存获取一个 EOS_Achievements_PlayerAchievement
结构的副本,然后通过输出参数 OutAchievement
输出副本。此函数接受以下参数:
|
||
---|---|---|
参数 |
说明 |
|
|
一个有效 |
|
|
一个 |
|
|
一个输出参数,包含请求的 |
|
|
||
|
设为 |
|
|
一个有效 |
|
|
从缓存获取的玩家成就数据的索引。 |
如请求的信息可用且传出到 OutAchievement
中,此函数将返回一个 EOS_EResult
,带一个 EOS_Success
的值。如通过输出参数传递一个空指针,则其将返回 EOS_InvalidParameters
。如未找到请求的玩家成就,则其将返回 EOS_NotFound
。
按ID复制玩家成就
函数 EOS_Achievements_CopyPlayerAchievementByAchievementId
在本地玩家成就缓存中搜索匹配给定 AchievementId
的成就,然后通过输出参数 OutAchievement
输出其数据的一个副本。此函数接受以下参数:
|
||
---|---|---|
参数 |
说明 |
|
|
一个有效 |
|
|
一个 |
|
|
一个输出参数,包含请求的 |
|
|
||
|
设为 |
|
|
一个有效 |
|
|
从缓存复制定义时要查找的成就ID。 |
如请求的信息可用且传出到 OutAchievement
中,此函数将返回一个 EOS_EResult
,带一个 EOS_Success
的值。如通过输出参数传递一个空指针,则其将返回 EOS_InvalidParameters
。如未找到请求的玩家成就,则其将返回 EOS_NotFound
。
从复制的玩家成就释放内存
以 EOS_Achievements_CopyPlayerAchievementByIndex
或 EOS_Achievements_CopyPlayerAchievementByAchievementId
OutAchievement
复制的信息必须使用函数 EOS_Achievements_PlayerAchievement_Release
从内存中释放。此函数接受指向名为 Achievement
的单一 EOS_Achievements_PlayerAchievement
的指针。
解锁EOS成就
绑定到EOS成就的 统计数据 被摄取时,成就便能被解锁;也可以调用 EOS_Achievements_UnlockAchievements
函数手动解锁。
通过统计数据解锁EOS成就
EOS成就由一套统计数据阈值定义,阈值由统计数据的名称、以及解锁EOS成就所需的数据量组成。所有必要阈值被满足后,成就将被解锁,进度 将被设为1.0。
请参见统计数据接口页面,详细了解如何通过 统计数据摄取 操作来更新统计数据。
手动解锁EOS成就
函数 EOS_Achievements_UnlockAchievements
可解锁一个用户的一个或多个EOS成就。此函数的参数如下:
|
||
---|---|---|
参数 |
说明 |
|
|
一个有效 |
|
|
一个 |
|
|
传回 |
|
|
操作完成时调用的函数,使用与 |
|
|
||
|
设为 |
|
|
|
|
|
要解锁的成就的ID列表。 |
|
|
要解锁的成就的数量。 |
EOS_Achievements_UnlockAchievements
操作完成时,回调函数 EOS_Achievements_OnUnlockAchievementsCompleteCallback
将会执行。此函数负责从操作返回数据。其参数如下:
|
|
---|---|
参数 |
说明 |
|
|
|
传入 |
|
The |
|
要解锁的成就的数量。 |
请注意,SDK不会以本地或离线形式保存成就状态。为了解决服务中断期间,未解锁EOS成就无法得到统计服务支持的问题,请考虑以下事项:
登录时始终下载用户成就状态。
将解锁状态与你的后台统计/数据进行比较,如果满足条件,则解锁成就。
此流程还涉及那些可能完成了新EOS成就的用户(该成就在更新中引入)。
可以多次调用 EOS_Achievements_UnlockAchievements
,甚至每次启动时都可以调用,只要它满足合适的重试频率,并且等待完成状态返回后再尝试。
EOS成就通知
通知 将在EOS成就被解锁时发生。摄取统计数据或手动解锁成就均可触发成就通知。
EOS成就被成功解锁时,函数 EOS_Achievements_AddNotifyAchievementsUnlockedV2
可注册到通知。其接受一个使用 EOS_Achievements_AddNotifyAchievementsUnlockedV2Options
结构的选项参数,以及对一个函数的引用(此函数的签名与 EOS_Achievements_OnAchievementsUnlockedCallbackV2
一致)。成就解锁时,该回调函数将被调用。ClientData
可用于将任意情境数据传递到发生时的回调。
结构 EOS_Achievements_AddNotifyAchievementsUnlockedV2Options
包含 ApiVersion
,其应被设为 EOS_ACHIEVEMENTS_ADDNOTIFYACHIEVEMENTSUNLOCKEDV2_API_LATEST
。
回调函数 EOS_Achievements_OnAchievementsUnlockedCallbackV2
返回一个 EOS_Achievements_OnAchievementsUnlockedCallbackV2Info
结构。回调信息将包含被解锁成就的 AchievementId
和 UnlockTime
。其还包含通过 EOS_Achievements_AddNotifyAchievementsUnlockedV2
传入的 ClientData
,以及EOS成就所属用户的 UserId
。
RemoveNotifyAchievementsUnlocked
可用于取消注册通知。
使用限制
成就接口允许开发者检索玩家EOS成就数据,解锁玩家EOS成就,检索某个应用所有的EOS成就。有关限制节流(throttling)、使用配额以及最佳实践的更多详情,请参阅服务使用限制。
以下限制适用于部署的所有EOS成就:
功能 |
限制 |
---|---|
成就总数 |
1000 |
单个成就的统计数据数量 |
3 |
成就ID长度 |
256个字符 |
单个成就的本地化文本变种 |
19 |
本地化文本长度 |
256个字符 |
成就图标文件大小 |
1.02 MB |
成就图标分辨率 |
1024x1024 像素 |
成就图标文件类型 |
PNG, JPG, BMP, 和 GIF (无动画) |
当你定义EOS成就时,你无法在 EOS_Achievements_DefinitionV2
的 AchievementId
参数中使用以下符号:
, { ^ } % ` ] > [ ~ < # | & $ @ = ; : + ? ! \ ( ) * /
导入导出定义时,这些符号可能会导致问题。
此外,还存在使用频率限制,具体要按用户或部署的情况而定。用户相关的限制所适用的情况包括用户玩游戏、用户和现有成就交互。部署相关的限制所适用的情况包括那些与设置成就供玩家查看和解锁有关的调用。
功能 |
限制(按用户) |
限制(按部署) |
---|---|---|
获取所有成就定义 |
每分钟10次调用 |
|
获取单个成就定义 |
每分钟100次请求 |
|
获取单个玩家成就 |
每分钟100次请求 |
|
解锁成就 |
每分钟100次请求 |
|
创建成就 |
每分钟100次请求 |
|
删除成就 |
每分钟100次请求 |
测试EOS成就
你可以在测试沙盒中测试你的EOS成就。你应该在部署到真实环境之前进行测试,这样就能检查成就定义中的错误,并确保玩家可以成功解锁EOS成就。 有关为产品创建测试沙盒的更多信息,请参阅产品、沙盒和部署ID。