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