UGameplayAbility

自动关联目录:UGameplayAbility

官方依据:Using Gameplay Abilities(UE 5.8 Documentation)。本页覆盖该页全部 6 个条目(Granting and Revoking / Basic Usage / Tags / Replication / Instancing Policy / Triggering with Gameplay Events),并补官方未展开的典型配置、代价与踩坑。

1. 定位

Ability 是"一段可以被引擎管理的技能逻辑"。引擎替它管的事:能否激活、冷却与消耗、被打断、网络复制、预测回滚。

一句话定位:把技能写成 Ability,换来的不是"框架约束",而是"冷却/消耗/打断/预测"这四件事不用自己实现——这四件自己做,每一件都会做出 bug。

2. 生命周期

CanActivateAbility(检查:标签、冷却、消耗、实例数)
  → TryActivateAbility(再检查一次 → CallActivateAbility)
       → ActivateAbility(主逻辑)
             ├── CommitAbility(扣 Cost + 上 Cooldown)
             ├── AbilityTask 等待(动画、输入、时间、事件)
             └── EndAbility / CancelAbility
回调用途
CanActivateAbility自定义激活条件(返回 bool)
ActivateAbility主逻辑入口(C++)/ Activate Ability(蓝图)
CommitAbility应用 Cost 与 Cooldown
EndAbility正常结束
CancelAbility被打断;CanBeCanceled 可拒绝取消
OnAvatarSetAvatar 绑定时(初始化/获取组件)

两条必须记住的显式调用:

  1. CommitAbility 要显式调用——不调就不扣冷却与消耗,这是新手最常见的"技能无限放"的原因
  2. 必须显式调用 EndAbility——否则系统认为 Ability 仍在运行,持续阻塞后续能力

取消流程会走结束流程并广播 OnGameplayAbilityCancelled。

3. 关键配置

配置说明
Ability Tags本技能自带的标签
Cancel Abilities With Tag激活时取消含匹配 Tag 的 Ability
Block Abilities With Tag激活期间阻止含匹配 Tag 的 Ability 激活
Activation Owned Tags激活期间赋给拥有者(如 State.Casting)
Activation Required Tags激活者必须拥有这些 Tag
Activation Blocked Tags拥有者有这些 Tag 时不能激活(如 State.Stun)
Target Required / Blocked Tags对目标做同样的检查
Cost GameplayEffect消耗
Cooldown GameplayEffect冷却
Net Execution Policy见第 4 节
Instancing Policy见第 5 节
Replication Policy是否复制 Ability 的状态与事件

标签阻断是 GAS 里最有用的机制之一:眩晕 = 给一个带 State.Stun 的 GE,所有技能把 State.Stun 写进 Activation Blocked Tags,一行代码不用改就全生效。

4. 网络执行策略(Replication)

Net Execution Policy 四种:

策略行为适用
Local Predicted客户端先预测执行,服务端最终裁决需要手感的玩家技能(默认选这个)
Local Only只在本地执行,不复制纯表现、无需权威
Server Initiated服务端发起,再下发到客户端服务端触发的效果
Server Only只在服务端执行完全不需要客户端感知的逻辑

Replication Policy 控制是否复制 Ability 的状态与事件(与 Net Execution Policy 是两件事)。

Local Predicted 的含义要理解清楚:客户端先跑一遍(手感好),但可能被服务端纠正——因此预测路径里的表现必须可回滚(见 网络预测与回滚)。

只有服务端能授予与移除 Ability(见第 6 节)。

5. 实例策略(Instancing Policy)

策略特点适用
InstancedPerActor每个 Actor 一个实例,可存成员变量大多数技能
InstancedPerExecution每次激活一个新实例需要并存多个同类技能
NonInstanced不创建实例,用 CDO 执行极高频、无状态技能

NonInstanced 性能最好但不能有成员变量,逻辑必须无状态。

6. 授予与移除(Granting / Revoking)

API说明端限制
GiveAbility(Spec)授予,返回 FGameplayAbilitySpecHandle仅服务端
GiveAbilityAndActivateOnce(Spec)授予并尝试在服务端执行一次;失败返回无效 Handle仅服务端
ClearAbility(Handle)按 Handle 移除仅服务端
SetRemoveAbilityOnEnd(Handle)结束时移除,并清除输入仅服务端
ClearAllAbilities()移除全部,无需 Handle仅服务端

SetRemoveAbilityOnEnd 的一个实际副作用:它会立即清除输入,玩家无法再激活或与该 Ability 交互。取消/结束流程同样会阻止再次交互。

// 授予
FGameplayAbilitySpec Spec(AbilityClass, Level, InputID, SourceObject);
FGameplayAbilitySpecHandle Handle = ASC->GiveAbility(Spec);

// 主动激活
ASC->TryActivateAbility(Handle);

7. 用 Gameplay Event 触发(Triggering with Gameplay Events)

除了输入绑定,Ability 也可以由 Gameplay Event 触发——这让"被动技能""受击反击""击杀触发"这类逻辑不需要自己写监听。

// 发事件
FGameplayEventData Payload;
Payload.Instigator = GetOwner();
Payload.Target = HitActor;
Payload.EventMagnitude = Damage;
ASC->HandleGameplayEvent(EventTag, &Payload);

// 在蓝图中把 Ability 的 Triggers 设为该 EventTag
要点说明
FGameplayEventData携带 Instigator / Target / 数值 / 自定义对象
触发方式配在 Ability 的 Triggers 上不需要在代码里逐个绑定
客户端预测事件触发的 Ability 同样受 Net Execution Policy 约束

8. 典型结构

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

    // 播放蒙太奇并等待事件
    UAbilityTask_PlayMontageAndWait* Task =
        UAbilityTask_PlayMontageAndWait::CreatePlayMontageAndWaitProxy(
            this, NAME_None, FireMontage);
    Task->OnCompleted.AddDynamic(this, &UGA_Fireball::OnMontageDone);
    Task->ReadyForActivation();
}

void UGA_Fireball::OnMontageDone()
{
    // 造成伤害:始终通过 GE
    ApplyGameplayEffectToTarget(..., DamageEffectClass);
    EndAbility(...);
}

要点:等待用 Task(见 UAbilityTask),伤害用 GE(见 UGameplayEffect),属性用 UAttributeSet。

9. 代价与权衡

设计收益代价什么时候不该用
Local Predicted手感好预测失败要能回滚;不可逆的表现不能放预测路径纯服务端逻辑不该用
NonInstanced性能最好、无实例开销不能有成员变量需要跨 Task 存状态时不可用
InstancedPerExecution同类技能可并存每次激活都新建对象高频技能慎用
标签阻断眩晕/沉默等状态一行配置全生效标签设计不好会互相干扰标签需要先规划命名空间
Event 触发解耦,被动技不用写监听事件链路不直观,调试要跟 EventTag简单直接调用更清楚的场景不必用
Replication Policy 开客户端能看到技能状态带宽只在必要时开

10. 踩坑与排查

坑现象怎么验证
忘记 CommitAbility冷却消耗不生效,技能无限放检查 ActivateAbility 里是否调用
忘记 EndAbility技能卡住,后续无法再激活用 showdebug abilitysystem 看活跃 Ability 列表
在 Ability 里用 GetWorld()->GetTimerManager() 等待不走预测、无法随技能取消应改用 AbilityTask
用成员变量但策略是 NonInstanced状态错乱检查 Instancing Policy
在客户端直接改属性不权威、预测失败不回滚应 Apply GE 走预测流程
关键判定写在客户端可作弊(见 Security)判定必须在服务端
客户端调 GiveAbility无效,仅服务端走 Server RPC
SetRemoveAbilityOnEnd 后输入没了设计如此它会立即清除输入
预测路径里播了不可逆表现回滚时穿帮(粒子闪一下就没)表现放到服务端下发的 GameplayCue
标签没生效拼写/层级不匹配用 showdebug abilitysystem 看实际拥有的 Tag
Cooldown GE 配错冷却不生效或永久冷却检查 GE 的 Duration Policy 与 Tag
冷却查询失败GetCooldownTimeRemaining 返回 0Cooldown GE 必须带 Cooldown Tag(与 Ability Tags 匹配)

11. 排查顺序

1. 激活不了?→ showdebug abilitysystem 看:是否拥有该 Ability、被哪个 Tag 阻断、冷却剩余
2. 放了没消耗?→ 是否 CommitAbility
3. 放一次就放不了了?→ 是否 EndAbility
4. 手感不对/回滚穿帮?→ Net Execution Policy 与预测路径(见网络预测篇)
5. 状态类失效?→ Tag 拼写与层级
6. 冷却异常?→ Cooldown GE 的 Tag 与 Duration Policy

12. 调试命令

命令作用
showdebug abilitysystemGAS 第一调试命令:看 Attribute、Tag、活跃 Ability、GE 列表
AbilitySystem.Debug.NextCategory切换调试页签
Log LogAbilitySystem Verbose打开详细日志

参考