zeling_v2/Docs/Architecture

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 技能模块	已于 2026-07-30 删除。 旧 Boss 技能轨（BossSkillSO / BossSkillExecutor / SkillSequenceSO / WeakPointSystem）整体退役，Boss 与小怪统一走 EnemyAbilitySO + EnemyAiBrain。实现见 07；写法见 Docs/Guides/09_BossAi_Authoring_Guide.md	07
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	初版，覆盖全部核心系统