《游戏引擎实现原理》8.3 序列化落盘与场景格式

{
  "format": "glimmer-isle.level",
  "version": 2,
  "root": "n0",
  "nodes": [
    { "uid": "n0", "name": "Level",  "parent": null, "position": [0, 0, 0] },
    { "uid": "n1", "name": "Player", "parent": "n0", "position": [1, 2, 3] },
    { "uid": "n2", "name": "Torch",  "parent": "n0", "position": [5, 0, 0] }
  ]
}

// file: src/editor/scene-format.ts
// tier: L1
// verify: npx vitest run src/editor/scene-format.test.ts
//
// helio 编辑器：《微光岛》关卡文件格式与版本迁移。
// 节点之间用稳定 uid 互相引用，绝不用数组下标；文件头带 format 与 version。
// 加载时按 version 升级，遇到比当前更高的版本直接拒绝，绝不猜、不静默降级。

import { SceneDocument } from './scene-document.ts';

export const LEVEL_FORMAT = 'glimmer-isle.level';
export const LEVEL_VERSION = 2;

export interface LevelNode {
  uid: string;
  name: string;
  parent: string | null;
  position: [number, number, number];
}

export interface LevelFile {
  format: string;
  version: number;
  root: string;
  nodes: LevelNode[];
}

/** v1：早期关卡用数组下标当父子引用，没有 uid。 */
export interface LevelFileV1 {
  format: string;
  version: number;
  nodes: { name: string; parentIndex: number; position: [number, number, number] }[];
}

/** 把文档写成关卡文件：uid 稳定，节点按 uid 数字后缀排序，产出可逐行 diff。 */
export function serializeLevel(doc: SceneDocument): LevelFile {
  const nodes = doc.all().map((n): LevelNode => ({
    uid: n.uid,
    name: n.name,
    parent: n.parent === null ? null : doc.node(n.parent).uid,
    position: [...n.position],
  }));
  nodes.sort((a, b) => Number(a.uid.slice(1)) - Number(b.uid.slice(1)));
  return { format: LEVEL_FORMAT, version: LEVEL_VERSION, root: doc.node(doc.root).uid, nodes };
}

/** 校验文件头并按需迁移；更高的版本、错误的 format 一律抛错。 */
export function parseLevel(raw: unknown): LevelFile {
  const f = raw as LevelFile | LevelFileV1;
  if (f?.format !== LEVEL_FORMAT) throw new Error(`Not a ${LEVEL_FORMAT} file`);
  if (typeof f.version !== 'number') throw new Error('Level file missing version');
  if (f.version > LEVEL_VERSION) throw new Error(`Level version ${f.version} is newer than ${LEVEL_VERSION}`);
  return f.version === LEVEL_VERSION ? (f as LevelFile) : migrateLevel(f as LevelFileV1);
}

/** v1 → v2：把 parentIndex 换成稳定 uid。 */
export function migrateLevel(v1: LevelFileV1): LevelFile {
  if (v1.version !== 1) throw new Error(`No migration from v${v1.version}`);
  const uidOf = v1.nodes.map((_, i) => `n${i}`);
  const nodes: LevelNode[] = v1.nodes.map((n, i) => ({
    uid: uidOf[i]!,
    name: n.name,
    parent: n.parentIndex < 0 ? null : uidOf[n.parentIndex]!,
    position: [...n.position],
  }));
  return { format: LEVEL_FORMAT, version: LEVEL_VERSION, root: uidOf[0]!, nodes };
}

/** 把关卡文件装回一棵文档树，uid 原样保留。父节点可能排在子节点之后。 */
export function loadLevel(f: LevelFile): SceneDocument {
  const doc = new SceneDocument(f.nodes.find((n) => n.uid === f.root)?.name ?? 'Level');
  const idOf = new Map<string, number>([[f.root, doc.root]]);
  const pending = f.nodes.filter((n) => n.uid !== f.root);
  let progress = true;
  while (pending.length > 0 && progress) {
    progress = false;
    for (let i = pending.length - 1; i >= 0; i--) {
      const n = pending[i]!;
      const parentId = n.parent === null ? doc.root : idOf.get(n.parent);
      if (parentId === undefined) continue;
      idOf.set(n.uid, doc.restoreNode(n.uid, n.name, parentId, n.position));
      pending.splice(i, 1);
      progress = true;
    }
  }
  if (pending.length > 0) throw new Error('Level has orphan or cyclic nodes');
  return doc;
}

// file: src/editor/scene-format.test.ts
// tier: L1
// verify: npx vitest run src/editor/scene-format.test.ts
import { describe, expect, it } from 'vitest';
import { SceneDocument } from './scene-document.ts';
import { LEVEL_FORMAT, LEVEL_VERSION, loadLevel, parseLevel, serializeLevel, type LevelFileV1 } from './scene-format.ts';

function sampleDoc(): SceneDocument {
  const doc = new SceneDocument('微光岛');
  const player = doc.createNode('Player', doc.root, [1, 2, 3]);
  doc.createNode('Hand', player, [0.5, 0, 0]);
  doc.createNode('Torch', doc.root, [5, 0, 0]);
  return doc;
}

describe('往返一致', () => {
  it('serialize → loadLevel → serialize 完全一致', () => {
    const a = serializeLevel(sampleDoc());
    const b = serializeLevel(loadLevel(a));
    expect(b).toEqual(a);
    expect(a.version).toBe(LEVEL_VERSION);
    expect(a.format).toBe(LEVEL_FORMAT);
  });

  it('uid 跨重排稳定：移动节点后写盘，uid 不变只改 parent', () => {
    const doc = sampleDoc();
    const hand = doc.all().find((n) => n.name === 'Hand')!;
    const root = doc.root;
    doc.reparent(hand.id, root);
    const file = serializeLevel(doc);
    const handNode = file.nodes.find((n) => n.name === 'Hand')!;
    expect(handNode.uid).toBe(hand.uid); // uid 没变
    expect(handNode.parent).toBe(doc.node(root).uid); // parent 变了
  });
});

describe('版本与格式', () => {
  it('v1 迁移到 v2：parentIndex 换成 uid', () => {
    const v1: LevelFileV1 = {
      format: LEVEL_FORMAT,
      version: 1,
      nodes: [
        { name: 'Level', parentIndex: -1, position: [0, 0, 0] },
        { name: 'Player', parentIndex: 0, position: [1, 0, 0] },
        { name: 'Hand', parentIndex: 1, position: [0.5, 0, 0] },
      ],
    };
    const f = parseLevel(v1);
    expect(f.version).toBe(LEVEL_VERSION);
    expect(f.root).toBe('n0');
    expect(f.nodes.find((n) => n.name === 'Hand')!.parent).toBe('n1');
    // 迁移后能装回文档树
    const doc = loadLevel(f);
    expect(doc.all().map((n) => n.name).sort()).toEqual(['Hand', 'Level', 'Player']);
  });

  it('比当前更高的版本直接拒绝', () => {
    expect(() => parseLevel({ format: LEVEL_FORMAT, version: 99, root: 'n0', nodes: [] }))
      .toThrow(/newer/);
  });

  it('错误 format 直接拒绝', () => {
    expect(() => parseLevel({ format: 'godot.tscn', version: 2, root: 'n0', nodes: [] }))
      .toThrow(/Not a/);
  });

  it('父子链断裂（孤立节点）抛错', () => {
    const orphan = {
      format: LEVEL_FORMAT,
      version: LEVEL_VERSION,
      root: 'n0',
      nodes: [
        { uid: 'n0', name: 'Level', parent: null, position: [0, 0, 0] as [number, number, number] },
        { uid: 'n9', name: 'Ghost', parent: 'nX', position: [0, 0, 0] as [number, number, number] },
      ],
    };
    expect(() => loadLevel(orphan)).toThrow(/orphan|cyclic/);
  });
});