31 KiB
31 KiB
00 · 总览与架构原则
所属文档集 ← 返回索引
关联文档 全部子文档均以本文规则为基准
目录
- 游戏定位
- 核心设计哲学
- 命名空间规范
- 程序集定义（Assembly Definitions）
- 系统依赖图
- 零耦合通信：ScriptableObject 事件频道
- 数据驱动：ScriptableObject 配置资产
- 帧执行顺序
- 项目目录结构
- 插件职责边界
- 功能优先级总表
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静态类中集中定义，禁止代码中出现魔法字符串
// 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 |
| 基础攻击（3连击 + 空中下斩 + 上挑） | 04_CombatSystem |
| 弹反机制（弹反窗口 + 子弹时间 + 反击） | 05_ParrySystem |
| 受击 / 死亡 / 无敌帧 | 03, 04 |
| HP / Soul / Geo 属性 | 03_PlayerSystem |
| 治疗（消耗 Soul） | 03_PlayerSystem |
| 基础敌人 AI（巡逻 / 追击 / 攻击） | 06_EnemySystem |
| Boss 战（2阶段）+ 攻击模式库 ✅ | 06_EnemySystem, 19_BossPatternLibrary |
| 存档点 | 08_WorldSystem |
| 房间切换 | 08_WorldSystem |
| 危险区域 | 08_WorldSystem |
| 能力解锁 | 08_WorldSystem |
| 视听反馈（命中/弹反/受伤/死亡） | 07_FeedbackSystem |
| 动画事件（HitBox/脚步/取消窗口）✅ | 20_AnimationEventSystem |
| 镜头：房间约束 + 战斗偏移 | 02_CameraSystem |
P1 — 完整体验（里程碑 2）
| 功能 | 涉及文档 |
|---|---|
| GameState 状态机 + 死亡复活流程 | 11_GameManager |
| HUD（HP 心形/Soul/Geo） | 10_UISystem |
| Boss HP 条 + 主菜单 + Pause 菜单 | 10_UISystem |
| 加载画面 + 无障碍选项 | 10_UISystem |
| 自适应音乐（探索/Boss/胜利） | 12_AudioSystem |
| 弹射物系统 + 对象池 | 13_ProjectileSystem |
| 区域进程 + AbilityGate + ProgressLock | 14_ProgressionSystem |
| NPC 对话系统 + IInteractable 接口 | 15_DialogueSystem |
| 地图系统 | 16_MapSystem |
| 商人 NPC | 15_DialogueSystem |
| 精英敌人（多阶段行为树） | 06_EnemySystem |
| 移动平台 + NavLinkCluster | 06_EnemySystem |
| Boss 战（专属 Cinemachine 镜头） | 02_CameraSystem |
| 本地化（中/英/日） | 22_LocalizationSystem |
P2 — 丰富度（里程碑 3）
| 功能 | 涉及文档 |
|---|---|
| 护符系统 | 17_EquipmentSystem |
| 法术系统（SoulSpell） | 21_SpellSystem |
| 触觉反馈（手柄震动） | 07_FeedbackSystem |
| 对话分支（P1 级条件对话） | 15_DialogueSystem |
| 快速旅行（Bench 传送） | 11_GameManager |
| 过场动画（Timeline） | 18_CutsceneSystem |
| 游泳 | 03_PlayerSystem |
| 编辑器工具完善（9.1–9.8） | 09_EditorExtensions |
| 游戏手感微调（参数参考） | 23_GameFeelTuningGuide |