附录A 版本演进与迁移

目标：准确了解 GAS 的版本脉络与 UE4→UE5 迁移要点，避免被过时/臆造的版本信息误导。

A.1 版本时间线（准确版）

注意：GAS 在 UE5 中仍是插件（Engine/Plugins/Runtime/GameplayAbilities），只是随引擎发行、无需单独安装。"移入引擎核心、不再需要 Plugin"的说法不准确。使用 = 加模块依赖即可。

A.2 UE4 → UE5 迁移要点

1. 全局初始化

// UE4（4.24+）必做：
UAssetManager::StartInitialLoading()
{
    UAbilitySystemGlobals::Get().InitGlobalData();
}

// UE 5.3+：引擎自动调用，这段可以移除（留着也不报错，但没必要）

2. 输入系统迁移

• UE4 默认 Input 系统 → UE5 Enhanced Input；
• 蓝图旧 Input 节点（Pressed/Released）替换为 InputAction + AbilityLocalInputPressed 接线（第 06 章）；
• Lyra 项目提供成熟参考（UGameplayAbility + Enhanced Input 绑定模板）。

3. API / 宏变化

4. 项目设置差异

• GameplayTags Fast Replication：UE5 在项目设置 → GameplayTags 开启，需保证两端标签列表一致；
• 默认 ReplicationMode：UE5 仍默认 Full，记得在初始化时设 Mixed/Minimal。

A.3 引擎源码位置（供查证）

Engine/Plugins/Runtime/GameplayAbilities/Source/
├── GameplayAbilities/        # ASC、GA、GE、Execution 等
│   ├── Public/AbilitySystemComponent.h
│   ├── Public/GameplayAbility.h
│   ├── Public/GameplayEffect.h
│   ├── Public/GameplayEffectAggregator.h   # 聚合公式
│   └── Public/GameplayCueManager.h
├── GameplayTasks/            # AbilityTask 底层
└── GameplayTags/             # 标签系统

遇到不确定的 API，直接查头文件比任何二手资料都可靠。

A.4 如何判断资料是否可信

A.5 UE 5.5：Gameplay Effect Components（GE 组件化架构）

🔴 高级知识 | 适用版本：UE 5.5+

UE 5.5 引入 Gameplay Effect Components，把原本集中在 UGameplayEffect 单体类中的功能拆分为可插拔组件。这是 GAS 架构的重要演进。

设计动机：原 UGameplayEffect 是庞大单体类，Modifier/Stacking/Tag/Cue 全硬编码在一起；新架构按需组合功能，更灵活易扩展。

核心变化：

• 新增 UGameplayEffectComponent 基类；
• GE 各项功能拆为独立组件；
• 配置从单一类属性变为组件列表。

迁移建议：新项目可用 GE Components 架构；存量项目旧架构向后兼容；关注标记 DEPRECATED 的属性。

同时注意：UE 5.5 起大量 UPROPERTY(config) 标记为 DEPRECATED，配置迁移到新配置系统——升级后检查 DefaultGame.ini 中 AbilitySystemGlobals / GameplayCueManager 相关配置是否仍有效。

A.6 Lyra 项目的 GAS 最佳实践

分层 GA 设计模式

Lyra 用三层抽象的 GameplayAbility：

UGameplayAbility（引擎基类）
  └── ULyraGameplayAbility（Lyra 通用层）
        ├── GA_WeaponFire（射击能力）
        ├── GA_MeleeAttack（近战能力）
        └── GA_Dodge（闪避能力）

Lyra 通用层封装：统一激活/结束逻辑、通用输入处理、标准化 Cost/Cooldown、能力集管理。

设计启示：不要直接继承 UGameplayAbility 写具体能力——先创建项目自己的中间层基类，封装通用逻辑。每个游戏框架层（武器系统、移动系统）有自己的 GA 子类。

AbilitySet 的 Lyra 实践

UCLASS()
class ULyraAbilitySet : public UPrimaryDataAsset
{
    UPROPERTY(EditDefaultsOnly, Category = "Abilities")
    TArray<FLyraAbilitySet_GameplayAbility> GrantedGameplayAbilities;
    UPROPERTY(EditDefaultsOnly, Category = "Effects")
    TArray<FLyraAbilitySet_GameplayEffect> GrantedGameplayEffects;
    UPROPERTY(EditDefaultsOnly, Category = "Attributes")
    TArray<FLyraAbilitySet_AttributeSet> GrantedAttributes;
};

关键设计点：AbilitySet 不只含能力，还含效果与属性集；用 FPrimaryDataAsset 支持资源管理与异步加载；每个角色/武器配一个 AbilitySet，简化初始化。

Game Feature 与 GAS 的模块化

GameFeatures/
├── ShooterCore/        # 核心射击能力
├── ShooterMaps/        # 地图相关能力
└── CustomFeature/      # 自定义能力（可热插拔）

• 能力按功能模块分组，运行时动态加载/卸载；
• Game Feature Action 激活时授予 GA/GE/AttributeSet，卸载自动清理；
• 适合 DLC、赛季内容更新、不同游戏模式组合不同能力集。

A.7 Enhanced Input 与 GAS 集成

方式一：传统枚举绑定（GAS 内置）

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

方式二：InputAction + Tag 映射（推荐，更灵活）

USTRUCT(BlueprintType)
struct FAbilityInputMapping
{
    UPROPERTY(EditAnywhere) UInputAction* InputAction;
    UPROPERTY(EditAnywhere, Meta = (Categories = "Input")) FGameplayTag InputTag;
};

void AMyCharacter::SetupPlayerInput(UInputComponent* PlayerInputComponent)
{
    for (const FAbilityInputMapping& Mapping : InputMappings)
    {
        BindAction(Mapping.InputAction, ETriggerEvent::Started,
            [this, Tag = Mapping.InputTag]()
            { AbilitySystemComponent->TryActivateAbilitiesByTag(FGameplayTagContainer(Tag)); });
    }
}

优势：输入和能力通过 Tag 解耦、支持运行时重新绑定、更灵活触发条件（Started/Ongoing/Completed）。

A.8 GAS 架构决策速查表

ASC 放在哪里？

GE 持续类型选择

MMC vs ExecCalc 选择

实例化策略选择

复制模式选择

A.9 GAS 常见设计模式总结

模式 1：伤害流水线

攻击者 GA → 创建 GE Spec (SetByCaller: Damage=50)
  → 投射物携带 GE Spec
    → 命中目标
      → ExecCalc: 读 Damage, 捕获目标 Armor, 计算减伤
        → PostGameplayEffectExecute: 扣 Health, 判死亡
          → GameplayCue: 命中特效

模式 2：Buff/Debuff 系统

Duration GE + Stacking (Aggregate by Target)
  + Granted Tags: State.Buff.AttackUp
  + Modifier: Attack, Add, +10 per stack
  + GameplayCue: 循环光环特效 (GameplayCueNotify_Actor)

模式 3：冷却共享

多个 GA 共用一个 Cooldown GE
  + 每个 GA 有自己的 CooldownTag (Ability.Skill1.Cooldown)
  + Override ApplyCooldown() 注入 CooldownTag
  + 通过 CooldownTag 查询冷却时间

模式 4：被动能力

GA: InstancedPerActor, ServerOnly
  + bActivateAbilityOnGranted = true
  + OnAvatarSet() 中自动激活
  + 使用 AbilityTask 监听事件
  + Infinite GE 持续生效

模式 5：充能技能

GA: LocalPredicted
  + WaitInputRelease AT: 等待松开按键
  + 计算充能时间
  + SetByCaller 传递充能比例到 GE Spec
  + 伤害 = 基础伤害 × 充能比例

A.10 GAS 学习资源汇总

官方：Epic 官方 GAS 文档、Lyra 示例项目、Action RPG 示例项目。 社区：tranek/GASDocumentation（最全社区文档）、tranek/GASShooter（射击高级示例）、Unreal Slackers Discord、Dave Ratti Q&A。 源码：Engine/Plugins/Runtime/GameplayAbilities/，重点文件 GameplayPrediction.h、GameplayAbility.h、AbilitySystemComponent.h、GameplayEffectAggregator.h。

下一章：附录B 术语与 API 速查