chore: initial commit

Docs/Design/README.md

@@ -0,0 +1,172 @@
+# 泽灵（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
+```