# 00 · 总览与架构原则

> **所属文档集** [← 返回索引](./README.md)  
> **关联文档** 全部子文档均以本文规则为基准

---

## 目录

1. [游戏定位](#1-游戏定位)
2. [核心设计哲学](#2-核心设计哲学)
3. [命名空间规范](#3-命名空间规范)
4. [程序集定义（Assembly Definitions）](#4-程序集定义)
5. [系统依赖图](#5-系统依赖图)
6. [零耦合通信：ScriptableObject 事件频道](#6-零耦合通信scriptableobject-事件频道)
7. [数据驱动：ScriptableObject 配置资产](#7-数据驱动scriptableobject-配置资产)
8. [帧执行顺序](#8-帧执行顺序)
9. [项目目录结构](#9-项目目录结构)
10. [插件职责边界](#10-插件职责边界)
11. [功能优先级总表](#11-功能优先级总表)

---

## 1. 游戏定位

| 项目 | 内容 |
|------|------|
| **类型** | 2D 横板像素风类银河恶魔城 |
| **参考** | Hollow Knight: Silksong 核心功能集 |
| **新增机制** | 弹反系统（Parry）|
| **引擎** | Unity 2022.3 LTS |
| **渲染管线** | Universal Render Pipeline (URP) + 2D Renderer |
| **输入** | Unity Input System (New) |
| **镜头** | Cinemachine 3 |
| **像素渲染** | Pixel Perfect Camera (com.unity.2d.pixel-perfect) |

---

## 2. 核心设计哲学

### 2.1 零耦合原则

系统间**不持有彼此的直接引用**，通过以下三种机制通信：

```
┌──────────────┐     ScriptableObject 事件频道      ┌──────────────┐
│   系统 A     │ ──────────────────────────────────► │   系统 B     │
│  (发送方)    │   触发 Channel.Raise(payload)       │  (监听方)    │
└──────────────┘                                     └──────────────┘

┌──────────────┐     MMEventManager 广播             ┌──────────────┐
│   系统 A     │ ──────────────────────────────────► │   系统 C     │
│  (触发方)    │   TriggerEvent<T>(struct event)     │  (任意监听)  │
└──────────────┘                                     └──────────────┘

┌──────────────┐     UnityEvent / C# Action          ┌──────────────┐
│   系统 A     │ ──────────────────────────────────► │  同 GO 组件  │
│  (持有方)    │   Inspector 中绑定，限同一 Prefab   │  (本地回调)  │
└──────────────┘                                     └──────────────┘
```

**禁止的依赖方式**：
- `FindObjectOfType<T>()` — 运行时搜索，性能差且隐藏依赖
- `GameObject.Find()` — 同上
- 跨系统的 `[SerializeField]` 直接引用（仅允许同一 Prefab 层级内）
- 静态全局单例持有具体系统引用（`GameManager` 仅管理生命周期，不暴露子系统）

### 2.2 数据驱动原则

- 所有**可配置数值**存放在 `ScriptableObject` 资产中，不在 MonoBehaviour 中硬编码
- 策划可在 Inspector 调整数值，无需修改代码、无需重新编译
- 动画配置、战斗参数、敌人属性、弹反参数均为独立 SO 资产

### 2.3 编辑器友好原则

- 每个系统提供自定义 Inspector（`[CustomEditor]` + `CreateInspectorGUI()`，UI Toolkit 实现），折叠分组，带工具按钮
- 关键运行时状态在 Inspector 中实时可见（只读显示）
- 场景中的 HitBox / HurtBox / NavLink 等用 Gizmos 可视化
- 提供 EditorWindow 工具辅助关卡搭建（敌人配置、房间连接检查），一律使用 UI Toolkit `CreateGUI()` 实现

### 2.4 资源管理原则（Addressables）

- **统一使用 Addressable Asset System**，禁止使用 `Resources/` 文件夹和 `Resources.Load()`
- 运行时动态加载资源（Prefab、Sprite、SO、Scene）一律通过 `Addressables.LoadAssetAsync<T>` / `Addressables.InstantiateAsync`
- 场景加载通过 `Addressables.LoadSceneAsync(address, LoadSceneMode.Additive)` 而非 `SceneManager.LoadSceneAsync`
- Prefab 引用字段使用 `AssetReferenceGameObject`（或 `AssetReference<T>`），而非裸 `GameObject` 序列化引用
- 所有 Addressable 地址（Address）与 Label 在 `AddressKeys` 静态类中集中定义，禁止代码中出现魔法字符串

```csharp
// Assets/Scripts/Core/AddressKeys.cs
public static class AddressKeys
{
    // 场景
    public const string ScenePersistent = "Scene_Persistent";
    public const string SceneMainMenu   = "Scene_MainMenu";

    // 通用标签
    public const string LabelEnemy      = "Enemy";
    public const string LabelPoolable   = "Poolable";
    public const string LabelBGM        = "BGM";
}
```

- **释放规则**：`Addressables.InstantiateAsync` 产生的实例通过 `Addressables.ReleaseInstance` 释放；`LoadAssetAsync` 的 Handle 由加载方持有，场景卸载时统一 `Release`
- 对象池中的 Prefab 在游戏启动时预加载到内存，预热完成后 Handle 保留（不 Release），池销毁时统一 Release

### 2.5 单一职责原则

- 每个 MonoBehaviour 只负责一件事
- `PlayerController` 是**协调器**，不包含具体逻辑
- 具体逻辑分散在各 State、各独立组件中

---

## 3. 命名空间规范

所有自定义代码均在 `BaseGames` 根命名空间下，按系统划分：

| 命名空间 | 对应目录 | 说明 |
|---------|---------|------|
| `BaseGames.Core` | `Scripts/Core/` | 全局管理：GameManager、SaveSystem、SceneLoader |
| `BaseGames.Core.Events` | `Scripts/Core/Events/` | SO 事件频道定义 |
| `BaseGames.Input` | `Scripts/Input/` | InputReaderSO、输入缓冲 |
| `BaseGames.Camera` | `Scripts/Camera/` | 镜头状态管理、房间约束 |
| `BaseGames.Player` | `Scripts/Player/` | PlayerController、PlayerStats |
| `BaseGames.Player.States` | `Scripts/Player/States/` | 所有玩家 FSM 状态 |
| `BaseGames.Combat` | `Scripts/Combat/` | DamageInfo、HitBox、HurtBox |
| `BaseGames.Combat.StatusEffects` | `Scripts/Combat/StatusEffects/` | FireEffect、PoisonEffect、StatusEffectManager |
| `BaseGames.Parry` | `Scripts/Parry/` | ParrySystem、ParryConfigSO |
| `BaseGames.Enemies` | `Scripts/Enemies/` | EnemyBase、EnemyStats |
| `BaseGames.Enemies.AI` | `Scripts/Enemies/AI/` | BehaviorDesigner Tasks |
| `BaseGames.Enemies.Boss.Patterns` | `Scripts/Enemies/Boss/Patterns/` | AttackPatternSO、BossOrchestrator、TelegraphSystem |
| `BaseGames.Enemies.Navigation` | `Scripts/Enemies/Navigation/` | EnemyNavAgent 封装 |
| `BaseGames.Feedback` | `Scripts/Feedback/` | PlayerFeedback、EnemyFeedback、IFeedbackPlayer |
| `BaseGames.World` | `Scripts/World/` | SavePoint、RoomTransition、Collectible |
| `BaseGames.World.Map` | `Scripts/World/Map/` | MapManager、MapRoomDataSO、地图渲染 |
| `BaseGames.World.Shop` | `Scripts/World/Shop/` | ShopController、ShopItemSO、ShopInventorySO |
| `BaseGames.UI` | `Scripts/UI/` | UIManager、HUD 组件、Canvas 管理、LoadingScreenManager |
| `BaseGames.Audio` | `Scripts/Audio/` | AudioManager、BGMController、AudioZone |
| `BaseGames.Progression` | `Scripts/Progression/` | AbilityGate、ProgressLock、HP 容器升级 |
| `BaseGames.Dialogue` | `Scripts/Dialogue/` | DialogueManager、InteractableNPC、IInteractable |
| `BaseGames.Equipment` | `Scripts/Equipment/` | EquipmentManager、CharmSO、ICharmEffect |
| `BaseGames.Cutscene` | `Scripts/Cutscene/` | CutsceneManager、CutsceneTrigger、CutsceneSO |
| `BaseGames.Animation` | `Scripts/Animation/` | AnimationEventConfigSO、FootstepSystem、CancelWindow |
| `BaseGames.Spells` | `Scripts/Spells/` | SoulSpellSO、SpellCaster、SpellModifierSnapshot |
| `BaseGames.Localization` | `Scripts/Localization/` | LanguageManagerSO、LocalizationKeys、DialogueLocalizationBridge |
| `BaseGames.Tutorial` | `Scripts/Tutorial/` | ContextualHintTrigger、FirstTimeTrigger、TutorialManager、AbilityTutorialSequence |
| `BaseGames.Platform` | `Scripts/Platform/` | IPlatformService、SteamPlatformService、NullPlatformService、PlatformBootstrap |
| `BaseGames.Editor` | `Scripts/Editor/` | 编辑器扩展（Editor Only）|

> **规则**：第三方插件代码保持其原始命名空间，不修改。

---

## 4. 程序集定义

通过 Assembly Definition（`.asmdef`）强制隔离依赖，避免循环引用，加速编译：

```
BaseGames.Core.asmdef
  └── 依赖: Unity.InputSystem, MoreMountains.Feedbacks

BaseGames.Input.asmdef
  └── 依赖: Unity.InputSystem

BaseGames.Camera.asmdef
  └── 依赖: Cinemachine

BaseGames.Player.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Input, BaseGames.Combat,
            BaseGames.Parry, Kybernetik.Animancer

BaseGames.Combat.asmdef
  └── 依赖: BaseGames.Core

BaseGames.Parry.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Combat, MoreMountains.Feedbacks

BaseGames.Enemies.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Combat,
            Kybernetik.Animancer, PathBerserker2d

BaseGames.Enemies.AI.asmdef
  └── 依赖: BaseGames.Enemies, BehaviorDesigner.Runtime

BaseGames.Feedback.asmdef
  └── 依赖: BaseGames.Core, MoreMountains.Feedbacks, Cinemachine

BaseGames.World.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Feedback

BaseGames.UI.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Combat  (BossHP 需要 DamageInfo)

BaseGames.Audio.asmdef
  └── 依赖: BaseGames.Core

BaseGames.Progression.asmdef
  └── 依赖: BaseGames.Core, BaseGames.World

BaseGames.Dialogue.asmdef
  └── 依赖: BaseGames.Core, BaseGames.UI, BaseGames.Input

BaseGames.Map.asmdef
  └── 依赖: BaseGames.Core, BaseGames.World, BaseGames.UI

BaseGames.Equipment.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Combat, BaseGames.Player

BaseGames.Combat.StatusEffects.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Combat

BaseGames.Cutscene.asmdef
  └── 依赖: BaseGames.Core, BaseGames.UI, BaseGames.Input,
            BaseGames.Dialogue, Unity.Timeline, Cinemachine

BaseGames.Enemies.Boss.Patterns.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Enemies, BaseGames.Enemies.AI

BaseGames.Animation.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Audio, Kybernetik.Animancer

BaseGames.Spells.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Combat, BaseGames.Player

BaseGames.Localization.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Dialogue, Unity.Localization

BaseGames.Tutorial.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Input, BaseGames.UI, BaseGames.Player
      命名空间: BaseGames.Tutorial → Scripts/Tutorial/
      内容: ContextualHintTrigger, FirstTimeTrigger, TutorialManager, AbilityTutorialSequence

BaseGames.Platform.asmdef
  └── 依赖: BaseGames.Core, BaseGames.Audio
      外部条件依赖: Steamworks.NET（#if STEAMWORKS_NET）
      命名空间: BaseGames.Platform → Scripts/Platform/
      内容: IPlatformService, SteamPlatformService, NullPlatformService, PlatformBootstrap

BaseGames.Editor.asmdef  [Editor Only]
  └── 依赖: 全部上述 asmdef
```

---

## 5. 系统依赖图

箭头方向为"依赖方 → 被依赖方"，**不存在反向箭头**（禁止循环依赖）：

```
                    ┌─────────────────────┐
                    │      Core 核心       │
                    │  GameManager（§11）  │
                    │  SaveSystem          │
                    │  ObjectPoolManager   │
                    │  SettingsManager     │
                    └──────────┬──────────┘
          ┌───────────────────┼──────────────────────────┐
          │                   │                          │
    ┌─────▼──────┐  ┌─────────▼──────┐         ┌────────▼───────┐
    │   Input    │  │    Combat       │         │     World      │
    │ InputReader│  │  DamageInfo     │         │  SavePoint     │
    │     SO     │  │  HitBox/HurtBox │         │  RoomTransition│
    └─────┬──────┘  │  Projectile（§13）│         │  Collectible   │
          │         └─────────┬───────┘         └────────────────┘
          │                   │
    ┌─────▼──────────┬─────────▼──────┐
    │     Player     │     Parry       │
    │  Controller    │  System         │
    │  States (FSM)  │  WindowSO       │
    └────────────────┴──────┬──────────┘
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
    ┌─────▼───┐  ┌──────────▼──┐  ┌───────────▼───┐
    │  Camera │  │  Feedback   │  │    Enemies    │
    │Cinemachine│ │  Feel       │  │  EnemyBase    │
    │  States │  │  MMF_Player │  │  AI Tasks     │
    └─────────┘  └─────────────┘  │  Navigation   │
                                  └───────────────┘
          ↑                ↑               ↑
    ┌─────┴────┐  ┌────────┴────┐  ┌──────┴──────────┐
    │    UI    │  │    Audio    │  │   Progression   │
    │  §10     │  │   §12       │  │     §14         │
    │ UIManager│  │AudioManager │  │ AbilityGate     │
    │ HUD      │  │BGMController│  │ ProgressLock    │
    └──────────┘  └─────────────┘  └─────────────────┘
                                         ↑
                                  ┌──────┴──────────┐
                                  │    Dialogue     │
                                  │     §15         │
                                  │DialogueManager  │
                                  │InteractableNPC  │
                                  └─────────────────┘
```

---

## 6. 零耦合通信：ScriptableObject 事件频道

### 6.1 频道类型

所有事件频道均为 `ScriptableObject`，存放于 `Assets/ScriptableObjects/Events/`：

| 频道类型 | 泛型参数 | 用途举例 |
|---------|---------|---------|
| `VoidEventChannelSO` | — | 玩家死亡、游戏暂停、场景加载完成 |
| `IntEventChannelSO` | `int` | HP 变化、Geo 变化、Soul 变化 |
| `FloatEventChannelSO` | `float` | 时间缩放变更 |
| `Vector2EventChannelSO` | `Vector2` | 玩家位置更新 |
| `TransformEventChannelSO` | `Transform` | 摄像机跟踪目标切换 |
| `StringEventChannelSO` | `string` | 场景名称加载请求 |
| `DamageInfoEventChannelSO` | `DamageInfo` | 命中事件广播 |
| `BoolEventChannelSO` | `bool` | Boss 战开始/结束 |

### 6.2 关键频道实例

```
Assets/ScriptableObjects/Events/
├── Player/
│   ├── OnPlayerDied.asset            (VoidEventChannelSO)
│   ├── OnPlayerHPChanged.asset       (IntEventChannelSO)
│   ├── OnPlayerSoulChanged.asset     (IntEventChannelSO)
│   ├── OnPlayerGeoChanged.asset      (IntEventChannelSO)
│   └── OnPlayerParrySuccess.asset    (DamageInfoEventChannelSO)
│
├── Combat/
│   ├── OnHitConfirmed.asset          (DamageInfoEventChannelSO)
│   ├── OnParryWindowOpened.asset     (VoidEventChannelSO)
│   └── OnParryableProjectileParried.asset (VoidEventChannelSO)
│
├── Camera/
│   ├── OnRoomEntered.asset           (TransformEventChannelSO)
│   └── OnBossFightToggled.asset      (BoolEventChannelSO)
│
├── World/
│   ├── LoadScene.asset               (StringEventChannelSO)
│   ├── OnSavePointActivated.asset    (VoidEventChannelSO)
│   ├── OnCollectiblePickedUp.asset   (StringEventChannelSO)
│   ├── OnDestructibleDestroyed.asset (StringEventChannelSO)
│   ├── OnDestructibleRespawned.asset (StringEventChannelSO)
│   └── OnMechanismTriggered.asset    (StringEventChannelSO)
│
├── Game/
│   ├── OnGameStateChanged.asset      (GameStateEventChannelSO)
│   ├── OnGamePaused.asset            (BoolEventChannelSO)
│   ├── OnTimeScaleChanged.asset      (FloatEventChannelSO)
│   ├── OnPlayerRespawned.asset       (VoidEventChannelSO)
│   ├── OnBossDefeated.asset          (StringEventChannelSO)
│   ├── OnBossPhaseChanged.asset      (IntEventChannelSO)
│   ├── OnFastTravelRequested.asset   (StringEventChannelSO)
│   └── OnQuitToMainMenu.asset        (VoidEventChannelSO)
│
├── Audio/
│   └── OnRegionEntered.asset         (StringEventChannelSO)
│
├── Progression/
│   ├── OnAbilityUnlocked.asset       (StringEventChannelSO)
│   ├── OnRegionUnlocked.asset        (StringEventChannelSO)
│   ├── OnMaxHPChanged.asset          (IntEventChannelSO)
│   └── OnProgressLockOpened.asset    (StringEventChannelSO)
│
├── UI/
│   ├── OnBossHPChanged.asset         (IntEventChannelSO)
│   ├── OnBossNameSet.asset           (StringEventChannelSO)
│   └── OnBossHPMaxSet.asset          (IntEventChannelSO)
│
└── Dialogue/
    ├── OnDialogueStarted.asset       (VoidEventChannelSO)
    └── OnDialogueEnded.asset         (VoidEventChannelSO)
```

### 6.3 频道使用规范

**发送方**：持有频道 SO 引用，调用 `channel.Raise(payload)` — 仅需知道频道，不知道谁在监听。

**接收方**：持有频道 SO 引用，在 `OnEnable` 订阅 `channel.OnEventRaised`，在 `OnDisable` 取消订阅 — 仅需知道频道，不知道谁在发送。

---

## 7. 数据驱动：ScriptableObject 配置资产

所有可配置数据均为 SO 资产，策划直接在 Inspector 中调整：

```
Assets/ScriptableObjects/Config/
├── Player/
│   ├── PlayerMovementConfigSO.asset     # 移动速度、跳跃力、冲刺参数
│   ├── PlayerCombatConfigSO.asset       # 攻击伤害、连击窗口时长
│   ├── PlayerAnimationConfigSO.asset    # 所有 ClipTransition
│   └── PlayerStatsSO.asset             # 初始 HP、Soul上限、Geo
│
├── Parry/
│   └── ParryConfigSO.asset             # 弹反窗口、子弹时间、反击参数
│
├── Enemies/
│   ├── SpiderScoutStatsSO.asset
│   ├── KnightEliteStatsSO.asset
│   └── ...
│
├── Camera/
│   └── CameraConfigSO.asset            # 偏移、跟随阻尼、镜头切换参数
│
└── World/
    └── GameSettingsSO.asset            # 全局游戏设置
```

---

## 8. 帧执行顺序

通过 `DefaultExecutionOrder` 特性保证更新顺序：

| 顺序值 | 系统 | 说明 |
|--------|------|------|
| `-5000` | `AnimancerComponent` | Playable Graph 最先更新（Animancer 内置）|
| `-200` | `CameraStateController` | 镜头状态在物理前锁定 |
| `-100` | `InputReaderSO` 消费者 | 输入采集优先于逻辑处理 |
| `0` | `PlayerController` | FSM 状态机驱动（默认顺序）|
| `0` | BehaviorDesigner ECS SystemGroup | 敌人 AI 决策（ECS 驱动，与默认同批次）|
| `0` | `EnemyNavAgent` | PathBerserker2d 事件回调 |
| `+100` | `PlayerFeedback` / `EnemyFeedback` | 反馈在逻辑后触发 |

**FixedUpdate 顺序**（物理帧）：

| 顺序 | 系统 | 说明 |
|------|------|------|
| 先 | `PlayerController.FixedUpdate` | 通过当前 State 设置 Rigidbody2D 速度 |
| 先 | `EnemyNavAgent.FixedUpdate` | 根据 NavAgent 事件设置敌人 Rigidbody2D 速度 |
| 后 | Unity Physics2D | 执行物理模拟 |

---

## 9. 项目目录结构

```
Assets/
│
├── Scripts/
│   ├── Core/
│   │   ├── Events/                     # SO 事件频道基类定义
│   │   ├── GameManager.cs
│   │   ├── SaveSystem.cs
│   │   └── SceneLoader.cs
│   │
│   ├── Input/
│   │   ├── InputReaderSO.cs            # SO：封装 Input Actions，发布输入事件
│   │   └── InputBuffer.cs              # 输入缓冲：跳跃/攻击/弹反
│   │
│   ├── Camera/
│   │   ├── CameraStateController.cs    # Cinemachine 虚拟相机状态切换
│   │   ├── RoomCameraBounds.cs         # 房间约束区域（Cinemachine Confiner2D 配置）
│   │   └── CameraConfigSO.cs          # 镜头参数配置
│   │
│   ├── Player/
│   │   ├── PlayerController.cs         # 协调器：不含业务逻辑
│   │   ├── PlayerStats.cs              # 运行时属性（监听 SO 配置）
│   │   ├── PlayerMovement.cs           # 物理移动计算（Rigidbody2D）
│   │   ├── PlayerCombat.cs             # HitBox 开关、连击链管理
│   │   └── States/
│   │       ├── PlayerStateBase.cs      # 抽象基类（Animancer.FSM.StateBehaviour）
│   │       ├── PlayerIdleState.cs
│   │       ├── PlayerRunState.cs
│   │       ├── PlayerAirState.cs       # 跳跃/双跳/墙跳/下落 合一
│   │       ├── PlayerDashState.cs
│   │       ├── PlayerAttackState.cs    # Layer 1 上半身攻击
│   │       ├── PlayerParryState.cs     # 弹反窗口 + 反击
│   │       ├── PlayerHurtState.cs      # 受击 + 死亡
│   │       ├── PlayerSpringState.cs    # 灵泉使用
│   │       ├── PlayerInteractState.cs
│   │       └── PlayerSwimState.cs      # P1：解锁后可用
│   │
│   ├── Combat/
│   │   ├── DamageInfo.cs               # 纯数据结构（struct）
│   │   ├── HitBox.cs                   # 攻击判定（Collider2D + AnimationEvent）
│   │   ├── HurtBox.cs                  # 受击区域（路由 DamageInfo 给 Owner）
│   │   ├── Projectile.cs               # 抛射物（P1）
│   │   └── ProjectilePool.cs           # 对象池（P1）
│   │
│   ├── Parry/
│   │   ├── ParrySystem.cs              # 弹反状态机：窗口/成功/反击
│   │   └── ParryConfigSO.cs           # 弹反参数配置 SO
│   │
│   ├── Enemies/
│   │   ├── EnemyBase.cs                # 基类：持有 Animancer + BT + NavAgent
│   │   ├── EnemyStatsSO.cs            # 敌人属性 SO（每种敌人一个实例）
│   │   ├── EnemyAnimationConfigSO.cs  # 动画配置 SO
│   │   ├── Boss/
│   │   │   ├── BossBase.cs             # 继承 EnemyBase，增加阶段管理
│   │   │   └── BossPhaseConfig.cs     # 阶段配置（阶段切换 HP 阈值）
│   │   ├── Concrete/                   # 具体敌人实现（继承 EnemyBase）
│   │   │   ├── SpiderScout.cs
│   │   │   └── KnightElite.cs
│   │   ├── AI/                         # BehaviorDesigner 自定义 Tasks
│   │   │   ├── Actions/
│   │   │   └── Conditions/
│   │   └── Navigation/
│   │       └── EnemyNavAgent.cs        # PathBerserker2d NavAgent 封装
│   │
│   ├── Feedback/
│   │   ├── PlayerFeedback.cs           # 玩家 MMF_Player 集中管理
│   │   └── EnemyFeedback.cs           # 敌人 MMF_Player 集中管理
│   │
│   ├── World/
│   │   ├── SavePoint.cs
│   │   ├── RoomTransition.cs
│   │   ├── HazardZone.cs
│   │   ├── Collectible.cs
│   │   ├── AbilityUnlock.cs
│   │   ├── Interactables/
│   │   │   ├── IInteractable.cs
│   │   │   ├── Sign.cs
│   │   │   ├── DirectionalInteractable.cs
│   │   │   └── AbilityGateInteractable.cs
│   │   └── ShopNPC.cs
│   │
│   ├── UI/                             # 见 10_UISystem.md
│   │   ├── UIManager.cs
│   │   ├── HUD/
│   │   │   ├── HPContainer.cs
│   │   │   ├── SoulGauge.cs
│   │   │   ├── GeoCounter.cs
│   │   │   └── BossHPBar.cs
│   │   ├── Menus/
│   │   │   ├── MainMenuPanel.cs
│   │   │   ├── PauseMenuPanel.cs
│   │   │   └── DeathScreenPanel.cs
│   │   ├── Overlays/
│   │   │   └── LoadingOverlay.cs
│   │   └── Settings/
│   │       └── SettingsPanel.cs
│   │
│   ├── Audio/                          # 见 12_AudioSystem.md
│   │   ├── AudioManager.cs
│   │   ├── BGMController.cs
│   │   ├── AudioZone.cs
│   │   ├── GlobalSFXPlayer.cs
│   │   └── SettingsManager.cs
│   │
│   ├── Progression/                    # 见 14_ProgressionSystem.md
│   │   ├── AbilityGate.cs
│   │   ├── ProgressLock.cs
│   │   ├── BossProgressTracker.cs
│   │   ├── HPContainerPickup.cs
│   │   └── RegionDefinitionSO.cs
│   │
│   ├── Dialogue/                       # 见 15_DialogueSystem.md
│   │   ├── DialogueManager.cs
│   │   ├── DialogueUI.cs
│   │   ├── DialogueSequenceSO.cs
│   │   ├── InteractableNPC.cs
│   │   ├── InteractionPromptController.cs
│   │   └── ShopNPC.cs
│   │
│   └── Editor/                         # 编辑器扩展（Editor Only）
│       ├── Inspectors/                 # 自定义 Inspector
│       ├── Windows/                    # EditorWindow 工具
│       └── Gizmos/                     # 场景 Gizmos 辅助绘制
│
├── ScriptableObjects/
│   ├── Events/                         # SO 事件频道实例
│   │   ├── Player/
│   │   ├── Combat/
│   │   ├── Camera/
│   │   ├── World/
│   │   ├── Game/
│   │   ├── Audio/
│   │   ├── Progression/
│   │   ├── UI/
│   │   └── Dialogue/
│   ├── Config/                         # 游戏配置 SO 实例
│   └── Dialogue/                       # DialogueSequenceSO 资产
│
├── Art/
│   ├── Sprites/
│   └── Animations/
│
├── Audio/
│   ├── SFX/
│   └── BGM/
│
└── Prefabs/
    ├── Player/
    ├── Enemies/
    └── World/
```

---

## 10. 插件职责边界

| 插件 | 命名空间 | 在本项目中的职责 | 明确不负责 |
|------|---------|----------------|-----------|
| **Animancer Pro v8.3** | `Animancer`, `Animancer.FSM` | 玩家 & 敌人的全部动画播放；玩家 FSM 骨架（`StateMachine<T>`）| AI 决策、寻路、反馈效果 |
| **Behavior Designer Pro v2.1** | `BehaviorDesigner.Runtime.Tasks` | 敌人 AI 决策树；黑板变量（`SharedVariable`）；BOSS 阶段切换 | 实际移动（交给 NavAgent）、动画（交给 Animancer）|
| **PathBerserker2d** | `PathBerserker2d` | 2D 平台寻路（`NavSurface` 烘焙 + `NavAgent` A*）；跳跃/下落 `NavLink` | 移动决策（交给 BT）、反馈（交给 Feel）|
| **Feel v4.3** | `MoreMountains.Feedbacks`, `MoreMountains.Tools` | 全部视听触觉反馈（`MMF_Player`）；子弹时间（`MMTimeManager`）；事件广播（`MMEventManager`）| 逻辑判断、动画、寻路 |
| **Cinemachine 3** | `Unity.Cinemachine` | 虚拟相机、房间约束（`CinemachineConfiner2D`）、镜头震动（`CinemachineImpulseSource`）| 游戏逻辑 |
| **Input System** | `UnityEngine.InputSystem` | 原始输入采集，封装到 `InputReaderSO` | 游戏逻辑决策 |

---

## 11. 功能优先级总表

### P0 — 核心可玩（里程碑 1）

| 功能 | 涉及文档 |
|------|---------|
| 横版移动（跑/跳/双跳/墙跳/冲刺）| [03_PlayerSystem](./03_PlayerSystem.md) |
| 基础攻击（3连击 + 空中下斩 + 上挑）| [04_CombatSystem](./04_CombatSystem.md) |
| **弹反机制**（弹反窗口 + 子弹时间 + 反击）| [05_ParrySystem](./05_ParrySystem.md) |
| 受击 / 死亡 / 无敌帧 | [03](./03_PlayerSystem.md), [04](./04_CombatSystem.md) |
| HP / Soul / Geo 属性 | [03_PlayerSystem](./03_PlayerSystem.md) |
| 治疗（消耗 Soul）| [03_PlayerSystem](./03_PlayerSystem.md) |
| 基础敌人 AI（巡逻 / 追击 / 攻击）| [06_EnemySystem](./06_EnemySystem.md) |
| Boss 战（2阶段）+ 攻击模式库 ✅ | [06_EnemySystem](./06_EnemySystem.md), [19_BossPatternLibrary](./19_BossPatternLibrary.md) |
| 存档点 | [08_WorldSystem](./08_WorldSystem.md) |
| 房间切换 | [08_WorldSystem](./08_WorldSystem.md) |
| 危险区域 | [08_WorldSystem](./08_WorldSystem.md) |
| 能力解锁 | [08_WorldSystem](./08_WorldSystem.md) |
| 视听反馈（命中/弹反/受伤/死亡）| [07_FeedbackSystem](./07_FeedbackSystem.md) |
| 动画事件（HitBox/脚步/取消窗口）✅ | [20_AnimationEventSystem](./20_AnimationEventSystem.md) |
| 镜头：房间约束 + 战斗偏移 | [02_CameraSystem](./02_CameraSystem.md) |

### P1 — 完整体验（里程碑 2）

| 功能 | 涉及文档 |
|------|---------|
| GameState 状态机 + 死亡复活流程 | [11_GameManager](./11_GameManager.md) |
| HUD（HP 心形/Soul/Geo） | [10_UISystem](./10_UISystem.md) |
| Boss HP 条 + 主菜单 + Pause 菜单 | [10_UISystem](./10_UISystem.md) |
| 加载画面 + 无障碍选项 | [10_UISystem](./10_UISystem.md) |
| 自适应音乐（探索/Boss/胜利） | [12_AudioSystem](./12_AudioSystem.md) |
| 弹射物系统 + 对象池 | [13_ProjectileSystem](./13_ProjectileSystem.md) |
| 区域进程 + AbilityGate + ProgressLock | [14_ProgressionSystem](./14_ProgressionSystem.md) |
| NPC 对话系统 + IInteractable 接口 | [15_DialogueSystem](./15_DialogueSystem.md) |
| 地图系统 | [16_MapSystem](./16_MapSystem.md) |
| 商人 NPC | [15_DialogueSystem](./15_DialogueSystem.md) |
| 精英敌人（多阶段行为树）| [06_EnemySystem](./06_EnemySystem.md) |
| 移动平台 + NavLinkCluster | [06_EnemySystem](./06_EnemySystem.md) |
| Boss 战（专属 Cinemachine 镜头）| [02_CameraSystem](./02_CameraSystem.md) |
| 本地化（中/英/日） | [22_LocalizationSystem](./22_LocalizationSystem.md) |

### P2 — 丰富度（里程碑 3）

| 功能 | 涉及文档 |
|------|------|
| 护符系统 | [17_EquipmentSystem](./17_EquipmentSystem.md) |
| 法术系统（SoulSpell） | [21_SpellSystem](./21_SpellSystem.md) |
| 触觉反馈（手柄震动）| [07_FeedbackSystem](./07_FeedbackSystem.md) |
| 对话分支（P1 级条件对话）| [15_DialogueSystem](./15_DialogueSystem.md) |
| 快速旅行（Bench 传送）| [11_GameManager](./11_GameManager.md) |
| 过场动画（Timeline）| [18_CutsceneSystem](./18_CutsceneSystem.md) |
| 游泳 | [03_PlayerSystem](./03_PlayerSystem.md) |
| 编辑器工具完善（9.1–9.8）| [09_EditorExtensions](./09_EditorExtensions.md) |
| 游戏手感微调（参数参考）| [23_GameFeelTuningGuide](./23_GameFeelTuningGuide.md) |