《游戏引擎实现原理》16.2 类型注册与属性描述符

// file: src/core/type-registry.ts
// tier: L1
// verify: npx vitest run src/core/type-registry.test.ts
//
// helio 内核：显式类型注册表 + 属性描述符。
// 不用装饰器、不依赖 emitDecoratorMetadata——类型信息由代码显式登记，
// 注册顺序即遍历顺序，序列化输出因此稳定可复现。

/** 引擎认得的字段类型，尺寸以字节计。字符串不进紧凑记录，用 handle 指向 intern 表（见 7.3）。 */
export type FieldType = 'f32' | 'f64' | 'i32' | 'u32' | 'bool' | 'handle' | 'vec3';

const FIELD_SIZE: Record<FieldType, number> = {
  f32: 4,
  f64: 8,
  i32: 4,
  u32: 4,
  bool: 1,
  handle: 4,
  vec3: 12,
};

/** 单个属性的描述符：名字、类型、在记录里的字节偏移、默认值。 */
export interface PropertyDescriptor {
  readonly name: string;
  readonly type: FieldType;
  readonly offset: number;
  readonly defaultValue: unknown;
  /** 可选访问器：字段不在紧凑记录里时用它读写（如 Map 支撑的属性）。 */
  readonly accessor?: (obj: Record<string, unknown>) => unknown;
}

/** 定义字段时的输入：只需名字、类型、默认值，偏移由布局算出。 */
export interface FieldSpec {
  readonly name: string;
  readonly type: FieldType;
  readonly defaultValue: unknown;
  readonly accessor?: (obj: Record<string, unknown>) => unknown;
}

/** 一个已注册类型：名字、紧凑记录大小、属性描述符列表。 */
export interface TypeDescriptor {
  readonly name: string;
  readonly size: number;
  readonly properties: readonly PropertyDescriptor[];
}

/** 按声明顺序累加偏移，得到紧凑布局与属性描述符。 */
export function defineType(name: string, specs: readonly FieldSpec[]): TypeDescriptor {
  let offset = 0;
  const properties: PropertyDescriptor[] = [];
  for (const s of specs) {
    properties.push({
      name: s.name,
      type: s.type,
      offset,
      defaultValue: s.defaultValue,
      accessor: s.accessor,
    });
    offset += FIELD_SIZE[s.type];
  }
  return { name, size: offset, properties };
}

/** 显式类型注册表。注册顺序被保留，遍历稳定。 */
export class TypeRegistry {
  #types = new Map<string, TypeDescriptor>();
  #order: string[] = [];

  get size(): number {
    return this.#types.size;
  }

  /** 登记一个类型；重名直接抛错——类型名是全局键，不能悄悄覆盖。 */
  register(desc: TypeDescriptor): void {
    if (this.#types.has(desc.name)) {
      throw new Error(`Duplicate type registration: ${desc.name}`);
    }
    this.#types.set(desc.name, desc);
    this.#order.push(desc.name);
  }

  registerAll(descs: readonly TypeDescriptor[]): void {
    for (const d of descs) this.register(d);
  }

  get(name: string): TypeDescriptor | undefined {
    return this.#types.get(name);
  }

  has(name: string): boolean {
    return this.#types.has(name);
  }

  /** 按注册顺序返回全部类型名——稳定，可复现。 */
  names(): readonly string[] {
    return this.#order;
  }

  /** 按注册顺序遍历类型，供序列化器等按固定次序消费。 */
  *[Symbol.iterator](): Generator<TypeDescriptor> {
    for (const n of this.#order) yield this.#types.get(n)!;
  }
}

/** 读一个属性的当前值：优先用访问器，否则按属性名直接取。 */
export function readProperty(obj: Record<string, unknown>, prop: PropertyDescriptor): unknown {
  return prop.accessor ? prop.accessor(obj) : obj[prop.name];
}

/** 全量读取一个对象在某个类型下的所有属性值，顺序即描述符顺序。 */
export function readAll(
  obj: Record<string, unknown>,
  desc: TypeDescriptor,
): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const p of desc.properties) out[p.name] = readProperty(obj, p);
  return out;
}

// file: src/apps/registry-demo.ts
// tier: L1
// verify: node src/apps/registry-demo.ts
//
// 手工登记三个类型，再按名字查询属性描述符——16.2 的可运行产物。

import { TypeRegistry, defineType, readAll } from '../core/type-registry.ts';

const reg = new TypeRegistry();
reg.registerAll([
  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: [1, 1, 1] },
  ]),
  defineType('Health', [
    { name: 'current', type: 'f32', defaultValue: 100 },
    { name: 'max', type: 'f32', defaultValue: 100 },
    { name: 'invulnerable', type: 'bool', defaultValue: false },
  ]),
]);

console.log('registered:', reg.size, '->', reg.names().join(', '));

// 按名字查询一个类型的属性描述符列表。
const vec3 = reg.get('Vec3')!;
console.log(`registry.get('Vec3').size = ${vec3.size}`);
for (const p of vec3.properties) {
  console.log(`  ${p.name}: ${p.type} @${p.offset} default=${JSON.stringify(p.defaultValue)}`);
}

// 注册顺序即遍历顺序——稳定，序列化靠它。
for (const desc of reg) console.log(`${desc.name}: size=${desc.size}`);

// 按描述符读出一个对象的全部字段值。
const hp = { current: 42, max: 100, invulnerable: true };
console.log('readAll(Health, hp) =', JSON.stringify(readAll(hp, reg.get('Health')!)));

registered: 3 -> Vec3, Transform, Health
registry.get('Vec3').size = 12
  x: f32 @0 default=0
  y: f32 @4 default=0
  z: f32 @8 default=0
Vec3: size=12
Transform: size=36
Health: size=9
readAll(Health, hp) = {"current":42,"max":100,"invulnerable":true}

// snippet: src/core/type-registry.test.ts 节选
const VEC3 = defineType('Vec3', [
  { name: 'x', type: 'f32', defaultValue: 0 },
  { name: 'y', type: 'f32', defaultValue: 0 },
  { name: 'z', type: 'f32', defaultValue: 0 },
]);

// 偏移按字段类型累加，不是手填的
expect(VEC3.properties.map((p) => p.offset)).toEqual([0, 4, 8]);
expect(VEC3.size).toBe(12);

// 重名注册直接抛错，且失败的那次不会污染注册表
const r = new TypeRegistry();
r.register(VEC3);
expect(() => r.register(VEC3)).toThrow(/Duplicate/);
expect(r.names()).toEqual(['Vec3']); // 仍是第一次注册的那份