《游戏引擎实现原理》17.2 引用、句柄与循环的处理

// file: src/core/circular-demo.ts
// tier: L1
// verify: node src/core/circular-demo.ts
//
// 朴素 JSON.stringify 遇环的真实报错文本。

type SceneNode = {
  name: string;
  parent: SceneNode | null;
  children: SceneNode[];
};

const island: SceneNode = { name: 'island', parent: null, children: [] };
const rock: SceneNode = { name: 'rock', parent: island, children: [] };
island.children = [rock];

try {
  JSON.stringify(island);
} catch (e) {
  const err = e as Error;
  console.log('name    :', err.name);
  console.log('message :', err.message.split('\n')[0]);
  console.log('--- full ---');
  console.log(err.message);
}

name    : TypeError
message : Converting circular structure to JSON
--- full ---
Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    |     property 'children' -> object with constructor 'Array'
    |     index 0 -> object with constructor 'Object'
    --- property 'parent' closes the circle

// file: src/core/replacer-demo.ts
// tier: L1
// verify: node src/core/replacer-demo.ts
//
// 用 JSON.stringify 的 replacer + WeakSet 去重：不抛错了，但形状丢了。

type SceneNode = { name: string; parent: SceneNode | null; children: SceneNode[] };

const island: SceneNode = { name: 'island', parent: null, children: [] };
const rock: SceneNode = { name: 'rock', parent: island, children: [] };
island.children = [rock];

const seen = new WeakSet<object>();
const json = JSON.stringify(island, (key, value) => {
  if (typeof value === 'object' && value !== null) {
    if (seen.has(value)) return '[circular]';
    seen.add(value);
  }
  return value;
});
console.log(json);

{"name":"island","parent":null,"children":[{"name":"rock","parent":"[circular]","children":[]}]}

// file: src/core/graph-serializer.ts
// tier: L1
// verify: npx vitest run src/core/graph-serializer.test.ts
//
// helio 内核：带 id 表的对象图序列化器。
// 引用被替换成整数 id，循环引用因此变成两次「指向同一 id」，可正常写盘。

import type { FieldDescriptor, TypeRegistry } from './registry.ts';
import { defaultValue } from './json-serde.ts';

export type GraphNode = {
  id: number;
  type: string;
  fields: Record<string, unknown>;
};

export type GraphDocument = {
  root: number;
  nodes: GraphNode[];
};

/**
 * 把以 root 为起点的对象图写成「节点表 + id 引用」。
 * 每个对象只在 nodes 里出现一次，第二次遇到就复用它的 id。
 */
export function serializeGraph(
  reg: TypeRegistry,
  typeName: string,
  root: Record<string, unknown>,
): GraphDocument {
  const ids = new Map<object, number>();
  const nodes: GraphNode[] = [];

  const visit = (obj: Record<string, unknown>, tName: string): number => {
    const seen = ids.get(obj);
    if (seen !== undefined) return seen;
    const desc = reg.require(tName);
    const id = nodes.length;
    ids.set(obj, id);
    const fields: Record<string, unknown> = {};
    nodes.push({ id, type: desc.name, fields }); // 先占位，再递归，环才走得通
    for (const f of desc.fields) {
      const v = obj[f.name];
      if (v === undefined) continue;
      if (f.kind === 'ref') {
        fields[f.name] = v === null ? null : visit(v as Record<string, unknown>, f.type!);
      } else if (f.kind === 'array') {
        fields[f.name] = (v as Record<string, unknown>[]).map((x) =>
          x === null ? null : visit(x, f.type!),
        );
      } else {
        fields[f.name] = v;
      }
    }
    return id;
  };

  const rootId = visit(root, typeName);
  return { root: rootId, nodes };
}

/** 两趟重建：先建所有空壳，再按 id 连引用——循环引用靠对象同一性自然复原。 */
export function deserializeGraph(
  reg: TypeRegistry,
  doc: GraphDocument,
): Record<string, unknown> {
  const shells: Record<string, unknown>[] = doc.nodes.map((n) => {
    const desc = reg.require(n.type);
    const obj: Record<string, unknown> = {};
    for (const f of desc.fields) {
      if (f.kind === 'ref') obj[f.name] = null;
      else if (f.kind === 'array') obj[f.name] = [];
      else obj[f.name] = defaultValue(f);
    }
    return obj;
  });

  for (const n of doc.nodes) {
    const desc = reg.require(n.type);
    const obj = shells[n.id];
    for (const f of desc.fields) {
      const raw = n.fields[f.name];
      if (raw === undefined) continue;
      if (f.kind === 'ref') {
        obj[f.name] = raw === null ? null : shells[raw as number];
      } else if (f.kind === 'array') {
        obj[f.name] = (raw as number[]).map((id) => shells[id]);
      } else {
        obj[f.name] = raw;
      }
    }
  }
  return shells[doc.root];
}

// file: src/core/graph-demo.ts
// tier: L1
// verify: node src/core/graph-demo.ts
//
// 父子互指的对象图：带 id 表的序列化器怎么把它写下来、再原样读回。

import { TypeRegistry } from './registry.ts';
import { deserializeGraph, serializeGraph } from './graph-serializer.ts';

type SceneNode = { name: string; parent: SceneNode | null; children: SceneNode[] };

const reg = new TypeRegistry();
reg.register({
  name: 'SceneNode',
  version: 1,
  fields: [
    { name: 'name', kind: 'string' },
    { name: 'parent', kind: 'ref', type: 'SceneNode' },
    { name: 'children', kind: 'array', type: 'SceneNode' },
  ],
});

const island: SceneNode = { name: 'island', parent: null, children: [] };
const rock: SceneNode = { name: 'rock', parent: island, children: [] };
island.children = [rock];

const doc = serializeGraph(reg, 'SceneNode', island as unknown as Record<string, unknown>);
console.log('nodes   :', doc.nodes.length);
console.log('doc     :', JSON.stringify(doc));

const back = deserializeGraph(reg, doc) as unknown as SceneNode;
console.log('identity:', back.children[0].parent === back);
console.log('name    :', back.children[0].name);

nodes   : 2
doc     : {"root":0,"nodes":[{"id":0,"type":"SceneNode","fields":{"name":"island","parent":null,"children":[1]}},{"id":1,"type":"SceneNode","fields":{"name":"rock","parent":0,"children":[]}}]}
identity: true
name    : rock

// snippet: 句柄随存档往返，实体销毁后旧句柄解析成 undefined
const entities = new SlotMap<{ label: string }>();
const chest = entities.insert({ label: 'chest' });

// 句柄是纯整数，序列化后仍是整数，加载后可以重新解析。
const saved = JSON.parse(JSON.stringify({ owner: chest })) as { owner: number };
entities.get(saved.owner)?.label; // 'chest'

// 实体销毁后，旧句柄的世代对不上，解析成 undefined（防悬垂）。
entities.remove(chest);
entities.get(chest); // undefined