gameplay-ability-system

用途

Gameplay Ability System（GAS）是 Epic 提供的技能、属性与效果框架，内置网络支持。该技能面向需要在虚幻引擎中实现带冷却、消耗、标签门控、属性增减与网络同步能力的游戏逻辑的开发者。原文明确提示：GAS 强大但重量级，技能与数值交互较多时适合采用；只有少量简单动作时，用普通组件可能更简单。

主要能力

• 实现玩家或敌人的技能，支持冷却、消耗与 GameplayTag 门控。
• 声明属性（生命、耐力、法力、护甲等），并通过增益、减益与伤害修改。
• 服务器权威、客户端预测的网络技能激活。
• 用 Gameplay Cues 实现外观效果，无需自建 RPC。
• 技能内异步逻辑：等待动画、输入、事件或延迟。

核心组件

• UAbilitySystemComponent（ASC）：集散中心，持有已授予技能、激活中的效果、属性集与标签。
• UAttributeSet：声明 FGameplayAttributeData 属性并重写变更回调。
• UGameplayAbility：可授予、可激活的技能，含消耗、冷却与异步逻辑。
• UGameplayEffect（GE）：数据驱动的属性或标签变更，持续策略为 Instant、HasDuration 或 Infinite。
• FGameplayAbilitySpec：已授予的技能实例（类、等级、输入 ID、源对象）。
• UAbilityTask：技能内的异步步骤（等待事件、蒙太奇、延迟、目标数据）。
• Gameplay Cues：以 GameplayCue.* 标签为键的外观反馈（VFX/SFX），网络高效。

使用方式

1. 启用 Gameplay Abilities 插件（.uplugin 中 Plugins，或向 .uproject 添加 GameplayAbilitiesPlugin）。
2. 在模块 Build.cs 的 PublicDependencyModuleNames 中加入 "GameplayAbilities"、"GameplayTags"、"GameplayTasks"。
3. 在启动时恰好调用一次 UAbilitySystemGlobals::Get().InitGlobalData()，通常在 UAssetManager::StartInitialLoading 或游戏模块启动函数中；遗漏会导致目标数据与蒙太奇预测静默失败。
4. 选择 ASC 挂载位置：多人玩家角色放在 PlayerState 以便重生后保留，Pawn 实现 IAbilitySystemInterface::GetAbilitySystemComponent() 返回 PlayerState 的 ASC，并在服务器 PossessedBy、客户端 OnRep_PlayerState（或监听服务器 Pawn 的 BeginPlay）调用 InitAbilityActorInfo(OwnerActor, AvatarPawn)；AI 或简单 Actor 直接把 ASC 放在 Pawn 上并调用 InitAbilityActorInfo(this, this)。
5. 在 ASC 所属 Actor 的构造函数中通过 CreateDefaultSubobject 创建 UAttributeSet 子对象进行注册；ASC 会自动发现同一 Actor 上的属性集。运行时不要直接写属性字段，应通过 UGameplayEffect 应用变更，以保证预测、复制与聚合正确。
6. 服务器端授予技能（GiveAbility 仅限权威端），用 TryActivateAbilityByClass 或 TryActivateAbility(Handle) 激活；消耗与冷却本身是技能上 CostGameplayEffectClass 与 CooldownGameplayEffectClass 引用的 UGameplayEffect 资产。
7. 编写技能时遵循生命周期：CanActivateAbility（只读检查）→ CommitAbility（消耗消耗与冷却）→ 技能逻辑（启动任务）→ EndAbility；不调用 EndAbility 会让技能无限处于激活状态。
8. 异步任务使用 NewAbilityTask<T>（不是 NewObject）并调用 ReadyForActivation()，始终重写 OnDestroy 以注销回调；常用内置任务包括 WaitDelay、PlayMontageAndWait、WaitGameplayEvent、WaitTargetData、WaitAttributeChange。
9. Gameplay Cues 用 ExecuteGameplayCue 触发一次性效果，用 AddGameplayCue/RemoveGameplayCue 管理持续效果；Cue 处理器须带 GameplayCue.* 标签并注册到 Cue 管理器。

网络模型

服务器权威：技能授予与移除仅在服务器进行，效果在服务器应用。ASC 复制模式设为 Full（单人或小型点对点）、Mixed（多人中玩家拥有的 ASC）、Minimal（AI 拥有的 ASC）。LocalPredicted 网络执行策略的技能在预测客户端立即运行，由服务器确认或回滚；外观输出使用 Gameplay Cues。复制属性需 ReplicatedUsing=OnRep_<Name>，并在属性集上实现 GetLifetimeReplicatedProps。

适用场景

技能与数值交互较多、需要冷却/消耗/标签门控、属性受增益减益影响、需要服务器权威与客户端预测的网络技能、需要外观反馈而不自建 RPC 的项目；AI 敌人技能与简单 Actor 也可使用。

限制与注意事项

• 单个 Actor 不支持多个 ASC（查询会歧义）；多个 Actor 可共享一个 ASC。
• 常见陷阱：未调用 InitGlobalData()；运行时直接写属性字段；重生型多人玩家的 ASC 放在 Pawn 上导致死亡后状态重置；缺少模块依赖导致链接错误；未调用 EndAbility；复制模式选错；Cue 标签未以 GameplayCue. 为前缀；忘记 CommitAbility；在 GE 构造函数中使用 FindOrAddComponent/AddComponent（NewObject 空名字在 CDO 构造时致命断言）；SetByCaller 消耗/冷却配裸 CommitAbility 导致数值未设置；未配置 GameplayCueNotifyPaths 使 Cue 管理器回退扫描整个 /Game/。
• 版本说明：NonInstanced 在 5.5 弃用，推荐默认 InstancedPerActor；AbilityTags 在 5.5 弃用，改用 GetAssetTags() 与 SetAssetTags()（仅构造函数）；UGameplayEffect 在 5.3 起组件化（EGameplayEffectVersion::Modular53），旧式单体数据仍可用；GetAbilitySystemComponentFromActorInfo_Checked() 在 5.5 弃用，改用 GetAbilitySystemComponentFromActorInfo_Ensured()。
• 该技能引用的引擎源码基于 UE 5.8，具体行号与 API 以对应引擎版本为准；原文未提供插件安装命令、价格或收费信息。

参考资料

官方文档涵盖 GAS 概览、ASC 与属性、Gameplay Ability、属性与属性集、Gameplay Effects、Ability Tasks；本技能内还附有 references/ability-system-component.md、references/gameplay-abilities.md、references/attributes-and-effects.md、references/ability-tasks-and-cues.md 等深入参考。相关技能：gameplay-tags（GAS 全程由标签驱动）、networking-and-replication、animation-system（蒙太奇任务）。