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 可拒绝取消 |
OnAvatarSet | Avatar 绑定时(初始化/获取组件) |
两条必须记住的显式调用:
CommitAbility要显式调用——不调就不扣冷却与消耗,这是新手最常见的"技能无限放"的原因- 必须显式调用
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 返回 0 | Cooldown 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 Policy12. 调试命令
| 命令 | 作用 |
|---|---|
showdebug abilitysystem | GAS 第一调试命令:看 Attribute、Tag、活跃 Ability、GE 列表 |
AbilitySystem.Debug.NextCategory | 切换调试页签 |
Log LogAbilitySystem Verbose | 打开详细日志 |