docs(10-22): 编写高级 II 自定义录像指令

2026-10-30 04:40:18 +08:00 · 2026-10-21 18:31:46 +08:00 · 2026-10-21 18:31:46 +08:00 · e3c2a455a9
commit e3c2a455a9
parent 6145607b18
1 changed files with 373 additions and 0 deletions
--- a/docs/advanced/ii/custom-replay-command.md
+++ b/docs/advanced/ii/custom-replay-command.md
@ -0,0 +1,373 @@
+# 自定义录像指令
+
+高级 I 的[录像一致性](../replay-consistency.md)讲的是「已有行为该不该记」，回答方式是给方法加 `@shouldReplay`。还有一种情况它覆盖不到：行为本身不在引擎里，录像里没有对应的指令码，回放时根本无从执行。这时需要新增一条录像指令。
+
+本篇讲一条自定义指令从指令码、指令对象、注册、记录到沙盒回放的完整路径。新增指令码会修改 `packages-user` 下的引擎内容，升级时要预期合并成本；如果只是给已有行为补标记，回到[录像一致性](../replay-consistency.md)即可，不必新增指令。
+
+## 什么时候需要自定义指令
+
+判断标准回到那条核心原则：玩家直接产生、会影响最终成绩的行为必须可复现。
+
+- 行为已经由引擎内置指令覆盖（移动、瞬移、使用道具、装备、卸下），只缺记录，补 `@shouldReplay` 与 `record`。
+- 行为是玩家操作，但引擎没有对应指令（技能、商店交易、自定义交互），需要一条新指令，让回放时能把这一步重新执行。
+
+中级教程的[录像指令](../../intermediate/replay-commands.md)已经讲过主动与被动、`IReplayCommand` 的主体结构；本篇不重复这些，直接进入「怎么把一条新指令接进引擎」。
+
+## 指令码是格式的一部分
+
+`ReplayCode` 是 `packages-user/data-common/src/replay/types.ts` 里的 `const enum`。它的数值会写进录像的命令数组，属于录像格式的一部分，因此遵循只增不改：新语义必须分配新值，删除或用旧值表示新语义都会让旧录像读错。
+
+```ts
+/** 录像指令码，数值属于录像格式的一部分 */
+export const enum ReplayCode {
+    /** 向上移动一步 */
+    Up,
+    /** 向右移动一步 */
+    Right,
+    /** 向下移动一步 */
+    Down,
+    /** 向左移动一步 */
+    Left,
+    /** 自动寻路瞬移至目标点 */
+    Teleport,
+    /** 使用道具 */
+    UseItem,
+    /** 装备物品 */
+    Equip,
+    /** 卸下装备 */
+    Unequip,
+    /** 使用技能（本篇新增） */
+    UseSkill
+}
+```
+
+新增一项意味着修改 `packages-user` 的引擎内容，而不是只改 `src`。`registerCommand` 收的是普通 `number`，跳过枚举直接写数字也能注册；但引擎之后分配新码时可能撞号，所以正式做法仍然是在枚举末尾追加。
+
+指令码的取值还受位宽限制。默认的 `ReplayCommandWidth.Uint8` 只支持 `0–255`，超出后写入会被截断。需要更多指令码时，要切到 `ReplayCommandWidth.Uint16`（`0–65535`）；这是录像格式的变更，已保存的录像会带上当时的位宽，不能假设新旧录像可以混用。
+
+## 指令对象
+
+一条指令实现 `IReplayCommand`：
+
+| 成员            | 作用                                            |
+| --------------- | ----------------------------------------------- |
+| `type`          | `ReplayCommandType.Active` 或 `Passive`         |
+| `execute(step)` | 执行这一步，返回 `Promise<ReplayCommandResult>` |
+| `finalize?()`   | 连续多步同一指令结束时统一收尾；可选            |
+
+`step` 提供 `command`（指令码）、`params`（参数列表）与 `index`（读取流给出的步索引）。返回值 `ReplayCommandResult` 有三种：
+
+- `Success`：这一步成功，继续播放；
+- `Failed`：这一步失败，播放中止；
+- `Ignored`：失败但可以忽略，控制台输出信息后继续。
+
+`finalize` 在两种时机被调用：下一步换了另一条指令，或整条录像已经播完。它没有参数，因此需要跨步保存的数据要放在指令对象的成员里。典型用途是「连续多步移动后，统一启动一次动画」：每步只更新目标，最后一步结束时再提交。
+
+## 主动录像与被动录像
+
+`ReplayCommandType.Active` 的指令自己执行逻辑，是最常见的形式。内置的移动、瞬移、使用道具、装备都是主动录像。
+
+`ReplayCommandType.Passive` 的指令不执行任何逻辑。沙盒在主动步执行期间把下一步暴露给 `IReplaySandbox.getPassive()`，由外部取走参数，处理完后调用 `next(status)` 才会推进。适合「需要渲染端配合、耗时不可预测」的行为：数据端只负责给出参数，什么时候处理完由外部决定。
+
+被动步必须紧跟在某个主动步之后，并在那个主动步结束前被取走。没有及时消费的被动步会被沙盒跳过，并输出告警。被动步对应的指令对象仍然要注册，沙盒要靠它判断 `type`；但它的 `execute` 不会被调用。
+
+渲染端的播放表现按渲染端教程处理，本篇只写数据端。 <!-- TODO(renderer): 被动录像的渲染端消费 -->
+
+## 用基类减少样板
+
+`src/data/replay/commands.ts` 里的 `BaseReplayCommand` 已经实现了参数校验：它按 `paramTypes` 检查参数个数与 `typeof` 结果，不匹配时直接返回 `Failed`，不会进入子类逻辑。子类只需要提供：
+
+- `name`：写进错误信息的指令名；
+- `paramTypes`：参数类型名数组，取值只能是 `'number'`、`'string'`、`'boolean'`、`'bigint'`；
+- `wrappedExecute(step)`：真正的执行逻辑，不需要再校验参数类型。
+
+下面是一条 `ReplayUseSkill`：参数为 `[number skillId, number x, number y]`，技能不可用时返回 `Failed`。
+
+```ts
+import {
+    IReplayStepHandler,
+    ReplayCommandResult,
+    ReplayCommandType
+} from '@user/data-common';
+import { IStateSystem } from '@user/data-system';
+import { BaseReplayCommand } from './commands';
+
+/** 技能服务：由作者自己的技能系统实现，引擎不内置 */
+export interface ISkillService {
+    /** 判断技能能否在目标点使用 */
+    canUse(skillId: number, x: number, y: number): boolean;
+    /** 执行技能效果；回放时也走这里，注意不要在这里写录像 */
+    apply(skillId: number, x: number, y: number): void;
+}
+
+/**
+ * 使用技能。
+ * 参数顺序必须与 paramTypes 一致：技能 id、目标横坐标、目标纵坐标。
+ */
+export class ReplayUseSkill extends BaseReplayCommand {
+    readonly type: ReplayCommandType = ReplayCommandType.Active;
+
+    protected readonly name: string = 'use-skill';
+    protected readonly paramTypes: readonly string[] = [
+        'number',
+        'number',
+        'number'
+    ];
+
+    constructor(
+        state: IStateSystem,
+        private readonly skills: ISkillService
+    ) {
+        super(state);
+    }
+
+    async wrappedExecute(
+        step: IReplayStepHandler
+    ): Promise<ReplayCommandResult> {
+        // 参数已由基类校验过，这里可以直接断言类型
+        const [skillId, x, y] = step.params as [number, number, number];
+
+        // 技能不可用时不继续播放，避免后续步骤建立在错误状态上
+        if (!this.skills.canUse(skillId, x, y)) {
+            return ReplayCommandResult.Failed;
+        }
+
+        this.skills.apply(skillId, x, y);
+        return ReplayCommandResult.Success;
+    }
+}
+```
+
+`BaseReplayCommand` 的 `execute` 会先校验参数再调用 `wrappedExecute`。因此不要在 `wrappedExecute` 里重复写 `typeof` 判断；参数个数或类型错了，基类已经返回 `Failed`。
+
+如果技能效果是异步的，要在 `wrappedExecute` 里 `await` 完再返回 `Success`，否则后续录像步可能在效果完成前就开始执行。
+
+## 注册
+
+指令必须在沙盒开始播放之前注册。沙盒每一步都通过 `state.replaySystem.getCommand(code)` 查表；查不到时告警并中止播放。
+
+内置指令在 `src/data/replay/initialize.ts` 的 `initializeReplay` 中注册。新增一条指令，就在同一个函数里加一行：
+
+```ts
+import { ReplayCode } from '@user/data-common';
+import { IDataPluginDefine, ICoreState } from '@user/data-state';
+import { ISkillService, ReplayUseSkill } from './commands';
+
+/**
+ * 技能插件：既提供技能服务，也具备数据端插件生命周期。
+ * 如果你的技能系统不是插件，换成自己的取得方式即可。
+ */
+export interface ISkillPlugin extends IDataPluginDefine, ISkillService {}
+
+/**
+ * 初始化录像指令。
+ * 注册必须发生在第一次创建沙盒之前。
+ */
+export function initializeReplay(state: ICoreState): void {
+    const replay = state.replaySystem;
+
+    // ...内置指令的注册保持不变
+
+    const skillPlugin = state.getDataPlugin<ISkillPlugin>('skill');
+    if (skillPlugin) {
+        replay.registerCommand(
+            ReplayCode.UseSkill,
+            new ReplayUseSkill(state, skillPlugin.plugin)
+        );
+    }
+}
+```
+
+同一指令码只能注册一次。重复注册会告警（code 163）并保留先注册的对象，后注册的不会生效；因此不要在插件初始化与主初始化里各注册一遍。
+
+如果技能系统不是插件，就换成你自己的取得方式；只要保证注册发生在第一次 `createReplaySandbox` 之前即可。
+
+## 记录
+
+注册只让回放认识这条指令，录制仍要在行为入口写入。高级 I 已经讲过 `@shouldReplay` 的规则，这里只给与自定义指令配合的写法：
+
+```ts
+import { ReplayCode, shouldReplay } from '@user/data-common';
+import { ICoreState } from '@user/data-state';
+
+/** 技能系统：玩家入口写录像，回放入口只执行效果 */
+export class SkillSystem implements ISkillService {
+    constructor(private readonly state: ICoreState) {}
+
+    canUse(skillId: number, x: number, y: number): boolean {
+        // ...判断技能是否可用
+        return true;
+    }
+
+    @shouldReplay('Using a skill should be replayed.')
+    use(skillId: number, x: number, y: number): void {
+        if (!this.canUse(skillId, x, y)) return;
+
+        // 先记录，再执行；参数顺序必须与 paramTypes 一致
+        this.state.replaySystem.record(ReplayCode.UseSkill, skillId, x, y);
+        this.apply(skillId, x, y);
+    }
+
+    apply(skillId: number, x: number, y: number): void {
+        // ...真正的技能效果；回放时由 ReplayUseSkill 调用这里
+    }
+}
+```
+
+把「记录 + 执行」的玩家入口与「只执行」的回放入口分开，可以避免同一次技能被记两遍。如果某个被动触发的路径会调用带记录的入口，用 `disable()` 与 `revert()` 把那段包住，并且必须配对。
+
+## 沙盒播放
+
+`createReplaySandbox` 创建播放沙盒：
+
+```ts
+import { IReplayArray, IStateReseter } from '@user/data-common';
+import { ICoreState } from '@user/data-state';
+
+/**
+ * 演示用重置器：把游戏恢复到录像开始前的状态。
+ * 恢复逻辑由项目的新游戏或读档入口提供，通过构造函数注入。
+ */
+export class ReplayReseter implements IStateReseter {
+    constructor(
+        private readonly restore: (save?: Map<string, unknown>) => void
+    ) {}
+
+    reset(save?: Map<string, unknown>): void {
+        // 传入存档时恢复到该存档；不传时回到新游戏初始状态
+        this.restore(save);
+    }
+}
+
+/**
+ * 播放一条录像。
+ * restore 由项目自己的读档或新游戏流程实现。
+ */
+async function playReplay(
+    state: ICoreState,
+    route: IReplayArray,
+    restore: (save?: Map<string, unknown>) => void
+): Promise<void> {
+    const replay = state.replaySystem;
+
+    // 从创建沙盒开始就禁用录制：
+    // 创建时会立刻重置状态，播放时还会执行各条指令，这些都不应写回录像
+    replay.disable();
+    try {
+        // 创建沙盒时会立刻调用 reseter.reset(save)，把状态恢复到起始点
+        const sandbox = replay.createReplaySandbox({
+            route,
+            reseter: new ReplayReseter(restore),
+            // 从第几步开始播放，默认为 0
+            startIndex: 0
+        });
+
+        // 先挂结束钩子，再开始播放
+        const stopped = new Promise<void>(resolve => {
+            sandbox.addHook({ onStopReplay: () => resolve() });
+        });
+
+        sandbox.play();
+        await stopped;
+    } finally {
+        replay.revert();
+        replay.releaseSandbox();
+    }
+}
+```
+
+`reseter` 负责把游戏状态重置到录像的起点；不重置的话，回放会叠加在当前状态上，结果与原始游玩对不上。`createReplaySandbox` 在创建时就会调用一次 `reset`，不是在 `play` 时。
+
+播放控制由 `IReplaySandbox` 提供：
+
+| 成员            | 作用                                            |
+| --------------- | ----------------------------------------------- |
+| `play()`        | 连续播放                                        |
+| `step()`        | 单步播放，返回该步是否成功                      |
+| `pause()`       | 暂停，返回的 Promise 在真正暂停后兑现           |
+| `resume()`      | 从暂停恢复                                      |
+| `stop()`        | 停止播放                                        |
+| `getReplayed()` | 已读取的录像步数量，不含当前正在播放的一步      |
+| `pausing`       | 是否处于暂停状态                                |
+| `ended`         | 是否已经播放完毕                                |
+| `playing`       | 是否处于播放状态                                |
+| `getPassive()`  | 取下一步的被动录像参数，不是被动步时返回 `null` |
+
+`ended` 由连续播放的循环在结束时置为 `true`。只用 `step()` 一步步走到末尾时，沙盒会完成 `finalize` 并停止推进，但不会因此设置 `ended`；需要观察结束状态时，用 `play()` 或 `resume()` 跑完循环。
+
+`onStep` 钩子可以在每一步完成后观察进度。它接收当前步的 `command`、`params` 与 `index`；`step()` 与连续播放都会触发。
+
+## 怎么验证
+
+先准备固定地图与固定英雄属性；技能依赖地图时，这一步不能省。然后构造一条只含 `UseSkill` 的录像，分别验证单步与连续播放：
+
+```ts
+import { IReplayArray, IReplaySandbox, IStateReseter } from '@user/data-common';
+import { ReplayCode } from '@user/data-common';
+import { ICoreState } from '@user/data-state';
+
+/** 等待沙盒自然结束。 */
+function waitForReplayEnd(sandbox: IReplaySandbox): Promise<void> {
+    return new Promise(resolve => {
+        sandbox.addHook({ onStopReplay: () => resolve() });
+    });
+}
+
+/**
+ * 验证 UseSkill：技能 1，目标 (5, 6)。
+ * reseter 由调用方提供，负责把状态恢复到录像起点。
+ */
+async function verifyUseSkill(
+    state: ICoreState,
+    route: IReplayArray,
+    reseter: IStateReseter
+): Promise<void> {
+    const replay = state.replaySystem;
+
+    // 只放一条技能录像
+    route.add(ReplayCode.UseSkill, [1, 5, 6]);
+
+    // 单步：确认这一步执行成功，且读取进度为 1
+    replay.disable();
+    try {
+        const single = replay.createReplaySandbox({ route, reseter });
+        const ok = await single.step();
+        console.log('单步结果', ok, '已播放', single.getReplayed());
+    } finally {
+        replay.revert();
+        replay.releaseSandbox();
+    }
+
+    // 连续播放：确认能自然结束
+    replay.disable();
+    try {
+        const player = replay.createReplaySandbox({ route, reseter });
+        const stopped = waitForReplayEnd(player);
+        player.play();
+        await stopped;
+        console.log('是否结束', player.ended);
+    } finally {
+        replay.revert();
+        replay.releaseSandbox();
+    }
+}
+```
+
+预期现象：
+
+- 单步调用返回 `true`，`getReplayed()` 为 `1`，技能效果（例如目标怪物掉血、勇士属性变化）已经发生；
+- 连续播放能走到结束，`ended` 为 `true`；
+- 整个过程中录像长度不变；若变长，说明播放期间没有禁用录制。
+
+## 边界与注意
+
+- **不要复用已删除的旧指令码**：数值属于录像格式，旧录像会按旧值解码。新语义一律追加新值。
+- **`Uint8` 下不要超过 255**：写入会截断，产生无法回放的录像。需要更多码时切 `Uint16`，并把它当成格式变更处理。
+- **参数类型必须与 `paramTypes` 一致**：只支持 `number`、`string`、`boolean`、`bigint`。传对象等无法编码的值会被丢弃，参数个数随之变化，基类会判为失败。
+- **被动步忘记 `next` 会卡住**：沙盒不会自己推进；重复调用 `getPassive()` 会得到同一步。被动步没有在主动步期间取走时，会被跳过并告警。
+- **`finalize` 返回 `Failed` 会中止播放**：它和 `execute` 一样会中断后续步骤，不要在里面吞掉错误。
+- **重复注册不会覆盖**：同一指令码重复注册会告警（code 163）并保留先注册的对象。确认注册只发生一次。
+- **未知指令码会中止播放**：沙盒查不到指令时告警并停止，不会跳过继续。
+- **播放期间必须禁用录制**：否则回放执行的行为会写回同一条录像，并让读取流过期。用 `disable()` 与 `revert()` 包住播放，且保证配对。
+- **不要在播放期间修改 `route`**：追加、插入或删除都会让读取流过期，播放随即停止。
+- **`finalize` 需要跨步状态**：它没有参数，连续步骤的信息只能保存在指令对象的成员里；指令对象在注册时创建一次，之后复用。