joywayerandClaude Opus 5
6d3816d7ef
新增 Docs/Guides/09_BossAi_Authoring_Guide.md： 定制路径写法（[AiDefinition] + AiScript）、建态原语（AiStateFragments + BossFragments + IBossControl）、阶段=换招池、一招怎么配（EnemyAbilitySO + EnemyAttackSO + 动画事件）、开战触发、死亡归物理层， 以已落地的 ChaoFengAi 为逐段范例，附 Boss 专属陷阱与已知缺口。 08 号指南加交叉引用。 删除两份整份描述已删除且从未实现的体系的文档： Docs/Architecture/23_BossSkillModule.md、Docs/Design/47_BossSkillSystem.md。 删前已确认全库无 Markdown 链接残留，索引行与关联文档行改指新指南或 spec。 修订：25_CharacterArchitectureOverview §4 Boss 章节按实际代码重写； 07_EnemyModule 加过时提示、§11 改重定向；02_EventSystem 修正 Boss 事件发送方； 19_BossPatternLibrary 加废止提示（设计意图仍有效，类型名已废）； AssetFolderSpec 删旧 Boss 技能编辑器条目；三处 README/索引同步。 Docs_Dev/ 历史记录保留不动。 spec 标记为已实施，并记录实施期偏差（无 Boss 骨架、Telegraph 枚举保留、 阶段直查不走黑板、BossSkillEvent 一并删除）与八项已知未完成项， 其中 EnemyHurtState 无受击动画永久卡死为最高优先级、且与 Boss 轨无关。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
109 lines
9.6 KiB
Markdown
109 lines
9.6 KiB
Markdown
# Architecture · 代码框架设计文档集
|
||
|
||
> **作用层**：本文档集位于 `Docs/Architecture/`，是 `Docs/Design/`（游戏设计文档）与实际代码实现之间的桥梁层。
|
||
> **读者**：程序员。描述"代码如何组织"，不涉及具体剧情、关卡数值、叙事内容。
|
||
> **输出物**：可直接作为实施计划（Sprint Backlog）的输入，每个模块文档对应一个或多个可独立实现的代码单元。
|
||
|
||
---
|
||
|
||
## 文档列表
|
||
|
||
| 编号 | 文档 | 覆盖内容 | 关联 Design 文档 |
|
||
|------|------|---------|----------------|
|
||
| [01](./01_ProjectStructure.md) | 项目结构与规范 | 文件夹布局、Assembly Definitions、命名规范、SO 资产路径、代码规范 | 00 |
|
||
| [02](./02_EventSystem.md) | SO 事件系统 | 所有事件频道类型、泛型基类、发布/订阅模式、全局事件频道列表 | 00 |
|
||
| [03](./03_CoreModule.md) | Core 核心模块 | GameManager、SceneLoader、ObjectPoolManager、SettingsManager | 00、11、43 |
|
||
| [04](./04_InputModule.md) | 输入模块 | InputReaderSO、InputBuffer、Action Map 定义、按键重绑定 | 01、25 |
|
||
| [05](./05_PlayerModule.md) | 玩家模块 | PlayerController、PlayerMovement、PlayerStats、PlayerCombat、FormController、FSM States | 03、05、14、21、53、54 |
|
||
| [06](./06_CombatModule.md) | 战斗模块 | DamageInfo、HitBox、HurtBox、Parry、Projectile、StatusEffects | 04、05、13、30、54 |
|
||
| [07](./07_EnemyModule.md) | 敌人模块 | EnemyBase、EnemyStats、AI Tasks、Navigation、Boss Patterns、Telegraph | 06、19、47、48 |
|
||
| [08](./08_WorldModule.md) | 世界模块 | 场景结构、RoomTransition、SavePoint、Collectible、HazardZone、WorldStateRegistry | 08、34、49 |
|
||
| [09](./09_ProgressionModule.md) | 进度模块 | AbilityType、AbilityGate、Equipment/Charms、Skills/Spells、Quest、Challenge | 14、17、21、37、38、39 |
|
||
| [10](./10_UIModule.md) | UI 模块 | UIManager、HUD、PauseMenu、DeathScreen、Panel 层级、UI Toolkit 规范 | 10、53_HUDSpec 参考 74 |
|
||
| [11](./11_AudioModule.md) | 音频模块 | AudioManager、BGMController、SFX Pool、AudioZone、FMOD 集成 | 12、63 |
|
||
| [12](./12_SaveModule.md) | 存档模块 | SaveData schema（C# 完整结构）、SaveManager、ISaveStorage、SaveMigrator、Checksum | 31 |
|
||
| [13](./13_AssetPoolModule.md) | 资源与对象池 | Addressables 工作流、ObjectPoolManager、预热策略、释放规范 | 43 |
|
||
| [14](./14_NarrativeModule.md) | 叙事模块 | DialogueManager、CutsceneManager、IInteractable NPC、EventChain | 15、18、34、50 |
|
||
| [15](./15_MapShopModule.md) | 地图与商店模块 | MapManager、RoomReveal、FastTravel、ShopController、ShopInventorySO | 16、28 |
|
||
| [16](./16_SupportingModules.md) | 支撑模块 | Localization、Platform Integration、Analytics、Achievement、Tutorial、Debug | 22、32、42、45、46、55 |
|
||
| [17](./17_CameraModule.md) | 摄像机模块 | CameraStateController、Cinemachine 虚拟相机、Zone-based 切换、CameraBounds | 03、26 |
|
||
| [18](./18_VFXFeedbackModule.md) | VFX 与反馈模块 | FeedbackConfigSO、VFXPool、HitFXSpawner、HurtFlashController、PostProcessManager | 04、12 |
|
||
| [19](./19_DifficultyModule.md) | 难度模块 | DifficultySettingsSO、DifficultyManager、IScalable、SteelSoul 模式 | 11 |
|
||
| [20](./20_ShieldModule.md) | 护盾模块 | ShieldComponent、ShieldConfigSO、IShieldable、护盾破碎/恢复管道 | 05、13 |
|
||
| [21](./21_LiquidPuzzleModule.md) | 液体谜题模块 | LiquidZone、LiquidPhysicsConfigSO、SwimState、PuzzleSwitch/PuzzleReceiver、WorldMarker | 08、41 |
|
||
| [22](./22_QuestChallengeModule.md) | 任务与挑战模块 | 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`](../Guides/09_BossAi_Authoring_Guide.md) | 07 |
|
||
| [24](./24_AnimEventModule.md) | 动画事件模块 | 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 | 初版，覆盖全部核心系统 |
|