unreal-gas

Unreal Engine Gameplay Ability System (GAS)——C++ 指南

官方文档（请始终查阅最新信息）

以下是权威资料。GAS 会随引擎版本不断演进，请参考这些资料获取最新的 API 详细信息：

来源	URL
Epic GAS 主页	https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-for-unreal-engine
了解 GAS（概述）	https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system
ASC 和属性	https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-component-and-gameplay-attributes-in-unreal-engine
Gameplay Abilities	https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-abilities-in-unreal-engine
属性和属性集	https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-attributes-and-attribute-sets-for-the-gameplay-ability-system-in-unreal-engine
Gameplay Effects	https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-effects-for-the-gameplay-ability-system-in-unreal-engine
Ability Tasks	https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-tasks-in-unreal-engine
社区 GAS 文档（tranek）	https://github.com/tranek/GASDocumentation

tranek 编写的社区文档是关于 GAS 最全面的单一资料来源。它涵盖了 Epic 官方文档未涉及的高级主题（预测内部机制、优化、复制模式、常见问题）。遇到边缘情况和生产实践问题时，请务必查阅。

Lyra Sample Project 是 Epic 推荐的 GAS 实际参考实现。

插件设置

1. 在编辑器中启用 Gameplay Abilities 插件
2. 添加到 Build.cs：

   PublicDependencyModuleNames.AddRange(new string[] {
       "GameplayAbilities", "GameplayTags", "GameplayTasks"
   });
   

3. UE 5.2 及更早版本：在 AssetManager 或 GameInstance 中调用 UAbilitySystemGlobals::Get().InitGlobalData()。UE 5.3+ 会自动执行此操作。

核心架构

完整的类参考、设置模式和 C++ 代码片段，请参见 references/core-classes.md。

系统概览：

Actor
  +-- UAbilitySystemComponent (ASC) --- manages everything below
        +-- UGameplayAbility instances (granted abilities)
        |     +-- UAbilityTask instances (async execution)
        +-- UAttributeSet instances (numeric data)
        +-- Active UGameplayEffect specs (modifiers)
        +-- FGameplayTag container (status/state)
        +-- GameplayCue triggers (cosmetic FX)

关键关系：

• ASC 是核心枢纽；每个 Actor 配置一个（放置在 Pawn 或 PlayerState 上）
• Ability 会创建并应用 Effect，以修改目标上的 Attribute 和 Tag
• Effect 的 Tag 与 GameplayCue.* Tag 匹配时，会自动触发 Cue
• Tag 系统性地控制 Ability 的激活、阻止和取消
• AbilityTask 在 Ability 中处理异步工作（蒙太奇、延迟、目标选择）

Gameplay Effects 快速参考

详细的 GE 模式、修饰符运算、叠加、冷却时间和属性处理，请参见 references/effects-and-attributes.md。

持续时间类型：

• Instant——永久修改 BaseValue，不会作为活动状态进行跟踪
• Duration——修改 CurrentValue，到期时自动还原
• Infinite——持续生效，直到被显式移除

修饰符聚合： ((Base + Additive) * Multiplicative) / Division

• 乘法/除法使用 1 + Sum(Mods - 1)——两个 +50% 的乘数等于 +100%，而不是 +125%

Ability 生命周期

GiveAbility() -> TryActivateAbility() -> CanActivateAbility()
  -> ActivateAbility() [override this] -> CommitAbility() [apply cost/cooldown]
  -> ... do work (AbilityTasks) ... -> EndAbility()

**四种激活方式：**显式句柄、GameplayEvent、GameplayEffect Tag、输入代码。

实例化策略：

• InstancedPerActor——推荐的默认选项；每个 Actor 使用一个可复用实例
• InstancedPerExecution——每次激活都创建新实例；最简单，但开销最大
• NonInstanced——使用 CDO；性能最佳，仅限 C++，不支持状态/委托/RPC

网络与预测

有关复制模式、预测详情和多人游戏模式，请参阅 references/networking.md。

网络执行策略： LocalPredicted、LocalOnly、ServerOnly、ServerInitiated。

关键规则：

• ASC 会向所有客户端复制属性和标签，但不会复制技能/效果（以优化带宽）
• 非即时 GE 支持预测回滚；即时 GE（伤害）不支持
• Cue 使用不可靠复制——仅用于外观效果，绝不可用于游戏逻辑
• ASC 的所属 Actor 必须由本地控制，远程激活才能生效
• 对于基于 PlayerState 的 ASC：玩家使用 Mixed 复制模式，AI 使用 Minimal 复制模式

常见模式与陷阱

有关实现方案和已知问题，请参阅 references/patterns-and-pitfalls.md。

关键陷阱：

• PreAttributeChange 中的钳制不会永久更改修饰符——应改为在 PostGameplayEffectExecute 中钳制 BaseValue
• Server Respects Remote Ability Cancellation 带来的麻烦得不偿失——请将其禁用
• GameplayAbility 上的 Replication Policy 名称容易误导——不要使用它
• PlayerState 的 NetUpdateFrequency 默认值过低——请提高该值，或启用 Adaptive Network Update Frequency
• 在运行时移除 AttributeSet 可能导致客户端崩溃
• 动画蒙太奇必须使用 PlayMontageAndWait AbilityTask，而不是直接调用 PlayMontage，才能进行复制