173 lines
18 KiB
Markdown
173 lines
18 KiB
Markdown
# 泽灵（Zeling）架构设计文档
|
||
|
||
> **引擎** Unity 2022.3 LTS · URP · Input System · Cinemachine 3
|
||
> **风格** 2D 像素 · 横板类银河恶魔城 · 参考 Hollow Knight: Silksong + 弹反机制
|
||
> **架构理念** 零耦合 · 编辑器友好 · 数据驱动 · 事件驱动
|
||
|
||
---
|
||
|
||
## 导航索引
|
||
|
||
| 序号 | 文档 | 内容摘要 |
|
||
|:----:|------|---------|
|
||
| 00 | [总览与架构原则](./00_Overview.md) | 零耦合设计原则、系统依赖图、ScriptableObject 事件频道、程序集划分 |
|
||
| 01 | [输入系统](./01_InputSystem.md) | InputReaderSO、Input Actions、输入缓冲、Coyote Time |
|
||
| 02 | [镜头系统](./02_CameraSystem.md) | Cinemachine 3、房间约束、镜头状态切换、Impulse 震屏、像素对齐 |
|
||
| 03 | [玩家系统](./03_PlayerSystem.md) | PlayerController、Animancer 双层 FSM、状态表、PlayerStats、能力解锁 |
|
||
| 04 | [战斗系统](./04_CombatSystem.md) | DamageInfo、HitBox / HurtBox、连击链、击退、状态效果/DoT |
|
||
| 05 | [弹反系统](./05_ParrySystem.md) | 弹反窗口、子弹时间、反击窗口、设计参数表 |
|
||
| 06 | [敌人系统](./06_EnemySystem.md) | EnemyBase、BehaviorDesigner 行为树模板、PathBerserker2d 寻路集成 |
|
||
| 07 | [反馈系统](./07_FeedbackSystem.md) | Feel MMF_Player、Cinemachine Impulse、触觉反馈、时间管理 |
|
||
| 08 | [世界系统](./08_WorldSystem.md) | 场景结构、房间切换、存档、可交互环境（6种类型）、商店、死亡遗骸 |
|
||
| 09 | [编辑器扩展](./09_EditorExtensions.md) | 自定义 Inspector、EditorWindow 工具、Gizmos、调试叠加层 |
|
||
| 10 | [UI 系统](./10_UISystem.md) | HUD（HP/Soul/Geo）、Boss HP 条、主菜单、Pause、死亡画面、加载遮罩、设置菜单 |
|
||
| 11 | [游戏管理器与生命周期](./11_GameManager.md) | GameState 状态机、死亡复活流程、Boss 战管理、快速旅行编排 |
|
||
| 12 | [音频系统](./12_AudioSystem.md) | AudioMixer 架构、自适应音乐（探索/Boss/胜利）、BGMController、AudioEventSO |
|
||
| 13 | [弹射物系统与对象池](./13_ProjectileSystem.md) | Projectile 组件、3 种弹道类型（含追踪修复）、可弹反弹射物、GlobalObjectPool |
|
||
| 14 | [进程系统](./14_ProgressionSystem.md) | 区域划分、AbilityGate、ProgressLock、Boss 进程、HP 容器升级 |
|
||
| 15 | [对话系统与交互接口](./15_DialogueSystem.md) | IInteractable 接口、DialogueSequenceSO、打字机 UI、NPC 交互 |
|
||
| 16 | [地图系统](./16_MapSystem.md) | 房间元数据、探索/雾战三级显示、全屏地图 UI、小地图 HUD、地图图钉 |
|
||
| 17 | [装备系统](./17_EquipmentSystem.md) | CharmSO、ICharmEffect 接口、Notch 槽位、EquipmentManager、装备 UI、过充咒 |
|
||
| 18 | [过场动画系统](./18_CutsceneSystem.md) | Timeline 规范、CutsceneManager、跳过机制、Signal Track 扩展、字幕轨道 |
|
||
| 19 | [Boss 攻击模式库](./19_BossPatternLibrary.md) | AttackPatternSO、BossPhaseConfigSO、BossOrchestrator、电报系统、5 内置模式 |
|
||
| 20 | [动画事件系统](./20_AnimationEventSystem.md) | AnimancerEvent 注册、AnimationEventConfigSO、FootstepSystem、取消窗口 |
|
||
| 21 | [形态技能系统](./21_SpellSystem.md) | FormSkillSO、SkillManager、形态资源（灵力/魄元/灵泉）、9 种形态技能（天魂/地魂/命魂各3）|
|
||
| 22 | [本地化系统](./22_LocalizationSystem.md) | LanguageManagerSO、StringTable 命名规范、DialogueLocalizationBridge |
|
||
| 23 | [游戏手感调优指南](./23_GameFeelTuningGuide.md) | 移动/跳跃/攻击/弹反/屏幕震动全参数表及调优 SOP |
|
||
| 24 | [地面检测系统](./24_GroundDetectionSystem.md) | BoxCast 地面检测、坡面、土地表面 SO、土狼时间、边缘检测 |
|
||
| 25 | [输入重绑定 UI](./25_InputRebindingUI.md) | RebindPanel、冲突检测、路径→可读字符串、PlayerPrefs 持久化 |
|
||
| 26 | [墙壁力学系统](./26_WallMechanicsSystem.md) | WallGrab（核心默认）、wallGrabY 高度记忆、双类型墙跳（普通/蓄力）、输入锁定 |
|
||
| 27 | [性能预算指南](./27_PerformanceBudgetGuide.md) | 16.6ms 帧预算、GC 限额、对象池公式、物理/动画/UI/音频配置、PR 清单 |
|
||
| 28 | [商店系统](./28_ShopSystem.md) | ShopItemSO、ShopInventorySO、补货时机、购买流程、SaveData 集成 |
|
||
| 29 | [难度模式指南](./29_DifficultyModesGuide.md) | Easy/Normal/Hard/钢铁之魂、DifficultyScalerSO、死亡规则、AI 差异 |
|
||
| 30 | [护盾力学系统](./30_ShieldMechanicsSystem.md) | 独立护盾耐久层、吸收比例、破碎惩罚、自动回充、格挡恢复（P1）|
|
||
| 31 | [SaveData 统一 Schema](./31_SaveDataSchema_Unified.md) | 完整 JSON Schema、C# 数据结构、版本迁移、存档验证、多槽管理 |
|
||
| 32 | [成就系统](./32_AchievementSystem.md) | AchievementSO、条件策略（12 种内置类型）、Toast 通知、成就面板、SaveData 集成 |
|
||
| 33 | [敌人掉落系统](./33_EnemyLootSystem.md) | LootTableSO、概率公式、难度缩放、LootPickup、Boss 必掉、SaveData 集成 |
|
||
| 34 | [事件链系统](./34_EventChainSystem.md) | EventChainSO、条件/动作策略、世界状态级联、EventChainManager、ChainStateRegistry |
|
||
| 35 | [谜题架构](./35_PuzzleArchitecture.md) | ISwitchable/IMovable/IActivatable、PuzzleSwitch、PuzzleReceiver、PuzzleWire（AND/OR/XOR）|
|
||
| 36 | [导航辅助系统](./36_NavigationHintSystem.md) | NavHintSO、WorldMarker、HintNPC 指引、BreadcrumbTracker、地图图钉联动 |
|
||
| 37 | [工具槽系统](./37_ToolSystem.md) | ToolSO、ToolSlotManager（2 槽）、ToolEffect 策略链、5 种内置工具（弹弓/小熊夹/绳索/祛毒药/光晕炸弹）、SaveData 集成 |
|
||
| 38 | [NPC 任务链系统](./38_QuestSystem.md) | QuestSO、5 种目标类型、QuestManager、QuestGiver、多分支条件、好感度集成、SaveData 集成 |
|
||
| 39 | [挑战房间与 Boss Rush](./39_ChallengeRoomSystem.md) | ChallengeRoomSO（5 类型）、BossRushSequenceSO、检查点保护、排行榜、S/A/B/C/F 评级奖励 |
|
||
| 40 | [液态区域与游泳系统](./40_LiquidSwimSystem.md) | LiquidZone（5 液体类型）、SwimState、LiquidPhysicsConfigSO、浮力参数、溺水计时、水下后处理 |
|
||
| 41 | [VFX 架构与 URP 2D 光照](./41_VFXArchitecture.md) | VFXPool、HitFXSpawner、HurtFlash（MPB）、PaletteSwap（形态换色）、Light Layer 规范、后处理 Volume 管理 |
|
||
| 42 | [Debug / 开发者工具](./42_DebugCheatSystem.md) | DebugConsole（控制台命令）、GodMode、Teleport、UnlockAbility、SetFlag、PerfOverlay、QABootstrapper |
|
||
| 43 | [Addressables 工作流指南](./43_AddressablesWorkflow.md) | 新增 Prefab/场景/VFX/SO 到 Addressables 的 Step-by-Step 全流程、Group 组织规范、AddressKeys 维护、常见错误排查 |
|
||
| 44 | [关卡设计指南](./44_LevelDesignGuide.md) | 房间尺寸规范、难度曲线与节奏、敌人布置原则、危险物规范、收集品与秘密房间设计、平台路径参数、房间连通性、视觉叙事、Tilemap SOP、关卡验收清单 |
|
||
| 45 | [教程与情境提示系统](./45_TutorialSystem.md) | ContextualHintTrigger、AbilityTutorialSequence、InGameHintPanel、TooltipPopup、TutorialManager、SaveData 集成（seenHints[]）、多语言支持 |
|
||
| 46 | [平台发布集成指南](./46_PlatformIntegration.md) | IPlatformService 抽象接口、Steam PC/Deck 集成、Steamworks.NET 成就桥接、Steam Cloud 存档同步、Steam Rich Presence、多平台手柄振动适配、构建配置、发布验收清单 |
|
||
| 47 | [Boss 技能系统框架](./47_BossSkillSystem.md) | BossSkillSO 数据层、技能分类体系（BossSkillCategory + InteractionTag）、脆弱窗口系统、玩家反制接口（PlayerCounterResponse）、技能序列系统（SkillSequenceSO）、Boss 资源/愤怒系统、场景联动接口（ArenaEventBus）、平衡数据模板、编辑器工作流 |
|
||
| 48 | [敌人图鉴](./48_EnemyRoster.md) | 5 区域 × 6-7 只普通敌人 + 5 只区域精英怪完整设计、AI 复杂度分级（T1-T4）、弹反标记、掉落表、房间编队配置建议 |
|
||
| 49 | [防软锁系统](./49_AntiSoftlockSystem.md) | SoftlockDetector（45s 无移动检测）、EscapeTeleporter（安全传送回存档点）、RoomEscapeInfoSO（每间房逃生路线）、HardAbilityGate（高风险门扩展）、EscapeGuaranteeValidator（BFS 可达性编辑器工具）|
|
||
| 50 | [叙事设计系统](./50_NarrativeDesignSystem.md) | NarrativeNodeSO 故事节点、WorldStateRegistry 全局状态标志、NarrativeNPC+DialogueVersion 世界状态对话版本、NPCMigrationConfigSO、LoreItemSO（题记/遗物/回忆/回响碎片）、EndingGate 结局评估、5阶段叙事弧线、NPC 迁移路线表 |
|
||
| 51 | [经济平衡设计](./51_EconomyBalanceDesign.md) | 各区域 Geo/min 收入模型、商店定价 L1-L5 层级、升级道具成本效益矩阵、稀有掉落保底机制（20连保底）、EconomyConfigSO、硬核模式经济调整、银行 NPC |
|
||
| 52 | [完成度与结局设计](./52_CompletionEndingDesign.md) | 1000 分完成度追踪系统、CompletionTracker 事件驱动、暂停菜单完成度 UI、NG+1-3 设计（继承规则/新内容/NPC 认知）、EndingDirector（普通/True/隐藏三结局）、隐藏 Boss VoidSentinel、收藏品回廊 |
|
||
| 53 | [武器系统](./53_WeaponSystem.md) | WeaponSO（连击动画 + DamageSource + HitBox 配置）、WeaponManager 形态联动切换、三形态武器规格表、护符武器覆盖（WeaponOverrideEffect）|
|
||
| 54 | [霸体系统](./54_PoiseSystem.md) | PoiseLevel / BreakLevel 枚举、PoiseWindowConfig、IPoiseSource 接口、HurtBox 三层打断判定（PoiseOverrideTable / ForceBreak / 数值比较）、玩家/技能/能力/Boss 霸体配置、全动作霸体参考表、PoiseOverrideTableSO 显式关系配置 |
|
||
| 55 | [遥测与分析系统](./55_AnalyticsTelemetrySystem.md) | GDPR/CCPA 合规设计、匿名 ID、AnalyticsManager + EventQueue、P0/P1 事件目录（死亡热力图/Boss 尝试/能力获取时间线）、本地 Session JSONL 日志、难度调整数据分析、留存关键节点、崩溃上报集成 |
|
||
| 56 | [崩溃恢复系统](./56_CrashRecoverySystem.md) | EmergencySaveService（5分钟自动存档/退出存档）、SaveWriteErrorHandler（原子写入+备份+错误分类）、云存档冲突解决 UI、CrashReporter（Sentry/Unity Cloud Diagnostics）、SaveIntegrityChecker（Checksum+Schema版本检查）|
|
||
| 57 | [物理层矩阵](./57_PhysicsLayerMatrix.md) | 32层完整分配表、碰撞矩阵（Collider/Trigger 区分）、PhysicsMaterial 目录（Stone/Ice/Bounce/Player 等）、Rigidbody2D 使用规范、Trigger vs Collider 决策表、Layers 常量类、Layer CI 验证测试 |
|
||
| 58 | [速通模式系统](./58_SpeedrunModeSystem.md) | RTA/IGT 双计时、IGT 暂停条件定义、SpeedrunTimer SO、速通分类（Any%/True%/100%/NG+）、分段计时（Split）与 PB 存储、SpeedrunHUD、Livesplit TCP 集成、速通合规性设计、社区沟通规范 |
|
||
| 59 | [QA 测试框架](./59_QATestingFramework.md) | 测试金字塔（EditMode/PlayMode 自动化）、关键系统回归清单、平台认证矩阵（Steam/Switch/PS 常见拒审）、Softlock 测试方法论、本地化 QA（文本溢出/字体/字幕同步）、性能基准 SOP（目标帧率/内存上限）、Bug 等级分类、CI/CD 质量门禁 |
|
||
| 60 | [世界观圣经](./60_Lore_WorldBible.md) | 世界时间线（3 纪元 4870 年）、灵素/蚀素规则、5 区域完整历史与 Lore、三祖设定、吞噬者·奥拉动机、泽灵真实身份、碎片系统（25题记+15遗物+5幻境+10回响）、3 结局条件 |
|
||
| 61 | [美术方向圣经](./61_ArtDirection_Bible.md) | 精炼/重量/诗意三关键词、像素规格（PPU=16）、玩家三形态调色板（含色值）、5 区域调色板、光照层次、UI 视觉语言、动画关键帧表、美术验收清单 |
|
||
| 62 | [无障碍功能系统](./62_Accessibility_System.md) | AccessibilitySettingsSO、色盲滤镜（5种模式）、屏幕震动/镜头运动关闭、SFX 字幕、弹反窗口扩展、长按替代连按、单声道/视觉危险提示、平台合规说明 |
|
||
| 63 | [音频创意方向](./63_AudioCreativeDirection.md) | 主旋律系统（泽灵/三祖/奥拉主题）、5区域情感曲线、SFX 世界内在一致性规则、弹反音效专项设计、Boss 战音乐四段结构、作曲参考与禁止方向 |
|
||
| 64 | [NPC 角色设定卡](./64_NPC_CharacterSheets.md) | 商人哈（8状态对话）、长者厄弗（8状态对话）、药师卡洁（4状态）、渡引者西罗（3状态）、流浪研究者米涅（5状态）、NPC 对话写作通用规则 |
|
||
| 65 | [区域视觉语言指南](./65_BiomeVisualGuide.md) | 各区域主题词/颜色锚点/完整调色板/场景层次结构/标志性元素/光照参数（5区域全覆盖）、区域过渡规范、庇护所统一视觉语言 |
|
||
| 66 | [教学关卡流程设计](./66_TeachingLevelFlow.md) | IPVC 四步框架（引入/纯化测试/变化/组合）、移动/攻击/弹反/形态切换/灵力管理教学序列、首个 Boss 前完整教学时间线、失败教学与发现式教学规范 |
|
||
| 67 | [上线后策略](./67_PostLaunchStrategy.md) | 发布后四阶段划分、热更新触发条件（P0-P3）、存档向后兼容迁移系统、v1.1/v1.2/v1.5 版本计划、DLC 规划（前传故事/免费吟游者）、社区运营、玩家行为监测 KPI |
|
||
| 68 | [世界地图蓝图](./68_WorldMapBlueprint.md) | 5区域拓扑结构、9条区域连接通道（FC-A/B、CR-A/B、RA-A/B、AC-A、F-F、C-C）、全部6个能力门控节点、7条捷径（SC-01~07）、6个快速旅行庇护所、全游戏约120间房间的分布规划、收集品密度分布表 |
|
||
| 69 | [Boss 设计圣经](./69_BossDesignBible.md) | 5个Boss全完整设计（卡拉旋/卓格拉/艾尔典/逆吞/奥拉）、每个Boss的设计动词/阶段规格/攻击表（含弹反标注）/相变触发/死亡演出台词、统一设计标准（电报颜色/时机目标/难度缩放）|
|
||
| 70 | [全游戏宏观节奏文档](./70_MacroPacingDocument.md) | 14~18小时总流程、7幕情感结构、各区域时长分配、17节点关键时间线（0:00→17:00）、情感曲线逐区域分析、能力解锁时间线、12个叙事里程碑、难度曲线规则、呼吸节奏公式（C-C-E-C-N-R）|
|
||
| 71 | [主角角色设计](./71_ProtagonistDesign.md) | "传承之躯"真实身份、沉默主角设计哲学（4个理由+6种替代表达方式）、三形态人格框架（天魂/地魂/命魂）、7节点情感弧、5个NPC关系设计（含专属互动动画）、视觉设计规格、体语情感系统、玩家代入设计 |
|
||
| 72 | [区域布局规划](./72_RegionLayoutPlans.md) | 5个区域内部房间拓扑图（森林/洞穴/废墟/深渊/熔炉）、主干+侧枝路径模型、环境叙事密度分布规则、各区域地形设计规范、关键节点设计意图、过渡通道叙事功能、区域布局验收清单 |
|
||
| 73 | [音乐提示单](./73_MusicCueSheet.md) | 自适应5层音乐系统架构、全部曲目清单（区域环境+Boss战+叙事关键时刻+3个结局专用）、5个Boss战完整音乐分段规格（含叙事意图）、自适应层激活/淡出规则、区域切换过渡参数、沉默战略性使用规范 |
|
||
| 74 | [UI 屏幕流程文档](./74_UIScreenFlowDocument.md) | 全游戏UI层次结构流程图、HUD五大元素规格（HP/魂力/形态/道具/小地图）、主菜单/暂停/死亡/大地图/对话/设置全屏幕规格、Boss血条三阶段规格（含奥拉特殊规格）、无障碍设置清单、PC/PS5/Switch三平台差异规格 |
|
||
|
||
---
|
||
|
||
## 快速上手
|
||
|
||
```
|
||
阅读顺序建议:
|
||
00_Overview → 01_InputSystem → 03_PlayerSystem
|
||
↘ 04_CombatSystem → 05_ParrySystem
|
||
↘ 06_EnemySystem
|
||
02_CameraSystem (独立，随时参考)
|
||
07_FeedbackSystem (独立，随时参考)
|
||
08_WorldSystem (场景搭建时参考)
|
||
09_EditorExtensions (编写 Editor 代码时参考)
|
||
|
||
── 游戏整体骨架 ──
|
||
11_GameManager → 10_UISystem
|
||
↘ 12_AudioSystem
|
||
↘ 14_ProgressionSystem
|
||
|
||
── 战斗扩展 ──
|
||
13_ProjectileSystem (弹射物/对象池，配合 04/05/06 阅读)
|
||
|
||
── 世界交互 ──
|
||
15_DialogueSystem (NPC 对话/IInteractable，配合 08 阅读；§13 NPC 好感度)
|
||
16_MapSystem (地图/探索，配合 08 阅读)
|
||
17_EquipmentSystem (魅力/装备，配合 03/04 阅读)
|
||
18_CutsceneSystem (过场动画，配合 11/15 阅读)
|
||
|
||
── 扩展系统 ──
|
||
32_AchievementSystem (成就，配合 04/06/11 阅读)
|
||
33_EnemyLootSystem (敌人掉落，配合 06 阅读)
|
||
34_EventChainSystem (世界状态级联，配合 08/15/18 阅读)
|
||
35_PuzzleArchitecture (环境谜题，配合 08/34 阅读)
|
||
36_NavigationHintSystem (导航提示，配合 16/15 阅读)
|
||
37_ToolSystem (工具槽，配合 03/04 阅读)
|
||
38_QuestSystem (NPC 任务链，配合 15/08 阅读)
|
||
39_ChallengeRoomSystem (挑战房间/Boss Rush，配合 06/04 阅读)
|
||
43_AddressablesWorkflow (新增任何资产时必读)
|
||
```
|
||
|
||
---
|
||
|
||
## 约定说明
|
||
|
||
| 符号 | 含义 |
|
||
|------|------|
|
||
| `SO` 后缀 | ScriptableObject 资产 |
|
||
| `Channel` 后缀 | 事件频道 ScriptableObject（零耦合通信） |
|
||
| `P0 / P1 / P2` | 实现优先级：P0 核心必须，P1 完整体验，P2 丰富度 |
|
||
| `[Editor]` 标注 | 仅在 Editor 模式下使用的功能 |
|
||
|
||
---
|
||
|
||
## 文件夹对应关系
|
||
|
||
```
|
||
Assets/Scripts/
|
||
├── Core/ → 00_Overview · 11_GameManager
|
||
├── Input/ → 01_InputSystem
|
||
├── Camera/ → 02_CameraSystem
|
||
├── Player/ → 03_PlayerSystem
|
||
├── Combat/ → 04_CombatSystem · 13_ProjectileSystem
|
||
├── Parry/ → 05_ParrySystem
|
||
├── Enemies/ → 06_EnemySystem
|
||
├── Feedback/ → 07_FeedbackSystem
|
||
├── World/ → 08_WorldSystem · 15_DialogueSystem · 16_MapSystem
|
||
├── UI/ → 10_UISystem
|
||
├── Audio/ → 12_AudioSystem
|
||
├── Progression/ → 14_ProgressionSystem
|
||
├── Dialogue/ → 15_DialogueSystem
|
||
├── Map/ → 16_MapSystem
|
||
├── Equipment/ → 17_EquipmentSystem
|
||
├── Cutscene/ → 18_CutsceneSystem
|
||
├── Shop/ → 28_ShopSystem
|
||
├── Shield/ → 30_ShieldMechanicsSystem
|
||
├── Tools/ → 37_ToolSystem
|
||
├── Quests/ → 38_QuestSystem
|
||
├── Challenges/ → 39_ChallengeRoomSystem
|
||
├── World/Liquid/ → 40_LiquidSwimSystem
|
||
├── VFX/ → 41_VFXArchitecture
|
||
├── Debug/ → 42_DebugCheatSystem
|
||
├── Core/Addressables/ → 43_AddressablesWorkflow（规范文档，无代码子目录）
|
||
└── Editor/ → 09_EditorExtensions
|
||
```
|