657 lines
31 KiB
Markdown
657 lines
31 KiB
Markdown
# 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) |
|