docs(10-25): 编写高级 II 导览

docs/advanced/ii/index.md

@@ -0,0 +1,118 @@
+# 高级 II 导览
+
+高级 II 是高级教程的第二层，难度标签是「深入定制」。这一层不再只讲「怎么扩展出一个新系统」，而是进入引擎已有的具体系统：范围、图块、装备、录像指令、寻路、属性与战斗上下文。目标很实际：把一个具体系统改到自己的需求上，并且改完之后存档、读档与录像仍然对得上。
+
+这一页说明这一层是给谁的、与高级 I 和高级 III 的区别、需要哪些前置、收录了哪些篇目，以及三条阅读路径。
+
+## 高级 II 是给谁的
+
+高级 II 面向这样的数据端作者：
+
+- 已经理解了绝大多数常用语法，能读懂类、接口、泛型与装饰器的常见写法；
+- 认真阅读样板后，能把一部分简单系统和中等复杂度的系统读明白；
+- 想把某个具体系统改成自己的规则，而不只是调用现成接口。
+
+这一层不预设你是资深引擎开发者，也不要求通读引擎源码。它要求的是能跟着样板找到改动点，并判断改动会不会影响存档与录像。这里仍然只写数据端；引擎编写者的内容属于高级 III。
+
+## 难度层定位
+
+高级教程按难度分三层，而不是按领域分类：
+
+| 层级                  | 难度标签   | 主要内容                                     |
+| --------------------- | ---------- | -------------------------------------------- |
+| 高级 I · 扩展基础     | 扩展基础   | 声明式接口、插件、可存档内容、录像一致性     |
+| 高级 II · 深入定制    | 深入定制   | 范围、图块、装备、录像指令、寻路、属性、战斗 |
+| 高级 III · 原理与架构 | 原理与架构 | 双端分离约束、数据端分层、编辑器协议、性能   |
+
+同一层的篇目可能分散在数据端的不同模块；层与层之间也可能调整主题。判断依据是难度与改动深度，不是模块归属。
+
+高级 III 目前只有代码 span `高级 III · 原理与架构` 这样的占位标记，没有页面入口。本篇不展开原理与架构，只用占位指出归属。
+
+## 前置
+
+高级 II 假设你已经读完高级 I，尤其是下面四篇：
+
+- [声明式 vs 命令式接口](../declarative-vs-imperative.md)：决定你是在声明规则，还是写一次性脚本；
+- [插件系统](../plugin-system.md)：新增系统优先放在插件里，而不是直接改内置；
+- [可存档内容](../saveable-content.md)：新增状态要能进入存档，并在读档后恢复；
+- [录像一致性](../replay-consistency.md)：会改变游戏进程的方法要考虑是否登记录像。
+
+同层的 [data-common 的 Store](../data-stores.md) 与 [钩子深入](../hooks-in-depth.md) 也会被反复引用：前者决定你从哪里读内容定义，后者决定你在什么时机插入行为。
+
+中级教程里的相关篇目同样重要，按主题列在下面：
+
+- 战斗：[光环](../../intermediate/enemy-aura.md)、[查询效果](../../intermediate/enemy-query.md)、[最终属性](../../intermediate/enemy-final.md)、[伤害计算](../../intermediate/enemy-calculator.md)、[地图伤害](../../intermediate/enemy-map-damage.md)；
+- 角色与内容：[勇士属性](../../intermediate/hero-attribute.md)、[勇士装备](../../intermediate/hero-equipment.md)；
+- 地图与流程：[地图图块](../../intermediate/map-tiles.md)、[录像指令](../../intermediate/replay-commands.md)。
+
+没有读过这些篇目也可以从本层开始，但遇到「这个接口原本怎么用」时，应当先回到对应中级篇目补齐，而不是在本层里找重复解释。
+
+## 本层包含什么
+
+本层一共九篇：这一页导览，加上八篇正文。
+
+| 序  | 篇目                                                  | 它能让你做什么                                             | 前置                                    |
+| --- | ----------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------- |
+| 1   | 高级 II 导览                                          | 看清定位、前置与阅读路径，决定先读哪篇                     | 高级 I                                  |
+| 2   | [自定义范围对象](./custom-range.md)                   | 写一个范围对象并绑定宿主，供光环、地图伤害与查询复用       | 高级 I 声明式接口；中级光环、地图伤害   |
+| 3   | [静态图块与动态图块](./static-vs-dynamic-tiles.md)    | 在两种图块之间转换，并安排点事件与图块事件的归属           | 中级地图结构、地图图块                  |
+| 4   | [勇士的装备系统](./equipment-system.md)               | 管理装备实例、实例修饰器、装备槽、对比与排序               | 中级勇士装备、勇士属性；高级 I 可存档   |
+| 5   | [自定义录像指令](./custom-replay-command.md)          | 从指令码、指令对象到注册与沙盒回放，新增一条录像指令       | 高级 I 录像一致性；中级录像指令         |
+| 6   | [自动寻路](./pathfinding.md)                          | 构建寻路图、求解路径、交给移动器，并处理瞬移与钩子         | 中级地图结构、图块事件                  |
+| 7   | [新增勇士属性](./adding-hero-attribute.md)            | 从接口、默认值到伤害计算，完整接入一个勇士属性             | 中级勇士属性；高级 I 可存档、录像一致性 |
+| 8   | [新增怪物属性](./adding-enemy-attribute.md)           | 从接口、数据到伤害、光环、查询与最终效果，接入一个怪物属性 | 中级战斗各篇；本篇的勇士属性对照        |
+| 9   | [怪物上下文与战斗深入](./enemy-context-and-combat.md) | 理解 buildup 的装配顺序、刷新时机、伤害缓存与各机制的交互  | 中级光环、查询、最终属性、伤害计算      |
+
+## 阅读路径
+
+按目标不同，可以走三条路径：
+
+- **系统定制**：范围对象 → 静态图块与动态图块 → 勇士的装备系统 → 新增勇士属性 → 新增怪物属性 → 怪物上下文与战斗深入。适合改造一整套系统，例如给战斗加一层新的属性与范围规则。
+- **行为扩展**：自定义录像指令 → 自动寻路。适合给游戏加一种新的可回放行为，或替换移动与选路策略。
+- **按需查阅**：每篇都单独成立，直接跳到解决当前问题的那一篇即可；篇末的「边界与注意」用于排查改动带来的副作用。
+
+三条路径都建议先读[自定义范围对象](./custom-range.md)。范围对象是光环、地图伤害与查询的共同底座，先理解它，后面几篇里的「扫描哪些格」「命中谁」才不会看混。
+
+## 本层不覆盖什么
+
+- **渲染端与编辑器**：渲染端表现、编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内，相关篇目只用占位说明归属。
+- **高级 III 的原理与架构**：双端分离约束、数据端分层、编辑器识别协议、录像深层原理与性能调优留给高级 III。
+- **API 全量参考**：本层只讲改动链路与关键接口，不做签名清单。
+
+## 优先插件
+
+新增系统优先通过插件承载；只有不得不修改内置系统时，才去改 `packages` 与 `packages-user`。原因是升级成本：`src` 基本不会被上游改动，而内置包会。把改动留在插件里，升级时需要对照的地方少得多。
+
+| 需求类型                       | 优先做法                       | 什么情况下才改内置                     |
+| ------------------------------ | ------------------------------ | -------------------------------------- |
+| 新增一套有状态与生命周期的系统 | 写成插件，在插件里装配对象     | 现有插件只差一个接口或默认值时         |
+| 给已有系统补一条范围或行为     | 注册自己的范围对象、视图或钩子 | 需要替换整套策略、或改动会破坏内置行为 |
+| 新增一个勇士或怪物属性         | 先确认能否用现有修饰器表达     | 属性要参与伤害、光环、查询与存档时     |
+| 新增一条可回放的行为           | 先给已有方法补录像标记         | 行为不在引擎里、录像没有对应指令码时   |
+
+判断标准不是改动多少行，而是改动落在谁的代码里。能由插件或注册项完成的，就留在 `src`；必须动内置包时，尽量把差异收敛在一个方法或一条分支上。
+
+## 怎么验证你读懂了
+
+读完这一层，可以用下面几条自检：
+
+- 能说出范围对象如何绑定宿主，以及为什么绑定后不能跨地图共用同一个实例；
+- 能区分点事件与图块事件，并说明图块移动后哪一种会跟着走；
+- 能解释装备修饰器为什么不进属性存档，以及绕过装备槽直接加修饰器会出什么问题；
+- 能说出录像指令主动与被动的差别，以及回放期间为什么必须禁用录制；
+- 能按顺序画出 buildup 的五段，并指出局部刷新在什么情况下会升级为全量重建。
+
+## 继续阅读
+
+从任意一篇开始：
+
+- [自定义范围对象](./custom-range.md)
+- [静态图块与动态图块](./static-vs-dynamic-tiles.md)
+- [勇士的装备系统](./equipment-system.md)
+- [自定义录像指令](./custom-replay-command.md)
+- [自动寻路](./pathfinding.md)
+- [新增勇士属性](./adding-hero-attribute.md)
+- [新增怪物属性](./adding-enemy-attribute.md)
+- [怪物上下文与战斗深入](./enemy-context-and-combat.md)
+
+返回[高级 I 导览](../index.md)。