template/docs/advanced/ii/index.md

高级 II 导览

高级 II 是高级教程的第二层，难度标签是「深入定制」。这一层不再只讲「怎么扩展出一个新系统」，而是进入引擎已有的具体系统：范围、图块、装备、录像指令、寻路、属性与战斗上下文。目标很实际：把一个具体系统改到自己的需求上，并且改完之后存档、读档与录像仍然对得上。

这一页说明这一层是给谁的、与高级 I 和高级 III 的区别、需要哪些前置、收录了哪些篇目，以及三条阅读路径。

高级 II 是给谁的

高级 II 面向这样的数据端作者：

• 已经理解了绝大多数常用语法，能读懂类、接口、泛型与装饰器的常见写法；
• 认真阅读样板后，能把一部分简单系统和中等复杂度的系统读明白；
• 想把某个具体系统改成自己的规则，而不只是调用现成接口。

这一层不预设你是资深引擎开发者，也不要求通读引擎源码。它要求的是能跟着样板找到改动点，并判断改动会不会影响存档与录像。这里仍然只写数据端；引擎编写者的内容属于高级 III。

难度层定位

高级教程按难度分三层，而不是按领域分类：

层级	难度标签	主要内容
高级 I · 扩展基础	扩展基础	声明式接口、插件、可存档内容、录像一致性
高级 II · 深入定制	深入定制	范围、图块、装备、录像指令、寻路、属性、战斗
高级 III · 原理与架构	原理与架构	双端分离约束、数据端分层、编辑器协议、性能

同一层的篇目可能分散在数据端的不同模块；层与层之间也可能调整主题。判断依据是难度与改动深度，不是模块归属。

高级 III 尚未编写。本层正文只在需要时用 高级 III · <topic> 这样的代码 span 或 <!-- TODO(advanced-III) --> 标出归属，不会写成真实链接；等该层建立后再替换。

前置

高级 II 假设你已经读完高级 I，尤其是下面四篇：

• 声明式 vs 命令式接口：决定你是在声明规则，还是写一次性脚本；
• 插件系统：新增系统优先放在插件里，而不是直接改内置；
• 可存档内容：新增状态要能进入存档，并在读档后恢复；
• 录像一致性：会改变游戏进程的方法要考虑是否登记录像。

同层的 data-common 的 Store 与 钩子深入 也会被反复引用：前者决定你从哪里读内容定义，后者决定你在什么时机插入行为。

中级教程里的相关篇目同样重要，按主题列在下面：

• 战斗：光环、查询效果、最终属性、伤害计算、地图伤害；
• 角色与内容：勇士属性、勇士装备；
• 地图与流程：地图图块、录像指令。

没有读过这些篇目也可以从本层开始，但遇到「这个接口原本怎么用」时，应当先回到对应中级篇目补齐，而不是在本层里找重复解释。

本层包含什么

本层一共十篇：这一页导览，加上九篇正文。

序	篇目	它能让你做什么	前置
1	高级 II 导览	看清定位、前置与阅读路径，决定先读哪篇	高级 I
2	自定义范围对象	写一个范围对象并绑定宿主，供光环、地图伤害与查询复用	高级 I 声明式接口；中级光环、地图伤害
3	静态图块与动态图块	在两种图块之间转换与移动，理解 keepEvent 的取舍	中级地图结构、地图图块
4	点事件与图块事件	区分两类事件的归属，安排它们跟随移动与存档恢复	静态图块与动态图块
5	勇士的装备系统	管理装备实例、实例修饰器、装备槽、对比与排序	中级勇士装备、勇士属性；高级 I 可存档
6	自定义录像指令	从指令码、指令对象到注册与沙盒回放，新增一条录像指令	高级 I 录像一致性；中级录像指令
7	自动寻路	构建寻路图、求解路径、交给移动器，并处理瞬移与钩子	中级地图结构、图块事件
8	新增勇士属性	从接口、默认值到伤害计算，完整接入一个勇士属性	中级勇士属性；高级 I 可存档、录像一致性
9	新增怪物属性	从接口、数据到伤害、光环、查询与最终效果，接入一个怪物属性	中级战斗各篇；本篇的勇士属性对照
10	怪物上下文与战斗深入	理解 buildup 的装配顺序、刷新时机、伤害缓存与各机制的交互	中级光环、查询、最终属性、伤害计算

阅读路径

按目标不同，可以走三条路径：

• 系统定制：范围对象 → 静态图块与动态图块 → 点事件与图块事件 → 勇士的装备系统 → 新增勇士属性 → 新增怪物属性 → 怪物上下文与战斗深入。适合改造一整套系统，例如给战斗加一层新的属性与范围规则。
• 行为扩展：自定义录像指令 → 自动寻路。适合给游戏加一种新的可回放行为，或替换移动与选路策略。
• 按需查阅：每篇都单独成立，直接跳到解决当前问题的那一篇即可；篇末的「边界与注意」用于排查改动带来的副作用。

三条路径都建议先读自定义范围对象。范围对象是光环、地图伤害与查询的共同底座，先理解它，后面几篇里的「扫描哪些格」「命中谁」才不会看混。

本层不覆盖什么

• 渲染端与编辑器：渲染端表现、编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内，相关篇目只用占位说明归属。
• 高级 III 的原理与架构：双端分离约束、数据端分层、编辑器识别协议、录像深层原理与性能调优留给高级 III。
• API 全量参考：本层只讲改动链路与关键接口，不做签名清单。

优先插件与改内置的边界

新增系统优先通过插件承载；只有不得不修改内置系统时，才去改 packages 与 packages-user。原因是升级成本：src 基本不会被上游改动，而内置包会。把改动留在插件里，升级时需要对照的地方少得多。

本层有几处只能改 packages-user，因为它们是接口或录像格式本身，插件没有扩展点：

• 给 IHeroAttr / IEnemyAttr 增加字段（类型定义在 packages-user/data-common/src/types.ts）；
• 追加 ReplayCode（录像格式的一部分）；
• 补 HERO_DEFAULT_ATTRIBUTE，以及需要随接口一起更新的默认值常量。

这些改动应在满足需求的前提下尽量小，只加字段、只追加枚举值，不要顺手改内置逻辑。除此之外，本层反复出现的范围、光环、查询、最终效果、录像指令注册与钩子都优先走注册或插件，不直接改内置实现。

需求类型	优先做法	什么情况下才改内置
新增一套有状态与生命周期的系统	写成插件，在插件里装配对象	现有插件只差一个接口或默认值时
给已有系统补一条范围或行为	注册自己的范围对象、视图或钩子	需要替换整套策略、或改动会破坏内置行为
新增一个勇士或怪物属性	先确认能否用现有修饰器表达	接口字段只能加在 packages-user 的类型里
新增一条可回放的行为	先给已有方法补录像标记	行为不在引擎里、录像没有对应指令码时

判断标准不是改动多少行，而是改动落在谁的代码里。能由插件或注册项完成的，就留在 src；必须动内置包时，尽量把差异收敛在一个字段、一个枚举值或一条分支上。

怎么验证你读懂了

读完这一层，可以用下面几条自检：

• 能说出范围对象如何绑定宿主，以及为什么绑定后不能跨地图共用同一个实例；
• 能区分点事件与图块事件，并说明图块移动后哪一种会跟着走；
• 能解释装备修饰器为什么不进属性存档，以及绕过装备槽直接加修饰器会出什么问题；
• 能说出录像指令主动与被动的差别，以及回放期间为什么必须禁用录制；
• 能按顺序画出 buildup 的五段，并指出局部刷新在什么情况下会升级为全量重建。

继续阅读

从任意一篇开始：

• 自定义范围对象
• 静态图块与动态图块
• 点事件与图块事件
• 勇士的装备系统
• 自定义录像指令
• 自动寻路
• 新增勇士属性
• 新增怪物属性
• 怪物上下文与战斗深入

返回高级 I 导览。