Achievements Interface

成就接口（Achievements Interface） 可用于完成以下操作：

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

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

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

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

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

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

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

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

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

EOS_Achievements_QueryDefinitions 采用以下参数：

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

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

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

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

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

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

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

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

若信息可用并传出到 OutDefinition 中，则此函数将返回一个值为 EOS_Success 的 EOS_EResult 。若为输出参数传递空指针，则将返回 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 包含后端中有关Epic在线服务成就的整体信息， EOS_Achievements_PlayerAchievement 则追踪特定玩家解锁Epic在线服务成就的进度、解锁时间（若已经解锁），以及解锁成就的相关统计信息。

EOS_Achievements_PlayerAchievement 的参数如下：

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

EOS_Achievements_QueryPlayerAchievements 的参数如下：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

此流程也适用于完成了更新后新出的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 结构。回调信息将包含已解锁成就的 AchievementId 和 UnlockTime 。它还会包含通过 EOS_Achievements_AddNotifyAchievementsUnlockedV2 传入的 ClientData 和Epic在线服务成就所属用户的 UserId 。

RemoveNotifyAchievementsUnlocked 可用于取消通知订阅。

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

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

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

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