Achievements Interface

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

29 分钟可读完

成就接口(Achievements Interface) 让开发者能够获取玩家EOS成就相关的数据、为该玩家解锁成就,并获取应用程序中所有成就的相关数据。

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

访问成就接口

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

EOS成就定义

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

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

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

EOS_Achievements_DefinitionV2

参数说明
ApiVersionEOS_ACHIEVEMENTS_DEFINITIONV2_API_LATEST
AchievementId用于独立识别成就的成就ID。
UnlockedDisplayName成就被解锁时显示的本地化显示名。
UnlockedDescription成就被解锁时显示的本地化描述。
LockedDisplayName成就锁定时显示的本地化名称。
LockedDescription成就锁定时显示的本地化描述。
FlavorText能以任意方式被游戏使用的本地化风味文本。如开发者门户中未配置数据,则此文本可为空。
UnlockedIconURL成就解锁时显示图标的URL。如开发者门户中未配置数据,则此数值可为空,并且社交覆层会使用一张默认的图片。
LockedIconURL成就锁定或隐藏时显示图标的URL。如开发者门户中未配置数据,则此数值可为空,并且社交覆层会使用一张默认的图片。
bIsHidden如成就为隐藏,则为 EOS_TRUE;否则为 EOS_FALSE。假如设置成 EOS_TRUE社交覆层会使用“隐藏成就”作为显示名称,并且成就为解锁时,描述内容是一段空的字符串。不过,在这个结构中, LockedDisplayNameLockedDescription 的保持不变。
StatThresholdsCount用于监控此成就解锁进度的统计数据阈值的数量。
StatThresholds需要满足才能解锁此成就的 EOS_Achievements_StatThresholds 的数组。由名称和阈值组成。

查询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
ApiVersion设为 EOS_ACHIEVEMENTS_QUERYDEFINITIONS_API_LATEST
LocalUserId正在查询定义的用户的产品用户ID。
EpicUserId已废弃。必须设为空。
HiddenAchievementIds已废弃。必须设为空。
HiddenAchievementsCount已废弃。必须设为零。

如查询成功,此函数将返回 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成就定义

函数 EOS_Achievements_CopyAchievementDefinitionV2ByIndex 使用缓存成就列表中的一个索引值来获取 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_CopyAchievement DefinitionV2ByIndexOptions
ApiVersionEOS_ACHIEVEMENTS_COPYDEFINITIONV2BYINDEX_API_LATEST
AchievementIndex从缓存获取的成就定义的索引。

如信息可用且传出到 OutDefinition 中,此函数将返回一个 EOS_EResult,带一个 EOS_Success 的值。如传递输出参数的一个空指针,则其将返回 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,将其从内存中释放。
CopyAchievementDefinitionV2 ByAchievementIdOptions
ApiVersion设为 EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYACHIEVEMENTID_API_LATEST
AchievementId从缓存复制定义时要查找的成就ID。

如信息可用且传出到 OutDefinition 中,此函数将返回一个 EOS_EResult,带一个 EOS_Success 的值。如传递输出参数的一个空指针,则其将返回 EOS_InvalidParameters。如未找到请求的成就定义,则其将返回 EOS_NotFound

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

EOS_Achievements_CopyAchievementDefinitionV2ByIndexEOS_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 的参数如下:

EOS_Achievements_PlayerAchievement

参数说明
ApiVersionEOS_ACHIEVEMENTS_PLAYERACHIEVEMENT_API_LATEST
AchievementId用于识别成就的独立辨识符。
Progress此成就的完成进度,以百分比显示。
UnlockTime成就被解锁的POSIX时间戳。如成就被解锁,此值将为 EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED。
StatInfoCount与此成就相关的玩家数据信息条目数量。
StatInfoEOS_Achievements_PlayerStatInfo 结构数组,包含以下信息:用于解锁成就的统计数据阈值、以及玩家在这些统计数据中当前的值。
DisplayName成就的本地化显示名称,基于此特定用户在成就上的当前进度。
EOS_Achievements_QueryPlayerAchievements 成功,成就解锁时,当前进度将更新。
Description成就的本地化描述,基于此特定用户在成就上的当前进度。
EOS_Achievements_QueryPlayerAchievements 成功,成就解锁时,当前进度将更新。
IconURL基于特定用户当前成就进度显示的图标的URL。如未在开发者门户中配置数据,这可能为空。
EOS_Achievements_QueryPlayerAchievements 成功,成就解锁时,当前进度将更新。
FlavorText能以任意方式被游戏使用的本地化风味文本。如开发者门户中未配置数据,则此文本可为空。
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
ClientData传回 CompletionDelegate 中的任意数据。
CompletionDelegate操作完成时调用的函数,使用与 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback 一致的签名。
EOS_Achievements_Query PlayerAchievementsOptions
ApiVersion设为 EOS_ACHIEVEMENTS_QUERYPLAYERACHIEVEMENTS_API_LATEST
UserId正在获取其成就进度数据的用户的帐户ID。

查询玩家成就已完成回调

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

复制玩家成就进度

玩家成就数据将缓存在本地。可以使用 EOS_Achievements_GetPlayerAchievementCount 来获取缓存的EOS成就的数量。

函数 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 柄。
Options一个 EOS_Achievements_CopyPlayerAchievementByIndexOptions 结构,包含从缓存复制的请求索引。
OutAchievement一个输出参数,包含请求的 EOS_Achievements_PlayerAchievement 的一个副本。如 OutAchievement 包含有效数据,则必须在此数据上调用 EOS_Achievements_PlayerAchievement_Release,将其从内存中释放。
EOS_Achievements_CopyPlayer AchievementByIndexOptions
ApiVersion设为 EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYINDEX_API_LATEST
UserId一个有效 EOS_ProductUserId,代表正在复制成就的用户的帐户ID。
AchievementIndex从缓存获取的玩家成就数据的索引。
[/REGION]

如请求的信息可用且传出到 OutAchievement 中,此函数将返回一个 EOS_EResult,带一个 EOS_Success 的值。如通过输出参数传递一个空指针,则其将返回 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_CopyPlayerAchievement ByAchievementIdOptions
ApiVersion设为 EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYACHIEVEMENTID_API_LATEST
UserId一个有效 EOS_ProductUserId,代表正在复制成就的用户的帐户ID。
AchievementId从缓存复制定义时要查找的成就ID。

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

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

EOS_Achievements_CopyPlayerAchievementByIndexEOS_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成就。此函数的参数如下:

EOS_Achievements_UnlockAchievements

参数说明
Handle一个有效 EOS_HAchievements 柄。
Options一个 EOS_Achievements_UnlockAchievementsOptions 结构,包含解锁EOS成就所属玩家、以及要解锁EOS成就的相关信息。
ClientData传回 CompletionDelegate 中的任意数据。
CompletionDelegate操作完成时调用的函数,使用与 EOS_Achievements_OnUnlockAchievementsCompleteCallback 一致的签名。
EOS_Achievements_ UnlockAchievementsOptions
ApiVersion设为 EOS_ACHIEVEMENTS_UNLOCKACHIEVEMENTS_API_LATEST
UserIdEOS_ProductUserId,代表要解锁成就所属用户的帐户ID。
AchievementIds要解锁的成就的ID列表。
AchievementsCount要解锁的成就的数量。

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

EOS_Achievements_OnUnlockAchievementsCompleteCallback

参数说明
ResultCodeEOS_EResult 表示操作的状态。EOS_Success 的结果意味着操作已成功完成。任何其他结果均代表错误。
ClientData传入 EOS_Achievements_UnlockAchievements 的情境。
UserIdThe EOS_ProductUserId,代表发起此请求的用户的帐户ID。
AchievementsCount要解锁的成就的数量。

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

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

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

此流程还涉及那些可能完成了新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 结构。回调信息将包含被解锁成就的 AchievementIdUnlockTime。其还包含通过 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_DefinitionV2AchievementId 参数中使用以下符号:

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

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

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

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

测试EOS成就

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