《游戏引擎实现原理》7.3 模块替换与状态迁移

// file: src/subsys/script/module-state.ts
// tier: L1
// verify: npx vitest run src/subsys/script/module-state.test.ts
//
// helio 脚本子系统：模块替换的状态迁移（数据路径）。
// 本节不承诺真正的 HMR——只做「模块边界 + 数据 / 代码分离 + 状态迁移」：
// 可替换模块把状态导出成纯数据 + 版本戳，替换时旧状态沿迁移链升到新版本，
// 再灌进新模块实例。代码怎么换是运行时的活，状态怎么搬才是这里要跑通的。

/** 模块对外的状态契约：纯数据 + 版本戳，不含函数 / 类实例 / 循环引用。 */
export interface ModuleState {
  readonly version: number;
  readonly data: Record<string, unknown>;
}

/** 可热替换模块：能导出当前状态，也能从状态恢复。 */
export interface ReplaceableModule {
  readonly name: string;
  readonly version: number;
  captureState(): ModuleState;
  restoreState(state: ModuleState): void;
}

/** 一步迁移：把某版本的数据改成下一版本。 */
export type StateMigration = (data: Record<string, unknown>) => Record<string, unknown>;

/** 迁移链：登记 v -> v+1 的迁移，沿链把数据升到目标版本。 */
export class StateMigrationChain {
  #steps = new Map<number, StateMigration>();

  add(from: number, step: StateMigration): void {
    if (this.#steps.has(from)) throw new Error(`Duplicate migration from v${from}`);
    this.#steps.set(from, step);
  }

  /** 从 fromVersion 逐级升到 toVersion；缺环即抛错，绝不静默降级。 */
  upgrade(
    data: Record<string, unknown>,
    fromVersion: number,
    toVersion: number,
  ): { data: Record<string, unknown>; applied: string[] } {
    if (fromVersion > toVersion) {
      throw new Error(`Cannot downgrade state: v${fromVersion} -> v${toVersion}`);
    }
    let cur = { ...data };
    const applied: string[] = [];
    for (let v = fromVersion; v < toVersion; v++) {
      const step = this.#steps.get(v);
      if (step === undefined) throw new Error(`No migration from v${v} to v${v + 1}`);
      cur = step(cur);
      applied.push(`${v}->${v + 1}`);
    }
    return { data: cur, applied };
  }
}

/** 深拷贝：用 structuredClone 保证导出的是快照而非活引用。 */
function cloneState(data: Record<string, unknown>): Record<string, unknown> {
  return structuredClone(data);
}

/**
 * 用旧模块的状态换上新模块的代码：
 * 1. 导出旧状态（深拷贝，隔离活引用）；2. 沿链升到新模块版本；
 * 3. 灌进新模块实例；4. 返回新状态与实际走过的迁移链。
 */
export function replaceModule(
  old: ReplaceableModule,
  next: ReplaceableModule,
  chain: StateMigrationChain,
): { state: ModuleState; applied: string[] } {
  const captured = old.captureState();
  const { data, applied } = chain.upgrade(
    cloneState(captured.data),
    captured.version,
    next.version,
  );
  const state: ModuleState = { version: next.version, data };
  next.restoreState(state);
  return { state, applied };
}

// file: src/subsys/script/module-state.test.ts
// tier: L1
// verify: npx vitest run src/subsys/script/module-state.test.ts
import { describe, expect, it } from 'vitest';
import {
  StateMigrationChain,
  replaceModule,
  type ModuleState,
  type ReplaceableModule,
} from './module-state.ts';

/** v1 的伤害模块：字段 count / step。 */
class DamageV1 implements ReplaceableModule {
  readonly name = 'damage';
  readonly version = 1;
  count = 0;
  step = 10;
  captureState(): ModuleState {
    return { version: this.version, data: { count: this.count, step: this.step } };
  }
  restoreState(s: ModuleState): void {
    this.count = s.data.count as number;
    this.step = s.data.step as number;
  }
}

/** v2：step 改名 stepSize，新增 paused。 */
class DamageV2 implements ReplaceableModule {
  readonly name = 'damage';
  readonly version = 2;
  count = 0;
  stepSize = 0;
  paused = false;
  captureState(): ModuleState {
    return { version: this.version, data: { count: this.count, stepSize: this.stepSize, paused: this.paused } };
  }
  restoreState(s: ModuleState): void {
    this.count = s.data.count as number;
    this.stepSize = s.data.stepSize as number;
    this.paused = s.data.paused as boolean;
  }
}

/** 一条从 v1 到 v2 的迁移：step -> stepSize，补 paused=false。 */
function v1to2(): StateMigrationChain {
  const chain = new StateMigrationChain();
  chain.add(1, (d) => ({ count: d.count, stepSize: d.step, paused: false }));
  return chain;
}

describe('迁移链', () => {
  it('逐级升级并记录走过的链', () => {
    const chain = new StateMigrationChain();
    chain.add(1, (d) => ({ ...d, b: 1 }));
    chain.add(2, (d) => ({ ...d, c: 2 }));
    const r = chain.upgrade({ a: 0 }, 1, 3);
    expect(r.data).toEqual({ a: 0, b: 1, c: 2 });
    expect(r.applied).toEqual(['1->2', '2->3']);
  });

  it('缺环抛错，不静默跳过；降级被拒绝', () => {
    const chain = new StateMigrationChain();
    chain.add(1, (d) => d);
    expect(() => chain.upgrade({}, 1, 3)).toThrow(/No migration from v2/);
    expect(() => chain.upgrade({}, 3, 1)).toThrow(/Cannot downgrade/);
  });
});

describe('模块替换', () => {
  it('v1 -> v2：字段改名与新增都被迁移', () => {
    const old = new DamageV1();
    old.count = 5;
    old.step = 25;
    const next = new DamageV2();
    const { state, applied } = replaceModule(old, next, v1to2());
    expect(applied).toEqual(['1->2']);
    expect(state.version).toBe(2);
    expect(next.count).toBe(5);
    expect(next.stepSize).toBe(25);
    expect(next.paused).toBe(false);
  });

  it('导出的是快照：替换后改旧模块不影响新模块', () => {
    const old = new DamageV1();
    old.count = 1;
    const next = new DamageV2();
    const { state } = replaceModule(old, next, v1to2());
    old.count = 999; // 旧模块继续活着也不该污染已迁走的状态
    expect(next.count).toBe(1);
    expect(state.data.count).toBe(1);
  });

  it('同版本替换：零迁移，状态原样搬过去', () => {
    const old = new DamageV2();
    old.count = 3;
    old.stepSize = 7;
    old.paused = true;
    const next = new DamageV2();
    const { applied } = replaceModule(old, next, v1to2());
    expect(applied).toEqual([]);
    expect(next.count).toBe(3);
    expect(next.stepSize).toBe(7);
    expect(next.paused).toBe(true);
  });

  it('captureState 结果可 structuredClone（无函数 / 类实例泄漏）', () => {
    const st = new DamageV1().captureState();
    expect(() => structuredClone(st)).not.toThrow();
    expect(JSON.stringify(st)).toContain('"step":10');
  });
});

// file: src/subsys/script/module-reloader.ts
// tier: L4
//
// 真实模块替换的时序：给模块 URL 加版本戳绕开缓存，用动态 import() 重新拉取，
// 拉回后用 replaceModule 把旧状态迁到新模块实例上。
// 它依赖浏览器的模块加载器与缓存行为——命令行不可复现，
// 需在浏览器中手动验证（本文件仅通过 tsc 类型检查，不在 Node 里运行）。

import {
  StateMigrationChain,
  replaceModule,
  type ReplaceableModule,
} from './module-state.ts';

/** 从拉回来的模块命名空间里造出一个可替换模块实例。 */
export type ModuleFactory = (mod: unknown) => ReplaceableModule;

export interface ReloadResult {
  /** 实际走过的迁移链，如 ["1->2"]。 */
  readonly applied: string[];
  readonly version: number;
  /** 拉取 + 迁移 + 换上花掉的墙钟毫秒（浏览器实测，命令行不可复现）。 */
  readonly elapsedMs: number;
}

/** 模块替换器：持有当前实例与迁移链，负责「拉新的 + 迁状态」。 */
export class ModuleReloader {
  #current: ReplaceableModule;
  readonly #chain: StateMigrationChain;
  #stamp = 0;

  constructor(initial: ReplaceableModule, chain: StateMigrationChain) {
    this.#current = initial;
    this.#chain = chain;
  }

  get current(): ReplaceableModule {
    return this.#current;
  }

  /**
   * 重新加载模块：给 URL 追加 ?v=<stamp> 绕开浏览器缓存，动态 import 回来，
   * 用 factory 造实例，再把旧状态迁过去。stamp 单调递增，保证每次都是新 URL。
   */
  async reload(url: string, factory: ModuleFactory): Promise<ReloadResult> {
    const t0 = performance.now();
    this.#stamp++;
    const sep = url.includes('?') ? '&' : '?';
    const stamped = `${url}${sep}v=${this.#stamp}`;
    const mod: unknown = await import(/* @vite-ignore */ stamped);
    const next = factory(mod);
    const { state, applied } = replaceModule(this.#current, next, this.#chain);
    this.#current = next;
    return { applied, version: state.version, elapsedMs: performance.now() - t0 };
  }
}