vault backup: 2026-05-31 15:35:41

07-Other/AI/AI Agent/UnrealEngine/RPGGameplayAbility重构/Lyra系统学习指南.md

@@ -0,0 +1,656 @@
+---
+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。