《游戏引擎实现原理》10.2 编辑器控件与类型映射

// file: src/editor/property/widget-map.ts
// tier: L1
// verify: npx vitest run src/editor/property/widget-map.test.ts
//
// helio 编辑器：字段类型 → 控件种类的映射表，以及可覆写的控件注册表。
// 这一层只决定「用哪种控件、带什么参数」，不创建任何 DOM 节点；
// 控件的真实创建在 L3 的 DOM 胶水里（见 10.2 末节）。

import type { FieldType } from '../../core/type-registry.ts';
import type { PanelField } from './panel-model.ts';

/** 编辑器控件种类。控件种类是「语义」，具体标签由 L3 层决定（input / select / ...）。 */
export type WidgetKind =
  | 'number'
  | 'slider'
  | 'checkbox'
  | 'text'
  | 'dropdown'
  | 'vector'
  | 'object-ref';

/** 控件描述：种类 + 该种类需要的参数。 */
export interface WidgetSpec {
  readonly kind: WidgetKind;
  readonly options?: readonly string[];
  readonly min?: number;
  readonly max?: number;
  readonly step?: number;
  readonly components?: number;
}

/** 字段类型 → 默认控件种类。整数类型步进为 1，浮点默认 0.01。 */
const DEFAULT_WIDGET: Record<FieldType, WidgetKind> = {
  f32: 'number',
  f64: 'number',
  i32: 'number',
  u32: 'number',
  bool: 'checkbox',
  handle: 'object-ref',
  vec3: 'vector',
};

/** 分量数表：vec3 展开成三个数字框。 */
const VEC_COMPONENTS: Partial<Record<FieldType, number>> = { vec3: 3 };

/** 整数类型用 1 步进，浮点用 0.01。 */
function defaultStep(type: FieldType): number {
  return type === 'i32' || type === 'u32' ? 1 : 0.01;
}

/** 默认映射：只看字段类型。 */
export function defaultWidget(type: FieldType): WidgetKind {
  return DEFAULT_WIDGET[type];
}

/** 给定控件种类，补齐该种类需要的参数。 */
export function specForKind(kind: WidgetKind, field: PanelField): WidgetSpec {
  if (kind === 'number' || kind === 'slider') {
    return { kind, min: field.min, max: field.max, step: field.step ?? defaultStep(field.type) };
  }
  if (kind === 'vector') {
    return { kind, components: VEC_COMPONENTS[field.type] ?? 3 };
  }
  return { kind };
}

/** 由字段描述出控件：枚举优先，其次按类型给参数。 */
export function describeWidget(field: PanelField): WidgetSpec {
  if (field.enumValues && field.enumValues.length > 0) {
    return { kind: 'dropdown', options: field.enumValues };
  }
  return specForKind(defaultWidget(field.type), field);
}

/** 可覆写的控件注册表：按类型或按「属性名」改写默认映射。 */
export class WidgetRegistry {
  readonly #byType = new Map<FieldType, WidgetKind>();
  readonly #byName = new Map<string, WidgetKind>();

  /** 覆写某个字段类型的默认控件（如把 f32 默认改成滑块）。 */
  overrideType(type: FieldType, kind: WidgetKind): void {
    this.#byType.set(type, kind);
  }

  /** 覆写某个属性名的控件（优先级最高，用于个别特殊字段）。 */
  overrideName(name: string, kind: WidgetKind): void {
    this.#byName.set(name, kind);
  }

  /** 解析优先级：属性名覆写 > 枚举 > 类型覆写 > 默认。 */
  resolve(field: PanelField): WidgetSpec {
    const named = this.#byName.get(field.name);
    if (named) return { kind: named };
    if (field.enumValues && field.enumValues.length > 0) {
      return { kind: 'dropdown', options: field.enumValues };
    }
    const byType = this.#byType.get(field.type);
    if (byType) return specForKind(byType, field);
    return describeWidget(field);
  }
}

/** 供文档与调试用：导出一份默认映射表的副本。 */
export function defaultWidgetTable(): ReadonlyArray<{ type: FieldType; kind: WidgetKind }> {
  return (Object.keys(DEFAULT_WIDGET) as FieldType[]).map((type) => ({
    type,
    kind: DEFAULT_WIDGET[type],
  }));
}

// file: src/apps/editor-widget-demo.ts
// tier: L1
// verify: node src/apps/editor-widget-demo.ts
//
// 把面板字段映射成控件描述——10.2 的可运行产物。

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

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

console.log('default widget table:');
for (const row of defaultWidgetTable()) console.log(`  ${row.type.padEnd(7)} -> ${row.kind}`);

const health = reg.get('Health')!;
const model = buildPanelModel(health, { current: 42, max: 100, invulnerable: false }, {
  'Health.max': { min: 1, max: 999 },
});

const widgets = new WidgetRegistry();
widgets.overrideType('f32', 'slider');
for (const f of model.fields) {
  const spec = widgets.resolve(f);
  console.log(`  ${f.name.padEnd(13)} -> ${spec.kind} ${JSON.stringify(spec)}`);
}

default widget table:
  f32     -> number
  f64     -> number
  i32     -> number
  u32     -> number
  bool    -> checkbox
  handle  -> object-ref
  vec3    -> vector
  current       -> slider {"kind":"slider","step":0.01}
  max           -> slider {"kind":"slider","min":1,"max":999,"step":0.01}
  invulnerable  -> checkbox {"kind":"checkbox"}

// file: src/editor/property/widget-factory.ts
// tier: L3
//
// 按控件描述创建真实 DOM 控件。依赖 document，命令行不可复现，
// 需在浏览器中手动验证（本文件仅通过 tsc 类型检查）。

import type { PanelField } from './panel-model.ts';
import type { WidgetSpec } from './widget-map.ts';

/** 一个已创建的控件：根节点 + 读写值的两个方法。 */
export interface WidgetHandle {
  readonly root: HTMLElement;
  setValue(value: unknown): void;
  getValue(): unknown;
}

function elementId(field: PanelField): string {
  return `fld-${field.name}`;
}

function numberWidget(field: PanelField, spec: WidgetSpec, slider: boolean): WidgetHandle {
  const input = document.createElement('input');
  input.type = slider ? 'range' : 'number';
  input.id = elementId(field);
  if (spec.min !== undefined) input.min = String(spec.min);
  if (spec.max !== undefined) input.max = String(spec.max);
  input.step = String(spec.step ?? 0.01);
  return {
    root: input,
    setValue: (v) => { input.value = String(v); },
    getValue: () => Number(input.value),
  };
}

function checkboxWidget(field: PanelField): WidgetHandle {
  const input = document.createElement('input');
  input.type = 'checkbox';
  input.id = elementId(field);
  return {
    root: input,
    setValue: (v) => { input.checked = Boolean(v); },
    getValue: () => input.checked,
  };
}

function dropdownWidget(field: PanelField, options: readonly string[]): WidgetHandle {
  const select = document.createElement('select');
  select.id = elementId(field);
  for (const opt of options) {
    const o = document.createElement('option');
    o.value = opt;
    o.textContent = opt;
    select.append(o);
  }
  return {
    root: select,
    setValue: (v) => { select.value = String(v); },
    getValue: () => select.value,
  };
}

function vectorWidget(field: PanelField, components: number): WidgetHandle {
  const root = document.createElement('div');
  root.className = 'vec-widget';
  const inputs: HTMLInputElement[] = [];
  for (let i = 0; i < components; i++) {
    const input = document.createElement('input');
    input.type = 'number';
    input.step = '0.01';
    input.dataset.component = String(i);
    inputs.push(input);
    root.append(input);
  }
  return {
    root,
    setValue: (v) => {
      const arr = Array.isArray(v) ? v : [];
      inputs.forEach((input, i) => { input.value = String(arr[i] ?? 0); });
    },
    getValue: () => inputs.map((input) => Number(input.value)),
  };
}

/** 按控件描述创建 DOM 控件。控件种类决定用哪个标签。 */
export function createWidget(field: PanelField, spec: WidgetSpec): WidgetHandle {
  switch (spec.kind) {
    case 'checkbox':
      return checkboxWidget(field);
    case 'dropdown':
      return dropdownWidget(field, spec.options ?? []);
    case 'vector':
      return vectorWidget(field, spec.components ?? 3);
    case 'slider':
      return numberWidget(field, spec, true);
    default:
      return numberWidget(field, spec, false);
  }
}

// snippet: src/editor/property/widget-map.test.ts 节选
expect(defaultWidget('bool')).toBe('checkbox');
expect(defaultWidget('vec3')).toBe('vector');
expect(defaultWidgetTable()).toHaveLength(7); // 覆盖全部 7 个字段类型

const reg = new WidgetRegistry();
reg.overrideType('f32', 'slider');
reg.overrideName('speed', 'text');
expect(reg.resolve(speed).kind).toBe('text');    // 属性名覆写优先
expect(reg.resolve(grounded).kind).toBe('checkbox'); // 未覆写类型不变