《游戏引擎实现原理》10.1 反射驱动的属性面板

// file: src/editor/property/panel-model.ts
// tier: L1
// verify: npx vitest run src/editor/property/panel-model.test.ts
//
// helio 编辑器：把反射类型描述符展开成属性面板的「描述数据」。
// 这一层是纯数据——只产出字段列表，不碰任何 DOM 节点；
// 真正的控件渲染在 10.2 的控件层与 L3 的 DOM 胶水里完成。

import type { TypeDescriptor, PropertyDescriptor, FieldType } from '../../core/type-registry.ts';
import { readProperty } from '../../core/type-registry.ts';

/** 每个属性的编辑器元数据：标签、隐藏、只读、枚举候选、数值范围。 */
export interface EditorHint {
  readonly label?: string;
  readonly hidden?: boolean;
  readonly readOnly?: boolean;
  readonly enumValues?: readonly string[];
  readonly min?: number;
  readonly max?: number;
  readonly step?: number;
}

/** 编辑器元数据表：键是「类型名.属性名」，如 'Health.invulnerable'。 */
export type EditorHints = Readonly<Record<string, EditorHint>>;

/** 一个面板字段：纯数据，不含任何 DOM 节点。 */
export interface PanelField {
  readonly name: string;
  readonly label: string;
  readonly type: FieldType;
  readonly value: unknown;
  readonly readOnly: boolean;
  readonly enumValues?: readonly string[];
  readonly min?: number;
  readonly max?: number;
  readonly step?: number;
}

/** 一个类型在面板里的完整描述数据。 */
export interface PanelModel {
  readonly typeName: string;
  readonly fields: readonly PanelField[];
}

/** camelCase / snake_case → 人类可读标签：grounded → Grounded，maxHealth → Max Health。 */
export function humanize(name: string): string {
  const spaced = name.replace(/[_-]+/g, ' ').replace(/([a-z0-9])([A-Z])/g, '$1 $2');
  return spaced
    .split(' ')
    .filter((w) => w.length > 0)
    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
    .join(' ');
}

/** 取一条属性的编辑器元数据，缺省时空对象。 */
function hintOf(desc: TypeDescriptor, p: PropertyDescriptor, hints: EditorHints): EditorHint {
  return hints[`${desc.name}.${p.name}`] ?? {};
}

/** 把反射描述符 + 实例 + 编辑器元数据展开成面板描述数据。 */
export function buildPanelModel(
  desc: TypeDescriptor,
  obj: Record<string, unknown>,
  hints: EditorHints = {},
): PanelModel {
  const fields: PanelField[] = [];
  for (const p of desc.properties) {
    const hint = hintOf(desc, p, hints);
    if (hint.hidden) continue;
    fields.push({
      name: p.name,
      label: hint.label ?? humanize(p.name),
      type: p.type,
      value: readProperty(obj, p),
      readOnly: hint.readOnly ?? false,
      enumValues: hint.enumValues,
      min: hint.min,
      max: hint.max,
      step: hint.step,
    });
  }
  return { typeName: desc.name, fields };
}

/** 面板分区配置：一组字段归到一个标题下。 */
export interface GroupSpec {
  readonly title: string;
  readonly names: readonly string[];
}

/** 一个面板分区：标题 + 组内字段（保持描述符原顺序）。 */
export interface PanelGroup {
  readonly title: string;
  readonly fields: readonly PanelField[];
}

/**
 * 按配置把字段切成若干分区；未被任何分区认领的字段收进「其它」。
 * 认领按配置顺序，同名重复认领只算第一次。
 */
export function groupFields(model: PanelModel, groups: readonly GroupSpec[]): readonly PanelGroup[] {
  const byName = new Map(model.fields.map((f) => [f.name, f]));
  const claimed = new Set<string>();
  const out: PanelGroup[] = [];
  for (const g of groups) {
    const fs: PanelField[] = [];
    for (const n of g.names) {
      const f = byName.get(n);
      if (f && !claimed.has(n)) {
        fs.push(f);
        claimed.add(n);
      }
    }
    out.push({ title: g.title, fields: fs });
  }
  const rest = model.fields.filter((f) => !claimed.has(f.name));
  if (rest.length > 0) out.push({ title: '其它', fields: rest });
  return out;
}

// file: src/apps/editor-panel-demo.ts
// tier: L1
// verify: node src/apps/editor-panel-demo.ts
//
// 从反射描述符展开属性面板的描述数据——10.1 的可运行产物。

import { TypeRegistry } from '../core/type-registry.ts';
import { GENERATED_TYPES } from '../generated/type-registry.gen.ts';
import { buildPanelModel, groupFields } from '../editor/property/panel-model.ts';

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

const transform = reg.get('Transform')!;
const obj = { position: [0, 1.5, 0], rotation: [0, 90, 0], scale: [1, 1, 1] };

const model = buildPanelModel(transform, obj, {
  'Transform.rotation': { label: '旋转（度）', step: 1 },
});
console.log(`panel: ${model.typeName}, fields=${model.fields.length}`);
for (const f of model.fields) {
  console.log(`  ${f.name.padEnd(10)} label="${f.label}" type=${f.type} value=${JSON.stringify(f.value)}`);
}

const groups = groupFields(model, [{ title: '变换', names: ['position', 'rotation'] }]);
for (const g of groups) console.log(`group "${g.title}": [${g.fields.map((f) => f.name).join(', ')}]`);

panel: Transform, fields=3
  position   label="Position" type=vec3 value=[0,1.5,0]
  rotation   label="旋转（度）" type=vec3 value=[0,90,0]
  scale      label="Scale" type=vec3 value=[1,1,1]
group "变换": [position, rotation]
group "其它": [scale]

// file: src/editor/property/panel-view.ts
// tier: L3
//
// 把面板描述数据渲染成 DOM。依赖 document，命令行不可复现，
// 需在浏览器中手动验证（本文件仅通过 tsc 类型检查）。

import type { PanelModel, PanelField } from './panel-model.ts';

/** 一个字段的 DOM 行：标签 + 控件槽。控件由 10.2 的工厂填进 slot。 */
export interface FieldRow {
  readonly field: PanelField;
  readonly root: HTMLElement;
  readonly label: HTMLLabelElement;
  readonly slot: HTMLElement;
}

/** 把一份面板描述数据渲染成 DOM，返回每行的句柄供后续绑定控件。 */
export function renderPanel(model: PanelModel, host: HTMLElement): FieldRow[] {
  host.replaceChildren();
  const rows: FieldRow[] = [];
  for (const field of model.fields) {
    const root = document.createElement('div');
    root.className = 'field-row';
    const label = document.createElement('label');
    label.textContent = field.label;
    label.htmlFor = `fld-${model.typeName}-${field.name}`;
    const slot = document.createElement('div');
    slot.className = 'field-slot';
    if (field.readOnly) root.classList.add('is-readonly');
    root.append(label, slot);
    host.append(root);
    rows.push({ field, root, label, slot });
  }
  return rows;
}

// snippet: src/editor/property/panel-model.test.ts 节选
const m = buildPanelModel(HEALTH, { current: 1, maxHealth: 2, invulnerable: false }, {
  'Health.current': { label: '当前血量', readOnly: true },
  'Health.invulnerable': { hidden: true },
});
expect(m.fields.map((f) => f.name)).toEqual(['current', 'maxHealth']); // hidden 被剔除
expect(m.fields[0].label).toBe('当前血量');
expect(m.fields[0].readOnly).toBe(true);

// 字段顺序 = 描述符顺序，值来自实例
const full = buildPanelModel(HEALTH, { current: 42, maxHealth: 100, invulnerable: true });
expect(full.fields.map((f) => f.value)).toEqual([42, 100, true]);