Files
zeling_v2/Docs/Design
joywayerandClaude Opus 5 6d3816d7ef docs(enemy): Boss AI 单轨落地——新增作者指南,清理描述已删除系统的长期文档
新增 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>
2026-07-30 17:14:32 +08:00
..
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-05-08 11:04:00 +08:00
2026-06-08 11:26:17 +08:00

泽灵(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 系统 HUDHP/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、PuzzleWireAND/OR/XOR
36 导航辅助系统 NavHintSO、WorldMarker、HintNPC 指引、BreadcrumbTracker、地图图钉联动
37 工具槽系统 ToolSO、ToolSlotManager2 槽)、ToolEffect 策略链、5 种内置工具(弹弓/小熊夹/绳索/祛毒药/光晕炸弹)、SaveData 集成
38 NPC 任务链系统 QuestSO、5 种目标类型、QuestManager、QuestGiver、多分支条件、好感度集成、SaveData 集成
39 挑战房间与 Boss Rush ChallengeRoomSO5 类型)、BossRushSequenceSO、检查点保护、排行榜、S/A/B/C/F 评级奖励
40 液态区域与游泳系统 LiquidZone5 液体类型)、SwimState、LiquidPhysicsConfigSO、浮力参数、溺水计时、水下后处理
41 VFX 架构与 URP 2D 光照 VFXPool、HitFXSpawner、HurtFlashMPB)、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 技能系统框架 已于 2026-07-30 删除。 该框架从未实现,且已被"Boss 与小怪单轨统一"取代:招式即能力(EnemyAbilitySO),阶段即招池(BossPhaseAbilityGate),决策即 AI 图(EnemyAiBrain)。作者指南见 Docs/Guides/09_BossAi_Authoring_Guide.md
48 敌人图鉴 5 区域 × 6-7 只普通敌人 + 5 只区域精英怪完整设计、AI 复杂度分级(T1-T4)、弹反标记、掉落表、房间编队配置建议
49 防软锁系统 SoftlockDetector45s 无移动检测)、EscapeTeleporter(安全传送回存档点)、RoomEscapeInfoSO(每间房逃生路线)、HardAbilityGate(高风险门扩展)、EscapeGuaranteeValidatorBFS 可达性编辑器工具)
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 崩溃恢复系统 EmergencySaveService5分钟自动存档/退出存档)、SaveWriteErrorHandler(原子写入+备份+错误分类)、云存档冲突解决 UI、CrashReporterSentry/Unity Cloud Diagnostics)、SaveIntegrityCheckerChecksum+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