basegames/zeling_v2
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initial commit

Browse Source
This commit is contained in:
Joywayer
2026-05-08 11:04:00 +08:00
commit f55d2a57c3
6278 changed files with 866081 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

656
Docs/Design/00_Overview.md Normal file
View File

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