--- tags: - Lyra - UE5 - GAS - 学习笔记 - GameFeatures created: 2026-05-31 --- # Lyra Starter Game 系统学习指南 > 从零开始理解 Lyra 的逻辑主干、GameModule vs GameFeature、以及如何迭代开发 --- ## 一、Lyra 整体逻辑架构 — 游戏从启动到运行的全貌 学 Lyra 最大的障碍不是某个类复杂，而是"不知道这些类是怎么串起来的"。这一章先画地图，再看路标。 ### 1.1 架构分层：三层金字塔 ``` ┌─────────────────────────────────────────────────────────┐ │ 第三层：GameFeature │ │ ShooterCore / TopDownArena / ShooterExplorer │ │ （玩法内容：DataAsset + 蓝图 + 地图 + 少量专用 C++） │ │ 职责："这个游戏模式有什么技能？按键怎么绑？UI什么样？" │ │ 加载方式：运行时按需加载，通过 Experience 触发 │ ├─────────────────────────────────────────────────────────┤ │ 第二层：LyraGame │ │ GameModule（C++ 编译单元，启动时强制加载） │ │ （游戏框架：ASC、Ability、AttributeSet、Character、输入） │ │ 职责："提供所有 GAS 基类、GameFeatureAction 机制、 │ │ Pawn 扩展系统、Experience 管理、UI 框架" │ ├─────────────────────────────────────────────────────────┤ │ 第一层：UE5 引擎 + 插件 │ │ Engine: GameplayAbilities / EnhancedInput / GameFeatures│ │ Engine: ModularGameplay / CommonUI / GameplayMessageRouter│ │ 职责："提供 GAS 核心、输入框架、Feature 加载/卸载" │ └─────────────────────────────────────────────────────────┘ ``` **依赖方向**：GameFeature → LyraGame → Engine。上层依赖下层，永不反向。 ### 1.2 启动流程全景图：谁先动、谁跟着动 这是整个 Lyra 最重要的时序图，看懂了这张图就看懂了 Lyra 的一半： ``` ┌─ 阶段0：引擎启动 ─────────────────────────────────────────┐ │ UE5 引擎启动 │ │ → 加载 LyraGame.dll（GameModule，不可卸载） │ │ → 所有 UCLASS 注册到反射系统 │ │ → ULyraGameEngineSubsystem::Initialize() │ │ → UGameFeaturesSubsystem 初始化 │ └───────────────────────────────────────────────────────────┘ ↓ ┌─ 阶段1：进入地图 ─────────────────────────────────────────┐ │ World 创建 │ │ → GameState 创建 → ULyraExperienceManagerComponent 创建 │ │ → GameMode 创建 → 调用 ChoosePlayerStart 等 │ │ │ │ 重点：此时还没有加载任何 GameFeature。 │ │ 只有 LyraGame 的 C++ 类在内存中。 │ └───────────────────────────────────────────────────────────┘ ↓ ┌─ 阶段2：Experience 加载（最关键！）────────────────────────┐ │ GameMode::InitGame() │ │ → ExperienceManager->SetCurrentExperience(ExperienceId) │ │ → StartExperienceLoad() │ │ │ │ 2a. 加载 Experience DataAsset │ │ Experience.GameFeaturesToEnable = [ │ │ "ShooterCore", │ │ "ShooterMaps" │ │ ] │ │ │ │ 2b. 逐个加载 GameFeature Plugin │ │ UGameFeaturesSubsystem::LoadPlugin("ShooterCore") │ │ → 加载 ShooterCore.dll（如果有 C++） │ │ → 扫描 ShooterCore 的 Content 目录 │ │ → 注册其中的所有 UGameFeatureAction │ │ → 调用每个 Action 的 OnGameFeatureRegistering() │ │ │ │ 2c. 激活 GameFeature │ │ 对每个 Action 调用 OnGameFeatureActivating(): │ │ │ │ GameFeatureAction_AddInputContextMapping │ │ → 把 IMC_ShooterGame 注册到 EnhancedInput 子系统 │ │ │ │ GameFeatureAction_AddInputBinding │ │ → 把 InputData_ShooterGame_AddOns 绑定到输入系统 │ │ │ │ GameFeatureAction_AddAbilities │ │ → 向 GameFrameworkComponentManager 注册: │ │ "当 ALyraCharacter 创建时，自动给它这些技能" │ │ │ │ GameFeatureAction_AddWidgets │ │ → 注册 Shooter 专用 HUD Widget │ │ │ │ ★ 注意：这时候还没有玩家加入，只是"注册了规则" │ │ │ │ 2d. 广播 Experience 加载完成 │ │ Broadcast OnExperienceLoaded │ └───────────────────────────────────────────────────────────┘ ↓ ┌─ 阶段3：玩家加入 + Pawn 生成 ──────────────────────────────┐ │ Login → APlayerController 创建 │ │ → ALyraPlayerState 创建（这是关键对象！） │ │ → 构造函数: ASC = CreateDefaultSubobject (ASC 诞生) │ │ → 构造函数: HealthSet = CreateDefaultSubobject │ │ → 构造函数: CombatSet = CreateDefaultSubobject │ │ → PostInitializeComponents: │ │ → ASC->InitAbilityActorInfo(this, GetPawn()) │ │ （Owner=PlayerState, Avatar=暂无/旧Pawn） │ │ → 注册 OnExperienceLoaded 回调 │ │ │ │ → 如果 Experience 已加载： │ │ → OnExperienceLoaded() │ │ → GameMode::GetPawnDataForController() │ │ → SetPawnData(PawnData) │ │ → 遍历 PawnData->AbilitySets │ │ → AbilitySet->GiveToAbilitySystem(ASC) ← 技能注入！│ │ → Broadcast NAME_LyraAbilityReady │ │ → 触发 GameFeatureAction_AddAbilities 的 │ │ HandleActorExtension（为 PlayerState 注入 │ │ GameFeature 专属技能） │ │ │ │ → RestartPlayer() │ │ → Pawn 创建 (ALyraCharacter) │ │ → Possess(Pawn) │ │ → ULyraHeroComponent::OnPawnReadyToInitialize() │ │ → PawnExtComp->InitializeAbilitySystem( │ │ PS->GetASC(), PS) ← ASC 桥接到新 Pawn！ │ │ → ASC->InitAbilityActorInfo(PlayerState, Pawn) │ │ （Owner=PlayerState, Avatar=新Pawn） │ │ → 设置 TagRelationshipMapping │ │ → Broadcast OnAbilitySystemInitialized │ │ │ │ → PlayerController 绑定输入 │ │ → LyraHeroComponent 绑定 EnhancedInput │ │ → InputConfig 映射 InputAction → InputTag │ │ → 玩家可以操作了 │ └───────────────────────────────────────────────────────────┘ ``` **核心理解**：三个阶段是**异步链式触发**的，不是硬编码顺序。机制是： - Experience 加载完 → 广播 `OnExperienceLoaded` → PlayerState 收到 → 执行 SetPawnData - Pawn 生成 + 输入绑定 → 广播 `InitState.GameplayReady` → 所有组件就绪 ### 1.3 各模块入口速查：从哪里开始读 按关注领域,给出每个模块的**入口文件**和**为什么从这里开始**： | 关注领域 | 入口文件 | 理由 | |----------|----------|------| | **整个游戏的启动** | `LyraExperienceManagerComponent.cpp` | `SetCurrentExperience()` 的 `StartExperienceLoad()` 是唯一入口 | | **Experience 是什么** | `LyraExperienceDefinition.h` | 只有 3 个字段（GameFeaturesToEnable, DefaultPawnData, Actions） | | **GameFeature 如何注入能力** | `GameFeatureAction_AddAbilities.cpp` | `AddToWorld()` → `HandleActorExtension()` → `AddActorAbilities()` 完整链路 | | **ASC 桥接（Pawn 切换）** | `LyraPawnExtensionComponent.cpp` | `InitializeAbilitySystem()` 和 `UninitializeAbilitySystem()` 是核心 | | **Pawn 和 PlayerState 如何粘合** | `LyraHeroComponent.cpp` | `OnPawnReadyToInitialize()` 中的 `InitializeAbilitySystem(PS->GetASC(), PS)` | | **输入如何变成技能** | `LyraAbilitySystemComponent.h` | 搜索 `AbilityInputTagPressed` + `ProcessAbilityInput` | | **技能从哪来** | `LyraAbilitySet.cpp` | `GiveToAbilitySystem()` 和 `TakeFromAbilitySystem()` | | **属性怎么设计** | `LyraHealthSet.h` | 先学 HealthSet（4属性），再学 CombatSet（2属性） | | **伤害怎么算** | `LyraDamageExecution.cpp` | `CalculateDamage_Implementation()` 和 `Capture` 机制 | | **网络怎么同步** | `LyraPlayerState.cpp` | `GetLifetimeReplicatedProps()` 看复制了什么 | | **AI/Bot 的 ASC** | `LyraCharacterWithAbilities.h` | 独立 ASC 的自给自足模式 | | **GameFeature 测试怎么测** | `ShooterTests/` | 看自动化测试如何验证 Feature 加载 | | **UI 框架** | `GameFeatureAction_AddWidgets.cpp` | 看 Widget 如何通过 GameFeature 注入 | | **游戏阶段** | `LyraGamePhaseSubsystem.cpp` | 看 WorldSubsystem 如何管理阶段状态 | ### 1.4 LyraGame 模块内部组织 `Source/LyraGame/` 目录按功能分为 14 个文件夹。你不必全部吃透，按关注度分三级： **红色必读**（GAS + Gameplay 核心）： ``` AbilitySystem/ ├── LyraAbilitySystemComponent.h/cpp ← ASC 扩展（输入缓冲 + ActivationGroup） ├── LyraAbilitySystemGlobals.h/cpp ← 全局 GAS 配置 ├── LyraGameplayEffectContext.h/cpp ← 扩展 EffectContext ├── LyraAbilitySet.h/cpp ← 技能打包 DataAsset ├── LyraAbilityTagRelationshipMapping.h/cpp ← Tag 互斥关系 ├── LyraGlobalAbilitySystem.h/cpp ← 全局技能分发 WorldSubsystem ├── Abilities/ │ ├── LyraGameplayAbility.h/cpp ← 技能基类 │ └── LyraAbilityCost*.h/cpp ← 可扩展 Cost 系统 ├── Attributes/ │ ├── LyraAttributeSet.h/cpp ← 属性集基类 │ ├── LyraHealthSet.h/cpp ← 生命值+Meta属性管线 │ └── LyraCombatSet.h/cpp ← 战斗属性 ├── Executions/ │ ├── LyraDamageExecution.h/cpp ← 伤害计算 │ └── LyraHealExecution.h/cpp ← 治疗计算 └── Phases/ ├── LyraGamePhaseAbility.h/cpp ← 游戏阶段 Ability └── LyraGamePhaseSubsystem.h/cpp ← 阶段管理器 Character/ ├── LyraCharacter.h/cpp ← Character 基类（委托 ASC） ├── LyraCharacterWithAbilities.h/cpp ← AI/Bot 独立 ASC 版本 ├── LyraHeroComponent.h/cpp ← 玩家 Hero 粘合层 ★ 关键 ├── LyraPawnExtensionComponent.h/cpp ← ASC 桥接层 ★ 关键 └── LyraPawnData.h ← Pawn 配置 DataAsset Player/ ├── LyraPlayerState.h/cpp ← ASC 持有者 ★ 关键 └── LyraPlayerController.h/cpp ← 玩家控制器 ``` **橙色按需**（输入/GameFeature/UI）： ``` Input/ ├── LyraInputConfig.h ← InputTag 映射 DataAsset └── LyraInputModifiers.h/cpp ← 输入修饰器 GameFeatures/ ├── GameFeatureAction_AddAbilities.h/cpp ← 能力注入 ★ 关键 ├── GameFeatureAction_AddInputBinding.h/cpp ├── GameFeatureAction_AddInputContextMapping.h/cpp ├── GameFeatureAction_AddWidgets.cpp ├── GameFeatureAction_WorldActionBase.h/cpp ← Action 基类 └── GameFeatureAction_SplitscreenConfig.cpp GameModes/ ├── LyraExperienceDefinition.h ← Experience DataAsset ★ 关键 ├── LyraExperienceManagerComponent.h/cpp ← Experience 加载器 ★ 关键 └── LyraGameMode.h/cpp ← GameMode 基类 UI/ ├── LyraHUD.h/cpp ← HUD 布局 └── LyraHUDLayout.h/cpp ← Widget 堆栈管理 ``` **灰色可选**（辅助系统）： ``` System/ ← GameplayTagStack、LyraGameData、Significance 等 Teams/ ← 队伍系统 Messages/ ← VerbMessage 消息系统 Weapons/ ← 武器 Actor + 武器状态机 Equipment/ ← 装备管理器 + 装备实例 Camera/ ← 摄像机模式 Performance/ ← 性能统计 Interaction/ ← 交互接口 Cosmetics/ ← 外观系统（皮肤/角色模型） ``` ### 1.5 初始化状态机（InitState） Lyra 不用 BeginPlay 的硬编码顺序，而是通过 `IGameFrameworkInitStateInterface` 实现状态机： ``` Spawned ← BeginPlay 后立即进入 ↓ CanChangeInitState(DataAvailable) ? ↓ Yes DataAvailable ← 组件数据已加载（PawnData Replicated） ↓ CanChangeInitState(DataInitialized) ? → "PawnExtensionComponent 说 ASC 初始化完成了？" → "HeroComponent 说输入准备好了？" ↓ Yes DataInitialized ← 所有组件初始化完成 ↓ CanChangeInitState(GameplayReady) ? → "所有 Feature Component 准备好了？" ↓ Yes GameplayReady ← 可以开始游戏了 ``` 这个机制的关键在于 `UGameFrameworkComponentManager`——它是来自 `ModularGameplay` 插件的全局注册中心。每个组件通过 `AddExtensionHandler` 注册自己关心哪些 Actor 类型，当该类 Actor 创建或状态变化时自动通知。 --- ## 零、先搞清楚：GameModule 和 GameFeature 到底有什么区别 这是最容易困惑的地方。一句话： **GameModule（.Build.cs）是 C++ 的编译单元。GameFeature（.uplugin + UGameFeatureAction）是游戏内容的加载/卸载单元。** | | GameModule | GameFeature Plugin | |---|---|---| | **本质** | C++ 编译单元，定义链接依赖 | 游戏功能的加载/卸载容器 | | **粒度** | 大（整个 .dll）| 小（一个玩法模式） | | **加载时机** | 引擎启动时强制加载 | 运行时按需加载（通过 Experience） | | **卸载** | 不可卸载 | 可以卸载（切换模式时） | | **包含什么** | C++ 类（ASC、AttributeSet、Character） | DataAsset + 蓝图 + 少量 C++ + 地图 | | **依赖方向** | GameFeature 依赖 GameModule | 不反向 | **Lyra 具体例子**： ``` LyraGame（GameModule — 编译时加载） │ 定义基础设施：ULyraAbilitySystemComponent、ULyraGameplayAbility、 │ ULyraHealthSet、ULyraAbilitySet、UGameFeatureAction_AddAbilities... │ 这些东西永远在内存中，不可卸载。 │ ├── ShooterCore（GameFeature Plugin — 运行时加载） │ │ 没有 C++ 基类定义，只有： │ │ - AbilitySet_ShooterHero（DataAsset：有哪些技能） │ │ - IMC_ShooterGame（InputMappingContext：按键绑定） │ │ - InputData_ShooterGame_AddOns（InputConfig：按键→Tag映射） │ │ - UAimAssistInputModifier（少量专用 C++） │ │ - 武器蓝图、地图、Experience 定义 │ │ │ │ 加载时：通过 UGameFeatureAction_AddAbilities 把 AbilitySet │ │ 里的技能"注入"到 PlayerState 的 ASC 上。 │ │ 卸载时：全部回收。 │ └── TopDownArena（GameFeature Plugin — 运行时加载） 完全不同的玩法模式，不同 AbilitySet、不同 InputConfig。 可以和 ShooterCore 共存或切换，互不依赖。 ``` **核心理解**：ShooterCore 自己**没有定义任何新的 GAS 类**。它只是"使用" LyraGame 中已经定义好的 `ULyraAbilitySet`、`ULyraInputConfig`、`GameFeatureAction` 这些基础设施，通过**数据配置**（DataAsset + 蓝图）来组织射击游戏的特定内容。 --- ## 二、逻辑主干 — Lyra 的 5 个核心流程 学 Lyra 最重要的不是记类名，而是理解这 5 个流程。每个流程是一条"主干链路"，挂载着相关的"枝叶类"。 ### 流程 1：游戏启动 → Experience 加载 ``` 服务器进入地图 → ULyraExperienceManagerComponent::SetCurrentExperience(ExperienceId) → StartExperienceLoad() → 加载 Experience 对应的 PrimaryAsset → 遍历 Experience.GameFeaturesToEnable → UGameFeaturesSubsystem::LoadPlugin(每个Feature) → OnGameFeaturePluginLoadComplete() ← 等所有Feature加载完 → OnExperienceFullLoadCompleted() → 执行 Experience.Actions（UGameFeatureAction 列表） → GameFeatureAction_AddAbilities::OnGameFeatureActivating() → GameFeatureAction_AddInputContextMapping::OnGameFeatureActivating() → GameFeatureAction_AddInputBinding::OnGameFeatureActivating() → Broadcast OnExperienceLoaded → PlayerState 开始授权技能 ``` **关键文件**： - `LyraExperienceManagerComponent.h/cpp` — 整个游戏的启动器 - `LyraExperienceDefinition.h` — 纯 DataAsset，定义了"启用哪些Feature + 用哪个 Pawn + 哪些 Action" - `GameFeatureAction_AddAbilities.h/cpp` — 把 Ability/Attribute/AbilitySet 注入 ASC **学习顺序**：先看懂 `LyraExperienceDefinition`（只有3个字段），再看 `LyraExperienceManagerComponent` 的状态机（Unloaded → Loading → LoadingGameFeatures → ExecutingActions → Loaded），最后看 `GameFeatureAction_AddAbilities::AddToWorld`。 ### 流程 2：PlayerState 初始化 → 技能授权 ``` ALyraPlayerState::PostInitializeComponents() → ASC->InitAbilityActorInfo(this, GetPawn()) ← Owner=PlayerState, Avatar=Pawn → 注册 OnExperienceLoaded 回调 ↓ Experience 加载完成 → OnExperienceLoaded() → SetPawnData(PawnData) → 遍历 PawnData->AbilitySets → AbilitySet->GiveToAbilitySystem(ASC) → 逐个 GiveAbility（注入 InputTag 到 DynamicSpecSourceTags） → 逐个 ApplyGameplayEffect（初始化属性） → 逐个 AddAttributeSetSubobject → Broadcast NAME_LyraAbilityReady → 触发 GameFeatureAction_AddAbilities::HandleActorExtension 为所有已注册ActorClass授予GameFeature专属能力 ``` **关键文件**： - `LyraPlayerState.h/cpp` — 拥有 ASC，是"数据的主人" - `LyraPawnData.h` — DataAsset，定义"这个Pawn类型用哪些 AbilitySet + 哪个 TagRelationshipMapping" - `LyraAbilitySet.h/cpp` — 不可变 DataAsset，包含 Abilities + Effects + AttributeSets **学习顺序**：`LyraAbilitySet` 的结构 → `GiveToAbilitySystem` 函数 → `LyraPawnData` → `LyraPlayerState::SetPawnData` ### 流程 3：Pawn 生成 → ASC 桥接 ``` GameMode::RestartPlayer() → Pawn 被创建 → Possess(Pawn) → ULyraHeroComponent::OnPawnReadyToInitialize() → PawnExtComp->InitializeAbilitySystem(PS->GetASC(), PS) ↓ ULyraPawnExtensionComponent::InitializeAbilitySystem(InASC, InOwnerActor) 1. 如果已有 ASC → UninitializeAbilitySystem（清理旧绑定） 2. 如果 ASC 已有其他 Avatar → 踢掉旧的 3. AbilitySystemComponent = InASC ← 瞬态缓存，不拥有 4. InASC->InitAbilityActorInfo(InOwnerActor, Pawn) 5. 设置 ASC 的 TagRelationshipMapping（来自 PawnData） 6. Broadcast OnAbilitySystemInitialized → ALyraCharacter::OnAbilitySystemInitialized() → HealthComponent->InitializeWithAbilitySystem() → InitializeGameplayTags() ``` **关键文件**： - `LyraHeroComponent.h/cpp` — "粘合层"，触发 ASC 初始化 - `LyraPawnExtensionComponent.h/cpp` — "桥接层"，热插拔管理 - `LyraCharacter.h/cpp` — Character 本身不持有 ASC，通过 PawnExtComp 委托 **核心理解**：Character 的生命周期是短暂的（死亡→重生）。ASC 不能放在 Character 上——否则死亡时数据全丢。PawnExtensionComponent 确保"新 Pawn 连接旧 ASC"。 ### 流程 4：输入处理 → Ability 激活 ``` 玩家按左键 → EnhancedInput 触发 UInputAction → ULyraHeroComponent 收到 InputAction → 查 ULyraInputConfig 找到对应的 InputTag → ASC->AbilityInputTagPressed(InputTag) 遍历 GetActivatableAbilities(): 匹配 DynamicSpecSourceTags.HasTagExact(InputTag) → InputPressedSpecHandles.AddUnique(Handle) ↓ 每帧 Tick → ASC->ProcessAbilityInput(DeltaTime, bGamePaused) 1. 检查 InputBlocked Tag（如果被阻断，清空全部缓冲） 2. Held handles: WhileInputActive → TryActivateAbility 3. Pressed handles: OnInputTriggered → 设置 InputPressed → TryActivateAbility 4. 统一批量激活所有待激活 Ability 5. Released handles: 设置 InputPressed=false → InputReleased 事件 6. 清空缓存 ``` **关键文件**： - `LyraInputConfig.h` — InputAction ↔ InputTag 映射表 - `LyraAbilitySystemComponent.h/cpp` — `AbilityInputTagPressed/Released/Held` + `ProcessAbilityInput` - `LyraHeroComponent.h/cpp` — 输入事件入口 **核心理解**：三层解耦——硬件按键(UInputAction) → 逻辑输入(InputTag) → 技能(AbilitySpec.DynamicSpecSourceTags)。策划可以在任意一层修改映射。 ### 流程 5：网络复制 ``` 服务端: ASC 在 PlayerState 上（Replicated） 属性变化 → ReplicatedUsing → OnRep 回调 AbilitySpec 通过 ASC 复制 GE 通过 Mixed 模式复制 客户端预测: ULyraGameplayAbility 默认 NetExecutionPolicy = LocalPredicted TryActivateAbility → 客户端先执行 → 服务器确认 → ScopedPredictionKey 如果服务器拒绝 → 客户端回滚 属性复制细节: HealthSet: COND_OwnerOnly（仅复制给Owner，减少带宽） CombatSet: COND_OwnerOnly Mixed 复制模式: Minimal 用于纯服务器属性，Mixed 用于可修改属性 ``` **关键文件**： - `LyraPlayerState.h` — ASC 是 Replicated 组件 - `LyraGameplayAbility.h` — ActivationPolicy/Group 控制预测行为 - `LyraHealthSet.h/cpp` — OnRep_Health 客户端通知 --- ## 三、学习路径 — 从哪里开始 ### 第 1 天：理解"三个 Actor 各管什么" 只读这些文件，不要跳： 1. `LyraPlayerState.h`（60行）— ASC 在哪？AttributeSet 在哪？什么时候 InitAbilityActorInfo？ 2. `LyraCharacter.h`（`GetAbilitySystemComponent` 函数）— Character 如何获取 ASC？ 3. `LyraPawnExtensionComponent.h`（100行）— InitializeAbilitySystem / UninitializeAbilitySystem / HandleControllerChanged **目标回答三个问题**： - 谁的组件拥有 ASC？（PlayerState） - 谁调用 InitAbilityActorInfo？（PawnExtensionComponent） - 谁是 Owner，谁是 Avatar？（PlayerState=Owner, Pawn=Avatar） ### 第 2 天：理解"技能从哪来" 1. `LyraAbilitySet.h` — 三个 TArray（Ability / GE / AttributeSet） 2. `LyraAbilitySet.cpp` — `GiveToAbilitySystem` 和 `TakeFromAbilitySystem` 3. `LyraPawnData.h` — 一个 Pawn 类型用哪些 AbilitySet 4. `LyraPlayerState.cpp` — `SetPawnData` 函数 **目标**：画一张图——AbilitySet → PawnData → PlayerState → ASC → AbilitySpec ### 第 3 天：理解"输入怎么变成技能激活" 1. `LyraInputConfig.h` — InputAction ↔ InputTag 映射结构 2. `LyraAbilitySystemComponent.h` — `AbilityInputTagPressed` + `ProcessAbilityInput` 3. `LyraGameplayAbility.h` — ActivationPolicy + ActivationGroup 枚举 **目标**：画一张图——按键→InputAction→InputTag→DynamicSpecSourceTags→ProcessAbilityInput→TryActivateAbility ### 第 4 天：理解 GameFeature 的"注入"机制 1. `LyraExperienceDefinition.h` — GameFeaturesToEnable + Actions 2. `GameFeatureAction_AddAbilities.h/cpp` — 完整的激活/停用流程 3. `GameFeatureAction_WorldActionBase.h/cpp` — 基类抽象 **目标**：理解 GameFeatureAction 的扩展机制——它本质上是一个Observer模式：监听特定ActorClass的创建/销毁，自动注入能力。 ### 第 5 天：理解"初始化顺序" 不看代码，先画 Lyra 的 InitState 状态机： ``` Spawned → DataAvailable → DataInitialized → GameplayReady ``` 每个组件通过 `IGameFrameworkInitStateInterface` 实现自己对这些状态转换的判断。 然后跟踪 `LyraHeroComponent::CheckDefaultInitialization` 的逻辑。 ### 第 6-7 天：综合阅读 LyraExperience 和 GameFeatureAction_AddInputContextMapping 完整跟踪从"服务器选择地图"到"玩家按键激活技能"的全链路。 --- ## 四、Lyra 的分支逻辑 — 哪些是主干、哪些是枝叶 ### 核心主干（必须理解） ``` LyraExperienceDefinition ← 游戏"模式"的定义 └── LyraExperienceManagerComponent ← 加载/卸载管理器 LyraPlayerState ← 数据持有者（ASC + AttributeSet + PawnData） └── LyraAbilitySet ← 技能打包授权 └── LyraPawnData ← Pawn 的配置数据 LyraPawnExtensionComponent ← ASC 桥接层 └── LyraCharacter ← 通过 PawnExtComp 间接获取 ASC └── LyraHeroComponent ← 玩家专用的粘合层 LyraAbilitySystemComponent ← ASC 扩展（输入缓冲/ActivationGroup/ProcessAbilityInput） └── LyraGameplayAbility ← Ability 基类（ActivationPolicy/Group/Cost） GameFeatureAction_AddAbilities ← GameFeature 注入能力的关键 Action └── GameFeatureAction_WorldActionBase ← 通用 Action 基类 ``` ### 枝叶（按需学习） ``` LyraHealthSet / LyraCombatSet ← 战斗属性→先学 HealthSet 的 Meta 属性模式 LyraDamageExecution ← 伤害计算→在你需要自定义伤害公式时学 LyraAbilityCost_* ← 消耗系统→在你需要特殊消耗（弹药/能量）时学 GlobalAbilitySystem ← 全局技能分发→在你需要全局Buff时学 LyraGamePhaseSubsystem ← 游戏阶段→在你需要"热身/进行/结束"阶段时学 GameplayTagStack ← Tag栈计数→在你需要弹药/消耗品时学 LyraEquipmentManagerComponent ← 装备系统→在你需要武器/装备切换时学 LyraGameplayCueManager ← Cue加载管理→在你需要大量特效时学 ShooterCore/* ← 射击游戏示范→在你需要参考 Feature 怎么做时学 TopDownArena/* ← 俯视角示范→同上 ``` --- ## 五、如何迭代增加新功能 ### 场景 1：新增一个技能（最简） 只需要编辑 DataAsset，不需要写 C++： 1. 创建 `GA_MyAbility` 蓝图，父类选 `LyraGameplayAbility` 2. 配置 ActivationPolicy / ActivationGroup 3. 创建 `GE_MyDamage`、`GE_MyCooldown`、`GE_MyCost` 4. 在 `AbilitySet_ShooterHero` 中新增一条 `GrantedGameplayAbilities`，配好 InputTag 5. 如果新增了按键，在 `InputData_ShooterGame_AddOns` 中新增 InputAction→InputTag 映射 6. 如果需要阻挡其他技能，在 `TagRelationshipMapping` 中配置 ### 场景 2：新增一个游戏模式（如 FighterGame） 1. 创建新的 GameFeature 插件 `FighterCore`（参考 ShooterCore 的 .uplugin 结构） 2. 创建 `AbilitySet_FighterHero`，放入格斗技能 3. 创建 `IMC_FighterGame`（InputMappingContext） 4. 创建 `InputData_FighterGame`（InputConfig） 5. 创建 `B_FighterGame.uasset`（Experience 定义），配置： - `GameFeaturesToEnable = ["FighterCore"]` - `Actions = [GameFeatureAction_AddAbilities, GameFeatureAction_AddInputBinding...]` 6. 如需专用 C++ 组件（连击管理器、输入缓冲），加在 `FighterCore/Source` 中 7. 选择地图时指定这个 Experience ### 场景 3：扩展现有的 GAS 基础设施 1. **新增属性**：新建 AttributeSet 类（如 `URPGStaminaSet`），在 `LyraPlayerState` 构造函数中 `CreateDefaultSubobject` 2. **新增 AbilityTask**：继承 `UAbilityTask`，放在 LyraGame 模块中 3. **新增 GameFeatureAction**：继承 `UGameFeatureAction_WorldActionBase`，重写 `AddToWorld` 4. **新增 AbilityCost 类型**：继承 `ULyraAbilityCost`（如果是 LyraGame 级别）或在 Feature 中自定义 ### 场景 4：修改初始化顺序 Lyra 的 InitState 是通过 `IGameFrameworkInitStateInterface` 实现的。不要直接改 BeginPlay 顺序，而是： 1. 你的组件实现 `IGameFrameworkInitStateInterface` 2. 在 `CanChangeInitState` 中声明"我要等到哪些条件才能进入下一个状态" 3. 在 `HandleChangeInitState` 中执行状态转换逻辑 4. 其他组件通过 `BindOnActorInitStateChanged` 监听你的状态变化 --- ## 六、最重要的 10 个概念速查 | 概念 | 一句话解释 | 在哪里 | |------|-----------|--------| | **Experience** | 游戏"模式"的配置清单：启用哪些Feature、用哪个Pawn | `LyraExperienceDefinition` | | **AbilitySet** | 把 Ability + GE + AttributeSet 打包成一个 DataAsset | `LyraAbilitySet` | | **PawnData** | 一个 Pawn 类型的配置：用哪些 AbilitySet、用什么 TagRelationshipMapping | `LyraPawnData` | | **PawnExtensionComponent** | ASC 的"插座"，Pawn 通过它连接/断开 ASC | `LyraPawnExtensionComponent` | | **GameFeatureAction** | Observer 模式：监听 Actor 创建→自动注入能力 | `GameFeatureAction_AddAbilities` | | **InputTag** | EnhancedInput 和 Ability 之间的"中间语言" | `LyraInputConfig` + `DynamicSpecSourceTags` | | **ActivationGroup** | 技能激活后的"排他性"规则（Independent / Replaceable / Blocking） | `LyraGameplayAbility` | | **ProcessAbilityInput** | 帧级输入缓冲，批量激活→避免时序竞争 | `LyraAbilitySystemComponent` | | **InitState** | 组件的初始化状态机：Spawned→DataAvailable→DataInitialized→GameplayReady | `IGameFrameworkInitStateInterface` | | **VerbMessage** | 松散耦合的事件广播（谁受到伤害→UI/音频/统计各管各的） | `FLyraVerbMessage` + `UGameplayMessageSubsystem` | --- ## 七、调试技巧 ### 跟踪 Experience 加载过程 在 `ULyraExperienceManagerComponent::OnExperienceFullLoadCompleted` 打断点。这个函数被调用时，所有 Feature 已加载、所有 Action 已执行。 ### 跟踪 ASC 桥接 在 `ULyraPawnExtensionComponent::InitializeAbilitySystem` 打断点。每次 ASC 被绑定到新 Pawn（重生、重连）都会触发。 ### 跟踪技能授权 在 `ULyraAbilitySet::GiveToAbilitySystem` 打断点。查看每个 Ability 的 InputTag 和 Level。 ### 跟踪输入 在 `ULyraAbilitySystemComponent::ProcessAbilityInput` 中的三个数组（Pressed/Held/Released handles）设条件断点，看当前帧哪些能力被收集了。 ### 验证 GameFeature 是否正确注入 `GameFeatureAction_AddAbilities::AddActorAbilities` 中，检查 `FindOrAddComponentForActor` 返回的 ASC 是不是你期望的那个。 --- ## 八、常见误解纠正 1. **"GameFeature 一定会被加载"** → 错。GameFeature 是按需加载的。在 Lyra 中由 Experience 触发加载。没有 Experience 引用它的 Feature 永远不会被加载。 2. **"每个 GameFeature 需要自己的 C++ 模块"** → 不必要。ShooterMaps 就是纯 Content 的 GameFeature，没有任何 C++。 3. **"AttributeSet 必须放在 PlayerState 上"** → 不必然。Lyra 的选择是因为 PlayerState 跨地图存活。但也可以放在 Character 上（如 Bot 的 `ALyraCharacterWithAbilities`）。 4. **"InitAbilityActorInfo 只能调用一次"** → 错。Lyra 在重生时会用新的 Pawn 再次调用，关键的 `UninitializeAbilitySystem` 负责清理旧绑定。 5. **"EnhancedInput 的 InputAction 直接绑定到 Ability"** → 错。Lyra 中间插入了 InputTag（GameplayTag）作为桥梁。这就是为何策划可以独立修改按键和技能映射。 6. **"PawnExtensionComponent 拥有 ASC"** → 错。它的 `AbilitySystemComponent` 成员是 `Transient`，只是一个缓存的指针。真正的所有者是 PlayerState。