Architecture · 代码框架设计文档集
作用层：本文档集位于
Docs/Architecture/，是Docs/Design/（游戏设计文档）与实际代码实现之间的桥梁层。
读者：程序员。描述"代码如何组织"，不涉及具体剧情、关卡数值、叙事内容。
输出物：可直接作为实施计划（Sprint Backlog）的输入，每个模块文档对应一个或多个可独立实现的代码单元。
文档列表
| 编号 | 文档 | 覆盖内容 | 关联 Design 文档 |
|---|---|---|---|
| 01 | 项目结构与规范 | 文件夹布局、Assembly Definitions、命名规范、SO 资产路径、代码规范 | 00 |
| 02 | SO 事件系统 | 所有事件频道类型、泛型基类、发布/订阅模式、全局事件频道列表 | 00 |
| 03 | Core 核心模块 | GameManager、SceneLoader、ObjectPoolManager、SettingsManager | 00、11、43 |
| 04 | 输入模块 | InputReaderSO、InputBuffer、Action Map 定义、按键重绑定 | 01、25 |
| 05 | 玩家模块 | PlayerController、PlayerMovement、PlayerStats、PlayerCombat、FormController、FSM States | 03、05、14、21、53、54 |
| 06 | 战斗模块 | DamageInfo、HitBox、HurtBox、Parry、Projectile、StatusEffects | 04、05、13、30、54 |
| 07 | 敌人模块 | EnemyBase、EnemyStats、AI Tasks、Navigation、Boss Patterns、Telegraph | 06、19、47、48 |
| 08 | 世界模块 | 场景结构、RoomTransition、SavePoint、Collectible、HazardZone、WorldStateRegistry | 08、34、49 |
| 09 | 进度模块 | AbilityType、AbilityGate、Equipment/Charms、Skills/Spells、Quest、Challenge | 14、17、21、37、38、39 |
| 10 | UI 模块 | UIManager、HUD、PauseMenu、DeathScreen、Panel 层级、UI Toolkit 规范 | 10、53_HUDSpec 参考 74 |
| 11 | 音频模块 | AudioManager、BGMController、SFX Pool、AudioZone、FMOD 集成 | 12、63 |
| 12 | 存档模块 | SaveData schema（C# 完整结构）、SaveManager、ISaveStorage、SaveMigrator、Checksum | 31 |
| 13 | 资源与对象池 | Addressables 工作流、ObjectPoolManager、预热策略、释放规范 | 43 |
| 14 | 叙事模块 | DialogueManager、CutsceneManager、IInteractable NPC、EventChain | 15、18、34、50 |
| 15 | 地图与商店模块 | MapManager、RoomReveal、FastTravel、ShopController、ShopInventorySO | 16、28 |
| 16 | 支撑模块 | Localization、Platform Integration、Analytics、Achievement、Tutorial、Debug | 22、32、42、45、46、55 |
| 17 | 摄像机模块 | CameraStateController、Cinemachine 虚拟相机、Zone-based 切换、CameraBounds | 03、26 |
| 18 | VFX 与反馈模块 | FeedbackConfigSO、VFXPool、HitFXSpawner、HurtFlashController、PostProcessManager | 04、12 |
| 19 | 难度模块 | DifficultySettingsSO、DifficultyManager、IScalable、SteelSoul 模式 | 11 |
| 20 | 护盾模块 | ShieldComponent、ShieldConfigSO、IShieldable、护盾破碎/恢复管道 | 05、13 |
| 21 | 液体谜题模块 | LiquidZone、LiquidPhysicsConfigSO、SwimState、PuzzleSwitch/PuzzleReceiver、WorldMarker | 08、41 |
| 22 | 任务与挑战模块 | QuestManager、QuestSO、QuestObjectiveSO、ChallengeRoom、QuestEventChannelSO | 37、38、39 |
| 23 | Boss 技能模块 | BossSkillSO、BossSkillExecutor、SkillSequenceSO、VulnerabilityWindow、WeakPointSystem | 19、47、48 |
| 24 | 动画事件模块 | PlayerAnimationEvents、EnemyAnimationEvents、AnimEventBridge、Animancer 事件回调 | 03 |
架构全景图
┌────────────────────────────────────────────────────────────────────────┐
│ Unity 引擎层 │
│ Addressables │ Cinemachine │ InputSystem │ UI Toolkit │ Animancer │
│ PathBerserker2d │ Behavior Designer │ Feel │ FMOD │ Timeline │
└───────────────────────────┬────────────────────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────────────────────┐
│ BaseGames.Core（核心层） │
│ GameManager │ SceneLoader │ ObjectPoolManager │ SettingsManager │
│ SO 事件系统（BaseEventChannel<T>）│ AddressKeys │
└───────────────────────────┬────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌───────▼───────┐ ┌────────▼──────┐ ┌─────────▼──────────┐
│ Input 层 │ │ World 层 │ │ Combat 层 │
│ InputReaderSO │ │ RoomTransition│ │ DamageInfo │
│ InputBuffer │ │ SavePoint │ │ HitBox / HurtBox │
└───────┬───────┘ │ Collectible │ │ Projectile │
│ └───────────────┘ │ StatusEffectManager │
│ └─────────┬───────────┘
│ │
┌───────▼──────────────────────────────────────▼──────────────┐
│ Player 层 │
│ PlayerController（协调器） │
│ PlayerMovement │ PlayerStats │ PlayerCombat │ FormController │
│ ParrySystem │ SkillManager │ WeaponManager │ SpringSystem │
│ FSM States（Idle/Run/Jump/Dash/Attack/Hurt/Dead/...） │
└───────────────────────────────┬──────────────────────────────┘
│
┌───────────────────────┼──────────────────────┐
│ │ │
┌───────▼──────┐ ┌─────────▼──────┐ ┌─────────▼──────────┐
│ Enemy 层 │ │ Progression 层│ │ Narrative 层 │
│ EnemyBase │ │ AbilityGate │ │ DialogueManager │
│ AI Tasks │ │ Equipment │ │ CutsceneManager │
│ BossPatterns│ │ SkillSO │ │ EventChain │
└──────────────┘ │ QuestManager │ └─────────────────────┘
└────────────────┘
│
┌───────────────────────────────▼──────────────────────────────────┐
│ 上层服务层 │
│ UIManager │ AudioManager │ MapManager │ ShopController │
│ SaveManager │ LocalizationManager │ PlatformService │ Analytics │
└──────────────────────────────────────────────────────────────────┘
模块间通信规则（三种合法方式）
| 方式 | 适用场景 | 示例 |
|---|---|---|
| SO 事件频道 | 跨模块异步通知 | _onPlayerDied.Raise() → AudioManager 响应 |
| 接口注入 | 同 Prefab 内组件间调用 | PlayerController 调用 _movement.Move() |
| Inspector 序列化引用 | 同一 Prefab 层级内组件 | [SerializeField] PlayerMovement _movement |
禁止：FindObjectOfType、GetComponent<T> 跨 GameObject、静态单例暴露子系统引用。
版本说明
| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0 | 2026-04 | 初版，覆盖全部核心系统 |