《游戏引擎实现原理》10.3 多选编辑与批量修改

// file: src/editor/property/multi-select.ts
// tier: L1
// verify: npx vitest run src/editor/property/multi-select.test.ts
//
// helio 编辑器：多选编辑——计算公共属性、识别混合值、生成批量编辑命令。
// 纯数据：不碰 DOM，也不直接改场景，只产出「批量命令描述」，
// 交给 9 章的命令栈去执行与撤销。

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

/** 多选下的一个值：要么全部一致，要么是混合（并记录样本数）。 */
export type MultiValue<T> =
  | { readonly kind: 'single'; readonly value: T }
  | { readonly kind: 'mixed'; readonly count: number };

/** 多选面板里的一个字段。 */
export interface MultiField {
  readonly name: string;
  readonly type: FieldType;
  readonly value: MultiValue<unknown>;
}

/** 多选面板描述数据。 */
export interface MultiPanel {
  readonly typeName: string;
  readonly total: number;
  readonly fields: readonly MultiField[];
}

/** 一个选中对象：它的类型描述符 + 实例。 */
export interface Selection {
  readonly desc: TypeDescriptor;
  readonly obj: Record<string, unknown>;
}

/** 结构相等：标量按 ===，数组逐元素（vec3 用得到）。 */
export function equalValue(a: unknown, b: unknown): boolean {
  if (a === b) return true;
  if (Array.isArray(a) && Array.isArray(b)) {
    return a.length === b.length && a.every((v, i) => equalValue(v, b[i]));
  }
  return false;
}

/** 多个描述符的公共属性名：按第一个描述符的顺序求交集。 */
export function commonFieldNames(descs: readonly TypeDescriptor[]): string[] {
  if (descs.length === 0) return [];
  const sets = descs.map((d) => new Set(d.properties.map((p) => p.name)));
  return descs[0].properties.map((p) => p.name).filter((n) => sets.every((s) => s.has(n)));
}

/** 从一个名字在多个选中项里找到第一个能提供它的属性描述符。 */
function findProp(sel: Selection, name: string): PropertyDescriptor | undefined {
  return sel.desc.properties.find((p) => p.name === name);
}

/** 聚合一个属性在多个选中项上的值：全等 → single，否则 mixed。 */
export function aggregate(values: readonly unknown[]): MultiValue<unknown> {
  if (values.length === 0) return { kind: 'mixed', count: 0 };
  const first = values[0];
  const same = values.every((v) => equalValue(v, first));
  return same ? { kind: 'single', value: first } : { kind: 'mixed', count: values.length };
}

/** 计算多选面板：公共属性 + 每个属性的聚合值。 */
export function computeMultiPanel(selections: readonly Selection[]): MultiPanel {
  const names = commonFieldNames(selections.map((s) => s.desc));
  const fields: MultiField[] = [];
  for (const name of names) {
    const values: unknown[] = [];
    let type: FieldType = 'f32';
    for (const sel of selections) {
      const prop = findProp(sel, name);
      if (!prop) continue;
      type = prop.type;
      values.push(readProperty(sel.obj, prop));
    }
    fields.push({ name, type, value: aggregate(values) });
  }
  const typeName = selections.length > 0 ? selections[0].desc.name : '';
  return { typeName, total: selections.length, fields };
}

/** 单条属性改动。target 是选中项下标，before/after 供命令栈做撤销。 */
export interface PropertyEdit {
  readonly target: number;
  readonly property: string;
  readonly before: unknown;
  readonly after: unknown;
}

/** 批量编辑命令描述：一个标签 + 一组改动。 */
export interface BatchEditCommand {
  readonly label: string;
  readonly edits: readonly PropertyEdit[];
}

/**
 * 生成批量编辑命令：把 property 在全部选中项上设成 next。
 * 已经是目标值的项被跳过——批量命令只包含真正变化的项，撤销栈因此干净。
 */
export function buildBatchEdit(
  selections: readonly Selection[],
  property: string,
  next: unknown,
): BatchEditCommand {
  const edits: PropertyEdit[] = [];
  for (let i = 0; i < selections.length; i++) {
    const prop = findProp(selections[i], property);
    if (!prop) continue;
    const before = readProperty(selections[i].obj, prop);
    if (equalValue(before, next)) continue;
    edits.push({ target: i, property, before, after: next });
  }
  return { label: `设置 ${selections.length} 个对象的 ${property}`, edits };
}

/** 把命令应用到普通对象上（演示用；真实场景走命令栈的 apply/undo）。 */
export function applyBatch(selections: readonly Selection[], cmd: BatchEditCommand): void {
  for (const e of cmd.edits) selections[e.target].obj[e.property] = e.after;
}

// file: src/apps/editor-multiselect-demo.ts
// tier: L1
// verify: node src/apps/editor-multiselect-demo.ts
//
// 多选公共属性、混合值判定与批量命令生成——10.3 的可运行产物。

import { TypeRegistry } from '../core/type-registry.ts';
import { GENERATED_TYPES } from '../generated/type-registry.gen.ts';
import { computeMultiPanel, buildBatchEdit, applyBatch, type Selection } from '../editor/property/multi-select.ts';

const reg = new TypeRegistry();
reg.registerAll(GENERATED_TYPES);
const health = reg.get('Health')!;

const selections: Selection[] = [
  { desc: health, obj: { current: 42, max: 100, invulnerable: false } },
  { desc: health, obj: { current: 42, max: 100, invulnerable: false } },
  { desc: health, obj: { current: 10, max: 100, invulnerable: true } },
];

const panel = computeMultiPanel(selections);
console.log(`multi-panel: ${panel.typeName}, total=${panel.total}`);
for (const f of panel.fields) {
  const v = f.value.kind === 'single' ? JSON.stringify(f.value.value) : `<mixed x${f.value.count}>`;
  console.log(`  ${f.name.padEnd(13)} = ${v}`);
}

const cmd = buildBatchEdit(selections, 'current', 100);
console.log(`command: "${cmd.label}" edits=${cmd.edits.length}`);
for (const e of cmd.edits) console.log(`  #${e.target} ${e.property}: ${JSON.stringify(e.before)} -> ${JSON.stringify(e.after)}`);
applyBatch(selections, cmd);
console.log('after apply:', selections.map((s) => s.obj.current).join(', '));

multi-panel: Health, total=3
  current       = <mixed x3>
  max           = 100
  invulnerable  = <mixed x3>
command: "设置 3 个对象的 current" edits=3
  #0 current: 42 -> 100
  #1 current: 42 -> 100
  #2 current: 10 -> 100
after apply: 100, 100, 100

// file: src/editor/property/multi-view.ts
// tier: L3
//
// 多选面板的 DOM 渲染：混合值显示占位、批量改动的交互入口。
// 依赖 document，命令行不可复现，需在浏览器中手动验证。

import type { MultiPanel, MultiField, Selection } from './multi-select.ts';
import { applyBatch, buildBatchEdit } from './multi-select.ts';

/** 混合值的占位符——多选时该项值不一致。 */
export const MIXED_PLACEHOLDER = '—';

function renderField(f: MultiField): HTMLElement {
  const row = document.createElement('div');
  row.className = 'field-row';
  const label = document.createElement('label');
  label.textContent = f.name;
  const value = document.createElement('span');
  if (f.value.kind === 'single') {
    value.textContent = String(f.value.value);
  } else {
    value.textContent = MIXED_PLACEHOLDER;
    value.classList.add('is-mixed');
  }
  row.append(label, value);
  return row;
}

/** 把多选面板渲染进宿主节点：标题是「类型名 × 选中数」。 */
export function renderMultiPanel(panel: MultiPanel, host: HTMLElement): void {
  host.replaceChildren();
  const title = document.createElement('header');
  title.className = 'multi-header';
  title.textContent = `${panel.typeName} × ${panel.total}`;
  host.append(title);
  for (const f of panel.fields) host.append(renderField(f));
}

/**
 * 批量改动的交互入口：生成批量命令并交给命令栈执行。
 * 真实场景里 applyBatch 会被 9 章命令栈的 apply/undo 取代，
 * 此处为演示直接落到对象上。
 */
export function commitBatch(
  selections: readonly Selection[],
  property: string,
  next: unknown,
): boolean {
  const cmd = buildBatchEdit(selections, property, next);
  if (cmd.edits.length === 0) return false;
  applyBatch(selections, cmd);
  return true;
}

// snippet: src/editor/property/multi-select.test.ts 节选
expect(commonFieldNames([HEALTH, ENEMY])).toEqual(['current']); // 混合类型只留交集

expect(aggregate([[1, 2, 3], [1, 2, 3]])).toEqual({ kind: 'single', value: [1, 2, 3] }); // vec3 逐元素
expect(aggregate([[1, 2, 3], [1, 2, 4]])).toEqual({ kind: 'mixed', count: 2 });

// 已是目标值的项被跳过
const cmd = buildBatchEdit([{ desc: HEALTH, obj: { current: 50 } },
                            { desc: HEALTH, obj: { current: 50 } }], 'current', 50);
expect(cmd.edits).toHaveLength(0);