GAS完整指南

说明： 本文基于 tranek/GASDocumentation 的中文翻译，仅供学习参考。

我对 Unreal Engine 5 的 GameplayAbilitySystem 插件（GAS）的理解，附带一个简单的多人联机示例项目。这不是官方文档，本项目和我本人都与 Epic Games 没有关联。我不保证这些信息的准确性。

这份文档的目标是解释 GAS 中的主要概念和类，并基于我的使用经验补充一些说明。社区用户之间存在很多关于 GAS 的“口口相传经验”，我希望把我知道的内容都分享在这里。

示例项目和本文档当前基于 Unreal Engine 5.3（UE5）。本文档为旧版本 Unreal Engine 提供过分支，但这些分支已不再维护，可能存在 bug 或信息过时的问题。请使用与你的引擎版本匹配的分支。

GASShooter 是一个姊妹示例项目，展示了多人 FPS/TPS 中 GAS 的高级技巧。

最好的文档永远是插件源码本身。

1. GameplayAbilitySystem 插件简介

摘自官方文档：

Gameplay Ability System 是一个高度灵活的框架，用于构建你在 RPG 或 MOBA 类型游戏中常见的能力与属性。你可以为游戏角色创建动作类或被动类能力，创建会逐步增强或削弱各种属性的状态效果，实现用于限制这些动作使用的“冷却”计时器或资源消耗，在每个等级上改变 Ability 及其效果的等级数值，触发粒子或音效，等等。简单来说，这个系统可以帮助你设计、实现并高效联网同步游戏内能力，小到跳跃，大到任何现代 RPG 或 MOBA 游戏中你最喜欢角色的完整技能组。

GameplayAbilitySystem 插件由 Epic Games 开发，并随 Unreal Engine 一起提供。它已经在 Paragon、Fortnite 等 AAA 商业游戏中经过实战验证。

该插件为单机和多人游戏开箱即用地提供了以下能力：

• 实现带可选消耗与冷却的、基于等级的角色能力或技能（GameplayAbilities）
• 操作属于 actors 的数值型 Attributes（Attributes）
• 为 actors 应用状态效果（GameplayEffects）
• 为 actors 应用 GameplayTags（GameplayTags）
• 生成视觉或音效（GameplayCues）
• 对以上所有内容进行 Replication

在多人游戏中，GAS 还支持以下内容的客户端：

• Ability 激活
• 播放动画蒙太奇
• Attributes 变化
• 应用 GameplayTags
• 生成 GameplayCues
• 通过连接到 CharacterMovementComponent 的 RootMotionSource 函数进行移动

GAS 必须在 C++ 中完成设置，但设计师可以用 Blueprint 创建 GameplayAbilities 和 GameplayEffects。

GAS 当前存在的问题：

• GameplayEffect 的延迟校正问题（无法 Prediction Ability 冷却，因此高延迟玩家在低冷却 Ability 上的射速会低于低延迟玩家）。
• 无法 Prediction GameplayEffects 的移除。不过我们可以 Prediction 添加带相反效果的 GameplayEffects，从效果上等于移除它们。但这并不总是合适或可行，因此仍然是个问题。
• 缺少样板模板、多人示例和文档。希望这份文档能帮上忙！

2. 示例项目

本文档附带了一个多人第三人称射击示例项目，面向刚接触 GameplayAbilitySystem 插件、但并非 Unreal Engine 新手的读者。默认读者已经了解 UE 中的 C++、Blueprints、UMG、Replication 以及其他中级主题。这个项目展示了如何搭建一个基础的、可用于多人联机的第三人称射击项目：对于玩家/AI 控制的英雄，将 AbilitySystemComponent（ASC）放在 PlayerState 类上；对于 AI 控制的小兵，则将 ASC 放在 Character 类上。

目标是在保持项目简单的同时展示 GAS 基础知识，并通过带有充分注释的代码演示一些常被请求实现的能力。由于聚焦入门内容，本项目不会展示像Prediction 投射物这样的高级主题。

演示的概念包括：

• ASC 位于 PlayerState 与位于 Character 的区别
• 已 Replication 的 Attributes
• 已 Replication 的动画蒙太奇
• 在 GameplayAbilities 内部以及外部应用和移除 GameplayEffects
• 通过护甲减伤后再对角色生命值造成伤害
• 眩晕效果
• 死亡与重生
• 在服务器上从 Ability 生成 actors（投射物）
• 通过开镜瞄准和冲刺，对本地玩家速度进行 Prediction 变化
• 持续消耗耐力以冲刺
• 使用法力释放 Abilities
• 被动 Abilities
• 堆叠 GameplayEffects
• 在 Blueprint 中创建的 GameplayAbilities
• 在 C++ 中创建的 GameplayAbilities
• 按 Actor 实例化的 GameplayAbilities
• 非实例化 GameplayAbilities（Jump）
• 静态 GameplayCues（FireGun 投射物命中粒子效果）
• Actor GameplayCues（Sprint 和 Stun 粒子效果）

英雄类拥有以下 Abilities：

GameplayAbilities 用 C++ 还是 Blueprint 创建并不重要。这里混合使用两种方式，只是为了演示如何在两种语言中实现。

小兵没有任何预定义的 GameplayAbilities。红方小兵有更高的生命回复，而蓝方小兵有更高的初始生命值。

在 GameplayAbility 命名上，我使用后缀 _BP 表示该 GameplayAbility 的逻辑是用 Blueprint 编写的。没有后缀则表示逻辑是用 C++ 编写的。

Blueprint 资源命名前缀 / Blueprint Asset Naming Prefixes

3. 使用 GAS 设置项目

使用 GAS 设置项目的基本步骤如下：

1. 在 Editor 中启用 GameplayAbilitySystem 插件
2. 编辑 YourProjectName.Build.cs，将 "GameplayAbilities", "GameplayTags", "GameplayTasks" 添加到 PrivateDependencyModuleNames
3. 刷新/重新生成 Visual Studio 项目文件
4. 从 4.24 到 5.2，若要使用 TargetData，必须调用 UAbilitySystemGlobals::Get().InitGlobalData()。示例项目在 UAssetManager::StartInitialLoading() 中完成此调用。从 5.3 开始这一步会自动执行。更多信息见 InitGlobalData()。

这就是启用 GAS 所需要做的全部工作。接下来，把 ASC 和 AttributeSet 添加到你的 Character 或 PlayerState，然后开始创建 GameplayAbilities 和 GameplayEffects 吧！

4. GAS 概念

4.1 关于 Ability System Component

AbilitySystemComponent（ASC）是 GAS 的核心。它是一个 UActorComponent（UAbilitySystemComponent），负责处理与整个系统的所有交互。任何希望使用 GameplayAbilities、拥有 Attributes 或接收 GameplayEffects 的 Actor，都必须附加一个 ASC。这些对象都存在于 ASC 中，并由 ASC 管理和 Replication（Attributes 例外，它们由各自的 AttributeSet 负责 Replication）。开发者通常会为它创建子类，但并非强制要求。

附加了 ASC 的 Actor 被称为该 ASC 的 OwnerActor。ASC 的物理表现 Actor 被称为 AvatarActor。在 MOBA 中的简单 AI 小兵场景里，OwnerActor 和 AvatarActor 可以是同一个 Actor。它们也可以是不同的 Actors，例如在玩家控制的 MOBA 英雄场景中，OwnerActor 是 PlayerState，而 AvatarActor 是英雄的 Character 类。大多数 Actors 会把 ASC 放在自己身上。如果你的 Actor 会重生，并且需要在多次生成之间保留 Attributes 或 GameplayEffects（例如 MOBA 英雄），那么把 ASC 放在 PlayerState 上通常是最理想的选择。

注意： 如果你的 ASC 在 PlayerState 上，那么你需要提高 PlayerState 的 NetUpdateFrequency。PlayerState 默认值非常低，这会导致客户端在 Attributes、GameplayTags 等变化生效前出现延迟或体感卡顿。请务必启用 Adaptive Network Update Frequency，Fortnite 就使用了它。

如果 OwnerActor 和 AvatarActor 是不同的 Actors，那么两者都应该实现 IAbilitySystemInterface。这个接口只要求重写一个函数：UAbilitySystemComponent* GetAbilitySystemComponent() const，用于返回其 ASC 指针。系统内部的 ASCs 之间会通过查找这个接口函数来互相交互。

ASC 使用 FActiveGameplayEffectsContainer ActiveGameplayEffects 保存当前激活的 GameplayEffects。

ASC 使用 FGameplayAbilitySpecContainer ActivatableAbilities 保存它被授予的 Gameplay Abilities。任何时候只要你计划遍历 ActivatableAbilities.Items，都务必在循环上方加上 ABILITYLIST_SCOPE_LOCK();，以便在遍历期间锁定列表不被修改（例如避免 Ability 在遍历时被移除）。作用域内每出现一个 ABILITYLIST_SCOPE_LOCK();，AbilityScopeLockCount 就会加一；离开作用域时再减一。不要在 ABILITYLIST_SCOPE_LOCK(); 的作用域内尝试移除 Ability（清除 Ability 的相关函数会在内部检查 AbilityScopeLockCount，防止在列表锁定时移除 Ability）。

4.1.1 关于 Replication Mode

ASC 为 GameplayEffects、GameplayTags 和 GameplayCues 提供了三种不同的 Replication 模式：Full、Mixed 和 Minimal。Attributes 的 Replication 由它们各自的 AttributeSet 负责。

注意： Mixed Replication 模式要求 OwnerActor 的 Owner 必须是 Controller。PlayerState 的 Owner 默认就是 Controller，但 Character 的不是。如果你在 OwnerActor 不是 PlayerState 的情况下使用 Mixed Replication 模式，那么需要对 OwnerActor 调用 SetOwner() 并传入有效的 Controller。

从 4.24 开始，PossessedBy() 现在会把 Pawn 的 owner 设置为新的 Controller。

4.1.2 设置与初始化

ASC 通常会在 OwnerActor 的构造函数中创建，并显式标记为可 Replication。这一步必须在 C++ 中完成。

AGDPlayerState::AGDPlayerState()
{
	// Create ability system component, and set it to be explicitly replicated
	AbilitySystemComponent = CreateDefaultSubobject<UGDAbilitySystemComponent>(TEXT("AbilitySystemComponent"));
	AbilitySystemComponent->SetIsReplicated(true);
	//...
}

ASC 需要在服务器和客户端两侧都用它的 OwnerActor 与 AvatarActor 完成初始化。你应当在 Pawn 的 Controller 已经设置好之后（即 possession 之后）再初始化。单机游戏只需要关心服务器路径。

对于 ASC 位于 Pawn 上的玩家控制角色，我通常会在服务器端的 Pawn::PossessedBy() 中初始化，并在客户端的 PlayerController::AcknowledgePossession() 中初始化。

void APACharacterBase::PossessedBy(AController * NewController)
{
	Super::PossessedBy(NewController);

	if (AbilitySystemComponent)
	{
		AbilitySystemComponent->InitAbilityActorInfo(this, this);
	}

	// ASC MixedMode replication requires that the ASC Owner's Owner be the Controller.
	SetOwner(NewController);
}

void APAPlayerControllerBase::AcknowledgePossession(APawn* P)
{
	Super::AcknowledgePossession(P);

	APACharacterBase* CharacterBase = Cast<APACharacterBase>(P);
	if (CharacterBase)
	{
		CharacterBase->GetAbilitySystemComponent()->InitAbilityActorInfo(CharacterBase, CharacterBase);
	}

	//...
}

对于 ASC 位于 PlayerState 上的玩家控制角色，我通常会在服务器端的 Pawn::PossessedBy() 中初始化，并在客户端的 Pawn::OnRep_PlayerState() 中初始化。这样可以确保客户端上的 PlayerState 已经存在。

 // Server only
void AGDHeroCharacter::PossessedBy(AController * NewController)
{
	Super::PossessedBy(NewController);

	AGDPlayerState* PS = GetPlayerState<AGDPlayerState>();
	if (PS)
	{
		// Set the ASC on the Server. Clients do this in OnRep_PlayerState()
		AbilitySystemComponent = Cast<UGDAbilitySystemComponent>(PS->GetAbilitySystemComponent());

		// AI won't have PlayerControllers so we can init again here just to be sure. No harm in initing twice for heroes that have PlayerControllers.
		PS->GetAbilitySystemComponent()->InitAbilityActorInfo(PS, this);
	}

	//...
}

 // Client only
void AGDHeroCharacter::OnRep_PlayerState()
{
	Super::OnRep_PlayerState();

	AGDPlayerState* PS = GetPlayerState<AGDPlayerState>();
	if (PS)
	{
		// Set the ASC for clients. Server does this in PossessedBy.
		AbilitySystemComponent = Cast<UGDAbilitySystemComponent>(PS->GetAbilitySystemComponent());

		// Init ASC Actor Info for clients. Server will init its ASC when it possesses a new Actor.
		AbilitySystemComponent->InitAbilityActorInfo(PS, this);
	}

	// ...
}

如果你看到错误消息 LogAbilitySystem: Warning: Can't activate LocalOnly or LocalPredicted ability %s when not local!，那说明你没有在客户端初始化 ASC。

4.2 关于 Gameplay Tags

FGameplayTags 是以 Parent.Child.Grandchild... 这种层级名称形式注册到 GameplayTagManager 中的标签。这些标签在分类和描述对象状态时极其有用。例如，如果一个角色被眩晕，我们可以在眩晕持续期间给它添加一个 State.Debuff.Stun GameplayTag。

你会发现，很多过去用布尔值或枚举处理的事情，最终都会被 GameplayTags 替代，而你的逻辑也会变成判断对象是否拥有某些 GameplayTags。

给对象添加标签时，如果对象有 ASC，我们通常会把标签加到它的 ASC 上，以便 GAS 可以与这些标签交互。UAbilitySystemComponent 实现了 IGameplayTagAssetInterface，提供了访问其所拥有 GameplayTags 的函数。

多个 GameplayTags 可以存放在一个 FGameplayTagContainer 中。相较于使用 TArray<FGameplayTag>，更推荐使用 GameplayTagContainer，因为 GameplayTagContainers 做了一些效率优化。虽然标签本质上是标准 FNames，但如果在项目设置中启用了 Fast Replication，它们在 FGameplayTagContainers 中可以被高效打包并进行 Replication。Fast Replication 要求服务器和客户端拥有相同的 GameplayTags 列表。通常这不成问题，所以你应该启用这个选项。GameplayTagContainers 也可以返回 TArray<FGameplayTag> 供遍历使用。

存储在 FGameplayTagCountContainer 中的 GameplayTags 带有一个 TagMap，用于保存该 GameplayTag 的实例数量。一个 FGameplayTagCountContainer 里可能仍然存在该 GameplayTag，但其 TagMapCount 为零。调试时如果发现某个 ASC 似乎仍然持有某个 GameplayTag，你可能会遇到这种情况。任何 HasTag()、HasMatchingTag() 等类似函数都会检查 TagMapCount，如果标签不存在或者其 TagMapCount 为零，就会返回 false。

GameplayTags 必须预先定义在 DefaultGameplayTags.ini 中。Unreal Engine Editor 在项目设置中提供了一个界面，让开发者无需手动编辑 DefaultGameplayTags.ini 就能管理 GameplayTags。GameplayTag 编辑器可以创建、重命名、查找引用以及删除 GameplayTags。

搜索 GameplayTag 引用会在 Editor 中打开熟悉的 Reference Viewer 图表，显示所有引用了该 GameplayTag 的资源。不过它不会显示任何引用这个 GameplayTag 的 C++ 类。

重命名 GameplayTags 时会创建一个 redirect，以便仍然引用旧 GameplayTag 的资源可以跳转到新的 GameplayTag。如果可以的话，我更倾向于新建一个 GameplayTag，手动把所有引用更新到新的 GameplayTag，然后删除旧的 GameplayTag，以避免产生 redirect。

除了 Fast Replication 之外，GameplayTag 编辑器还有一个选项，可以填写常见会被 Replication 的 GameplayTags 以进一步优化它们。

如果 GameplayTags 是通过 GameplayEffect 添加的，它们会被 Replication。ASC 还允许你添加不会被 Replication 的 LooseGameplayTags，这类标签必须手动管理。示例项目使用一个 LooseGameplayTag 来表示 State.Dead，这样拥有者客户端可以在生命值降到零时立刻作出响应。重生时会手动把 TagMapCount 设回零。只有在处理 LooseGameplayTags 时才应手动调整 TagMapCount。相比手动修改 TagMapCount，更推荐使用 UAbilitySystemComponent::AddLooseGameplayTag() 和 UAbilitySystemComponent::RemoveLooseGameplayTag()。

在 C++ 中获取一个 GameplayTag 的引用：

FGameplayTag::RequestGameplayTag(FName("Your.GameplayTag.Name"))

如果你要进行更高级的 GameplayTag 操作，例如获取父级或子级 GameplayTags，可以查看 GameplayTagManager 提供的函数。要访问 GameplayTagManager，包含 GameplayTagManager.h，然后调用 UGameplayTagManager::Get().FunctionName。GameplayTagManager 实际上以关系节点（父、子等）的形式存储 GameplayTags，因此比持续进行字符串操作和比较更高效。

GameplayTags 和 GameplayTagContainers 可以带上可选的 UPROPERTY 说明符 Meta = (Categories = "GameplayCue")，这样在 Blueprint 中就只会显示父标签为 GameplayCue 的 GameplayTags。当你明确知道某个 GameplayTag 或 GameplayTagContainer 变量只应该用于 GameplayCues 时，这会很有用。

另一种方式是使用一个单独的结构 FGameplayCueTag，它封装了一个 FGameplayTag，并且会在 Blueprint 中自动过滤，只显示父标签为 GameplayCue 的 GameplayTags。

如果你想过滤函数中的某个 GameplayTag 参数，可以使用 UFUNCTION 说明符 Meta = (GameplayTagFilter = "GameplayCue")。函数中的 GameplayTagContainer 参数则无法这样过滤。如果你想修改引擎来支持它，可以看看 Engine\Plugins\Editor\GameplayTagsEditor\Source\GameplayTagsEditor\Private\SGameplayTagGraphPin.cpp 中 SGameplayTagGraphPin::ParseDefaultValueData() 如何调用 FilterString = UGameplayTagsManager::Get().GetCategoriesMetaFromField(PinStructType);，并在 SGameplayTagGraphPin::GetListContent() 中把 FilterString 传给 SGameplayTagWidget。而 Engine\Plugins\Editor\GameplayTagsEditor\Source\GameplayTagsEditor\Private\SGameplayTagContainerGraphPin.cpp 中对应的 GameplayTagContainer 版本函数并不会检查这些 meta 字段属性，也不会传递这个过滤器。

示例项目广泛使用了 GameplayTags。

4.2.1 响应 Gameplay Tags 的变化

ASC 提供了一个 delegate，用于在 GameplayTags 被添加或移除时触发。它接收一个 EGameplayTagEventType，可指定只在 GameplayTag 被添加/移除时触发，或者在该 GameplayTag 的 TagMapCount 发生任何变化时触发。

AbilitySystemComponent->RegisterGameplayTagEvent(FGameplayTag::RequestGameplayTag(FName("State.Debuff.Stun")), EGameplayTagEventType::NewOrRemoved).AddUObject(this, &AGDPlayerState::StunTagChanged);

回调函数会接收 GameplayTag 和新的 TagCount 作为参数。

virtual void StunTagChanged(const FGameplayTag CallbackTag, int32 NewCount);

4.2.2 从插件 .ini 文件加载 Gameplay Tags

如果你创建了一个插件，并且它有自己包含 GameplayTags 的 .ini 文件，那么你可以在插件的 StartupModule() 函数中加载该插件的 GameplayTag .ini 目录。

例如，Unreal Engine 自带的 CommonConversation 插件就是这样做的：

void FCommonConversationRuntimeModule::StartupModule()
{
	TSharedPtr<IPlugin> ThisPlugin = IPluginManager::Get().FindPlugin(TEXT("CommonConversation"));
	check(ThisPlugin.IsValid());

	UGameplayTagsManager::Get().AddTagIniSearchPath(ThisPlugin->GetBaseDir() / TEXT("Config") / TEXT("Tags"));

	//...
}

这会在引擎启动时查找目录 Plugins\CommonConversation\Config\Tags，并在插件启用的情况下，把其中所有带有 GameplayTags 的 .ini 文件加载到你的项目里。

4.3 关于 Attributes

4.3.1 Attributes 定义

Attributes 是由结构体 FGameplayAttributeData 定义的 float 值。它们可以表示从角色生命值、角色等级，到药水剩余充能次数等各种内容。只要某个数值属于某个 Actor，并且与玩法相关，你就应该考虑把它实现为一个 Attribute。通常 Attributes 应只通过 GameplayEffects 来修改，这样 ASC 才能对这些变化进行 Prediction。

Attributes 由 AttributeSet 定义并存储在其中。AttributeSet 负责 Replication 被标记为可同步的 Attributes。关于如何定义 Attributes，请参见 AttributeSets 章节。

提示： 如果你不想让某个 Attribute 出现在 Editor 的 Attributes 列表中，可以使用 Meta = (HideInDetailsView) property specifier。

4.3.2 BaseValue 与 CurrentValue

一个 Attribute 由两个值组成：BaseValue 和 CurrentValue。BaseValue 是该 Attribute 的永久值，而 CurrentValue 则是 BaseValue 加上来自 GameplayEffects 的临时修改。比如，你的 Character 可能有一个移动速度 Attribute，它的 BaseValue 是 600 units/second。因为这时还没有 GameplayEffects 修改移动速度，所以 CurrentValue 也是 600 u/s。如果角色获得一个临时的 50 u/s 移速增益，那么 BaseValue 仍然是 600 u/s，而 CurrentValue 会变成 600 + 50，也就是 650 u/s。当这个移速增益结束后，CurrentValue 会恢复为 BaseValue 的 600 u/s。

很多 GAS 初学者经常会把 BaseValue 误认为是某个 Attribute 的最大值，并试图这样使用它。这是错误的做法。对于会变化、或者需要在 Ability 或 UI 中引用的最大值，应该把它们当作单独的 Attributes。对于写死的最大/最小值，虽然可以通过 FAttributeMetaData 定义一个 DataTable 来设置这些限制，但 Epic 在该结构体上方的注释里也说明它仍是“work in progress”。更多信息请参见 AttributeSet.h。为了避免混淆，我建议：凡是会在 Ability 或 UI 中被引用的最大值，都做成单独的 Attributes；而仅用于 clamp Attributes 的硬编码最大值与最小值，则在 AttributeSet 中定义为硬编码 float。关于 Attributes 的 clamp：对于 CurrentValue 的变化，请参考 PreAttributeChange()；对于 GameplayEffects 引起的 BaseValue 变化，请参考 PostGameplayEffectExecute()。

对 BaseValue 的永久修改来自 Instant GameplayEffects，而 Duration 和 Infinite GameplayEffects 修改的是 CurrentValue。Periodic GameplayEffects 会被当作 instant GameplayEffects 处理，因此它们修改的也是 BaseValue。

有些 Attributes 会被当作临时值占位符，用来与其他 Attributes 交互。这些就叫做 Meta Attributes。例如，我们通常会把 damage 定义成一个 Meta Attribute。不是让 GameplayEffect 直接修改 health Attribute，而是把 damage 作为一个占位值。这样 damage 值就可以在 GameplayEffectExecutionCalculation 中被 buff/debuff 修改，也可以在 AttributeSet 中进一步处理，例如先从当前 shield Attribute 中扣除 damage，再把剩余值从 health Attribute 中扣除。damage 这个 Meta Attribute 不会在不同 GameplayEffects 之间持久存在，每次都会被新的值覆盖。Meta Attributes 通常不会被 Replication。

Meta Attributes 为诸如伤害和治疗之类的流程提供了一个很好的逻辑分层：把“我们造成了多少伤害？”和“我们如何处理这份伤害？”分开。这种分离意味着我们的 Gameplay Effects 和 Execution Calculations 不需要知道目标是如何处理伤害的。继续用伤害举例：Gameplay Effect 负责确定伤害数值，而 AttributeSet 决定如何处理这些伤害。并不是所有角色都会有同样的 Attributes，尤其是在你使用 AttributeSets 子类时。基础 AttributeSet 类可能只有 health Attribute，而某个子类 AttributeSet 可能额外增加 shield Attribute。拥有 shield Attribute 的子类 AttributeSet，收到伤害时就会采用不同于基础 AttributeSet 类的分配方式。

虽然 Meta Attributes 是很好的设计模式，但并不是强制要求。如果你的所有伤害实例都只会用同一个 Execution Calculation，并且所有角色也只共享一个 Attribute Set 类，那么你也许完全可以直接在 Execution Calculation 里完成对 health、shield 等的伤害分配，并直接修改那些 Attributes。你牺牲的只是灵活性，但这对你的项目来说可能完全可以接受。

4.3.4 响应 Attributes 变化

如果你想监听某个 Attribute 的变化，以更新 UI 或驱动其他玩法逻辑，可以使用 UAbilitySystemComponent::GetGameplayAttributeValueChangeDelegate(FGameplayAttribute Attribute)。这个函数会返回一个 delegate，你可以将它绑定到回调上；只要该 Attribute 发生变化，回调就会自动触发。该 delegate 会提供一个 FOnAttributeChangeData 参数，其中包含 NewValue、OldValue 和 FGameplayEffectModCallbackData。注意： FGameplayEffectModCallbackData 只会在服务器上有值。

AbilitySystemComponent->GetGameplayAttributeValueChangeDelegate(AttributeSetBase->GetHealthAttribute()).AddUObject(this, &AGDPlayerState::HealthChanged);

virtual void HealthChanged(const FOnAttributeChangeData& Data);

示例项目在 GDPlayerState 上绑定了这些 Attribute 值变化的 delegates，用于更新 HUD，并在生命值降到零时响应玩家死亡。

示例项目中还包含了一个自定义 Blueprint 节点，它把这件事包装成了一个 ASyncTask。该节点在 UI_HUD 的 UMG Widget 中用于更新 health、mana 和 stamina 数值。这个 AsyncTask 会一直存活，直到你手动调用 EndTask()；我们在 UMG Widget 的 Destruct 事件中这么做。见 AsyncTaskAttributeChanged.h/cpp。

4.3.5 派生 Attributes

如果你想创建一个 Attribute，让它的全部或部分值从一个或多个其他 Attributes 派生而来，可以使用一个带有一个或多个 Attribute Based 或 MMC Modifiers 的 Infinite GameplayEffect。当它依赖的某个 Attribute 更新时，这个 Derived Attribute 会自动更新。

应用到 Derived Attribute 上的所有 Modifiers 最终采用的公式，与 Modifier Aggregators 的公式相同。如果你需要按特定顺序执行计算，请把所有逻辑都放进一个 MMC 里。

((CurrentValue + Additive) * Multiplicitive) / Division

注意： 如果你在 PIE 中使用多个客户端测试，需要在 Editor Preferences 中关闭 Run Under One Process，否则除了第一个客户端之外，其余客户端上的 Derived Attributes 不会在其依赖 Attributes 变化时自动更新。

在这个例子里，我们使用一个 Infinite GameplayEffect，让 TestAttrA 的值从 TestAttrB 和 TestAttrC 这两个 Attributes 派生，公式是 TestAttrA = (TestAttrA + TestAttrB) * ( 2 * TestAttrC)。每当其中任意一个 Attribute 的值发生变化时，TestAttrA 都会自动重新计算。

4.4 关于 Attribute Set

4.4.1 Attribute Set 定义

AttributeSet 用于定义、保存并管理 Attributes 的变化。开发者应该从 UAttributeSet 继承创建子类。在 OwnerActor 的构造函数中创建 AttributeSet 会自动把它注册到对应的 ASC 上。这一步必须在 C++ 中完成。

4.4.2 Attribute Set 设计

一个 ASC 可以拥有一个或多个 AttributeSets。AttributeSets 的内存开销几乎可以忽略不计，因此使用多少个 AttributeSets 更多是一个组织结构上的决定，由开发者自行权衡。

你完全可以只使用一个大型的、单体式 AttributeSet，让游戏里每个 Actor 都共享它；需要时使用其中的属性，不需要时就忽略未使用的属性。

另一种做法是使用多个 AttributeSet，按 Attributes 的分组来组织，并根据需要有选择地加到不同的 Actors 上。例如，你可以有一个负责生命相关 Attributes 的 AttributeSet，一个负责法力相关 Attributes 的 AttributeSet，等等。在 MOBA 游戏里，英雄可能需要法力，而小兵可能不需要。因此英雄会获得 mana AttributeSet，而小兵不会。

此外，你还可以通过继承 AttributeSets 的方式，有选择地决定某个 Actor 拥有哪些 Attributes。内部表示时，Attributes 的名称格式是 AttributeSetClassName.AttributeName。当你继承一个 AttributeSet 时，父类里的所有 Attributes 仍然会继续使用父类名作为前缀。

虽然你可以拥有多个 AttributeSet，但你不应该在同一个 ASC 上放置多个同类 AttributeSet。如果同一类 AttributeSet 存在多个实例，系统不知道该使用哪一个，最终只会随意选一个。

4.4.2.1 带独立 Attributes 的子组件

在某些场景中，一个 Pawn 可能带有多个可受伤的组件，比如可分别被破坏的护甲部件。如果你知道一个 Pawn 最多会有多少个这类可受伤组件，我建议在一个 AttributeSet 上预先定义那么多个 health Attributes，例如 DamageableCompHealth0、DamageableCompHealth1 等，把它们当作这些可受伤组件对应的逻辑“槽位”。在你的可受伤组件实例类中，分配一个槽位编号 Attribute，这样 GameplayAbilities 或 Executions 就能读取这个编号，并知道该把伤害作用到哪个 Attribute 上。拥有少于最大数量、甚至完全没有这类组件的 Pawns 也没有问题。AttributeSet 里有某个 Attribute，并不意味着你必须用它。未使用的 Attributes 只占用极少的内存。

如果你的子组件每个都需要很多 Attributes、子组件数量理论上没有上限、子组件可以拆下并被其他玩家使用（例如武器），或者出于其他原因这个方案不适合你，那么我建议不要再使用 Attributes，而是直接在这些组件上存储普通 float。见 物品。

4.4.2.2 运行时添加和移除 AttributeSets

AttributeSets 可以在运行时被添加到 ASC 或从中移除；不过，移除 AttributeSets 可能很危险。比如说，如果客户端先于服务器移除了某个 AttributeSet，而这时服务器又把某个 Attribute 的值变化 Replication 到客户端，那么该 Attribute 在客户端上就找不到自己的 AttributeSet，从而导致游戏崩溃。

武器加入背包时：

AbilitySystemComponent->GetSpawnedAttributes_Mutable().AddUnique(WeaponAttributeSetPointer);
AbilitySystemComponent->ForceReplication();

武器从背包移除时：

AbilitySystemComponent->GetSpawnedAttributes_Mutable().Remove(WeaponAttributeSetPointer);
AbilitySystemComponent->ForceReplication();

4.4.2.3 物品 Attributes（武器弹药）

实现可装备物品的 Attributes（武器弹药、护甲耐久等）有几种方式。这几种方式都会把数值直接存储在物品本身上。这对于那些生命周期内可能被多个玩家装备过的物品来说是必须的。

1. 在物品上使用普通 float（推荐）
2. 在物品上放置独立的 AttributeSet
3. 在物品上放置独立的 ASC

4.4.2.3.1 物品上的普通 float

与其使用 Attributes，不如直接在物品类实例上存储普通 float 值。Fortnite 和 GASShooter 都是这样处理枪械弹药的。对于一把枪，你可以直接在枪实例上用可 Replication 的 float（COND_OwnerOnly）保存弹匣最大容量、当前弹匣子弹数、备用弹药等。如果多个武器共享备用弹药，那么你应当把备用弹药移动到角色身上，作为共享弹药 AttributeSet 中的一个 Attribute（装填 Ability 可以使用 Cost GE，把共享备用弹药扣除并补到枪的 float 弹匣子弹数中）。因为当前弹匣子弹数不再使用 Attributes，你需要重写 UGameplayAbility 中的一些函数，以便基于枪上的 float 来检查和应用消耗。若在授予 Ability 时，把枪设置为 GameplayAbilitySpec 的 SourceObject，那么在 Ability 内部你就能访问到这把授予该 Ability 的枪。

为了防止自动射击期间，枪械把 ammo 数量 Replication 回本地并覆盖本地 ammo 数值，可以在 PreReplication() 中，当玩家拥有 IsFiring GameplayTag 时禁用这部分 Replication。本质上你是在自己实现一套本地 Prediction。

void AGSWeapon::PreReplication(IRepChangedPropertyTracker& ChangedPropertyTracker)
{
	Super::PreReplication(ChangedPropertyTracker);

	DOREPLIFETIME_ACTIVE_OVERRIDE(AGSWeapon, PrimaryClipAmmo, (IsValid(AbilitySystemComponent) && !AbilitySystemComponent->HasMatchingGameplayTag(WeaponIsFiringTag)));
	DOREPLIFETIME_ACTIVE_OVERRIDE(AGSWeapon, SecondaryClipAmmo, (IsValid(AbilitySystemComponent) && !AbilitySystemComponent->HasMatchingGameplayTag(WeaponIsFiringTag)));
}

优点：

1. 避免使用 AttributeSets 的限制（见下文）

限制：

1. 不能直接使用现有的 GameplayEffect 工作流（例如使用 Cost GEs 扣除弹药等）
2. 需要额外重写 UGameplayAbility 中的关键函数，才能基于枪上的 float 检查和应用弹药消耗

4.4.2.3.2 物品上的 AttributeSet

在物品上使用独立的 AttributeSet，并在物品加入玩家背包时把它添加到玩家的 ASC 中，这种做法是可行的，但有几个很大的限制。在早期版本的 GASShooter 中，我就是这样处理武器弹药的。武器把诸如弹匣最大容量、当前弹匣子弹数、备用弹药等 Attributes 存在一个挂在武器类上的 AttributeSet 里。如果多个武器共享备用弹药，那么你应该把备用弹药移到角色身上，放在一个共享弹药 AttributeSet 中。当武器在服务器上加入玩家背包时，武器会把自己的 AttributeSet 加到玩家 ASC::SpawnedAttributes 中。随后服务器会把这件事 Replication 给客户端。如果武器从背包中移除，它也会把自己的 AttributeSet 从 ASC::SpawnedAttributes 中移除。

当 AttributeSet 挂在 OwnerActor 之外的对象上（比如武器）时，你一开始通常会在 AttributeSet 中遇到一些编译错误。解决办法是在 BeginPlay() 而不是构造函数中创建 AttributeSet，并且在武器上实现 IAbilitySystemInterface（当武器加入玩家背包时，把 ASC 指针设置进去）。

void AGSWeapon::BeginPlay()
{
	if (!AttributeSet)
	{
		AttributeSet = NewObject<UGSWeaponAttributeSet>(this);
	}
	//...
}

如果你想看实际实现，可以查看这个 GASShooter 的旧版本。

优点：

1. 可以使用现有的 GameplayAbility 和 GameplayEffect 工作流（例如用 Cost GEs 扣除弹药）
2. 对于非常少量的物品，设置起来较简单

限制：

1. 你必须为每种武器类型新建一个 AttributeSet 类。ASCs 实际上只能有效使用某个类的一个 AttributeSet 实例，因为当某个 Attribute 发生变化时，系统会在 ASCs 的 SpawnedAttributes 数组中查找该 AttributeSet 类的第一个实例。后续同类 AttributeSet 实例都会被忽略。
2. 由于上一个原因，玩家背包里每种武器类型只能有一把，因为每个 AttributeSet 类只能有一个实例。
3. 移除一个 AttributeSet 是危险的。在 GASShooter 中，如果玩家被自己的火箭炸死，系统会立刻把火箭发射器从背包里移除（包括把它的 AttributeSet 从 ASC 中移除）。当服务器随后 Replication 火箭发射器的 ammo Attribute 变化时，客户端 ASC 上已经没有对应的 AttributeSet 了，游戏就崩溃了。

4.4.2.3.3 物品上的 ASC

给每个物品都挂一个完整的 AbilitySystemComponent 是一种非常极端的做法。我自己没有这么做过，也没在实际项目中见过。这会需要相当多的工程投入才能运转起来。

让多个 AbilitySystemComponents 共享同一个 owner、但拥有不同的 avatars，是否可行？（例如 pawn、weapon、items、projectiles 上都有，各自的 Owner 都指向 PlayerState）

我首先看到的问题会是：在 owning actor 上实现 IGameplayTagAssetInterface 和 IAbilitySystemInterface。前者也许可行：只需要把所有 ASC 的 tags 聚合起来（不过要注意，HasAllMatchingGameplayTags 可能只有在跨 ASC 聚合时才成立。不能只是简单把调用转发到每个 ASC，再把结果 OR 起来）。但后者更棘手：到底哪个 ASC 才是权威的？如果有人想应用一个 GE，应该交给哪一个来接收？也许你能把这些问题解决掉，但这部分会是最难的：owners 下面会挂着多个 ASC。

不过，把独立的 ASC 放在 pawn 和 weapon 上，本身倒是可能说得通。比如，把描述 weapon 的 tags 和描述拥有它的 pawn 的 tags 分开。也许让授予给 weapon 的 tags 同样“作用于” owner，而其他内容（例如 attributes 和 GEs）仍然保持独立，同时 owner 聚合这些 owned tags，像我上面描述的那样，这确实可能可行。我相信这是能做出来的。但让多个 ASC 共享同一个 owner 可能会变得很棘手。

Dave Ratti（Epic）对社区问题 #6 的回答

优点：

1. 可以使用现有的 GameplayAbility 和 GameplayEffect 工作流（例如用 Cost GEs 扣除弹药）
2. 可以复用 AttributeSet 类（每个武器 ASC 上挂一个）

限制：

1. 工程成本未知
2. 这件事究竟是否可行都还不确定

4.4.3 定义 Attributes

Attributes 只能在 C++ 中定义，并且定义位置在 AttributeSet 的头文件中。建议在每个 AttributeSet 头文件顶部加上这一组宏。它会自动为你的 Attributes 生成 getter 和 setter 函数。

 // Uses macros from AttributeSet.h
#define ATTRIBUTE_ACCESSORS(ClassName, PropertyName) \
	GAMEPLAYATTRIBUTE_PROPERTY_GETTER(ClassName, PropertyName) \
	GAMEPLAYATTRIBUTE_VALUE_GETTER(PropertyName) \
	GAMEPLAYATTRIBUTE_VALUE_SETTER(PropertyName) \
	GAMEPLAYATTRIBUTE_VALUE_INITTER(PropertyName)

一个会进行 Replication 的 health Attribute 可以这样定义：

UPROPERTY(BlueprintReadOnly, Category = "Health", ReplicatedUsing = OnRep_Health)
FGameplayAttributeData Health;
ATTRIBUTE_ACCESSORS(UGDAttributeSetBase, Health)

还要在头文件里定义 OnRep 函数：

UFUNCTION()
virtual void OnRep_Health(const FGameplayAttributeData& OldHealth);

在 AttributeSet 的 .cpp 文件中，应当用 Prediction 系统使用的 GAMEPLAYATTRIBUTE_REPNOTIFY 宏来实现 OnRep 函数：

void UGDAttributeSetBase::OnRep_Health(const FGameplayAttributeData& OldHealth)
{
	GAMEPLAYATTRIBUTE_REPNOTIFY(UGDAttributeSetBase, Health, OldHealth);
}

最后，还需要把这个 Attribute 加入 GetLifetimeReplicatedProps：

void UGDAttributeSetBase::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
	Super::GetLifetimeReplicatedProps(OutLifetimeProps);

	DOREPLIFETIME_CONDITION_NOTIFY(UGDAttributeSetBase, Health, COND_None, REPNOTIFY_Always);
}

REPNOTIFY_Always 的含义是：即便本地值因为 Prediction 已经等于服务器 Replication 下来的值，也依然会触发 OnRep。默认情况下，如果本地值和服务器传下来的值相同，OnRep 是不会触发的。

如果这个 Attribute 不需要 Replication，比如 Meta Attribute，那么 OnRep 和 GetLifetimeReplicatedProps 这两步就可以省略。

4.4.4 初始化 Attributes

初始化 Attributes（设置它们的 BaseValue，并因此使 CurrentValue 也拥有某个初始值）有多种方式。Epic 推荐使用一个 instant GameplayEffect。示例项目也采用了这种方式。

如何创建一个用于初始化 Attributes 的 instant GameplayEffect，请查看示例项目中的 GE_HeroAttributes Blueprint。这个 GameplayEffect 的应用是在 C++ 中完成的。

如果你在定义 Attributes 时使用了 ATTRIBUTE_ACCESSORS 宏，那么 AttributeSet 会自动为每个 Attribute 生成一个初始化函数，你可以在 C++ 中随时调用。

 // InitHealth(float InitialValue) is an automatically generated function for an Attribute 'Health' defined with the `ATTRIBUTE_ACCESSORS` macro
AttributeSet->InitHealth(100.0f);

更多初始化 Attributes 的方式，请查看 AttributeSet.h。

注意： 在 4.24 之前，FAttributeSetInitterDiscreteLevels 不能和 FGameplayAttributeData 一起工作。它是在 Attributes 还是原始 float 时创建的，因此会抱怨 FGameplayAttributeData 不是 Plain Old Data（POD）。这个问题已在 4.24 中修复：https://issues.unrealengine.com/issue/UE-76557。

PreAttributeChange(const FGameplayAttribute& Attribute, float& NewValue) 是 AttributeSet 中响应 Attribute 的 CurrentValue 变化、且发生在变化之前的主要函数之一。它是通过引用参数 NewValue 对即将到来的 CurrentValue 变化进行 clamp 的理想位置。

例如，在示例项目中，对移动速度 modifiers 的 clamp 是这样做的：

if (Attribute == GetMoveSpeedAttribute())
{
	// Cannot slow less than 150 units/s and cannot boost more than 1000 units/s
	NewValue = FMath::Clamp<float>(NewValue, 150, 1000);
}

GetMoveSpeedAttribute() 函数是由我们加入到 AttributeSet.h 中的宏块生成的（见 定义）。

无论 Attributes 的变化来自 Attribute setters（由 AttributeSet.h 中的宏块定义，见 定义）还是来自 GameplayEffects，这里都会被触发。

注意： 在这里做的任何 clamp 都不会永久修改 ASC 上的 modifier 本身。它只会改变查询 modifier 时返回的值。这意味着，任何会根据全部 modifiers 重新计算 CurrentValue 的地方，例如 GameplayEffectExecutionCalculations 和 ModifierMagnitudeCalculations，都需要再次实现 clamp 逻辑。

注意： Epic 对 PreAttributeChange() 的注释中提到，不要用它来触发玩法事件，而应主要用于 clamp。对 Attribute 变化响应玩法事件的推荐位置，是 UAbilitySystemComponent::GetGameplayAttributeValueChangeDelegate(FGameplayAttribute Attribute)（见 响应 Attributes 变化）。

PostGameplayEffectExecute(const FGameplayEffectModCallbackData & Data) 只会在 instant GameplayEffect 修改某个 Attribute 的 BaseValue 之后触发。当 Attributes 因某个 GameplayEffect 而发生变化时，这里是进一步处理它们的合适位置。

例如，在示例项目里，我们会在这里把最终的 damage Meta Attribute 从 health Attribute 中扣掉。如果存在 shield Attribute，就会先从 shield 中扣除伤害，再把剩余值从 health 中扣除。示例项目还会在这里触发受击反应动画、显示飘字伤害数字，并把经验和金币赏金分配给击杀者。按照设计，damage Meta Attribute 总是通过 instant GameplayEffect 进入，而不会通过 Attribute setter。

对于 mana、stamina 这类只会被 instant GameplayEffects 修改 BaseValue 的其他 Attributes，也可以在这里把它们 clamp 到与之对应的最大值 Attributes。

注意： 当 PostGameplayEffectExecute() 被调用时，Attribute 的变化已经发生，但还没有 Replication 回客户端，因此在这里进行 clamp 不会导致客户端收到两次网络更新。客户端只会在 clamp 完成后收到更新。

OnAttributeAggregatorCreated(const FGameplayAttribute& Attribute, FAggregator* NewAggregator) 会在该集合中的某个 Attribute 创建 Aggregator 时触发。它允许你自定义 FAggregatorEvaluateMetaData 的设置。AggregatorEvaluateMetaData 由 Aggregator 用于根据所有作用其上的 Modifiers 来计算 Attribute 的 CurrentValue。默认情况下，AggregatorEvaluateMetaData 只用于决定哪些 Modifiers 具备参与计算的资格。一个典型例子是 MostNegativeMod_AllPositiveMods：它允许所有正向 Modifiers 生效，但负向 Modifiers 中只允许“最负”的那个生效。Paragon 就用它来实现：无论玩家身上同时存在多少个减速效果，都只应用其中最强的那个负向移速效果，而所有正向移速增益都会生效。不符合资格的 Modifiers 仍然存在于 ASC 中，只是不会被聚合到最终的 CurrentValue 里。一旦条件变化，它们未来仍可能重新具备资格；例如当当前“最负”的那个 Modifier 过期后，下一个最负的 Modifier（如果存在）就会变成合格项。

下面这个例子展示了如何通过 AggregatorEvaluateMetaData 实现“只允许最强负向 Modifier 和所有正向 Modifiers 生效”：

virtual void OnAttributeAggregatorCreated(const FGameplayAttribute& Attribute, FAggregator* NewAggregator) const override;

void UGSAttributeSetBase::OnAttributeAggregatorCreated(const FGameplayAttribute& Attribute, FAggregator* NewAggregator) const
{
	Super::OnAttributeAggregatorCreated(Attribute, NewAggregator);

	if (!NewAggregator)
	{
		return;
	}

	if (Attribute == GetMoveSpeedAttribute())
	{
		NewAggregator->EvaluationMetaData = &FAggregatorEvaluateMetaDataLibrary::MostNegativeMod_AllPositiveMods;
	}
}

你自定义的、用于 qualifier 的 AggregatorEvaluateMetaData 应该作为静态变量添加到 FAggregatorEvaluateMetaDataLibrary 中。

4.5 关于 Gameplay Effects

4.5.1 Gameplay Effect 定义

GameplayEffects（GE）是 abilities 用来改变自身和其他对象上的 Attributes 与 GameplayTags 的载体。它们既可以造成即时的 Attribute 变化，例如伤害或治疗，也可以施加长期状态 buff/debuff，例如移动速度提升或眩晕。UGameplayEffect 类应当是一个纯数据类，用于定义单个 gameplay effect。不应向 GameplayEffects 中添加额外逻辑。通常设计师会创建许多 UGameplayEffect 的 Blueprint 子类。

GameplayEffects 通过 Modifiers 和 Executions（GameplayEffectExecutionCalculation） 来改变 Attributes。

GameplayEffects 有三种持续时间类型：Instant、Duration 和 Infinite。

另外，GameplayEffects 还可以添加/执行 GameplayCues。Instant GameplayEffect 会对 GameplayCue GameplayTags 调用 Execute，而 Duration 或 Infinite GameplayEffect 会对 GameplayCue GameplayTags 调用 Add 和 Remove。

Duration 和 Infinite GameplayEffects 可以选择应用 Periodic Effects，即按照其 Period 定义的每 X 秒执行一次其 Modifiers 和 Executions。在修改 Attribute 的 BaseValue 以及执行 GameplayCues 时，Periodic Effects 会被当作 Instant GameplayEffects 处理。这对于持续伤害（DOT）类效果很有用。注意：Periodic Effects 不能被 predicted。

Duration 和 Infinite GameplayEffects 在应用之后，如果其 Ongoing Tag Requirements 不满足/满足条件，还可以被临时关闭和重新开启（见 Gameplay Effect Tags）。关闭一个 GameplayEffect 会移除其 Modifiers 和已应用的 GameplayTags 的效果，但不会移除这个 GameplayEffect 本身。重新开启该 GameplayEffect 时，会重新应用其 Modifiers 和 GameplayTags。

如果你需要手动重新计算某个 Duration 或 Infinite GameplayEffect 的 Modifiers（例如你有一个 MMC 使用的数据并不来自 Attributes），你可以调用 UAbilitySystemComponent::ActiveGameplayEffects.SetActiveGameplayEffectLevel(FActiveGameplayEffectHandle ActiveHandle, int32 NewLevel)，并传入它当前已有的相同 level，该 level 可通过 UAbilitySystemComponent::ActiveGameplayEffects.GetActiveGameplayEffect(ActiveHandle).Spec.GetLevel() 获取。基于后备 Attributes 的 Modifiers 会在这些后备 Attributes 更新时自动更新。SetActiveGameplayEffectLevel() 用于更新 Modifiers 的关键函数如下：

MarkItemDirty(Effect);
Effect.Spec.CalculateModifierMagnitudes();
// Private function otherwise we'd call these three functions without needing to set the level to what it already is
UpdateAllAggregatorModMagnitudes(Effect);

GameplayEffects 通常不会被直接实例化。当一个 ability 或 ASC 想要应用某个 GameplayEffect 时，它会从该 GameplayEffect 的 ClassDefaultObject 创建一个 GameplayEffectSpec。成功应用的 GameplayEffectSpecs 随后会被加入到一个名为 FActiveGameplayEffect 的新结构体中，而这正是 ASC 在一个名为 ActiveGameplayEffects 的特殊容器结构体中跟踪的对象。

4.5.2 应用 Gameplay Effects

GameplayEffects 可以通过 GameplayAbilities 上的函数以及 ASC 上的函数以多种方式应用，通常表现为 ApplyGameplayEffectTo 这一类函数。不同函数本质上都是便捷封装，最终通常都会在 Target 上调用 UAbilitySystemComponent::ApplyGameplayEffectSpecToSelf()。

如果要在 GameplayAbility 之外应用 GameplayEffects，例如从一个 projectile 中应用，你需要获取 Target 的 ASC，然后使用其某个 ApplyGameplayEffectToSelf 函数。

你可以通过绑定其 delegate，监听任意 Duration 或 Infinite GameplayEffects 被应用到某个 ASC 上的事件：

AbilitySystemComponent->OnActiveGameplayEffectAddedDelegateToSelf.AddUObject(this, &APACharacterBase::OnActiveGameplayEffectAddedCallback);

回调函数：

virtual void OnActiveGameplayEffectAddedCallback(UAbilitySystemComponent* Target, const FGameplayEffectSpec& SpecApplied, FActiveGameplayEffectHandle ActiveHandle);

无论使用哪种 Replication 模式，服务器都会始终调用这个函数。autonomous proxy 只会在 Full 和 Mixed Replication 模式下，对已复制的 GameplayEffects 调用它。simulated proxy 则只会在 Full Replication 模式下调用它。

4.5.3 移除 Gameplay Effects

GameplayEffects 可以通过 GameplayAbilities 上的函数以及 ASC 上的函数以多种方式移除，通常表现为 RemoveActiveGameplayEffect 这一类函数。不同函数本质上都是便捷封装，最终通常都会在 Target 上调用 FActiveGameplayEffectsContainer::RemoveActiveEffects()。

如果要在 GameplayAbility 之外移除 GameplayEffects，你需要获取 Target 的 ASC，然后使用其某个 RemoveActiveGameplayEffect 函数。

你可以通过绑定其 delegate，监听任意 Duration 或 Infinite GameplayEffects 从某个 ASC 上移除的事件：

AbilitySystemComponent->OnAnyGameplayEffectRemovedDelegate().AddUObject(this, &APACharacterBase::OnRemoveGameplayEffectCallback);

回调函数：

virtual void OnRemoveGameplayEffectCallback(const FActiveGameplayEffect& EffectRemoved);

无论使用哪种 Replication 模式，服务器都会始终调用这个函数。autonomous proxy 只会在 Full 和 Mixed Replication 模式下，对已复制的 GameplayEffects 调用它。simulated proxy 则只会在 Full Replication 模式下调用它。

Modifiers 会改变一个 Attribute，并且它们是唯一可以预测式地改变 Attribute 的方式。一个 GameplayEffect 可以有零个或多个 Modifiers。每个 Modifier 只负责通过某个指定操作改变一个 Attribute。

一个 Attribute 的 CurrentValue 是其所有 Modifiers 与其 BaseValue 聚合后的结果。Modifiers 的聚合公式在 GameplayEffectAggregator.cpp 的 FAggregatorModChannel::EvaluateWithBase 中定义如下：

((InlineBaseValue + Additive) * Multiplicitive) / Division

任何 Override Modifiers 都会覆盖最终值，并且最后应用的 Modifier 具有最高优先级。

**注意：**对于基于百分比的变化，请确保使用 Multiply 操作，这样它会发生在加法之后。

注意：Prediction 对百分比变化的支持存在问题。

Modifiers 有四种类型：Scalable Float、Attribute Based、Custom Calculation Class 和 Set By Caller。它们都会生成某个 float 值，然后根据其操作方式用于改变 Modifier 所指定的 Attribute。

4.5.4.1 Multiply 和 Divide Modifiers

默认情况下，所有 Multiply 和 Divide Modifiers 会先彼此相加，然后再乘到或除到该 Attribute 的 BaseValue 上。

float FAggregatorModChannel::EvaluateWithBase(float InlineBaseValue, const FAggregatorEvaluateParameters& Parameters) const
{
	...
	float Additive = SumMods(Mods[EGameplayModOp::Additive], GameplayEffectUtilities::GetModifierBiasByModifierOp(EGameplayModOp::Additive), Parameters);
	float Multiplicitive = SumMods(Mods[EGameplayModOp::Multiplicitive], GameplayEffectUtilities::GetModifierBiasByModifierOp(EGameplayModOp::Multiplicitive), Parameters);
	float Division = SumMods(Mods[EGameplayModOp::Division], GameplayEffectUtilities::GetModifierBiasByModifierOp(EGameplayModOp::Division), Parameters);
	...
	return ((InlineBaseValue + Additive) * Multiplicitive) / Division;
	...
}

float FAggregatorModChannel::SumMods(const TArray<FAggregatorMod>& InMods, float Bias, const FAggregatorEvaluateParameters& Parameters)
{
	float Sum = Bias;

	for (const FAggregatorMod& Mod : InMods)
	{
		if (Mod.Qualifies())
		{
			Sum += (Mod.EvaluatedMagnitude - Bias);
		}
	}

	return Sum;
}

摘自 GameplayEffectAggregator.cpp

在这个公式中，Multiply 和 Divide Modifiers 的 Bias 都是 1（Addition 的 Bias 是 0）。因此它看起来会像这样：

1 + (Mod1.Magnitude - 1) + (Mod2.Magnitude - 1) + ...

这个公式会带来一些意料之外的结果。首先，它会先把所有 modifier 相加，再乘到或除到 BaseValue 上。大多数人更预期它们应该彼此相乘或相除。例如，如果你有两个值为 1.5 的 Multiply modifier，大多数人会预期 BaseValue 被乘以 1.5 x 1.5 = 2.25。但实际上，这里是把两个 1.5 相加，从而使 BaseValue 被乘以 2（50% increase + another 50% increase = 100% increase）。在 GameplayPrediction.h 的示例中，500 基础速度上的 10% 速度 buff 会得到 550。再加一个 10% 速度 buff，则会变成 600。

其次，这个公式还包含一些未文档化的规则，限制了可使用的数值范围，因为它是围绕 Paragon 的需求设计的。

Multiply 和 Divide 的乘法加法公式规则：

公式中的 Bias 本质上会把范围 [1, 2) 内数字的整数位减掉。第一个 Modifier 的 Bias 会从初始 Sum 值中抵消（循环前 Sum 被设为 Bias），这就是为什么任意单个值都能正常工作，以及为什么一个 < 1 的值可以与 [1, 2) 范围内的数字一起工作。

下面是一些 Multiply 的示例：

许多游戏会希望它们的 Multiply 和 Divide Modifiers 在应用到 BaseValue 之前彼此相乘和相除。要实现这一点，你需要修改引擎代码中的 FAggregatorModChannel::EvaluateWithBase()。

float FAggregatorModChannel::EvaluateWithBase(float InlineBaseValue, const FAggregatorEvaluateParameters& Parameters) const
{
	...
	float Multiplicitive = MultiplyMods(Mods[EGameplayModOp::Multiplicitive], Parameters);
	float Division = MultiplyMods(Mods[EGameplayModOp::Division], Parameters);
	...

	return ((InlineBaseValue + Additive) * Multiplicitive) / Division;
}

float FAggregatorModChannel::MultiplyMods(const TArray<FAggregatorMod>& InMods, const FAggregatorEvaluateParameters& Parameters)
{
	float Multiplier = 1.0f;

	for (const FAggregatorMod& Mod : InMods)
	{
		if (Mod.Qualifies())
		{
			Multiplier *= Mod.EvaluatedMagnitude;
		}
	}

	return Multiplier;
}

4.5.4.2 Modifier 上的 Gameplay Tags

可以为每个 Modifier 设置 SourceTags 和 TargetTags。它们的工作方式与 GameplayEffect 的 Application Tag requirements 相同。因此，这些 tags 只会在 effect 被应用时考虑。也就是说，对于 periodic、infinite effect，它们只会在 effect 第一次应用时被纳入考虑，而不会在每次 periodic 执行时重新考虑。

Attribute Based Modifiers 还可以设置 SourceTagFilter 和 TargetTagFilter。在确定作为 Attribute Based Modifier 来源的那个 attribute 的 magnitude 时，这些过滤器会用于排除该 attribute 上的某些 Modifiers。凡是其 source 或 target 不具备过滤器中全部 tags 的 Modifiers，都会被排除。

更详细地说：source ASC 和 target ASC 的 tags 会被 GameplayEffects 捕获。source ASC 的 tags 在 GameplayEffectSpec 创建时捕获，target ASC 的 tags 在 effect 执行时捕获。当判断某个 infinite 或 duration effect 的 Modifier 是否“符合应用条件”（即其 Aggregator 是否 qualifies）且设置了这些过滤器时，会将捕获到的 tags 与过滤器进行比较。

4.5.5 堆叠 Gameplay Effects

默认情况下，GameplayEffects 在应用时会创建新的 GameplayEffectSpec 实例，而这些新实例并不会知道也不会关心此前已存在的 GameplayEffectSpec 实例。GameplayEffects 可以被设置为可堆叠，此时不会添加新的 GameplayEffectSpec 实例，而是修改当前已存在的 GameplayEffectSpec 的 stack count。堆叠只对 Duration 和 Infinite GameplayEffects 生效。

堆叠有两种类型：Aggregate by Source 和 Aggregate by Target。

堆叠还带有关于过期、持续时间刷新以及 period 重置的策略。这些在 GameplayEffect Blueprint 中都带有很有帮助的悬停提示。

Sample Project 包含一个自定义 Blueprint 节点，用于监听 GameplayEffect 堆叠变化。HUD UMG Widget 使用它来更新玩家拥有的被动护甲层数。这个 AsyncTask 会一直存活，直到手动调用 EndTask()，而我们是在 UMG Widget 的 Destruct 事件中这么做的。参见 AsyncTaskEffectStackChanged.h/cpp。

4.5.6 授予的 Abilities

GameplayEffects 可以向 ASCs 授予新的 GameplayAbilities。只有 Duration 和 Infinite GameplayEffects 能够授予 abilities。

这种机制的一个常见用例是：当你想强制另一个玩家执行某种行为，例如把他们击退或拉拽移动时。你可以对其应用一个 GameplayEffect，该 effect 会授予他们一个自动激活的 ability（关于在 ability 被授予时如何自动激活，见 Passive Abilities），这个 ability 会对他们执行所需动作。

设计师可以选择 GameplayEffect 授予哪些 abilities、以什么 level 授予、绑定到什么输入，以及授予 ability 的移除策略。

GameplayEffects 携带多个 GameplayTagContainers。设计师会为每个类别编辑其 Added 和 Removed GameplayTagContainers，编译后结果会显示在 Combined GameplayTagContainer 中。Added tags 是该 GameplayEffect 新增而其父类此前没有的 tags。Removed tags 是父类拥有但这个子类不再拥有的 tags。

4.5.8 免疫

GameplayEffects 可以授予 immunity，本质上是基于 GameplayTags 阻止其他 GameplayEffects 的应用。虽然也可以通过 Application Tag Requirements 等其他方式达到类似 immunity 的效果，但使用这个系统的好处是：当 GameplayEffects 因 immunity 而被阻止时，会触发一个 delegate：UAbilitySystemComponent::OnImmunityBlockGameplayEffectDelegate。

GrantedApplicationImmunityTags 会检查 Source ASC（包括 Source ability 的 AbilityTags，如果存在该 ability）是否拥有任意指定 tags。这是一种基于 tags，为来自特定角色或来源的所有 GameplayEffects 提供免疫的方法。

Granted Application Immunity Query 会检查传入的 GameplayEffectSpec 是否匹配任意 query，从而阻止或允许其应用。

这些 query 在 GameplayEffect Blueprint 中都带有很有帮助的悬停提示。

GameplayEffectSpec（GESpec）可以理解为 GameplayEffects 的实例化结果。它们持有自己所代表的 GameplayEffect 类的引用、创建时的 level，以及创建者信息。与应该在运行时之前由设计师创建好的 GameplayEffects 不同，这些对象可以在运行时自由创建和修改，然后再进行应用。当应用一个 GameplayEffect 时，会先根据该 GameplayEffect 创建一个 GameplayEffectSpec，而实际应用到 Target 上的正是它。

GameplayEffectSpecs 通过 UAbilitySystemComponent::MakeOutgoingSpec() 从 GameplayEffects 创建，该函数可 BlueprintCallable。GameplayEffectSpecs 不需要立即应用。常见做法是：某个 ability 创建一个 projectile，同时把 GameplayEffectSpec 传给这个 projectile，后者在之后命中目标时再应用它。当 GameplayEffectSpecs 成功应用后，它们会返回一个名为 FActiveGameplayEffect 的新结构体。

值得注意的 GameplayEffectSpec 内容：

• 该 GameplayEffect 是从哪个 GameplayEffect 类创建出来的。The GameplayEffect class that this GameplayEffect was created from.
• 该 GameplayEffectSpec 的 level。通常与创建它的 ability 的 level 相同，但也可以不同。The level of this GameplayEffectSpec. Usually the same as the level of the ability that created the GameplayEffectSpec but can be different.
• 该 GameplayEffectSpec 的持续时间。默认等于 GameplayEffect 的持续时间，但也可以不同。The duration of the GameplayEffectSpec. Defaults to the duration of the GameplayEffect but can be different.
• periodic effect 的 GameplayEffectSpec 的 period。默认等于 GameplayEffect 的 period，但也可以不同。The period of the GameplayEffectSpec for periodic effects. Defaults to the period of the GameplayEffect but can be different.
• 该 GameplayEffectSpec 当前的 stack count。stack limit 定义在 GameplayEffect 上。The current stack count of this GameplayEffectSpec. The stack limit is on the GameplayEffect.
• GameplayEffectContextHandle 用来说明是谁创建了这个 GameplayEffectSpec。The GameplayEffectContextHandle tells us who created this GameplayEffectSpec.
• 由于 snapshotting 而在创建 GameplayEffectSpec 时被捕获的 Attributes。Attributes that were captured at the time of the GameplayEffectSpec’s creation due to snapshotting.
• DynamicGrantedTags，即除 GameplayEffect 本身授予的 GameplayTags 之外，GameplayEffectSpec 额外授予给 Target 的 tags。DynamicGrantedTags that the GameplayEffectSpec grants to the Target in addition to the GameplayTags that the GameplayEffect grants.
• DynamicAssetTags，即除 GameplayEffect 本身已有的 AssetTags 之外，GameplayEffectSpec 额外拥有的 tags。DynamicAssetTags that the GameplayEffectSpec has in addition to the AssetTags that the GameplayEffect has.

SetByCallers 允许 GameplayEffectSpec 携带与某个 GameplayTag 或 FName 关联的 float 值。这些值分别存储在 GameplayEffectSpec 上对应的 TMaps 中：TMap<FGameplayTag, float> 和 TMap<FName, float>。它们既可以作为 GameplayEffect 上的 Modifiers 使用，也可以作为一种通用方式来携带 float 数据。在 ability 内部生成的数值数据，常常会通过 SetByCallers 传递给 GameplayEffectExecutionCalculations 或 ModifierMagnitudeCalculations。

在 Blueprint 中为 SetByCaller 赋值时，使用你需要的那个版本的 Blueprint 节点（GameplayTag 或 FName）：

在 Blueprint 中读取 SetByCaller 值时，你需要在自己的 Blueprint Library 中创建自定义节点。

在 C++ 中为 SetByCaller 赋值时，使用你需要的那个函数版本（GameplayTag 或 FName）：

void FGameplayEffectSpec::SetSetByCallerMagnitude(FName DataName, float Magnitude);

void FGameplayEffectSpec::SetSetByCallerMagnitude(FGameplayTag DataTag, float Magnitude);

在 C++ 中读取 SetByCaller 值时，使用你需要的那个函数版本（GameplayTag 或 FName）：

float GetSetByCallerMagnitude(FName DataName, bool WarnIfNotFound = true, float DefaultIfNotFound = 0.f) const;

float GetSetByCallerMagnitude(FGameplayTag DataTag, bool WarnIfNotFound = true, float DefaultIfNotFound = 0.f) const;

我建议优先使用 GameplayTag 版本，而不是 FName 版本。这样可以避免在 Blueprint 中出现拼写错误。

GameplayEffectContext 结构体保存了 GameplayEffectSpec 的 instigator 以及 TargetData 信息。它也是一个很适合拿来做子类扩展的结构体，可在 ModifierMagnitudeCalculations / GameplayEffectExecutionCalculations、AttributeSets 和 GameplayCues 等位置之间传递任意数据。

要为 GameplayEffectContext 创建子类：

1. 继承 FGameplayEffectContext。Subclass FGameplayEffectContext
2. 重写 FGameplayEffectContext::GetScriptStruct()。Override FGameplayEffectContext::GetScriptStruct()
3. 重写 FGameplayEffectContext::Duplicate()。Override FGameplayEffectContext::Duplicate()
4. 如果你的新数据需要被 Replication，则重写 FGameplayEffectContext::NetSerialize()。Override FGameplayEffectContext::NetSerialize() if your new data needs to be replicated
5. 为你的子类实现 TStructOpsTypeTraits，就像父结构体 FGameplayEffectContext 那样。Implement TStructOpsTypeTraits for your subclass, like the parent struct FGameplayEffectContext has
6. 在你的 AbilitySystemGlobals 类中重写 AllocGameplayEffectContext()，以返回你的子类新对象。Override AllocGameplayEffectContext() in your AbilitySystemGlobals class to return a new object of your subclass

GASShooter 使用了一个子类化的 GameplayEffectContext 来附加 TargetData，从而可以在 GameplayCues 中访问这些数据，特别适用于 shotgun，因为它可能命中多个敌人。

ModifierMagnitudeCalculations（ModMagCalc 或 MMC）是用于 GameplayEffects 中作为 Modifiers 的强大类。它们的工作方式与 GameplayEffectExecutionCalculations 类似，但功能较弱，而最重要的是它们可以被 predicted。它们唯一的职责是从 CalculateBaseMagnitude_Implementation() 返回一个 float 值。你可以在 Blueprint 或 C++ 中继承并重写这个函数。

MMCs 可以用于任意持续时间类型的 GameplayEffects：Instant、Duration、Infinite 或 Periodic。

MMCs 的强大之处在于，它们可以捕获 GameplayEffect 的 Source 或 Target 上任意数量的 Attributes 值，并且可以完整访问 GameplayEffectSpec，从而读取 GameplayTags 和 SetByCallers。Attributes 可以选择 snapshot 或不 snapshot。被 snapshot 的 Attributes 会在 GameplayEffectSpec 创建时被捕获；未 snapshot 的 Attributes 会在 GameplayEffectSpec 应用时被捕获，并且对于 Infinite 和 Duration GameplayEffects，当该 Attribute 发生变化时会自动更新。捕获 Attributes 时，会根据 ASC 上已有的 mods 重新计算它们的 CurrentValue。这种重新计算不会运行 AbilitySet 中的 PreAttributeChange()，因此任何 clamp 都必须在这里再次处理。

来自 MMC 的结果 float 值，还可以在 GameplayEffect 的 Modifier 中通过 coefficient 以及 coefficient 前后附加值做进一步修改。

下面是一个 MMC 示例：它会捕获 Target 的 mana Attribute，并在 poison effect 中减少 mana；减少量会根据 Target 当前有多少 mana 以及 Target 可能拥有的某个 tag 而变化：

UPAMMC_PoisonMana::UPAMMC_PoisonMana()
{

	//ManaDef defined in header FGameplayEffectAttributeCaptureDefinition ManaDef;
	ManaDef.AttributeToCapture = UPAAttributeSetBase::GetManaAttribute();
	ManaDef.AttributeSource = EGameplayEffectAttributeCaptureSource::Target;
	ManaDef.bSnapshot = false;

	//MaxManaDef defined in header FGameplayEffectAttributeCaptureDefinition MaxManaDef;
	MaxManaDef.AttributeToCapture = UPAAttributeSetBase::GetMaxManaAttribute();
	MaxManaDef.AttributeSource = EGameplayEffectAttributeCaptureSource::Target;
	MaxManaDef.bSnapshot = false;

	RelevantAttributesToCapture.Add(ManaDef);
	RelevantAttributesToCapture.Add(MaxManaDef);
}

float UPAMMC_PoisonMana::CalculateBaseMagnitude_Implementation(const FGameplayEffectSpec & Spec) const
{
	// Gather the tags from the source and target as that can affect which buffs should be used
	const FGameplayTagContainer* SourceTags = Spec.CapturedSourceTags.GetAggregatedTags();
	const FGameplayTagContainer* TargetTags = Spec.CapturedTargetTags.GetAggregatedTags();

	FAggregatorEvaluateParameters EvaluationParameters;
	EvaluationParameters.SourceTags = SourceTags;
	EvaluationParameters.TargetTags = TargetTags;

	float Mana = 0.f;
	GetCapturedAttributeMagnitude(ManaDef, Spec, EvaluationParameters, Mana);
	Mana = FMath::Max<float>(Mana, 0.0f);

	float MaxMana = 0.f;
	GetCapturedAttributeMagnitude(MaxManaDef, Spec, EvaluationParameters, MaxMana);
	MaxMana = FMath::Max<float>(MaxMana, 1.0f); // Avoid divide by zero

	float Reduction = -20.0f;
	if (Mana / MaxMana > 0.5f)
	{
		// Double the effect if the target has more than half their mana
		Reduction *= 2;
	}

	if (TargetTags->HasTagExact(FGameplayTag::RequestGameplayTag(FName("Status.WeakToPoisonMana"))))
	{
		// Double the effect if the target is weak to PoisonMana
		Reduction *= 2;
	}

	return Reduction;
}

如果你没有在 MMC 构造函数中把 FGameplayEffectAttributeCaptureDefinition 加入 RelevantAttributesToCapture，却尝试去捕获 Attributes，你会得到一个关于在捕获时缺少 Spec 的错误。如果你不需要捕获 Attributes，那就不必往 RelevantAttributesToCapture 中添加任何内容。

GameplayEffectExecutionCalculations（ExecutionCalculation、Execution，在插件源码中你会经常看到这个术语，或者 ExecCalc）是 GameplayEffects 对 ASC 进行更改的最强大方式。和 ModifierMagnitudeCalculations 一样，它们可以捕获 Attributes，并可选择是否 snapshot。与 MMCs 不同的是，它们可以改变不止一个 Attribute，并且几乎可以做任何程序员想做的事。其代价是这种能力和灵活性无法被 predicted，并且它们必须用 C++ 实现。

ExecutionCalculations 只能与 Instant 和 Periodic GameplayEffects 一起使用。通常，任何名字里带有 Execute 的内容，基本都指的是这两类 GameplayEffects。

Snapshotting 表示在创建 GameplayEffectSpec 时捕获 Attribute，而非 snapshotting 则是在应用 GameplayEffectSpec 时捕获 Attribute。捕获 Attributes 时，会根据 ASC 上已有的 mods 重新计算它们的 CurrentValue。这种重新计算不会运行 AbilitySet 中的 PreAttributeChange()，因此任何 clamp 都必须在这里再次处理。

为了设置 Attribute 捕获，我们遵循 Epic 的 ActionRPG Sample Project 建立的模式：定义一个 struct 来持有并定义如何捕获这些 Attributes，并在该 struct 的构造函数中创建一份实例。每个 ExecCalc 都会有这样一个 struct。**注意：**每个 struct 都需要唯一的名称，因为它们共享同一个命名空间。若这些 struct 使用相同名称，会在捕获 Attributes 时导致错误行为（主要是捕获到了错误 Attributes 的值）。

对于 Local Predicted、Server Only 和 Server Initiated 的 GameplayAbilities，ExecCalc 只会在服务器上调用。

根据复杂公式，读取 Source 和 Target 上多个 attributes 来计算所受伤害，是 ExecCalc 最常见的用例。附带的 Sample Project 中包含一个简单的 ExecCalc 用于计算伤害：它从 GameplayEffectSpec 的 SetByCaller 中读取伤害值，然后根据从 Target 捕获到的 armor Attribute 对该值进行减伤。参见 GDDamageExecCalculation.cpp/.h。

4.5.12.1 向 Execution Calculations 发送数据

除了捕获 Attributes 之外，还有几种方式可以向 ExecutionCalculation 发送数据。

任何设置在 GameplayEffectSpec 上的 SetByCallers 都可以在 ExecutionCalculation 中直接读取。

const FGameplayEffectSpec& Spec = ExecutionParams.GetOwningSpec();
float Damage = FMath::Max<float>(Spec.GetSetByCallerMagnitude(FGameplayTag::RequestGameplayTag(FName("Data.Damage")), false, -1.0f), 0.0f);

如果你想把某些值硬编码到一个 GameplayEffect 中，可以通过使用某个已捕获 Attribute 作为后备数据的 CalculationModifier 来传入这些值。

在这个截图示例中，我们给捕获到的 Damage Attribute 增加了 50。你也可以把它设为 Override，这样就只会采用这个硬编码值。

ExecutionCalculation 会在捕获该 Attribute 时读取这个值。

float Damage = 0.0f;
// Capture optional damage value set on the damage GE as a CalculationModifier under the ExecutionCalculation
ExecutionParams.AttemptCalculateCapturedAttributeMagnitude(DamageStatics().DamageDef, EvaluationParameters, Damage);

如果你想把某些值硬编码到一个 GameplayEffect 中，也可以通过使用 CalculationModifier，其后备数据为 Temporary Variable（在 C++ 中称为 Transient Aggregator）来传入。这种 Temporary Variable 与一个 GameplayTag 关联。

在这个截图示例中，我们通过 Data.Damage GameplayTag 向一个 Temporary Variable 添加了 50。

把后备 Temporary Variables 添加到 ExecutionCalculation 的构造函数中：

ValidTransientAggregatorIdentifiers.AddTag(FGameplayTag::RequestGameplayTag("Data.Damage"));

ExecutionCalculation 会使用一组与 Attribute 捕获函数类似的专用捕获函数来读取该值。

float Damage = 0.0f;
ExecutionParams.AttemptCalculateTransientAggregatorMagnitude(FGameplayTag::RequestGameplayTag("Data.Damage"), EvaluationParameters, Damage);

你可以通过 GameplayEffectSpec 上自定义的 GameplayEffectContext 向 ExecutionCalculation 发送数据。

在 ExecutionCalculation 中，你可以从 FGameplayEffectCustomExecutionParameters 访问这个 EffectContext。

const FGameplayEffectSpec& Spec = ExecutionParams.GetOwningSpec();
FGSGameplayEffectContext* ContextHandle = static_cast<FGSGameplayEffectContext*>(Spec.GetContext().Get());

如果你需要修改 GameplayEffectSpec 或 EffectContext 上的某些内容：

FGameplayEffectSpec* MutableSpec = ExecutionParams.GetOwningSpecForPreExecuteMod();
FGSGameplayEffectContext* ContextHandle = static_cast<FGSGameplayEffectContext*>(MutableSpec->GetContext().Get());

如果要在 ExecutionCalculation 中修改 GameplayEffectSpec，请务必谨慎。参见 GetOwningSpecForPreExecuteMod() 的注释。

/** Non const access. Be careful with this, especially when modifying a spec after attribute capture. */
FGameplayEffectSpec* GetOwningSpecForPreExecuteMod() const;

4.5.13 自定义应用要求

CustomApplicationRequirement（CAR）类为设计师提供了比 GameplayEffect 上简单 GameplayTag 检查更高级的控制手段，用于决定一个 GameplayEffect 是否可以被应用。它们既可以在 Blueprint 中通过重写 CanApplyGameplayEffect() 来实现，也可以在 C++ 中通过重写 CanApplyGameplayEffect_Implementation() 来实现。

适合使用 CARs 的示例：

• Target 需要拥有某个数量的 Attribute。Target needs to have a certain amount of an Attribute
• Target 需要拥有某个 GameplayEffect 的一定层数。Target needs to have a certain number of stacks of a GameplayEffect

CARs 还可以做更高级的事情，例如检查这个 GameplayEffect 的某个实例是否已经在 Target 身上，并且不是应用一个新实例，而是修改现有实例的持续时间（此时 CanApplyGameplayEffect() 返回 false）。

4.5.14 消耗型 Gameplay Effect

GameplayAbilities 有一个可选的 GameplayEffect，专门设计用作该 ability 的 cost。cost 指的是一个 ASC 要激活某个 GameplayAbility 所必须拥有的 Attribute 数值。如果某个 GA 负担不起这个 Cost GE，它就无法激活。这个 Cost GE 应该是一个 Instant GameplayEffect，包含一个或多个会从 Attributes 中扣减的 Modifiers。默认情况下，Cost GEs 是为 Prediction 而设计的，建议保持这一能力，也就是不要使用 ExecutionCalculations。对于复杂 cost 计算，MMCs 完全可用并且值得推荐。

刚开始时，你很可能会为每个有 cost 的 GA 使用一个独立的 Cost GE。更高级的技巧是：让多个 GAs 复用同一个 Cost GE，然后只修改从这个 Cost GE 创建出来的 GameplayEffectSpec，把 GA 特有的数据写进去（cost 值定义在 GA 上）。这只对 Instanced abilities 有效。

复用 Cost GE 有两种技巧：

1. **使用 MMC。**这是最简单的方法。创建一个 MMC，从 GameplayEffectSpec 中拿到 GameplayAbility 实例，并读取其中的 cost 值。

float UPGMMC_HeroAbilityCost::CalculateBaseMagnitude_Implementation(const FGameplayEffectSpec & Spec) const
{
	const UPGGameplayAbility* Ability = Cast<UPGGameplayAbility>(Spec.GetContext().GetAbilityInstance_NotReplicated());

	if (!Ability)
	{
		return 0.0f;
	}

	return Ability->Cost.GetValueAtLevel(Ability->GetAbilityLevel());
}

在这个示例中，cost 值是我添加到 GameplayAbility 子类上的一个 FScalableFloat。

UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Cost")
FScalableFloat Cost;

2. **重写 UGameplayAbility::GetCostGameplayEffect()。**重写这个函数，并在运行时创建一个 GameplayEffect，让它去读取 GameplayAbility 上的 cost 值。

4.5.15 冷却型 Gameplay Effect

GameplayAbilities 有一个可选的 GameplayEffect，专门设计用作该 ability 的 cooldown。cooldown 决定了 ability 在激活后，多久之后才能再次激活。如果某个 GA 仍处于 cooldown 中，它就无法激活。这个 Cooldown GE 应该是一个 Duration GameplayEffect，不带任何 Modifiers，并且在 GameplayEffect 的 GrantedTags 中为每个 GameplayAbility（或每个 ability 槽位，如果你的游戏允许在共享 cooldown 的槽位间替换 abilities）设置一个唯一的 GameplayTag（即“Cooldown Tag”）。GA 实际检查的是 Cooldown Tag 是否存在，而不是 Cooldown GE 是否存在。默认情况下，Cooldown GEs 是为 Prediction 而设计的，建议保持这一能力，也就是不要使用 ExecutionCalculations。对于复杂 cooldown 计算，MMCs 完全可用并且值得推荐。

刚开始时，你很可能会为每个有 cooldown 的 GA 使用一个独立的 Cooldown GE。更高级的技巧是：让多个 GAs 复用同一个 Cooldown GE，然后只修改从这个 Cooldown GE 创建出来的 GameplayEffectSpec，把 GA 特有的数据写进去（cooldown 持续时间和 Cooldown Tag 定义在 GA 上）。这只对 Instanced abilities 有效。

复用 Cooldown GE 有两种技巧：

1. **使用 SetByCaller。**这是最简单的方法。把共享 Cooldown GE 的持续时间设为带有某个 GameplayTag 的 SetByCaller。在你的 GameplayAbility 子类上，定义一个用于持续时间的 float / FScalableFloat、一个用于唯一 Cooldown Tag 的 FGameplayTagContainer，以及一个临时的 FGameplayTagContainer，它将作为我们返回的指针，表示 Cooldown Tag 与 Cooldown GE tags 的并集。

UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Cooldown")
FScalableFloat CooldownDuration;

UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Cooldown")
FGameplayTagContainer CooldownTags;

// Temp container that we will return the pointer to in GetCooldownTags().
// This will be a union of our CooldownTags and the Cooldown GE's cooldown tags.
UPROPERTY(Transient)
FGameplayTagContainer TempCooldownTags;

然后重写 UGameplayAbility::GetCooldownTags()，返回我们自己的 Cooldown Tags 与任意现有 Cooldown GE tags 的并集。

const FGameplayTagContainer * UPGGameplayAbility::GetCooldownTags() const
{
	FGameplayTagContainer* MutableTags = const_cast<FGameplayTagContainer*>(&TempCooldownTags);
	MutableTags->Reset(); // MutableTags writes to the TempCooldownTags on the CDO so clear it in case the ability cooldown tags change (moved to a different slot)
	const FGameplayTagContainer* ParentTags = Super::GetCooldownTags();
	if (ParentTags)
	{
		MutableTags->AppendTags(*ParentTags);
	}
	MutableTags->AppendTags(CooldownTags);
	return MutableTags;
}

最后，重写 UGameplayAbility::ApplyCooldown()，把我们的 Cooldown Tags 注入到 cooldown GameplayEffectSpec 中，并把 SetByCaller 添加到该 cooldown GameplayEffectSpec。

void UPGGameplayAbility::ApplyCooldown(const FGameplayAbilitySpecHandle Handle, const FGameplayAbilityActorInfo * ActorInfo, const FGameplayAbilityActivationInfo ActivationInfo) const
{
	UGameplayEffect* CooldownGE = GetCooldownGameplayEffect();
	if (CooldownGE)
	{
		FGameplayEffectSpecHandle SpecHandle = MakeOutgoingGameplayEffectSpec(CooldownGE->GetClass(), GetAbilityLevel());
		SpecHandle.Data.Get()->DynamicGrantedTags.AppendTags(CooldownTags);
		SpecHandle.Data.Get()->SetSetByCallerMagnitude(FGameplayTag::RequestGameplayTag(FName(  OurSetByCallerTag  )), CooldownDuration.GetValueAtLevel(GetAbilityLevel()));
		ApplyGameplayEffectSpecToOwner(Handle, ActorInfo, ActivationInfo, SpecHandle);
	}
}

在这张图中，cooldown 持续时间的 Modifier 被设置为带有 Data Tag Data.Cooldown 的 SetByCaller。Data.Cooldown 就是上面代码中的 OurSetByCallerTag。

2. **使用 MMC。**这与上面的设置基本相同，不同之处在于：你不再把 SetByCaller 作为 Cooldown GE 的持续时间，也不在 ApplyCooldown 中设置它。相反，应把持续时间设为 Custom Calculation Class，并指向我们即将创建的新 MMC。

UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Cooldown")
FScalableFloat CooldownDuration;

UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Cooldown")
FGameplayTagContainer CooldownTags;

// Temp container that we will return the pointer to in GetCooldownTags().
// This will be a union of our CooldownTags and the Cooldown GE's cooldown tags.
UPROPERTY(Transient)
FGameplayTagContainer TempCooldownTags;

然后重写 UGameplayAbility::GetCooldownTags()，返回我们自己的 Cooldown Tags 与任意现有 Cooldown GE tags 的并集。

const FGameplayTagContainer * UPGGameplayAbility::GetCooldownTags() const
{
	FGameplayTagContainer* MutableTags = const_cast<FGameplayTagContainer*>(&TempCooldownTags);
	MutableTags->Reset(); // MutableTags writes to the TempCooldownTags on the CDO so clear it in case the ability cooldown tags change (moved to a different slot)
	const FGameplayTagContainer* ParentTags = Super::GetCooldownTags();
	if (ParentTags)
	{
		MutableTags->AppendTags(*ParentTags);
	}
	MutableTags->AppendTags(CooldownTags);
	return MutableTags;
}

最后，重写 UGameplayAbility::ApplyCooldown()，把我们的 Cooldown Tags 注入到 cooldown GameplayEffectSpec 中。

void UPGGameplayAbility::ApplyCooldown(const FGameplayAbilitySpecHandle Handle, const FGameplayAbilityActorInfo * ActorInfo, const FGameplayAbilityActivationInfo ActivationInfo) const
{
	UGameplayEffect* CooldownGE = GetCooldownGameplayEffect();
	if (CooldownGE)
	{
		FGameplayEffectSpecHandle SpecHandle = MakeOutgoingGameplayEffectSpec(CooldownGE->GetClass(), GetAbilityLevel());
		SpecHandle.Data.Get()->DynamicGrantedTags.AppendTags(CooldownTags);
		ApplyGameplayEffectSpecToOwner(Handle, ActorInfo, ActivationInfo, SpecHandle);
	}
}

float UPGMMC_HeroAbilityCooldown::CalculateBaseMagnitude_Implementation(const FGameplayEffectSpec & Spec) const
{
	const UPGGameplayAbility* Ability = Cast<UPGGameplayAbility>(Spec.GetContext().GetAbilityInstance_NotReplicated());

	if (!Ability)
	{
		return 0.0f;
	}

	return Ability->CooldownDuration.GetValueAtLevel(Ability->GetAbilityLevel());
}

4.5.15.1 获取 Cooldown Gameplay Effect 的剩余时间

bool APGPlayerState::GetCooldownRemainingForTag(FGameplayTagContainer CooldownTags, float & TimeRemaining, float & CooldownDuration)
{
	if (AbilitySystemComponent && CooldownTags.Num() > 0)
	{
		TimeRemaining = 0.f;
		CooldownDuration = 0.f;

		FGameplayEffectQuery const Query = FGameplayEffectQuery::MakeQuery_MatchAnyOwningTags(CooldownTags);
		TArray< TPair<float, float> > DurationAndTimeRemaining = AbilitySystemComponent->GetActiveEffectsTimeRemainingAndDuration(Query);
		if (DurationAndTimeRemaining.Num() > 0)
		{
			int32 BestIdx = 0;
			float LongestTime = DurationAndTimeRemaining[0].Key;
			for (int32 Idx = 1; Idx < DurationAndTimeRemaining.Num(); ++Idx)
			{
				if (DurationAndTimeRemaining[Idx].Key > LongestTime)
				{
					LongestTime = DurationAndTimeRemaining[Idx].Key;
					BestIdx = Idx;
				}
			}

			TimeRemaining = DurationAndTimeRemaining[BestIdx].Key;
			CooldownDuration = DurationAndTimeRemaining[BestIdx].Value;

			return true;
		}
	}

	return false;
}

**注意：**在客户端查询 cooldown 的剩余时间，要求客户端能够接收到已 Replication 的 GameplayEffects。这取决于它们的 ASC 的 Replication 模式。

4.5.15.2 监听 Cooldown 开始和结束

要监听 cooldown 何时开始，你可以通过绑定 AbilitySystemComponent->OnActiveGameplayEffectAddedDelegateToSelf 来响应 Cooldown GE 被应用，或者通过绑定 AbilitySystemComponent->RegisterGameplayTagEvent(CooldownTag, EGameplayTagEventType::NewOrRemoved) 来响应 Cooldown Tag 被添加。我更推荐监听 Cooldown GE 被添加，因为这样你还能访问应用它时使用的 GameplayEffectSpec。借此你可以判断该 Cooldown GE 是本地 predicted 的那个，还是服务器修正后的那个。

要监听 cooldown 何时结束，你可以通过绑定 AbilitySystemComponent->OnAnyGameplayEffectRemovedDelegate() 来响应 Cooldown GE 被移除，或者通过绑定 AbilitySystemComponent->RegisterGameplayTagEvent(CooldownTag, EGameplayTagEventType::NewOrRemoved) 来响应 Cooldown Tag 被移除。我更推荐监听 Cooldown Tag 被移除，因为当服务器修正后的 Cooldown GE 到来时，它会移除本地 predicted 的那个，从而触发 OnAnyGameplayEffectRemovedDelegate()，即使我们实际上仍然处于 cooldown 中。在移除 predicted Cooldown GE 和应用服务器修正后的 Cooldown GE 这一过程中，Cooldown Tag 不会发生变化。

**注意：**在客户端监听 GameplayEffect 的添加或移除，要求客户端能够接收到已 Replication 的 GameplayEffects。这取决于它们的 ASC 的 Replication 模式。

Sample Project 包含一个自定义 Blueprint 节点，用于监听 cooldown 的开始和结束。HUD UMG Widget 使用它来更新 Meteor cooldown 的剩余时间。这个 AsyncTask 会一直存活，直到手动调用 EndTask()，而我们是在 UMG Widget 的 Destruct 事件中这么做的。参见 AsyncTaskCooldownChanged.h/cpp。

4.5.15.3 Prediction 冷却

当前 cooldown 实际上还无法真正被 predicted。我们可以在本地 predicted 的 Cooldown GE 被应用时启动 UI cooldown timer，但 GameplayAbility 的真实 cooldown 是绑定在服务器 cooldown 的剩余时间上的。根据玩家的延迟情况，本地 predicted cooldown 可能已经结束，但服务器上的 GameplayAbility 仍然处于 cooldown 中，这会阻止该 GameplayAbility 被立即再次激活，直到服务器 cooldown 也结束为止。

Sample Project 的处理方式是：当本地 predicted cooldown 开始时，将 Meteor ability 的 UI 图标变灰；然后等服务器修正后的 Cooldown GE 到来后，再启动 cooldown timer。

这会带来一个 gameplay 层面的后果：高延迟玩家在使用短 cooldown abilities 时，其射速会低于低延迟玩家，因此会处于劣势。Fortnite 通过为武器使用不依赖 cooldown GameplayEffects 的自定义 bookkeeping 来避免这个问题。

允许真正意义上的 predicted cooldown（即本地 cooldown 结束时玩家就能激活 GameplayAbility，即使服务器仍然处于 cooldown）是 Epic 希望未来在 GAS 的后续迭代 中实现的内容。

4.5.16 修改活动中的 Gameplay Effect 持续时间

要修改某个 Cooldown GE 或任意 Duration GameplayEffect 的剩余时间，我们需要修改其 GameplayEffectSpec 的 Duration，更新它的 StartServerWorldTime、CachedStartServerWorldTime 和 StartWorldTime，然后通过 CheckDuration() 重新执行持续时间检查。在服务器上这样做，并把该 FActiveGameplayEffect 标记为 dirty，就会把这些变更 Replication 给客户端。 **注意：**这确实涉及 const_cast，可能并不是 Epic 预期的修改持续时间方式，但到目前为止看起来工作得不错。

bool UPAAbilitySystemComponent::SetGameplayEffectDurationHandle(FActiveGameplayEffectHandle Handle, float NewDuration)
{
	if (!Handle.IsValid())
	{
		return false;
	}

	const FActiveGameplayEffect* ActiveGameplayEffect = GetActiveGameplayEffect(Handle);
	if (!ActiveGameplayEffect)
	{
		return false;
	}

	FActiveGameplayEffect* AGE = const_cast<FActiveGameplayEffect*>(ActiveGameplayEffect);
	if (NewDuration > 0)
	{
		AGE->Spec.Duration = NewDuration;
	}
	else
	{
		AGE->Spec.Duration = 0.01f;
	}

	AGE->StartServerWorldTime = ActiveGameplayEffects.GetServerWorldTime();
	AGE->CachedStartServerWorldTime = AGE->StartServerWorldTime;
	AGE->StartWorldTime = ActiveGameplayEffects.GetWorldTime();
	ActiveGameplayEffects.MarkItemDirty(*AGE);
	ActiveGameplayEffects.CheckDuration(Handle);

	AGE->EventSet.OnTimeChanged.Broadcast(AGE->Handle, AGE->StartWorldTime, AGE->GetDuration());
	OnGameplayEffectDurationChange(*AGE);

	return true;
}

4.5.17 在运行时创建动态 Gameplay Effects

在运行时创建动态 GameplayEffects 是一个高级主题。你通常不需要经常这么做。

只有 Instant GameplayEffects 能够在 C++ 中从零开始于运行时创建。Duration 和 Infinite GameplayEffects 不能在运行时动态创建，因为当它们进行 Replication 时，会去查找并不存在的 GameplayEffect 类定义。要实现类似功能，你应当像平常一样先在 Editor 中创建一个原型 GameplayEffect 类，然后在运行时按需定制它的 GameplayEffectSpec 实例。

在本地 的 GameplayAbility 中，也可以调用在运行时创建的 Instant GameplayEffects。不过，目前仍不清楚这种动态创建是否会带来副作用。

示例

Sample Project 会在角色的 AttributeSet 中，当角色承受致命一击时，创建一个这样的对象，把 gold 和 experience points 返还给击杀者。

 // Create a dynamic instant Gameplay Effect to give the bounties
UGameplayEffect* GEBounty = NewObject<UGameplayEffect>(GetTransientPackage(), FName(TEXT("Bounty")));
GEBounty->DurationPolicy = EGameplayEffectDurationType::Instant;

int32 Idx = GEBounty->Modifiers.Num();
GEBounty->Modifiers.SetNum(Idx + 2);

FGameplayModifierInfo& InfoXP = GEBounty->Modifiers[Idx];
InfoXP.ModifierMagnitude = FScalableFloat(GetXPBounty());
InfoXP.ModifierOp = EGameplayModOp::Additive;
InfoXP.Attribute = UGDAttributeSetBase::GetXPAttribute();

FGameplayModifierInfo& InfoGold = GEBounty->Modifiers[Idx + 1];
InfoGold.ModifierMagnitude = FScalableFloat(GetGoldBounty());
InfoGold.ModifierOp = EGameplayModOp::Additive;
InfoGold.Attribute = UGDAttributeSetBase::GetGoldAttribute();

Source->ApplyGameplayEffectToSelf(GEBounty, 1.0f, Source->MakeEffectContext());

第二个示例展示了在本地 predicted GameplayAbility 内部创建运行时 GameplayEffect。请自行承担使用风险（见代码中的注释）！

UGameplayAbilityRuntimeGE::UGameplayAbilityRuntimeGE()
{
	NetExecutionPolicy = EGameplayAbilityNetExecutionPolicy::LocalPredicted;
}

void UGameplayAbilityRuntimeGE::ActivateAbility(const FGameplayAbilitySpecHandle Handle, const FGameplayAbilityActorInfo* ActorInfo, const FGameplayAbilityActivationInfo ActivationInfo, const FGameplayEventData* TriggerEventData)
{
	if (HasAuthorityOrPredictionKey(ActorInfo, &ActivationInfo))
	{
		if (!CommitAbility(Handle, ActorInfo, ActivationInfo))
		{
			EndAbility(Handle, ActorInfo, ActivationInfo, true, true);
		}

		// Create the GE at runtime.
		UGameplayEffect* GameplayEffect = NewObject<UGameplayEffect>(GetTransientPackage(), TEXT("RuntimeInstantGE"));
		GameplayEffect->DurationPolicy = EGameplayEffectDurationType::Instant; // Only instant works with runtime GE.

		// Add a simple scalable float modifier, which overrides MyAttribute with 42.
		// In real world applications, consume information passed via TriggerEventData.
		const int32 Idx = GameplayEffect->Modifiers.Num();
		GameplayEffect->Modifiers.SetNum(Idx + 1);
		FGameplayModifierInfo& ModifierInfo = GameplayEffect->Modifiers[Idx];
		ModifierInfo.Attribute.SetUProperty(UMyAttributeSet::GetMyModifiedAttribute());
		ModifierInfo.ModifierMagnitude = FScalableFloat(42.f);
		ModifierInfo.ModifierOp = EGameplayModOp::Override;

		// Apply the GE.

		// Create the GESpec here to avoid the behavior of ASC to create GESpecs from the GE class default object.
		// Since we have a dynamic GE here, this would create a GESpec with the base GameplayEffect class, so we
		// would lose our modifiers. Attention: It is unknown, if this "hack" done here can have drawbacks!
		// The spec prevents the GE object being collected by the GarbageCollector, since the GE is a UPROPERTY on the spec.
		FGameplayEffectSpec* GESpec = new FGameplayEffectSpec(GameplayEffect, {}, 0.f); // "new", since lifetime is managed by a shared ptr within the handle
		ApplyGameplayEffectSpecToOwner(Handle, ActorInfo, ActivationInfo, FGameplayEffectSpecHandle(GESpec));
	}
	EndAbility(Handle, ActorInfo, ActivationInfo, false, false);
}

4.5.18 Gameplay Effect 容器

Epic 的 Action RPG Sample Project 实现了一个名为 FGameplayEffectContainer 的结构。这些并不属于原生 GAS，但它们对于封装 GameplayEffects 和 TargetData 极其方便。它能够自动化一部分工作，例如从 GameplayEffects 创建 GameplayEffectSpecs，以及在其 GameplayEffectContext 中设置默认值。在 GameplayAbility 中创建一个 GameplayEffectContainer 并把它传给生成出来的 projectile 非常简单直接。我在附带的 Sample Project 中选择不实现 GameplayEffectContainers，是为了展示在原生 GAS 中不使用它们时应该如何工作；但我强烈建议你研究一下它们，并考虑将其加入你的项目。

如果你想访问 GameplayEffectContainers 里的 GESpecs，以执行像添加 SetByCallers 这样的操作，可以拆开 FGameplayEffectContainer，然后通过 GESpecs 数组中的索引访问对应的 GESpec 引用。这要求你预先知道你要访问的 GESpec 在数组中的索引。

GameplayEffectContainers 还包含一种可选且高效的选目标方式。

4.6 关于 Gameplay Abilities

4.6.1 Gameplay Ability 定义

GameplayAbilities（GA）是游戏中某个 Actor 能执行的任何动作或技能。一个 GameplayAbility 可以和其他 GameplayAbility 同时处于激活状态，例如冲刺时开枪。它们可以用 Blueprint 或 C++ 实现。

GameplayAbilities 的示例：

• 跳跃
• 冲刺
• 开枪
• 每隔 X 秒被动格挡一次攻击
• 使用药水
• 开门
• 收集资源
• 建造建筑

不应使用 GameplayAbilities 实现的内容：

• 基础移动输入
• 某些 UI 交互，例如不要用 GameplayAbility 来从商店购买物品

这些不是规则，只是我的建议。你的设计和实现可能会不同。

GameplayAbilities 自带默认功能，可以拥有等级，用于修改 Attributes 的变化量，或改变 GameplayAbility 的功能。

GameplayAbilities 会在拥有它的客户端和/或服务器上运行，具体取决于 Net Execution Policy，但不会在模拟代理上运行。Net Execution Policy 决定某个 GameplayAbility 是否会进行本地 Prediction。它们还自带对可选的消耗与冷却 GameplayEffects 的默认支持。GameplayAbilities 使用 AbilityTasks 来处理跨时间发生的动作，例如等待事件、等待 Attribute 变化、等待玩家选择目标，或者使用 Root Motion Source 移动 Character。模拟客户端不会运行 GameplayAbilities。相反，当服务器运行能力时，任何需要在模拟代理上表现出来的视觉效果（如动画蒙太奇）都会通过 AbilityTasks 进行 Replication 或 RPC，而声音、粒子等纯表现效果则通过 GameplayCues 处理。

所有 GameplayAbilities 都会重写其 ActivateAbility() 函数以放入你的游戏逻辑。你还可以在 EndAbility() 中添加额外逻辑，该函数会在 GameplayAbility 完成或被取消时执行。

简单 GameplayAbility 的流程图：

更复杂 GameplayAbility 的流程图：

复杂能力可以通过多个彼此交互（激活、取消等）的 GameplayAbilities 来实现。

4.6.1.1 Replication Policy 说明

不要使用这个选项。这个名字具有误导性，而且你并不需要它。默认情况下，GameplayAbilitySpecs 会从服务器 Replication 到拥有它的客户端。如上所述，GameplayAbilities 不会在模拟代理上运行。它们通过 AbilityTasks 和 GameplayCues 将视觉变化 Replication 或 RPC 到模拟代理。Epic 的 Dave Ratti 表示他希望未来移除这个选项。

4.6.1.2 服务器尊重远程能力取消

这个选项往往弊大于利。它的含义是：如果客户端上的 GameplayAbility 因取消或自然完成而结束，那么无论服务器上的版本是否真正完成，都会强制服务器版本结束。后者尤其成问题，特别是对于高延迟玩家使用的本地预测 GameplayAbilities。通常你会希望关闭这个选项。

4.6.1.3 直接 Replication 输入

启用这个选项后，输入按下与松开事件将始终 Replication 到服务器。Epic 建议不要使用它，而是依赖现有输入相关 AbilityTasks 内建的 Generic Replicated Events，前提是你已经将输入绑定到你的 ASC。

Epic 的注释：

/** Direct Input state replication. These will be called if bReplicateInputDirectly is true on the ability and is generally not a good thing to use. (Instead, prefer to use Generic Replicated Events). */
UAbilitySystemComponent::ServerSetInputPressed()

4.6.2 将输入绑定到 ASC

ASC 允许你将输入动作直接绑定到它，并在授予 GameplayAbilities 时把这些输入分配给它们。若 GameplayTag 条件满足，分配给 GameplayAbilities 的输入动作会在按下时自动激活对应 GameplayAbilities。若要使用内建的响应输入的 AbilityTasks，必须分配输入动作。

除了用于激活 GameplayAbilities 的输入动作外，ASC 还接受通用的 Confirm 和 Cancel 输入。这些特殊输入会被 AbilityTasks 用于确认诸如 Target Actors 之类的操作或取消它们。

要把输入绑定到 ASC，你必须先创建一个枚举，把输入动作名称映射成一个字节。枚举名必须与项目设置中该输入动作使用的名称完全一致。DisplayName 无关紧要。

来自 Sample Project：

UENUM(BlueprintType)
enum class EGDAbilityInputID : uint8
{
	// 0 None
	None			UMETA(DisplayName = "None"),
	// 1 Confirm
	Confirm			UMETA(DisplayName = "Confirm"),
	// 2 Cancel
	Cancel			UMETA(DisplayName = "Cancel"),
	// 3 LMB
	Ability1		UMETA(DisplayName = "Ability1"),
	// 4 RMB
	Ability2		UMETA(DisplayName = "Ability2"),
	// 5 Q
	Ability3		UMETA(DisplayName = "Ability3"),
	// 6 E
	Ability4		UMETA(DisplayName = "Ability4"),
	// 7 R
	Ability5		UMETA(DisplayName = "Ability5"),
	// 8 Sprint
	Sprint			UMETA(DisplayName = "Sprint"),
	// 9 Jump
	Jump			UMETA(DisplayName = "Jump")
};

如果你的 ASC 位于 Character 上，那么请在 SetupPlayerInputComponent() 中加入绑定到 ASC 的函数：

// Bind to AbilitySystemComponent
FTopLevelAssetPath AbilityEnumAssetPath = FTopLevelAssetPath(FName("/Script/GASDocumentation"), FName("EGDAbilityInputID"));
AbilitySystemComponent->BindAbilityActivationToInputComponent(PlayerInputComponent, FGameplayAbilityInputBinds(FString("ConfirmTarget"),
	FString("CancelTarget"), AbilityEnumAssetPath, static_cast<int32>(EGDAbilityInputID::Confirm), static_cast<int32>(EGDAbilityInputID::Cancel)));

如果你的 ASC 位于 PlayerState 上，那么在 SetupPlayerInputComponent() 内部存在潜在竞争条件：此时 PlayerState 可能尚未 Replication 到客户端。因此，我建议在 SetupPlayerInputComponent() 和 OnRep_PlayerState() 中都尝试进行输入绑定。单靠 OnRep_PlayerState() 并不够，因为有一种情况是：PlayerState 在 PlayerController 通知客户端调用 ClientRestart()（从而创建 InputComponent）之前就先完成了 Replication，此时 Actor 的 InputComponent 可能还是空。Sample Project 展示了如何在这两个位置都尝试绑定，并用一个布尔值做门控，确保输入实际上只绑定一次。

注意： 在 Sample Project 中，枚举里的 Confirm 和 Cancel 与项目设置中的输入动作名（ConfirmTarget 和 CancelTarget）并不一致，但我们在 BindAbilityActivationToInputComponent() 中提供了它们之间的映射。这两个是特殊情况，因为我们显式提供了映射，所以不必匹配，但也可以匹配。枚举中的所有其他输入必须与项目设置中的输入动作名完全一致。

对于那些只会由一个输入激活的 GameplayAbilities（例如在 MOBA 中总是存在于同一个“槽位”），我更喜欢在自己的 UGameplayAbility 子类中添加一个变量来定义它们的输入。之后在授予能力时，我可以从 ClassDefaultObject 中读取这个值。

4.6.2.1 绑定输入但不激活能力

如果你不希望在按下输入时自动激活 GameplayAbilities，但仍想将它们绑定到输入以配合 AbilityTasks 使用，那么你可以在自己的 UGameplayAbility 子类中添加一个新的布尔变量 bActivateOnInput，默认值为 true，然后重写 UAbilitySystemComponent::AbilityLocalInputPressed()。

void UGSAbilitySystemComponent::AbilityLocalInputPressed(int32 InputID)
{
	// Consume the input if this InputID is overloaded with GenericConfirm/Cancel and the GenericConfim/Cancel callback is bound
	if (IsGenericConfirmInputBound(InputID))
	{
		LocalInputConfirm();
		return;
	}

	if (IsGenericCancelInputBound(InputID))
	{
		LocalInputCancel();
		return;
	}

	// ---------------------------------------------------------

	ABILITYLIST_SCOPE_LOCK();
	for (FGameplayAbilitySpec& Spec : ActivatableAbilities.Items)
	{
		if (Spec.InputID == InputID)
		{
			if (Spec.Ability)
			{
				Spec.InputPressed = true;
				if (Spec.IsActive())
				{
					if (Spec.Ability->bReplicateInputDirectly && IsOwnerActorAuthoritative() == false)
					{
						ServerSetInputPressed(Spec.Handle);
					}

					AbilitySpecInputPressed(Spec);

					// Invoke the InputPressed event. This is not replicated here. If someone is listening, they may replicate the InputPressed event to the server.
					InvokeReplicatedEvent(EAbilityGenericReplicatedEvent::InputPressed, Spec.Handle, Spec.ActivationInfo.GetActivationPredictionKey());
				}
				else
				{
					UGSGameplayAbility* GA = Cast<UGSGameplayAbility>(Spec.Ability);
					if (GA && GA->bActivateOnInput)
					{
						// Ability is not active, so try to activate it
						TryActivateAbility(Spec.Handle);
					}
				}
			}
		}
	}
}

4.6.3 授予能力

将某个 GameplayAbility 授予给 ASC 后，它会被加入 ASC 的 ActivatableAbilities 列表，使其在满足 GameplayTag 要求 时可以被随时激活。

我们在服务器上授予 GameplayAbilities，随后服务器会自动把 GameplayAbilitySpec Replication 给拥有它的客户端。其他客户端 / 模拟代理不会收到 GameplayAbilitySpec。

Sample Project 在 Character 类上存储了一个 TArray<TSubclassOf<UGDGameplayAbility>>，并在游戏开始时读取并授予这些能力：

void AGDCharacterBase::AddCharacterAbilities()
{
	// Grant abilities, but only on the server
	if (Role != ROLE_Authority || !AbilitySystemComponent.IsValid() || AbilitySystemComponent->bCharacterAbilitiesGiven)
	{
		return;
	}

	for (TSubclassOf<UGDGameplayAbility>& StartupAbility : CharacterAbilities)
	{
		AbilitySystemComponent->GiveAbility(
			FGameplayAbilitySpec(StartupAbility, GetAbilityLevel(StartupAbility.GetDefaultObject()->AbilityID), static_cast<int32>(StartupAbility.GetDefaultObject()->AbilityInputID), this));
	}

	AbilitySystemComponent->bCharacterAbilitiesGiven = true;
}

在授予这些 GameplayAbilities 时，我们创建了 GameplayAbilitySpecs，其中包含 UGameplayAbility 类、能力等级、绑定输入，以及 SourceObject（也就是是谁把这个 GameplayAbility 授予给这个 ASC 的）。

4.6.4 激活能力

如果某个 GameplayAbility 被分配了输入动作，那么当输入被按下并且满足其 GameplayTag 条件时，它会自动被激活。但这并不总是理想的激活方式。ASC 还提供了另外四种激活 GameplayAbilities 的方式：通过 GameplayTag、GameplayAbility 类、GameplayAbilitySpec 句柄，以及通过事件。通过事件激活 GameplayAbility 还允许你随事件传入一份数据载荷。

UFUNCTION(BlueprintCallable, Category = "Abilities")
bool TryActivateAbilitiesByTag(const FGameplayTagContainer& GameplayTagContainer, bool bAllowRemoteActivation = true);

UFUNCTION(BlueprintCallable, Category = "Abilities")
bool TryActivateAbilityByClass(TSubclassOf<UGameplayAbility> InAbilityToActivate, bool bAllowRemoteActivation = true);

bool TryActivateAbility(FGameplayAbilitySpecHandle AbilityToActivate, bool bAllowRemoteActivation = true);

bool TriggerAbilityFromGameplayEvent(FGameplayAbilitySpecHandle AbilityToTrigger, FGameplayAbilityActorInfo* ActorInfo, FGameplayTag Tag, const FGameplayEventData* Payload, UAbilitySystemComponent& Component);

FGameplayAbilitySpecHandle GiveAbilityAndActivateOnce(const FGameplayAbilitySpec& AbilitySpec, const FGameplayEventData* GameplayEventData);

要通过事件激活 GameplayAbility，该 GameplayAbility 必须在自身中配置好 Triggers。为它指定一个 GameplayTag，并为 GameplayEvent 选择一种选项。发送事件时，使用函数 UAbilitySystemBlueprintLibrary::SendGameplayEventToActor(AActor* Actor, FGameplayTag EventTag, FGameplayEventData Payload)。通过事件激活 GameplayAbility 的好处是你可以传入带数据的 payload。

GameplayAbility 的 Triggers 还允许你在某个 GameplayTag 被添加或移除时激活该 GameplayAbility。

注意： 在 Blueprint 中通过事件激活 GameplayAbility 时，你必须使用 ActivateAbilityFromEvent 节点。

注意： 除非你的 GameplayAbility 会一直运行（例如被动能力），否则别忘了在它应当终止时调用 EndAbility()。

本地预测 GameplayAbilities 的激活顺序：

1. 拥有该能力的客户端 调用 TryActivateAbility()
2. 调用 InternalTryActivateAbility()
3. 调用 CanActivateAbility()，并返回是否满足 GameplayTag 要求、ASC 是否承担得起消耗、GameplayAbility 是否不在冷却中，以及当前是否没有其他实例处于激活状态
4. 调用 CallServerTryActivateAbility()，并传入它生成的 Prediction Key
5. 调用 CallActivateAbility()
6. 调用 PreActivate()，Epic 将其称为“样板初始化工作”
7. 调用 ActivateAbility()，最终真正激活该能力

服务器 接收到 CallServerTryActivateAbility()

1. 调用 ServerTryActivateAbility()
2. 调用 InternalServerTryActivateAbility()
3. 调用 InternalTryActivateAbility()
4. 调用 CanActivateAbility()，并返回是否满足 GameplayTag 要求、ASC 是否承担得起消耗、GameplayAbility 是否不在冷却中，以及当前是否没有其他实例处于激活状态
5. 如果成功，则调用 ClientActivateAbilitySucceed()，通知客户端更新其 ActivationInfo，表明本次激活已被服务器确认，并广播 OnConfirmDelegate 委托。这与输入确认不是一回事。
6. 调用 CallActivateAbility()
7. 调用 PreActivate()，Epic 将其称为“样板初始化工作”
8. 调用 ActivateAbility()，最终真正激活该能力

如果服务器在任何时刻激活失败，它都会调用 ClientActivateAbilityFailed()，立即终止客户端上的 GameplayAbility，并撤销所有预测更改。

4.6.4.1 被动能力

要实现会自动激活并持续运行的被动 GameplayAbilities，请重写 UGameplayAbility::OnAvatarSet()。当某个 GameplayAbility 被授予且 AvatarActor 被设置时，这个函数会自动调用；此时再调用 TryActivateAbility()。

我建议在你的自定义 UGameplayAbility 类中添加一个 bool，用于指定该 GameplayAbility 在被授予时是否应自动激活。Sample Project 就是这样实现其被动护甲叠层能力的。

被动 GameplayAbilities 通常会使用 Net Execution Policy 中的 Server Only。

void UGDGameplayAbility::OnAvatarSet(const FGameplayAbilityActorInfo * ActorInfo, const FGameplayAbilitySpec & Spec)
{
	Super::OnAvatarSet(ActorInfo, Spec);

	if (bActivateAbilityOnGranted)
	{
		ActorInfo->AbilitySystemComponent->TryActivateAbility(Spec.Handle, false);
	}
}

Epic 将这个函数描述为启动被动能力以及处理 BeginPlay 类型逻辑的正确位置。

4.6.4.2 激活失败标签

能力自带默认逻辑，可以告诉你某次能力激活失败的原因。要启用这一点，你必须先配置与默认失败场景对应的 Gameplay Tags。

把这些标签（或使用你自己的命名约定）加入项目中：

+GameplayTagList=(Tag="Activation.Fail.BlockedByTags",DevComment="")
+GameplayTagList=(Tag="Activation.Fail.CantAffordCost",DevComment="")
+GameplayTagList=(Tag="Activation.Fail.IsDead",DevComment="")
+GameplayTagList=(Tag="Activation.Fail.MissingTags",DevComment="")
+GameplayTagList=(Tag="Activation.Fail.Networking",DevComment="")
+GameplayTagList=(Tag="Activation.Fail.OnCooldown",DevComment="")

然后把它们加入 GASDocumentation\Config\DefaultGame.ini：

[/Script/GameplayAbilities.AbilitySystemGlobals]
ActivateFailIsDeadName=Activation.Fail.IsDead
ActivateFailCooldownName=Activation.Fail.OnCooldown
ActivateFailCostName=Activation.Fail.CantAffordCost
ActivateFailTagsBlockedName=Activation.Fail.BlockedByTags
ActivateFailTagsMissingName=Activation.Fail.MissingTags
ActivateFailNetworkingName=Activation.Fail.Networking

现在每当某次能力激活失败时，对应的 GameplayTag 都会出现在输出日志中，或显示在 showdebug AbilitySystem HUD 上。

LogAbilitySystem: Display: InternalServerTryActivateAbility. Rejecting ClientActivation of Default__GA_FireGun_C. InternalTryActivateAbility failed: Activation.Fail.BlockedByTags
LogAbilitySystem: Display: ClientActivateAbilityFailed_Implementation. PredictionKey :109 Ability: Default__GA_FireGun_C

在 showdebug AbilitySystem 中显示的 Activation Failed Tags：

4.6.5 取消能力

如果要在 GameplayAbility 内部取消它自身，可以调用 CancelAbility()。这会调用 EndAbility()，并将其 WasCancelled 参数设为 true。

如果要从外部取消某个 GameplayAbility，ASC 提供了几个函数：

/** Cancels the specified ability CDO. */
void CancelAbility(UGameplayAbility* Ability);

/** Cancels the ability indicated by passed in spec handle. If handle is not found among reactivated abilities nothing happens. */
void CancelAbilityHandle(const FGameplayAbilitySpecHandle& AbilityHandle);

/** Cancel all abilities with the specified tags. Will not cancel the Ignore instance */
void CancelAbilities(const FGameplayTagContainer* WithTags=nullptr, const FGameplayTagContainer* WithoutTags=nullptr, UGameplayAbility* Ignore=nullptr);

/** Cancels all abilities regardless of tags. Will not cancel the ignore instance */
void CancelAllAbilities(UGameplayAbility* Ignore=nullptr);

/** Cancels all abilities and kills any remaining instanced abilities */
virtual void DestroyActiveState();

注意： 我发现如果你存在 Non-Instanced GameplayAbilities，CancelAllAbilities 似乎不能正常工作。它看起来会命中那个 Non-Instanced GameplayAbility 然后放弃。CancelAbilities 对 Non-Instanced GameplayAbilities 的处理更好，Sample Project 使用的就是它（Jump 就是一个非实例化 GameplayAbility）。你的实际结果可能不同。

4.6.6 获取激活中的能力

初学者经常会问：“我怎样才能拿到当前激活的能力？”也许是为了给它设置变量，或者取消它。实际上，同一时间可以有多个 GameplayAbility 处于激活状态，所以并不存在唯一的“当前激活能力”。你必须遍历 ASC 的 ActivatableAbilities 列表（即 ASC 拥有的、已授予的 GameplayAbilities），找到与你想要的 Asset 或 Granted GameplayTag 匹配的那个。

UAbilitySystemComponent::GetActivatableAbilities() 会返回一个 TArray<FGameplayAbilitySpec> 供你迭代。

ASC 还提供了另一个辅助函数，它接收一个 GameplayTagContainer 参数，以帮助你查找，而不必手动遍历 GameplayAbilitySpecs 列表。参数 bOnlyAbilitiesThatSatisfyTagRequirements 只会返回满足其 GameplayTag 要求、并且当前可以被激活的 GameplayAbilitySpecs。例如，你可能有两个基础攻击 GameplayAbilities，一个用于持武器，一个用于空手；当是否装备武器改变并设置相应 GameplayTag 条件时，就会激活正确的那个。更多信息请参见 Epic 对该函数的注释。

UAbilitySystemComponent::GetActivatableGameplayAbilitySpecsByAllMatchingTags(const FGameplayTagContainer& GameplayTagContainer, TArray < struct FGameplayAbilitySpec* >& MatchingGameplayAbilities, bool bOnlyAbilitiesThatSatisfyTagRequirements = true)

一旦拿到了你要找的 FGameplayAbilitySpec，就可以对其调用 IsActive()。

4.6.7 实例化策略

GameplayAbility 的 Instancing Policy 决定它在激活时是否以及如何被实例化。

4.6.8 网络执行策略

GameplayAbility 的 Net Execution Policy 决定该 GameplayAbility 由谁运行，以及按什么顺序运行。

4.6.9 能力标签

GameplayAbilities 自带若干 GameplayTagContainers 及其内建逻辑。这些 GameplayTags 都不会被 Replication。

4.6.10 Gameplay Ability Spec 说明

在某个 GameplayAbility 被授予之后，ASC 上会存在一个 GameplayAbilitySpec，它定义了这个可激活的 GameplayAbility，包括 GameplayAbility 类、等级、输入绑定，以及必须与 GameplayAbility 类本身分离保存的运行时状态。

当一个 GameplayAbility 在服务器上被授予时，服务器会把 GameplayAbilitySpec Replication 给拥有它的客户端，以便她可以激活它。

激活 GameplayAbilitySpec 时，会根据它的 Instancing Policy 创建一个 GameplayAbility 实例（Non-Instanced GameplayAbilities 则不会创建实例）。

4.6.11 向能力传递数据

GameplayAbilities 的通用范式是 Activate->Generate Data->Apply->End。有时你需要基于已有数据执行逻辑。GAS 为把外部数据传入 GameplayAbilities 提供了几种方案：

4.6.12 能力消耗与冷却

GameplayAbilities 自带可选的消耗与冷却功能。消耗是 ASC 为了激活某个 GameplayAbility 必须拥有的预定义数量的 Attributes，它通过一个 Instant GameplayEffect（Cost GE）实现。冷却是阻止 GameplayAbility 在到期前再次激活的计时器，它通过一个 Duration GameplayEffect（Cooldown GE）实现。

在某个 GameplayAbility 调用 UGameplayAbility::Activate() 之前，它会先调用 UGameplayAbility::CanActivateAbility()。这个函数会检查拥有它的 ASC 是否承担得起消耗（UGameplayAbility::CheckCost()），并确保该 GameplayAbility 当前不在冷却中（UGameplayAbility::CheckCooldown()）。

在 GameplayAbility 调用 Activate() 之后，它可以在任意时刻通过 UGameplayAbility::CommitAbility() 选择性地提交消耗和冷却，这会调用 UGameplayAbility::CommitCost() 与 UGameplayAbility::CommitCooldown()。设计者也可以选择分别调用 CommitCost() 或 CommitCooldown()，如果它们不应同时提交的话。提交消耗和冷却时会再次调用 CheckCost() 和 CheckCooldown()，这是该 GameplayAbility 因它们而失败的最后机会。因为在 GameplayAbility 激活后，拥有它的 ASC 的 Attributes 仍有可能发生变化，从而在提交时不再满足消耗条件。如果在提交时 prediction key 仍然有效，那么提交消耗和冷却可以进行本地。

实现细节请参见 CostGE 和 CooldownGE。

4.6.13 提升能力等级

能力升级通常有两种常见方式：

这两种方法的主要区别在于：你是否希望激活中的 GameplayAbilities 在升级时被取消。你大概率会根据不同的 GameplayAbilities 同时使用这两种方法。我建议在你的 UGameplayAbility 子类中添加一个 bool 来指定使用哪一种方法。

4.6.14 能力集合

GameplayAbilitySets 是一种便捷的 UDataAsset 类，用于保存输入绑定和角色初始 GameplayAbilities 列表，并带有授予这些 GameplayAbilities 的逻辑。子类还可以包含额外逻辑或属性。Paragon 为每个英雄都准备了一个 GameplayAbilitySet，其中包含该英雄拥有的全部 GameplayAbilities。

至少基于我目前看到的情况，我觉得这个类并不是必需的。Sample Project 把 GameplayAbilitySets 的全部功能都放在了 GDCharacterBase 及其子类内部处理。

4.6.15 能力批处理

传统的 Gameplay Ability 生命周期通常至少涉及客户端向服务器发送两个或三个 RPC。

1. ServerSetReplicatedTargetData()（可选）

如果某个 GameplayAbility 会在一帧内以一个原子分组完成所有这些动作，我们就可以优化这条流程，把原来的两到三个 RPC 批量合并成一个 RPC。GAS 把这种 RPC 优化称为 Ability Batching。最常见的使用场景是 hitscan 枪械。hitscan 枪会激活能力、执行一条线性检测、把 TargetData 发送给服务器，然后在同一帧内结束能力。示例项目 GASShooter 为其 hitscan 枪演示了这一技术。

半自动枪是最佳场景，它会把 CallServerTryActivateAbility()、ServerSetReplicatedTargetData()（子弹命中结果）和 ServerEndAbility() 从原本三个 RPC 合并为一个 RPC。

全自动/点射枪会把第一发子弹的 CallServerTryActivateAbility() 和 ServerSetReplicatedTargetData() 从两个 RPC 合并为一个 RPC。之后每一发子弹仍然各自发送一个 ServerSetReplicatedTargetData() RPC。最后，在枪停止射击时，ServerEndAbility() 会以单独的 RPC 发送。这是最差场景，因为第一发子弹只节省了一个 RPC，而不是两个。这个场景也可以通过使用 Gameplay Event 激活能力来实现，那样会把子弹的 TargetData 放进 EventPayload 从客户端发送到服务器。后一种方式的缺点是 TargetData 必须在能力外部生成，而批处理方式则是在能力内部生成 TargetData。

在 ASC 上，Ability Batching 默认是关闭的。要启用 Ability Batching，请重写 ShouldDoServerAbilityRPCBatch() 并返回 true：

virtual bool ShouldDoServerAbilityRPCBatch() const override { return true; }

启用 Ability Batching 之后，在激活你希望被批处理的能力之前，必须先创建一个 FScopedServerAbilityRPCBatcher 结构体。这个特殊结构体会尝试把其作用域内后续发生的能力相关 RPC 进行批处理。一旦 FScopedServerAbilityRPCBatcher 离开作用域，之后激活的能力就不会再尝试批处理。FScopedServerAbilityRPCBatcher 的工作方式是：在每个可被批处理的函数中都有特殊代码，它会拦截原本要直接发送 RPC 的调用，转而把消息打包进一个批处理结构体。当 FScopedServerAbilityRPCBatcher 离开作用域时，它会在 UAbilitySystemComponent::EndServerAbilityRPCBatch() 中自动把这个批处理结构体通过 RPC 发给服务器。服务器会在 UAbilitySystemComponent::ServerAbilityRPCBatch_Internal(FServerAbilityRPCBatch& BatchInfo) 中接收该批处理 RPC。BatchInfo 参数中会包含一些标记，用来说明能力是否应结束、激活时输入是否被按下，以及是否包含了 TargetData。这是一个很适合打断点来确认批处理是否正常工作的函数。或者，也可以使用 cvar AbilitySystem.ServerRPCBatching.Log 1 来开启专门的能力批处理日志。

这种机制只能在 C++ 中完成，而且只能通过 FGameplayAbilitySpecHandle 来激活能力。

bool UGSAbilitySystemComponent::BatchRPCTryActivateAbility(FGameplayAbilitySpecHandle InAbilityHandle, bool EndAbilityImmediately)
{
	bool AbilityActivated = false;
	if (InAbilityHandle.IsValid())
	{
		FScopedServerAbilityRPCBatcher GSAbilityRPCBatcher(this, InAbilityHandle);
		AbilityActivated = TryActivateAbility(InAbilityHandle, true);

		if (EndAbilityImmediately)
		{
			FGameplayAbilitySpec* AbilitySpec = FindAbilitySpecFromHandle(InAbilityHandle);
			if (AbilitySpec)
			{
				UGSGameplayAbility* GSAbility = Cast<UGSGameplayAbility>(AbilitySpec->GetPrimaryInstance());
				GSAbility->ExternalEndAbility();
			}
		}

		return AbilityActivated;
	}

	return AbilityActivated;
}

GASShooter 对半自动和全自动枪复用了同一个可批处理的 GameplayAbility，它们从不直接调用 EndAbility()（结束由一个仅本地运行的能力负责，这个本地能力根据当前开火模式管理玩家输入以及对批处理能力的调用）。由于所有 RPC 都必须发生在 FScopedServerAbilityRPCBatcher 的作用域内，所以我提供了 EndAbilityImmediately 参数，让负责控制/管理的本地能力可以指定：这个能力是否应把 EndAbility() 调用一起批处理（半自动），或者不把 EndAbility() 一起批处理（全自动），在后者情况下，EndAbility() 会在之后某个时刻通过它自己的 RPC 发送。

GASShooter 暴露了一个 Blueprint 节点来支持能力批处理，上面提到的仅本地能力就用它来触发这个被批处理的能力。

激活批处理能力：

4.6.16 网络安全策略

GameplayAbility 的 NetSecurityPolicy 决定一个能力应当在网络中的哪里执行。它可以防止客户端试图执行受限制的能力。

4.7 关于 Ability Tasks

4.7.1 Ability Task 定义

GameplayAbilities 只会在一帧内执行完。这本身不具备太多灵活性。为了执行跨时间发生的动作，或者响应未来某个时间点触发的委托，我们使用一种称为 AbilityTasks 的潜伏动作。

GAS 自带很多现成的 AbilityTasks：

• 使用 RootMotionSource 移动 Characters 的任务
• 播放动画蒙太奇的任务
• 响应 Attribute 变化的任务
• 响应 GameplayEffect 变化的任务
• 响应玩家输入的任务
• 以及更多

UAbilityTask 构造函数强制规定了一个写死的、全游戏范围的上限：同一时间最多只能有 1000 个并发运行的 AbilityTasks。当你为同一世界中可能同时存在数百个角色的游戏（例如 RTS）设计 GameplayAbilities 时，要牢记这一点。

4.7.2 自定义 Ability Tasks

很多时候你都会自己编写自定义 AbilityTasks（用 C++）。Sample Project 附带了两个自定义 AbilityTasks：

1. PlayMontageAndWaitForEvent 是默认 PlayMontageAndWait 与 WaitGameplayEvent AbilityTasks 的组合。这让动画蒙太奇可以通过 AnimNotifies 把 gameplay events 回传给启动它们的 GameplayAbility。用它可以在动画蒙太奇中的特定时刻触发动作。
2. WaitReceiveDamage 负责监听 OwnerActor 是否受到伤害。被动护甲层数 GameplayAbility 会在英雄受到一次伤害时移除一层护甲。

AbilityTasks 由以下部分组成：

• 一个用于创建新 AbilityTask 实例的静态函数
• 当 AbilityTask 完成其目标时会广播的委托
• 一个 Activate() 函数，用于开始其主要工作、绑定外部委托等
• 一个 OnDestroy() 函数，用于清理，包括解绑它绑定过的外部委托
• 它绑定的所有外部委托所对应的回调函数
• 成员变量，以及任何内部辅助函数

注意： AbilityTasks 只能声明一种输出委托类型。无论是否使用参数，你的所有输出委托都必须是这种类型。对于未使用的委托参数，请传入默认值。

AbilityTasks 只会在运行其所属 GameplayAbility 的客户端或服务器上执行；不过，也可以通过在 AbilityTask 构造函数中设置 bSimulatedTask = true;、重写 virtual void InitSimulatedTask(UGameplayTasksComponent& InGameplayTasksComponent);，并让相关成员变量支持 Replication，从而让 AbilityTasks 在模拟客户端上运行。这个能力只在少数场景有用，比如移动类 AbilityTasks，你不想 Replication 每一次移动变化，而是希望整个移动 AbilityTask 都被模拟。所有 RootMotionSource AbilityTasks 都是这样做的。可参考 AbilityTask_MoveToLocation.h/.cpp。

如果你在 AbilityTask 构造函数中设置 bTickingTask = true; 并重写 virtual void TickTask(float DeltaTime);，那么 AbilityTasks 就可以 Tick。当你需要在多帧之间平滑插值时，这会很有用。可参考 AbilityTask_MoveToLocation.h/.cpp。

4.7.3 使用 Ability Tasks

在 C++ 中创建并激活一个 AbilityTask（摘自 GDGA_FireGun.cpp）：

UGDAT_PlayMontageAndWaitForEvent* Task = UGDAT_PlayMontageAndWaitForEvent::PlayMontageAndWaitForEvent(this, NAME_None, MontageToPlay, FGameplayTagContainer(), 1.0f, NAME_None, false, 1.0f);
Task->OnBlendOut.AddDynamic(this, &UGDGA_FireGun::OnCompleted);
Task->OnCompleted.AddDynamic(this, &UGDGA_FireGun::OnCompleted);
Task->OnInterrupted.AddDynamic(this, &UGDGA_FireGun::OnCancelled);
Task->OnCancelled.AddDynamic(this, &UGDGA_FireGun::OnCancelled);
Task->EventReceived.AddDynamic(this, &UGDGA_FireGun::EventReceived);
Task->ReadyForActivation();

在 Blueprint 中，我们只需要使用为该 AbilityTask 创建的 Blueprint 节点，不需要手动调用 ReadyForActivation()。它会由 Engine/Source/Editor/GameplayTasksEditor/Private/K2Node_LatentGameplayTaskCall.cpp 自动调用。如果你的 AbilityTask 类中存在 BeginSpawningActor() 和 FinishSpawningActor()（参见 AbilityTask_WaitTargetData），K2Node_LatentGameplayTaskCall 也会自动调用它们。再次强调，K2Node_LatentGameplayTaskCall 的这类“自动魔法”只对 Blueprint 生效。在 C++ 中，我们必须手动调用 ReadyForActivation()、BeginSpawningActor() 和 FinishSpawningActor()。

Blueprint 中的 WaitTargetData AbilityTask：

如果要手动取消一个 AbilityTask，只需在 Blueprint（其中它叫 Async Task Proxy）或 C++ 中，对该 AbilityTask 对象调用 EndTask()。

GAS 自带一些 AbilityTasks，用于通过挂接到 CharacterMovementComponent 的 Root Motion Sources，让 Characters 随时间移动，以实现击退、复杂跳跃、拉拽、冲刺等效果。

注意： RootMotionSource AbilityTasks 的 Prediction 在 4.19 和 4.25+ 引擎版本中可用。4.20-4.24 版本中 Prediction 存在 bug；不过，这些 AbilityTasks 在多人游戏中仍然能工作，只会有轻微的网络校正，在单机中则完全正常。你可以把 4.25 中的这个 prediction 修复 cherry-pick 到自定义的 4.20-4.24 引擎中。

4.8 关于 Gameplay Cues

4.8.1 Gameplay Cue 定义

GameplayCues（GC）负责执行与 gameplay 无关的内容，例如音效、粒子效果、镜头震动等。GameplayCues 通常会进行 Replication（除非你显式在本地 Executed、Added 或 Removed）并支持 Prediction。

我们通过 ASC 向 GameplayCueManager 发送一个对应的 GameplayTag 来触发 GameplayCues。这个 GameplayTag 必须带有父名称 GameplayCue.，同时还要带上事件类型（Execute、Add 或 Remove）。GameplayCueNotify 对象和其他实现了 IGameplayCueInterface 的 Actors，都可以根据该 GameplayCue 的 GameplayTag（GameplayCueTag）来订阅这些事件。

注意： 再强调一次，GameplayCue 的 GameplayTags 必须以父级 GameplayTag GameplayCue 开头。例如，一个合法的 GameplayCue GameplayTag 可以是 GameplayCue.A.B.C。

GameplayCueNotifies 分为两类：Static 和 Actor。它们响应的事件不同，也由不同类型的 GameplayEffects 触发。请重写对应事件并填入你的逻辑。

从技术上讲，GameplayCueNotifies 可以响应任意事件，但通常我们就是按上表这种方式使用它们。

注意： 使用 GameplayCueNotify_Actor 时，请检查 Auto Destroy on Remove，否则后续针对该 GameplayCueTag 的 Add 调用将不起作用。

当 ASC 使用的 Replication Mode 不是 Full 时，Add 和 Remove 类型的 GC 事件会在服务器玩家（listen server）上触发两次：一次来自应用该 GE，另一次来自发给客户端的 “Minimal” NetMultiCast。不过，WhileActive 事件仍然只会触发一次。所有事件在客户端上都只会触发一次。

Sample Project 包含一个用于 stun 和 sprint 效果的 GameplayCueNotify_Actor，也包含一个用于 FireGun 投射物命中的 GameplayCueNotify_Static。这些 GCs 还可以进一步优化，即在本地触发它们，而不是通过 GE 来 Replication。我在 Sample Project 中选择了展示更适合初学者的用法。

4.8.2 触发 Gameplay Cues

在 GameplayEffect 成功应用时（没有被 tags 或免疫阻挡），在其内部填写所有应被触发的 GameplayCues 对应的 GameplayTags。

从 GameplayEffect 触发的 GameplayCue：

UGameplayAbility 提供了 Blueprint 节点来 Execute、Add 或 Remove GameplayCues。

从 GameplayAbility 触发的 GameplayCue：

在 C++ 中，你可以直接在 ASC 上调用这些函数（或者在你的 ASC 子类中把它们暴露给 Blueprint）：

/** GameplayCues can also come on their own. These take an optional effect context to pass through hit result, etc */
void ExecuteGameplayCue(const FGameplayTag GameplayCueTag, FGameplayEffectContextHandle EffectContext = FGameplayEffectContextHandle());
void ExecuteGameplayCue(const FGameplayTag GameplayCueTag, const FGameplayCueParameters& GameplayCueParameters);

/** Add a persistent gameplay cue */
void AddGameplayCue(const FGameplayTag GameplayCueTag, FGameplayEffectContextHandle EffectContext = FGameplayEffectContextHandle());
void AddGameplayCue(const FGameplayTag GameplayCueTag, const FGameplayCueParameters& GameplayCueParameters);

/** Remove a persistent gameplay cue */
void RemoveGameplayCue(const FGameplayTag GameplayCueTag);

/** Removes any GameplayCue added on its own, i.e. not as part of a GameplayEffect. */
void RemoveAllGameplayCues();