虚幻引擎中的成就接口 | 虚幻引擎 5.2 文档

成就是一种目标或奖品，在游戏环境之外判定，因完成游戏内任务而解锁或奖励。利用成就，你可以激励、挑战和奖励玩家。你可以使用成就执行以下操作：

引导玩家完成游戏
提高游戏的重玩价值
支持玩家之间的较量

在线服务成就接口（Online Services Achievements Interface） 向你提供了工具来读取成就定义以及读取和更新玩家的成就状态。成就接口不处理成就的创建、删除或修改。每个在线服务都有自己的后端系统来管理成就的这些方面。

你可以设置以下机制来根据接口的配置解锁成就：

由平台服务管理 ：关联的统计数据达到预定义阈值时，成就会自动由平台服务解锁。
由作品管理（自动） ：关联的统计数据达到预定义阈值时，成就会自动由作品解锁。请参阅下面的配置作品自动管理的成就小节，了解更多信息。
由作品管理（手动） ：成就由作品根据作品逻辑和 UnlockAchievements 函数手动解锁。

这三个选项具体哪些可用，将根据你使用的在线服务实现/平台而有所不同。请查阅你的特定在线服务实现的文档，了解更多信息。

API概述

函数

下表概述了成就接口提供的函数：

函数	定义
`QueryAchievementDefinitions`	查询此作品的所有成就定义。
`GetAchievementIds`	检索 `QueryAchievementDefinitions` 缓存的成就的成就ID。
`GetAchievementDefinition`	使用 `QueryAchievementDefinitions` 缓存的所提供成就ID检索成就定义。
`QueryAchievementStates`	为提供的玩家查询所有成就的状态。
`GetAchievementState`	按ID为提供的玩家检索成就的状态。
`UnlockAchievements`	手动解锁提供的成就。
`DisplayAchievementUI`	为提供的成就启动平台UI。
`OnAchievementStateUpdated`	玩家的成就状态更改时触发的事件。

主结构体

成就接口主要通过三个结构体传达其功能：FAchievementDefinition 、FAchievementStatDefinition 和 FAchievementState ，以及一些特定于函数的结构体，用于传递参数和返回值。

FAchievementDefinition

成员	类型	说明
`AchievementId`	`FString`	唯一的成就ID。
`UnlockedDisplayName`	`FText`	此成就解锁之后使用的本地化显示名称。
`UnlockedDescription`	`FText`	此成就解锁之后使用的本地化说明。
`LockedDisplayName`	`FText`	此成就未解锁时使用的本地化显示名称。
`LockedDescription`	`FText`	此成就未解锁时使用的本地化说明。
`FlavorText`	`FText`	本地化风格文本。
`UnlockedIconUrl`	`FString`	解锁后使用的此成就的图标URL。
`LockedIconUrl`	`FString`	此成就未解锁时使用的图标URL。
`bIsHidden`	`bool`	此成就在解锁之前是否隐藏。
`StatDefinitions`	`TArray<FAchievementStatDefinition>`	与此成就相关的统计数据。

FAchievementStatDefinition

成员	类型	说明
`StatId`	`FString`	统计数据的唯一ID。
`UnlockThreshold`	`uint32`	要使成就自动解锁，用户必须使用关联的统计数据满足的阈值。

FAchievementState

成员	类型	说明
`AchievementId`	`FString`	与此状态相关的成就。
`Progress`	`float`	解锁此成就的进度，表示为0.0到1.0之间的百分比。小于1.0的值表示成就处于未解锁状态。值1.0表示成就已解锁。
`UnlockTime`	`FDateTime`	如果已解锁，表示此成就解锁的时间。

配置作品自动管理的成就

在成就由平台服务管理或由作品管理并手动解锁时，成就接口不需要引擎配置。如果你的成就进度由作品管理，并且你希望成就在一个或多个统计数据达到预定义阈值时自动解锁，你必须配置引擎。

对于自动解锁、由作品管理的成就，成就接口将与统计数据接口一起使用。你必须为引擎配置此机制，以设置成就的解锁规则，并基于使用统计数据接口配置定义的统计数据确定条件。

一般语法

DefaultEngine.ini

	[OnlineServices.Achievements]
	bIsTitleManaged=true
	!UnlockRules=ClearRules
	+UnlockRules=(AchievementId=<AchievementId1>, Conditions=((StatName=<StatName>, UnlockThreshold="<Type>:<Value>"), ...))
	+UnlockRules=(AchievementId=<AchievementId2>, Conditions=((StatName=<StatName>, UnlockThreshold="<Type>:<Value>"), ...))
	...

要使自动解锁且由作品管理的成就基于统计数据更改进行更新，你必须将 bIsTitleManaged 标记设置为 true 。此标记会将客户端配置为侦听在线服务统计数据接口的 FStatsUpdated 事件，以根据统计数据更改自动更新成就状态。bIsTitleManaged 标记的默认值是 false 。如果你不将此标记设置为 true ，成就不会基于 DefaultEngine.ini 中的成就定义中配置的统计数据变化而自动更新。

UnlockRules 中的 Conditions 列表包含单独的条件对。成就可能取决于与 UnlockThreshold 耦合的一个或多个统计数据。仅当成就的关联 Conditions 列表中的每个统计数据都满足或超过预定义阈值之后，成就才会解锁。

解锁规则

字段	类型	说明
`AchievementId`	`String`	与此解锁规则关联的成就的ID。
`Conditions`	`List`	此成就的解锁条件列表。

条件

字段	类型	说明
`StatName`	`String`	要关联此成就的解锁阈值的统计数据名称。
`UnlockThreshold`	冒号分隔的 `Type:Value` 对	形如 `<Type>:<Value>` 的数据对，其中 `Type` 是此统计数据的类型， `Value` 是阈值，满足此条件即可解锁此成就。

配置示例

下面是有两个不同成就的成就接口示例配置。第一个成就取决于名为 Total_Distance 的单个统计数据，它记录了玩家行进的总距离，以米为单位。第二个成就要解锁则取决于三个不同的统计数据：Distance_Run 、 Distance_Swim 和 Distance_Cycle ，全部以米为单位。

DefaultEngine.ini

	[OnlineServices.Stats]
	!StatDefinitions=ClearDefinitions
	+StatDefinitions=(Name=Total_Distance, Id=0, ModifyMethod=Sum)
	+StatDefinitions=(Name=Distance_Run, Id=1, ModifyMethod=Sum)
	+StatDefinitions=(Name=Distance_Swim, Id=2, ModifyMethod=Sum)
	+StatDefinitions=(Name=Distance_Cycle, Id=3, ModifyMethod=Sum)

	[OnlineServices.Achievements]
	bIsTitleManaged=true
	!UnlockRules=ClearRules
	+UnlockRules=(AchievementId=Around_the_World, Conditions=((StatName=Total_Distance, UnlockThreshold="Int32:40075000"))
	+UnlockRules=(AchievementId=Triathlon, Conditions=((StatName=Distance_Run, UnlockThreshold="Int32:10000"),(StatName=Distance_Swim, UnlockThreshold="Int32:1500"), (StatName=Distance_Cycle, UnlockThreshold="Int32:40000"))

读取

成就接口旨在读取成就定义和状态。下面概括说明了读取定义和状态所涉及的步骤。如需代码示例，使用在线服务接口查询和获取信息时，过程很像统计数据接口文档中的查询和获取统计数据的示例。

成就定义

成就接口可以通过执行以下步骤，读取平台服务上配置的成就的定义：

QueryAchievementDefinitions 使用成就定义填充本地接口缓存。
GetAchievementIds 检索步骤1中缓存的成就的ID列表。
GetAchievementDefinition 获取与步骤2中每个ID关联的完整定义。

FAchievementDefintion 结构体表示成就定义。对于由平台服务管理的成就，定义包含与成就关联的统计数据及其解锁阈值，高于阈值后，成就会自动解锁。

成就状态

如[成就定义]#成就定义)小节中所述，查询并检索玩家的成就定义之后，使用 QueryAchievementStates 和 GetAchievementState 读取玩家成就状态：

QueryAchievementStates 使用成就状态信息填充本地接口缓存。
GetAchievementState 检索成就的当前解锁进度（如果仍处于未解锁状态）或解锁时间（如果成就已解锁）。

对于由作品管理的成就，进度为二元0.0（未解锁）或1.0（已解锁）。对于由平台服务管理的成就，若解锁规则基于统计数据，则进度可能会准确地反映成就的当前解锁进度，表示为0.0到1.0之间的百分比。

成就接口