《游戏引擎实现原理》8.1 编辑器与运行时的关系

// file: src/editor/play-mode.ts
// tier: L1
// verify: npx vitest run src/editor/play-mode.test.ts
//
// helio 编辑器：编辑态与运行态的关系，以及预览（Play / Pause / Resume / Stop）。
// 编辑器与运行时共用同一种场景数据形状（同一份数据模型），但各持一份实例：
// 进入 Play 时对编辑态文档做深拷贝，运行时只改自己的副本，Stop 后编辑态原样恢复。
// 只属于编辑器的状态（选择、展开、视口相机）永不进入运行态，也不写盘。

export type PlayState = 'editing' | 'playing' | 'paused';

/** 场景节点：编辑器与运行时共用同一种形状。 */
export interface SceneNode {
  id: number;
  name: string;
  parent: number | null;
  children: number[];
  /** 局部平移。运行时物理 / 脚本会就地改写它。 */
  position: [number, number, number];
  /** 运行期累计的「已存活秒数」，只存在于运行态副本。 */
  runtimeAge?: number;
}

export type SceneDoc = Map<number, SceneNode>;

/** 深拷贝一份文档。编辑器与运行时之间只允许通过拷贝传递。 */
export function cloneDoc(src: SceneDoc): SceneDoc {
  const out: SceneDoc = new Map();
  for (const [id, n] of src) {
    out.set(id, { ...n, position: [...n.position], children: [...n.children] });
  }
  return out;
}

/** 只属于编辑器的状态：不进运行时，也不写盘。 */
export interface EditorState {
  selection: number[];
  expanded: Set<number>;
  camera: [number, number, number];
}

/** 一帧运行时的推进函数：只应触碰传入的文档，不得捕获编辑态。 */
export type AdvanceFn = (doc: SceneDoc, dt: number) => void;

export class PlayModeController {
  readonly #edit: SceneDoc;
  readonly #editor: EditorState;
  #runtime: SceneDoc | null = null;
  #state: PlayState = 'editing';
  #elapsed = 0;

  constructor(doc: SceneDoc, editor: EditorState) {
    this.#edit = doc;
    this.#editor = editor;
  }

  get state(): PlayState { return this.#state; }
  /** 运行态已模拟的秒数；编辑态恒为 0。 */
  get elapsed(): number { return this.#elapsed; }
  /** 编辑态文档：始终是「作者写下的那一份」。 */
  edit(): SceneDoc { return this.#edit; }
  /** 编辑器的界面状态（选择 / 展开 / 视口）。 */
  editorState(): EditorState { return this.#editor; }
  /** 运行态文档：仅 playing / paused 时存在，编辑态为 null。 */
  runtime(): SceneDoc | null { return this.#runtime; }

  /** 进入 Play：拷贝编辑态文档，运行时从零开始模拟。 */
  play(): void {
    if (this.#state !== 'editing') return;
    this.#runtime = cloneDoc(this.#edit);
    this.#elapsed = 0;
    this.#state = 'playing';
  }

  /** Pause：冻结模拟，但保留运行态，便于检查现场。 */
  pause(): void {
    if (this.#state === 'playing') this.#state = 'paused';
  }

  resume(): void {
    if (this.#state === 'paused') this.#state = 'playing';
  }

  /** Stop：丢弃运行态副本，编辑态文档一行未改。 */
  stop(): void {
    if (this.#state === 'editing') return;
    this.#runtime = null;
    this.#elapsed = 0;
    this.#state = 'editing';
  }

  /** 模拟推进：只有 playing 会真正改运行态，返回本帧是否推进过。 */
  step(dt: number, advance: AdvanceFn): boolean {
    if (this.#state !== 'playing' || !this.#runtime) return false;
    advance(this.#runtime, dt);
    this.#elapsed += dt;
    return true;
  }
}

// file: src/editor/play-mode.test.ts
// tier: L1
// verify: npx vitest run src/editor/play-mode.test.ts
import { describe, expect, it } from 'vitest';
import { PlayModeController, type EditorState, type SceneDoc } from './play-mode.ts';

function makeDoc(): SceneDoc {
  const doc: SceneDoc = new Map();
  doc.set(0, { id: 0, name: 'Level', parent: null, children: [1], position: [0, 0, 0] });
  doc.set(1, { id: 1, name: 'Player', parent: 0, children: [], position: [0, 0, 0] });
  return doc;
}

function makeEditor(): EditorState {
  return { selection: [1], expanded: new Set([0]), camera: [0, 0, 10] };
}

describe('编辑态与运行态', () => {
  it('Play 后运行时只改副本，编辑态文档不变', () => {
    const ctl = new PlayModeController(makeDoc(), makeEditor());
    ctl.play();
    ctl.step(0.5, (d) => { d.get(1)!.position[0] += 5; });
    expect(ctl.edit().get(1)!.position[0]).toBe(0);
    expect(ctl.runtime()!.get(1)!.position[0]).toBe(5);
  });

  it('Stop 丢弃运行态，编辑态文档与编辑器状态都原样', () => {
    const doc = makeDoc();
    const ed = makeEditor();
    const ctl = new PlayModeController(doc, ed);
    ctl.play();
    ctl.step(1, (d) => { d.get(1)!.position[2] = 9; });
    ctl.stop();
    expect(ctl.state).toBe('editing');
    expect(ctl.runtime()).toBeNull();
    expect(ctl.edit().get(1)!.position[2]).toBe(0);
    expect(ed.selection).toEqual([1]);
    expect(ctl.elapsed).toBe(0);
  });
});

describe('预览的暂停与恢复', () => {
  it('Pause 冻结模拟，Resume 继续，elapsed 不倒退', () => {
    const ctl = new PlayModeController(makeDoc(), makeEditor());
    ctl.play();
    ctl.step(1, () => {});
    ctl.pause();
    expect(ctl.step(1, () => {})).toBe(false);
    expect(ctl.elapsed).toBe(1);
    ctl.resume();
    ctl.step(1, () => {});
    expect(ctl.elapsed).toBe(2);
  });

  it('编辑态不允许推进', () => {
    const ctl = new PlayModeController(makeDoc(), makeEditor());
    expect(ctl.step(1, () => {})).toBe(false);
    expect(ctl.runtime()).toBeNull();
  });

  it('重复 play / stop 是幂等的', () => {
    const ctl = new PlayModeController(makeDoc(), makeEditor());
    ctl.play();
    ctl.play();
    expect(ctl.state).toBe('playing');
    ctl.stop();
    ctl.stop();
    expect(ctl.state).toBe('editing');
  });
});