@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/export/bin-writer.ts

@@ -0,0 +1,79 @@
+// Packs typed arrays into one 4-byte-aligned glTF buffer and records bufferViews + accessors.
+
+export const ARRAY_BUFFER = 34962;
+export const ELEMENT_ARRAY_BUFFER = 34963;
+const FLOAT = 5126;
+const UINT32 = 5125;
+const UINT16 = 5123;
+
+export interface Json {
+  [key: string]: unknown;
+}
+
+export class BinWriter {
+  private readonly chunks: Uint8Array[] = [];
+  length = 0;
+  readonly views: Json[] = [];
+  readonly accessors: Json[] = [];
+
+  private push(bytes: Uint8Array, target?: number): number {
+    const pad = (4 - (this.length % 4)) % 4;
+    if (pad) {
+      this.chunks.push(new Uint8Array(pad));
+      this.length += pad;
+    }
+    this.views.push({
+      buffer: 0,
+      byteOffset: this.length,
+      byteLength: bytes.byteLength,
+      ...(target ? { target } : {}),
+    });
+    this.chunks.push(bytes);
+    this.length += bytes.byteLength;
+    return this.views.length - 1;
+  }
+
+  accessor(
+    data: Float32Array | Uint32Array | Uint16Array,
+    type: 'SCALAR' | 'VEC2' | 'VEC3' | 'VEC4',
+    target?: number,
+    bounds = false,
+    /** Integer data read as 0..1 (vertex colour as normalised unsigned short). */
+    normalized = false,
+  ): number {
+    const view = this.push(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), target);
+    const width = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4 }[type];
+    const acc: Json = {
+      bufferView: view,
+      componentType:
+        data instanceof Uint32Array ? UINT32 : data instanceof Uint16Array ? UINT16 : FLOAT,
+      count: data.length / width,
+      type,
+      ...(normalized ? { normalized: true } : {}),
+    };
+    if (bounds) {
+      const min = Array<number>(width).fill(Infinity);
+      const max = Array<number>(width).fill(-Infinity);
+      for (let i = 0; i < data.length; i++) {
+        const k = i % width;
+        const v = data[i] ?? 0;
+        if (v < (min[k] ?? 0)) min[k] = v;
+        if (v > (max[k] ?? 0)) max[k] = v;
+      }
+      acc['min'] = min;
+      acc['max'] = max;
+    }
+    this.accessors.push(acc);
+    return this.accessors.length - 1;
+  }
+
+  bytes(): Uint8Array {
+    const out = new Uint8Array(Math.ceil(this.length / 4) * 4);
+    let o = 0;
+    for (const c of this.chunks) {
+      out.set(c, o);
+      o += c.byteLength;
+    }
+    return out;
+  }
+}

package/src/export/container.ts

@@ -0,0 +1,35 @@
+// The GLB container: 12-byte header, JSON chunk (space-padded), BIN chunk (zero-padded), every
+// length a multiple of 4 [glTF 2.0 §glb-file-format-specification].
+
+import type { Json } from './bin-writer.ts';
+
+export function packGlb(gltf: Json, body: Uint8Array): Uint8Array {
+  let json = new TextEncoder().encode(JSON.stringify(gltf));
+  const jsonPad = (4 - (json.byteLength % 4)) % 4;
+  if (jsonPad) {
+    const padded = new Uint8Array(json.byteLength + jsonPad).fill(0x20);
+    padded.set(json);
+    json = padded;
+  }
+  const total = 12 + 8 + json.byteLength + 8 + body.byteLength;
+  const out = new Uint8Array(total);
+  const dv = new DataView(out.buffer);
+  dv.setUint32(0, 0x46546c67, true);
+  dv.setUint32(4, 2, true);
+  dv.setUint32(8, total, true);
+  dv.setUint32(12, json.byteLength, true);
+  dv.setUint32(16, 0x4e4f534a, true);
+  out.set(json, 20);
+  const binAt = 20 + json.byteLength;
+  dv.setUint32(binAt, body.byteLength, true);
+  dv.setUint32(binAt + 4, 0x004e4942, true);
+  out.set(body, binAt + 8);
+  return out;
+}
+
+export function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.byteLength + b.byteLength);
+  out.set(a);
+  out.set(b, a.byteLength);
+  return out;
+}

package/src/export/glb.ts

@@ -0,0 +1,200 @@
+// glTF 2.0 binary writer. One material (the trim sheet) for the whole asset, one node per part
+// with its pivot as translation, and each part's motion baked as a looping animation clip.
+// Extras a stock viewer understands: light sockets → KHR_lights_punctual, glowing parts →
+// emissive (+ KHR_materials_emissive_strength), provenance → asset.copyright + KHR_xmp_json_ld.
+// Zero dependencies and byte-deterministic: same CompiledAsset in, same bytes out.
+
+import type { CompiledAsset, Part } from '../core/index.ts';
+import { quatFromAxisAngle, Ts23dError } from '../core/index.ts';
+import type { OptimizeOptions } from '../passes/index.ts';
+import { BinWriter, type Json } from './bin-writer.ts';
+import { concat, packGlb } from './container.ts';
+import { LIGHTS, lightOf } from './lights.ts';
+import { EMISSIVE_STRENGTH, type GlowRule, glowMaterial, materialsFor } from './materials.ts';
+import { globRe, glowLayer, mergeToPivots } from './merge-pivots.ts';
+import { type GlbMeta, metadata } from './metadata.ts';
+import { motionChannel } from './motion.ts';
+import { type ExportReport, optimizeParts } from './optimize-parts.ts';
+import { writePrimitive } from './primitive.ts';
+import { type SheetBinding, sheetGltf } from './textures.ts';
+
+// Viewers auto-play the FIRST clip and glTF has no "paused" flag, so the first clip is `rest`: two
+// keys holding the root's rest rotation. The file opens still; pick `run` to play it.
+// Authoring frame: Z up, +X front. glTF: Y up, +Z front, +X = the asset's left. This root
+// rotation maps +X→+Z, +Z→+Y, +Y→+X (verified numerically), so assets face forward in engines.
+const Z_UP_TO_Y_UP = [-0.5, -0.5, -0.5, 0.5];
+function restClip(bin: BinWriter): Json {
+  const input = bin.accessor(new Float32Array([0, 1]), 'SCALAR', undefined, true);
+  const output = bin.accessor(new Float32Array([...Z_UP_TO_Y_UP, ...Z_UP_TO_Y_UP]), 'VEC4');
+  return {
+    name: 'rest',
+    samplers: [{ input, output, interpolation: 'STEP' }],
+    channels: [{ sampler: 0, target: { node: 0, path: 'rotation' } }],
+  };
+}
+
+export interface GlbOptions {
+  /** Keep every part as its own node (debugging, per-part picking). Default merges to pivots. */
+  readonly keepParts?: boolean;
+  /**
+   * Bake each part's `motion` into a looping `run` clip. Off by default: glTF has no autoplay
+   * flag and most viewers play the first clip, while engines usually drive the named pivots
+   * from game code. Turn it on for previews, cutscenes and ambient props.
+   */
+  readonly animations?: boolean;
+  /**
+   * Bind the painted trim sheet to every material: a `PaintedSheet` embeds the three PNGs (one
+   * self-contained file); `{ external: true, prefix? }` references shared `trim_sheet_*.png` by
+   * URI. Omitted: no textures, byte-identical to the untextured output.
+   */
+  readonly sheet?: SheetBinding;
+  /**
+   * Weld + vertex-cache + vertex-fetch optimisation per primitive (passes/optimize). On by
+   * default; `false` writes the meshes exactly as compiled (debugging the IR).
+   */
+  readonly optimize?: boolean | OptimizeOptions;
+  /** Parts that emit light (lamp lenses, lit windows): one emissive material per rule. */
+  readonly glow?: readonly GlowRule[];
+  /** Provenance: asset.copyright + an XMP packet (title, creators, licence, sources). */
+  readonly meta?: GlbMeta;
+}
+
+/** The GLB bytes plus what the optimiser did (vertex counts, ACMR before/after, per part). */
+export interface GlbResult {
+  readonly glb: Uint8Array;
+  readonly report: ExportReport;
+}
+
+export function toGlb(input: CompiledAsset, o: GlbOptions = {}): Uint8Array {
+  return exportGlb(input, o).glb;
+}
+
+function checkGlow(rules: readonly GlowRule[]): void {
+  for (const r of rules)
+    if ((r.strength ?? 4) < 0 || (r.color ?? [0, 0, 0]).some((c) => c < 0 || c > 1))
+      throw new Ts23dError('T3D_RECIPE_INVALID', {
+        cause: `glow rule for ${JSON.stringify(r.parts)} has a colour outside 0..1 or a negative strength`,
+        fix: 'colour is linear 0..1 (hex() converts sRGB); brightness goes in `strength`',
+      });
+}
+
+export function exportGlb(input: CompiledAsset, o: GlbOptions = {}): GlbResult {
+  const glow = o.glow ?? input.glow ?? [];
+  checkGlow(glow);
+  const opt = o.optimize === false ? false : o.optimize === true ? {} : (o.optimize ?? {});
+  const merged = o.keepParts
+    ? input
+    : mergeToPivots(
+        input,
+        glow.map((g) => g.parts),
+      );
+  const { asset, report } = optimizeParts(merged, opt);
+  // optimizeParts copies parts: carry the glow tag across by position.
+  const glowRes = glow.map((g) => g.parts.map(globRe));
+  const glowOf = (p: Part, i: number): number =>
+    glowLayer.get(merged.parts[i] ?? p) ??
+    (o.keepParts ? glowRes.findIndex((rs) => rs.some((r) => r.test(p.name))) : -1);
+  const mats = materialsFor(
+    new Set(asset.parts.flatMap((p) => (p.surface ? [p.surface] : []))),
+    o.sheet !== undefined,
+  );
+  const glowAt = mats.materials.length;
+  const materials = [
+    ...mats.materials,
+    ...glow.map((g, i) => glowMaterial(g, i, o.sheet !== undefined)),
+  ];
+  const bin = new BinWriter();
+  const meshes: Json[] = [];
+  const nodes: Json[] = [{ name: asset.name, children: [] as number[] }];
+  const index = new Map<string, number>();
+  const samplers: Json[] = [];
+  const channels: Json[] = [];
+  const lights: Json[] = [];
+  const attach = (parentId: number, id: number): void => {
+    const parent = nodes[parentId];
+    if (!parent) return;
+    parent['children'] = [...((parent['children'] as number[] | undefined) ?? []), id];
+  };
+
+  asset.parts.forEach((part: Part, i) => {
+    const node: Json = { name: part.name, translation: [...part.at] };
+    if (part.yaw) node['rotation'] = [...quatFromAxisAngle([0, 0, 1], part.yaw)];
+    if (part.emitter || part.socket) {
+      node['extras'] = {
+        ts23d: {
+          ...(part.emitter ? { emitter: part.emitter } : {}),
+          ...(part.socket ? { socket: part.socket } : {}),
+        },
+      };
+    }
+    if (part.mesh && part.mesh.indices.length > 0) {
+      const g = glowOf(part, i);
+      const material = g >= 0 ? glowAt + g : (mats.index.get(part.surface ?? 'opaque') ?? 0);
+      meshes.push({
+        name: part.name,
+        primitives: [writePrimitive(bin, part.mesh, material, o.sheet !== undefined)],
+      });
+      node['mesh'] = meshes.length - 1;
+    }
+    nodes.push(node);
+    const id = nodes.length - 1;
+    index.set(part.name, id);
+    attach(part.parent === null ? 0 : (index.get(part.parent) ?? 0), id);
+    const lit = lightOf(part);
+    if (lit) {
+      lights.push(lit.light);
+      nodes.push({
+        name: `${part.name}_light`,
+        rotation: [...lit.rotation],
+        extensions: { [LIGHTS]: { light: lights.length - 1 } },
+      });
+      attach(id, nodes.length - 1);
+    }
+    if (part.motion && o.animations) {
+      const { sampler, channel } = motionChannel(bin, part.motion, id, part.at);
+      samplers.push(sampler);
+      channels.push({ ...channel, sampler: samplers.length - 1 });
+    }
+  });
+
+  // Every accessor — the rest clip's included — must be written BEFORE the buffer is sealed.
+  const animations = channels.length ? [restClip(bin), { name: 'run', samplers, channels }] : [];
+  const geometry = bin.bytes();
+  const tex = o.sheet ? sheetGltf(o.sheet, bin.views, geometry.byteLength) : null;
+  const body = tex?.tail.byteLength ? concat(geometry, tex.tail) : geometry;
+  const meta = metadata(asset.name, o.meta ?? input.meta);
+  const used = [
+    ...mats.extensionsUsed,
+    ...(glow.some((g) => (g.strength ?? 4) !== 1) ? [EMISSIVE_STRENGTH] : []),
+    ...(lights.length ? [LIGHTS] : []),
+    ...meta.used,
+  ].sort();
+  const extensions: Json = {
+    ...(lights.length ? { [LIGHTS]: { lights } } : {}),
+    ...(meta.extensions ?? {}),
+  };
+  const root = nodes[0];
+  if (root) root['rotation'] = Z_UP_TO_Y_UP;
+  const gltf: Json = {
+    asset: meta.asset,
+    extras: {
+      kind: asset.kind,
+      lod: asset.lod,
+      units: 'metres',
+      up: 'Z (rotated to glTF Y-up at the root)',
+    },
+    ...(used.length ? { extensionsUsed: used } : {}),
+    ...(Object.keys(extensions).length ? { extensions } : {}),
+    scene: 0,
+    scenes: [{ name: asset.name, nodes: [0] }],
+    nodes,
+    meshes,
+    materials,
+    ...(tex ? tex.json : {}),
+    buffers: [{ byteLength: body.byteLength }],
+    bufferViews: bin.views,
+    accessors: bin.accessors,
+    ...(animations.length ? { animations } : {}),
+  };
+  return { glb: packGlb(gltf, body), report };
+}

package/src/export/index.ts

@@ -0,0 +1,18 @@
+// Public API of /export: back ends that turn a CompiledAsset into a file.
+
+export { exportGlb, type GlbOptions, type GlbResult, toGlb } from './glb.ts';
+export { mergeToPivots } from './merge-pivots.ts';
+export {
+  type ExportReport,
+  optimizeParts,
+  type PartOptimizeReport,
+  summarize,
+} from './optimize-parts.ts';
+export {
+  type ExternalSheet,
+  SHEET_MAPS,
+  type SheetBinding,
+  type SheetMap,
+  sheetFileName,
+  sheetPngs,
+} from './textures.ts';

package/src/export/lights.ts

@@ -0,0 +1,49 @@
+// KHR_lights_punctual from light sockets: `ctx.socket('headlamp_l', { kind: 'light', dir,
+// data: { light: 'spot', color: '#ffe8c0', intensity: 200, range: 30, cone: 25 } })` becomes a
+// real light every engine and viewer can switch on. The socket node stays as authored; the light
+// rides a child node `<socket>_light` rotated so its −Z (the glTF light direction) is `dir`.
+
+import type { Part, Quat, Vec3 } from '../core/index.ts';
+import { hex } from '../material/index.ts';
+import type { Json } from './bin-writer.ts';
+
+export const LIGHTS = 'KHR_lights_punctual';
+
+/** Shortest rotation taking unit `a` onto unit `b`. */
+function between(a: Vec3, b: Vec3): Quat {
+  const d = a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+  if (d < -0.999999) return [1, 0, 0, 0]; // opposite: half turn about X (⊥ to −Z)
+  const c: Vec3 = [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+  const w = 1 + d;
+  const n = Math.hypot(c[0], c[1], c[2], w);
+  return [c[0] / n, c[1] / n, c[2] / n, w / n];
+}
+
+const num = (v: unknown, fallback: number): number =>
+  typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+
+/** The glTF light for a light socket, or null for any other part. */
+export function lightOf(part: Part): { light: Json; rotation: Quat } | null {
+  const s = part.socket;
+  if (s?.kind !== 'light') return null;
+  const d = s.data ?? {};
+  const type = d['light'] === 'point' || d['light'] === 'directional' ? d['light'] : 'spot';
+  const color = typeof d['color'] === 'string' ? hex(d['color']) : [1, 1, 1];
+  const dir = s.dir ?? [1, 0, 0];
+  const len = Math.hypot(...dir) || 1;
+  const outer = (Math.min(89, num(d['cone'], 30)) * Math.PI) / 180;
+  const inner = Math.min(outer * 0.999, (num(d['inner'], 0) * Math.PI) / 180);
+  const range = num(d['range'], 0);
+  return {
+    light: {
+      name: part.name,
+      type,
+      color,
+      // Spot/point: candela; directional: lux. Defaults suit a vehicle lamp / a sun.
+      intensity: num(d['intensity'], type === 'directional' ? 3 : type === 'point' ? 20 : 100),
+      ...(range > 0 && type !== 'directional' ? { range } : {}),
+      ...(type === 'spot' ? { spot: { innerConeAngle: inner, outerConeAngle: outer } } : {}),
+    },
+    rotation: between([0, 0, -1], [dir[0] / len, dir[1] / len, dir[2] / len]),
+  };
+}

package/src/export/materials.ts

@@ -0,0 +1,126 @@
+// The (at most) four shared materials, one per Surface in use. All sample the same trim sheet and
+// take tint from COLOR_0, so batching holds; only the shading model differs. Glass/translucent use
+// KHR_materials_transmission + _volume + _ior (three, Babylon, glTFast); engines without them fall
+// back to alpha BLEND via baseColorFactor.a. With a painted sheet bound (textures.ts), every
+// material samples it: baseColor (sRGB, alpha = cutout mask), normal, and ORM in both the
+// occlusion and metallicRoughness slots. Opaque/cutout factors go to 1 so the ORM texture rules;
+// glass/translucent keep theirs as multipliers (clear stays clear whatever strip it maps).
+
+import type { Surface } from '../core/index.ts';
+import type { Json } from './bin-writer.ts';
+
+const MATERIALS: Readonly<Record<Surface, Json>> = {
+  opaque: {
+    name: 'ts23d_trim',
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 1],
+      metallicFactor: 0,
+      roughnessFactor: 0.8,
+    },
+  },
+  cutout: {
+    name: 'ts23d_trim_cutout',
+    alphaMode: 'MASK',
+    alphaCutoff: 0.5,
+    doubleSided: true,
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 1],
+      metallicFactor: 0,
+      roughnessFactor: 0.9,
+    },
+  },
+  glass: {
+    name: 'ts23d_glass',
+    alphaMode: 'BLEND',
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 0.25],
+      metallicFactor: 0,
+      roughnessFactor: 0.05,
+    },
+    extensions: {
+      KHR_materials_transmission: { transmissionFactor: 1 },
+      KHR_materials_volume: { thicknessFactor: 0.01 },
+      KHR_materials_ior: { ior: 1.5 },
+    },
+  },
+  translucent: {
+    name: 'ts23d_translucent',
+    alphaMode: 'BLEND',
+    pbrMetallicRoughness: {
+      baseColorFactor: [1, 1, 1, 0.6],
+      metallicFactor: 0,
+      roughnessFactor: 0.35,
+    },
+    extensions: {
+      KHR_materials_transmission: { transmissionFactor: 0.6 },
+      KHR_materials_volume: { thicknessFactor: 0.02 },
+      KHR_materials_ior: { ior: 1.45 },
+    },
+  },
+};
+
+const ORDER: readonly Surface[] = ['opaque', 'cutout', 'glass', 'translucent'];
+
+/** The same material sampling the sheet (texture indices fixed by textures.ts). */
+function textured(m: Json, surface: Surface): Json {
+  const pbr = m['pbrMetallicRoughness'] as Json;
+  const own = surface === 'opaque' || surface === 'cutout';
+  return {
+    ...m,
+    pbrMetallicRoughness: {
+      ...pbr,
+      baseColorTexture: { index: 0 },
+      metallicRoughnessTexture: { index: 2 },
+      ...(own ? { metallicFactor: 1, roughnessFactor: 1 } : {}),
+    },
+    normalTexture: { index: 1 },
+    occlusionTexture: { index: 2 },
+  };
+}
+
+/** Materials for the surfaces present, plus each surface's index and the extensions used. */
+export function materialsFor(
+  used: ReadonlySet<Surface>,
+  withSheet = false,
+): {
+  materials: Json[];
+  index: Map<Surface, number>;
+  extensionsUsed: string[];
+} {
+  const present = ORDER.filter((s) => s === 'opaque' || used.has(s));
+  const index = new Map(present.map((s, i) => [s, i] as const));
+  const ext = new Set<string>();
+  for (const s of present)
+    for (const e of Object.keys((MATERIALS[s]['extensions'] as Json | undefined) ?? {})) ext.add(e);
+  const materials = present.map((s) => (withSheet ? textured(MATERIALS[s], s) : MATERIALS[s]));
+  return { materials, index, extensionsUsed: [...ext].sort() };
+}
+
+export const EMISSIVE_STRENGTH = 'KHR_materials_emissive_strength';
+
+/** A lit surface: lamp lenses, windows at night, panel glow. */
+export interface GlowRule {
+  /** Part names or globs: 'headlamp_*', 'window_*'. */
+  readonly parts: readonly string[];
+  /** Linear RGB 0..1 (use `hex('#ffd9a0')` from /material). Default warm white. */
+  readonly color?: readonly [number, number, number];
+  /** Brightness multiplier (KHR_materials_emissive_strength, Ratified); 1 = plain glTF. */
+  readonly strength?: number;
+}
+
+/**
+ * The opaque trim material plus emission. emissiveFactor caps at 1 in core glTF; anything
+ * brighter rides KHR_materials_emissive_strength (engines without it see the clamped glow).
+ */
+export function glowMaterial(rule: GlowRule, i: number, withSheet: boolean): Json {
+  const base = withSheet ? textured(MATERIALS.opaque, 'opaque') : MATERIALS.opaque;
+  const strength = rule.strength ?? 4;
+  return {
+    ...base,
+    name: `ts23d_glow_${i}`,
+    emissiveFactor: [...(rule.color ?? [1, 0.85, 0.6])],
+    ...(strength !== 1
+      ? { extensions: { [EMISSIVE_STRENGTH]: { emissiveStrength: strength } } }
+      : {}),
+  };
+}

package/src/export/merge-pivots.ts

@@ -0,0 +1,146 @@
+// Batching for engines: every part that is NOT a pivot is merged into its nearest pivot ancestor,
+// so draw calls = pivots with geometry, not parts. A pivot is anything the engine may move: a
+// group (`ctx.group`, a named handle like `turret`, `gun`, `door_l`) or a part with `motion`.
+// Static top-level geometry merges into one `body` part. Names the engine binds to survive.
+// Non-opaque surfaces split into `<pivot>_<surface>` children (one draw call per surface), and
+// glowing parts (GlbOptions.glow) into `<pivot>_glow_<i>` children with their emissive material.
+
+import {
+  type CompiledAsset,
+  type Mesh,
+  merge,
+  type Part,
+  rotateZ,
+  type Surface,
+  toWorld,
+  type WorldTransform,
+  worldTransforms,
+} from '../core/index.ts';
+
+const isPivot = (p: Part): boolean => p.mesh === null || p.motion !== null;
+
+/** Merged layer parts that glow → index of the glow rule (read by the GLB writer). */
+export const glowLayer = new WeakMap<Part, number>();
+
+/** `*`/`?` glob → anchored RegExp (export cannot import /qa: same tier). */
+export const globRe = (pattern: string): RegExp =>
+  new RegExp(
+    `^${pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replaceAll('*', '.*')
+      .replaceAll('?', '.')}$`,
+  );
+const SURFACES: readonly Surface[] = ['cutout', 'glass', 'translucent'];
+
+/** Re-express a part's mesh in its pivot's local space. */
+function intoPivot(mesh: Mesh, part: WorldTransform, pivot: WorldTransform): Mesh {
+  const positions = new Float32Array(mesh.positions.length);
+  const normals = new Float32Array(mesh.normals.length);
+  for (let i = 0; i < positions.length; i += 3) {
+    const w = toWorld(part, [
+      mesh.positions[i] ?? 0,
+      mesh.positions[i + 1] ?? 0,
+      mesh.positions[i + 2] ?? 0,
+    ]);
+    positions.set(
+      rotateZ([w[0] - pivot.origin[0], w[1] - pivot.origin[1], w[2] - pivot.origin[2]], -pivot.yaw),
+      i,
+    );
+    normals.set(
+      rotateZ(
+        rotateZ(
+          [mesh.normals[i] ?? 0, mesh.normals[i + 1] ?? 0, mesh.normals[i + 2] ?? 0],
+          part.yaw,
+        ),
+        -pivot.yaw,
+      ),
+      i,
+    );
+  }
+  return { ...mesh, positions, normals };
+}
+
+export function mergeToPivots(
+  asset: CompiledAsset,
+  glow: readonly (readonly string[])[] = [],
+): CompiledAsset {
+  const glowRes = glow.map((globs) => globs.map(globRe));
+  const glowOf = (name: string): number => glowRes.findIndex((rs) => rs.some((r) => r.test(name)));
+  const byName = new Map(asset.parts.map((p) => [p.name, p]));
+  const xf = worldTransforms(asset.parts);
+  const ROOT = 'body';
+  const identity: WorldTransform = { origin: [0, 0, 0], yaw: 0 };
+  const pivotOf = (p: Part): string => {
+    let cur = p.parent ? byName.get(p.parent) : undefined;
+    while (cur && !isPivot(cur)) cur = cur.parent ? byName.get(cur.parent) : undefined;
+    return cur?.name ?? ROOT;
+  };
+  // Buckets keyed by pivot + surface: opaque merges into the pivot's own mesh; each other
+  // surface in use becomes one child `<pivot>_<surface>` so materials never mix in a primitive.
+  const extra = new Map<string, Mesh[]>();
+  const bucket = (pivot: string, surface: Surface | undefined, mesh: Mesh, g = -1): void => {
+    const k = `${pivot}|${g >= 0 ? `glow_${g}` : (surface ?? 'opaque')}`;
+    extra.set(k, [...(extra.get(k) ?? []), mesh]);
+  };
+  for (const p of asset.parts) {
+    if (!p.mesh) continue;
+    const g = glowOf(p.name);
+    if (isPivot(p)) {
+      bucket(p.name, p.surface, p.mesh, g);
+      continue;
+    }
+    const pivot = pivotOf(p);
+    const t = xf.get(p.name) ?? identity;
+    const pt = pivot === ROOT ? identity : (xf.get(pivot) ?? identity);
+    bucket(pivot, p.surface, intoPivot(p.mesh, t, pt), g);
+  }
+  const parts: Part[] = [];
+  const layers = (pivot: string, parent: string | null): void => {
+    for (const surface of SURFACES) {
+      const meshes = extra.get(`${pivot}|${surface}`);
+      if (!meshes) continue;
+      parts.push({
+        name: `${pivot}_${surface}`,
+        mesh: merge(meshes),
+        at: [0, 0, 0],
+        parent,
+        yaw: 0,
+        motion: null,
+        surface,
+      });
+    }
+    glow.forEach((_, g) => {
+      const meshes = extra.get(`${pivot}|glow_${g}`);
+      if (!meshes) return;
+      const part: Part = {
+        name: `${pivot}_glow_${g}`,
+        mesh: merge(meshes),
+        at: [0, 0, 0],
+        parent,
+        yaw: 0,
+        motion: null,
+      };
+      glowLayer.set(part, g);
+      parts.push(part);
+    });
+  };
+  const body = extra.get(`${ROOT}|opaque`);
+  if (body)
+    parts.push({
+      name: ROOT,
+      mesh: merge(body),
+      at: [0, 0, 0],
+      parent: null,
+      yaw: 0,
+      motion: null,
+    });
+  layers(ROOT, null);
+  for (const p of asset.parts) {
+    if (!isPivot(p)) continue;
+    const own = extra.get(`${p.name}|opaque`);
+    const { surface: _drop, ...rest } = p;
+    parts.push({ ...rest, mesh: own ? merge(own) : null });
+    layers(p.name, p.name);
+  }
+  return { ...asset, parts };
+}