《游戏引擎实现原理》16.3 显式注册表 + 代码生成扫描

// @reflect
export interface Vec3 {
  x: number;
  y: number;
  z: number;
}

// file: tools/gen-registry.mjs
// tier: L1
// verify: node tools/gen-registry.mjs
//
// 构建期扫描器：读 src/game 下带「// @reflect」标记的 interface，
// 生成 src/generated/type-registry.gen.ts 里的显式类型注册表。
// 只扫一遍、只生成一次，运行时不碰源码。

import { readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join, dirname } from 'node:path';

const SRC_DIR = 'src/game';
const OUT = 'src/generated/type-registry.gen.ts';

// TS 字段类型 -> 引擎字段类型。未登记的映射直接抛错，让扫描在构建期失败。
const TYPE_MAP = { number: 'f32', boolean: 'bool', string: 'handle', Vec3: 'vec3' };
const DEFAULT_VALUE = { f32: 0, bool: false, handle: 0, vec3: [0, 0, 0] };

// 标记 + 紧跟的 export interface。
const TYPE_RE = /\/\/ @reflect\s*\n\s*export interface (\w+)\s*\{([\s\S]*?)\n\}/g;
const FIELD_RE = /^\s*(\w+)\??:\s*([A-Za-z_][\w<>[\]| ]*?);?\s*$/;

function parseSource(text, file) {
  const types = [];
  for (const m of text.matchAll(TYPE_RE)) {
    const name = m[1];
    const fields = [];
    for (const line of m[2].split('\n')) {
      if (!line.trim()) continue;
      const fm = FIELD_RE.exec(line);
      if (!fm) continue;
      const [, fieldName, tsType] = fm;
      const type = TYPE_MAP[tsType.trim()];
      if (!type) throw new Error(`${file}: unknown field type "${tsType}" in ${name}.${fieldName}`);
      fields.push({ name: fieldName, type, defaultValue: DEFAULT_VALUE[type] });
    }
    types.push({ name, fields });
  }
  return types;
}

function generate(types) {
  const out = [];
  out.push('// file: src/generated/type-registry.gen.ts');
  out.push('// tier: L1');
  out.push('// verify: npx vitest run src/generated/type-registry.gen.test.ts');
  out.push('');
  out.push('// AUTO-GENERATED by tools/gen-registry.mjs. DO NOT EDIT BY HAND.');
  out.push("import { defineType, type TypeDescriptor } from '../core/type-registry.ts';");
  out.push('');
  out.push('export const GENERATED_TYPES: readonly TypeDescriptor[] = [');
  for (const t of types) {
    out.push(`  defineType('${t.name}', [`);
    for (const f of t.fields) {
      out.push(`    { name: '${f.name}', type: '${f.type}', defaultValue: ${JSON.stringify(f.defaultValue)} },`);
    }
    out.push('  ]),');
  }
  out.push('];');
  out.push('');
  return out.join('\n');
}

const files = readdirSync(SRC_DIR)
  .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'))
  .sort();

let types = [];
for (const f of files) types = types.concat(parseSource(readFileSync(join(SRC_DIR, f), 'utf8'), f));

const code = generate(types);
mkdirSync(dirname(OUT), { recursive: true });
writeFileSync(OUT, code);

const lines = code.replace(/\n$/, '').split('\n').length;
const props = types.reduce((n, t) => n + t.fields.length, 0);
console.log(`scanned ${files.length} files -> ${types.length} types, ${props} properties`);
console.log(`wrote ${OUT} (${lines} lines, ${Buffer.byteLength(code)} bytes)`);

// file: src/game/components.ts
// tier: L1
// verify: node tools/gen-registry.mjs

// @reflect
export interface Vec3 {
  x: number;
  y: number;
  z: number;
}

// @reflect
export interface Transform {
  position: Vec3;
  rotation: Vec3;
  scale: Vec3;
}

// file: src/game/gameplay.ts
// tier: L1
// verify: node tools/gen-registry.mjs

// @reflect
export interface Health {
  current: number;
  max: number;
  invulnerable: boolean;
}

// @reflect
export interface Player {
  name: string;
  speed: number;
  grounded: boolean;
}

$ node tools/gen-registry.mjs
scanned 2 files -> 4 types, 12 properties
wrote src/generated/type-registry.gen.ts (29 lines, 1127 bytes)

// file: src/generated/type-registry.gen.ts
// tier: L1
// verify: npx vitest run src/generated/type-registry.gen.test.ts

// AUTO-GENERATED by tools/gen-registry.mjs. DO NOT EDIT BY HAND.
import { defineType, type TypeDescriptor } from '../core/type-registry.ts';

export const GENERATED_TYPES: readonly TypeDescriptor[] = [
  defineType('Vec3', [
    { name: 'x', type: 'f32', defaultValue: 0 },
    { name: 'y', type: 'f32', defaultValue: 0 },
    { name: 'z', type: 'f32', defaultValue: 0 },
  ]),
  defineType('Transform', [
    { name: 'position', type: 'vec3', defaultValue: [0,0,0] },
    { name: 'rotation', type: 'vec3', defaultValue: [0,0,0] },
    { name: 'scale', type: 'vec3', defaultValue: [0,0,0] },
  ]),
  defineType('Health', [
    { name: 'current', type: 'f32', defaultValue: 0 },
    { name: 'max', type: 'f32', defaultValue: 0 },
    { name: 'invulnerable', type: 'bool', defaultValue: false },
  ]),
  defineType('Player', [
    { name: 'name', type: 'handle', defaultValue: 0 },
    { name: 'speed', type: 'f32', defaultValue: 0 },
    { name: 'grounded', type: 'bool', defaultValue: false },
  ]),
];

// snippet: src/generated/type-registry.gen.test.ts 节选
import { TypeRegistry } from '../core/type-registry.ts';
import { GENERATED_TYPES } from './type-registry.gen.ts';

const reg = new TypeRegistry();
reg.registerAll(GENERATED_TYPES);

expect(reg.size).toBe(4);
expect(reg.names()).toEqual(['Vec3', 'Transform', 'Health', 'Player']); // 扫描顺序

// 扫描器还原出的布局
expect(reg.get('Vec3')!.properties.map((p) => p.offset)).toEqual([0, 4, 8]);

// string 字段被映射成 handle
const player = reg.get('Player')!;
expect(player.properties.find((p) => p.name === 'name')!.type).toBe('handle');