@volter/editor-threejs 0.5.65 → 0.5.66

package/serving/model-import-conversion.ts

@@ -0,0 +1,344 @@
+/// <reference lib="dom" />
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, extname } from 'node:path';
+import * as THREE from 'three';
+import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
+import { mergeVertices } from 'three/addons/utils/BufferGeometryUtils.js';
+import type { ModelConverter, ModelImportSettings } from '@volter/editor-sdk/session/project-serving';
+
+/** three.js's conversion of the source formats its loaders read, as the asset library's
+ *  model converter (`ProjectServingServices.registerModelConverter`). */
+export const threeModelConverter: ModelConverter = {
+  formats: ['fbx', 'obj', 'dae', 'stl', 'ply', '3ds'],
+  convert: (primaryPath, format, settings) => convertStagedModelToGlb(primaryPath, format, settings),
+};
+
+/** Convert a staged source model to a runtime GLB without requiring Blender. */
+export async function convertStagedModelToGlb(
+  primaryPath: string,
+  format: string,
+  settings: ModelImportSettings,
+): Promise<Uint8Array> {
+  installNodeDom();
+  const bytes = new Uint8Array(await readFile(primaryPath));
+  const object = await parseSourceModel(primaryPath, format.toLowerCase(), bytes);
+  discardUnloadedTextures(object);
+  applyModelImportSettings(object, settings);
+  installNodeFileReader();
+  try {
+    const result = await new Promise<ArrayBuffer>((resolve, reject) => {
+      new GLTFExporter().parse(
+        object,
+        (output) =>
+          output instanceof ArrayBuffer
+            ? resolve(output)
+            : reject(new Error('Model conversion produced JSON instead of binary GLB.')),
+        reject,
+        { binary: true, animations: object.animations, onlyVisible: false },
+      );
+    });
+    const output = new Uint8Array(result);
+    await validateConvertedGlb(output);
+    return output;
+  } finally {
+    disposeObject(object);
+  }
+}
+
+const materialTextureSlots = [
+  'map',
+  'alphaMap',
+  'aoMap',
+  'bumpMap',
+  'displacementMap',
+  'emissiveMap',
+  'envMap',
+  'lightMap',
+  'metalnessMap',
+  'normalMap',
+  'roughnessMap',
+  'specularMap',
+] as const;
+
+/** Apply the persisted conversion settings before the runtime GLB is exported. */
+export function applyModelImportSettings(
+  object: THREE.Object3D,
+  settings: ModelImportSettings,
+): void {
+  object.scale.multiplyScalar(settings.scale * sourceUnitScale(settings.sourceUnits));
+  object.quaternion.premultiply(importAxisRotation(settings.upAxis, settings.forwardAxis));
+
+  const discardedTextures = new Set<THREE.Texture>();
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one traversal deliberately applies the persisted mesh, material, texture, normal, tangent, and optimization settings to each converted renderable.
+  object.traverse((node) => {
+    const mesh = node as THREE.Mesh;
+    if (!mesh.geometry) return;
+    let geometry = mesh.geometry;
+    if (settings.meshOptimization !== 'none') {
+      const optimized = mergeVertices(
+        geometry,
+        settings.meshOptimization === 'aggressive' ? 1e-3 : 1e-6,
+      );
+      if (optimized !== geometry) {
+        mesh.geometry = optimized;
+        geometry.dispose();
+        geometry = optimized;
+      }
+    }
+    if (settings.normals !== 'preserve') {
+      geometry.deleteAttribute('normal');
+      geometry.computeVertexNormals();
+    }
+    if (settings.tangents === 'discard') geometry.deleteAttribute('tangent');
+    if (
+      settings.tangents === 'generate' &&
+      geometry.index &&
+      geometry.hasAttribute('position') &&
+      geometry.hasAttribute('normal') &&
+      geometry.hasAttribute('uv')
+    ) {
+      geometry.computeTangents();
+    }
+    geometry.computeBoundingBox();
+    geometry.computeBoundingSphere();
+
+    const priorMaterials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    if (settings.materials === 'discard') {
+      mesh.material = Array.isArray(mesh.material)
+        ? priorMaterials.map(() => new THREE.MeshStandardMaterial())
+        : new THREE.MeshStandardMaterial();
+      for (const material of priorMaterials) material.dispose();
+      return;
+    }
+    if (settings.textures !== 'discard') return;
+    for (const material of priorMaterials) {
+      const textured = material as THREE.Material & Record<string, unknown>;
+      for (const slot of materialTextureSlots) {
+        const texture = textured[slot];
+        if (texture instanceof THREE.Texture) discardedTextures.add(texture);
+        textured[slot] = null;
+      }
+      material.needsUpdate = true;
+    }
+  });
+  for (const texture of discardedTextures) texture.dispose();
+
+  if (settings.animations.length > 0) {
+    const requested = new Set(settings.animations);
+    const selected = object.animations.filter((clip) => requested.has(clip.name));
+    const missing = settings.animations.filter(
+      (name) => !selected.some((clip) => clip.name === name),
+    );
+    if (missing.length > 0) throw new Error(`Animation clips not found: ${missing.join(', ')}.`);
+    object.animations = selected;
+  }
+  object.updateWorldMatrix(true, true);
+}
+
+function sourceUnitScale(units: ModelImportSettings['sourceUnits']): number {
+  return { auto: 1, mm: 0.001, cm: 0.01, m: 1, in: 0.0254, ft: 0.3048 }[units];
+}
+
+function importAxisRotation(
+  upAxis: ModelImportSettings['upAxis'],
+  forwardAxis: ModelImportSettings['forwardAxis'],
+): THREE.Quaternion {
+  const up = upAxis === 'auto' ? null : axisVector(upAxis);
+  const forward = forwardAxis === 'auto' ? null : axisVector(forwardAxis);
+  if (up && forward) {
+    if (Math.abs(up.dot(forward)) > 0.001)
+      throw new Error('Import up and forward axes must be perpendicular.');
+    const right = new THREE.Vector3().crossVectors(forward, up).normalize();
+    const correctedForward = new THREE.Vector3().crossVectors(up, right).normalize();
+    const sourceBasis = new THREE.Matrix4().makeBasis(right, up, correctedForward.clone().negate());
+    return new THREE.Quaternion().setFromRotationMatrix(sourceBasis.invert());
+  }
+  if (up) return new THREE.Quaternion().setFromUnitVectors(up, new THREE.Vector3(0, 1, 0));
+  if (forward)
+    return new THREE.Quaternion().setFromUnitVectors(forward, new THREE.Vector3(0, 0, -1));
+  return new THREE.Quaternion();
+}
+
+function axisVector(axis: Exclude<ModelImportSettings['forwardAxis'], 'auto'> | 'x' | 'y' | 'z') {
+  const sign = axis.startsWith('-') ? -1 : 1;
+  const name = axis.replace('-', '');
+  return new THREE.Vector3(
+    name === 'x' ? sign : 0,
+    name === 'y' ? sign : 0,
+    name === 'z' ? sign : 0,
+  );
+}
+
+async function parseSourceModel(
+  primaryPath: string,
+  format: string,
+  bytes: Uint8Array,
+): Promise<THREE.Object3D> {
+  const resourcePath = `${dirname(primaryPath)}/`;
+  switch (format) {
+    case 'fbx':
+      return new FBXLoader().parse(bytes.buffer as ArrayBuffer, resourcePath);
+    case 'obj': {
+      const loader = new OBJLoader();
+      const materialPath = primaryPath.replace(/\.obj$/i, '.mtl');
+      try {
+        const materials = new MTLLoader().parse(await readFile(materialPath, 'utf8'), resourcePath);
+        materials.preload();
+        loader.setMaterials(materials);
+      } catch {
+        // Geometry-only OBJ conversion remains valid when no MTL is present.
+      }
+      return loader.parse(new TextDecoder().decode(bytes));
+    }
+    case 'dae': {
+      return new ColladaLoader().parse(new TextDecoder().decode(bytes), resourcePath).scene;
+    }
+    case 'stl': {
+      const geometry = new STLLoader().parse(bytes.buffer as ArrayBuffer);
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({ color: 0x8fb5da, roughness: 0.75 }),
+      );
+    }
+    case 'ply': {
+      const geometry = new PLYLoader().parse(bytes.buffer as ArrayBuffer);
+      if (!geometry.hasAttribute('normal')) geometry.computeVertexNormals();
+      return new THREE.Mesh(
+        geometry,
+        new THREE.MeshStandardMaterial({
+          color: geometry.hasAttribute('color') ? 0xffffff : 0xb8d09b,
+          vertexColors: geometry.hasAttribute('color'),
+          roughness: 0.8,
+          side: THREE.DoubleSide,
+        }),
+      );
+    }
+    case '3ds':
+      return new TDSLoader().parse(bytes.buffer as ArrayBuffer, resourcePath);
+    default:
+      throw new Error(`Built-in conversion does not support ${format || extname(primaryPath)}.`);
+  }
+}
+
+/** Three's source loaders construct browser image elements even when the
+ * conversion runs in Node. JSDOM supplies that parser boundary; unresolved
+ * asynchronous images are removed below rather than passed to GLTFExporter
+ * as invalid zero-sized image objects. */
+function installNodeDom(): void {
+  if (typeof document !== 'undefined' && typeof DOMParser !== 'undefined') return;
+  const { JSDOM } = createRequire(import.meta.url)('jsdom') as {
+    JSDOM: new () => {
+      window: {
+        document: Document;
+        DOMParser: typeof DOMParser;
+        HTMLImageElement: typeof HTMLImageElement;
+        HTMLCanvasElement: typeof HTMLCanvasElement;
+        Image: typeof Image;
+      };
+    };
+  };
+  const window = new JSDOM().window;
+  Object.assign(globalThis, {
+    document: window.document,
+    DOMParser: window.DOMParser,
+    HTMLImageElement: window.HTMLImageElement,
+    HTMLCanvasElement: window.HTMLCanvasElement,
+    Image: window.Image,
+  });
+}
+
+function discardUnloadedTextures(root: THREE.Object3D): void {
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one bounded traversal removes only unresolved image slots across every supported material shape.
+  root.traverse((object) => {
+    const mesh = object as THREE.Mesh;
+    const materials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+    for (const material of materials) {
+      const textured = material as THREE.Material & Record<string, unknown>;
+      for (const slot of materialTextureSlots) {
+        const value = textured[slot];
+        if (!(value instanceof THREE.Texture)) continue;
+        const image = value.image as { width?: number; height?: number } | null;
+        if (image && (image.width ?? 0) > 0 && (image.height ?? 0) > 0) continue;
+        textured[slot] = null;
+        value.dispose();
+      }
+      material.needsUpdate = true;
+    }
+  });
+}
+
+async function validateConvertedGlb(bytes: Uint8Array): Promise<void> {
+  const parsed = await new GLTFLoader().parseAsync(Uint8Array.from(bytes).buffer, '');
+  let renderable = false;
+  parsed.scene.traverse((object) => {
+    renderable ||= Boolean((object as THREE.Mesh).isMesh || (object as THREE.Points).isPoints);
+  });
+  disposeObject(parsed.scene);
+  if (!renderable && parsed.animations.length === 0) {
+    throw new Error('Converted GLB contains neither renderable geometry nor animation clips.');
+  }
+}
+
+function installNodeFileReader(): void {
+  if (typeof FileReader !== 'undefined') return;
+  class NodeFileReader {
+    result: string | ArrayBuffer | null = null;
+    error: Error | null = null;
+    onloadend: ((event: ProgressEvent<FileReader>) => void) | null = null;
+    onerror: ((event: ProgressEvent<FileReader>) => void) | null = null;
+    readAsArrayBuffer(blob: Blob): void {
+      void blob.arrayBuffer().then(
+        (result) => {
+          this.result = result;
+          this.onloadend?.({ target: this } as unknown as ProgressEvent<FileReader>);
+        },
+        (error) => {
+          this.error = error instanceof Error ? error : new Error(String(error));
+          this.onerror?.({ target: this } as unknown as ProgressEvent<FileReader>);
+        },
+      );
+    }
+    readAsDataURL(blob: Blob): void {
+      void blob.arrayBuffer().then((result) => {
+        this.result = `data:${blob.type || 'application/octet-stream'};base64,${Buffer.from(result).toString('base64')}`;
+        this.onloadend?.({ target: this } as unknown as ProgressEvent<FileReader>);
+      });
+    }
+  }
+  Object.assign(globalThis, { FileReader: NodeFileReader });
+}
+
+function disposeObject(root: THREE.Object3D): void {
+  root.traverse((object) => {
+    const renderable = object as THREE.Mesh;
+    renderable.geometry?.dispose();
+    const materials = Array.isArray(renderable.material)
+      ? renderable.material
+      : renderable.material
+        ? [renderable.material]
+        : [];
+    for (const material of materials) {
+      for (const value of Object.values(material))
+        if (value instanceof THREE.Texture) value.dispose();
+      material.dispose();
+    }
+  });
+}

package/src/adapter/ingest/scene-capture.ts

@@ -53,6 +53,7 @@
  * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
  */
 
+import type { WorldAdoptionEvent } from '@volter/editor-sdk/kit/world-adoption-event';
 import type * as THREE from 'three';
 import {
   type CaptureWaitOptions,
@@ -144,29 +145,6 @@ export interface SceneCaptureOptions {
   onWorldAdoption?: (event: WorldAdoptionEvent) => void;
 }
 
-/**
- * One world-adoption fact. `adopted` fires exactly once, when the trap commits
- * to a (scene, camera, renderer) triple; `alternate` fires for each DISTINCT
- * triple seen afterwards, up to {@link MAX_RECORDED_ALTERNATES}.
- */
-export type WorldAdoptionEvent =
-  | {
-      readonly phase: 'adopted';
-      /** `declared` = the contract named this scene; `measured` = first render won. */
-      readonly source: 'declared' | 'measured';
-      readonly sceneId: string;
-      readonly cameraId: string;
-    }
-  | {
-      readonly phase: 'alternate';
-      readonly sceneId: string;
-      readonly cameraId: string;
-      /** `false` ⇒ a SECOND renderer is drawing, which is the stronger signal. */
-      readonly sameRenderer: boolean;
-      /** Draws observed when this alternate first appeared — how far past the
-       *  adoption it is, without a wall clock. */
-      readonly drawCount: number;
-    };
 
 /**
  * How many distinct alternates are recorded before the trap stops looking.

package/src/animation/live-mixers.ts

@@ -0,0 +1,55 @@
+/**
+ * The mixers a running world animates with, as the editor reads them: the registry the served
+ * animation stamp fills (`serving/animation-live-module.ts`) in the game's graph. An instrument
+ * that drives time on an object asks here for the mixer the game already made for it, so the
+ * skeleton keeps one writer.
+ */
+
+import type * as THREE from 'three';
+
+export interface LiveMixer {
+  /** The call site that made it (`src/prefabs/Player.tsx:358:37`). */
+  readonly key: string;
+  readonly mixer: THREE.AnimationMixer;
+  /** Every clip the game has played through it, and every clip `useAnimations` was handed. */
+  readonly clips: ReadonlyMap<string, THREE.AnimationClip>;
+  /** The objects its actions animate. */
+  readonly roots: ReadonlySet<unknown>;
+}
+
+interface Registry {
+  readonly mixers: Map<unknown, LiveMixer>;
+  readonly listeners: Set<() => void>;
+  version: number;
+}
+
+const REGISTRY = Symbol.for('volter.three.animation.live');
+
+function registry(): Registry {
+  const holder = globalThis as unknown as Record<symbol, Registry | undefined>;
+  return (holder[REGISTRY] ??= { mixers: new Map(), listeners: new Set(), version: 0 });
+}
+
+/** The live mixer that animates `object`, or null when the game animates it with none. */
+export function liveMixerFor(object: THREE.Object3D): LiveMixer | null {
+  for (const entry of registry().mixers.values()) {
+    if (entry.clips.size === 0) continue;
+    if (entry.mixer.getRoot() === object || entry.roots.has(object)) return entry;
+  }
+  return null;
+}
+
+/** Every mixer the running world's code has made, in the order it made them. */
+export function liveMixers(): LiveMixer[] {
+  return [...registry().mixers.values()];
+}
+
+export function subscribeLiveMixers(listener: () => void): () => void {
+  const listeners = registry().listeners;
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function liveMixersVersion(): number {
+  return registry().version;
+}

package/src/ecs/user-data.ts

@@ -42,10 +42,8 @@
  *
  * Animation (load-bearing — ED5 disposal contract):
  * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
- * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF.
  * - `_availableClips`     — string[] of clip names discovered on the GLTF
- *                           (inspector dropdown; same names as `_animClips`' keys).
- * - `_animationRuntime`   — format-neutral live native mixer/action inspection.
+ *                           (inspector dropdown).
  *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
@@ -119,7 +117,6 @@ import type { ConstraintMark } from '../adapter/constraint';
 import type { Object3DAuthoringSubjectMark } from '../adapter/object3d-authoring-subject';
 import type { ReflectionProbeMark } from '../adapter/reflection-probe';
 import type { TriggerVolumeMark } from '../adapter/trigger-volume';
-import type { AnimationRuntimeInspection } from '../animation/runtime-inspection';
 import { ObjectMarkKeys, type ObjectMarkSchema } from './object-marks';
 
 export type { EditorHelperType } from './object-marks';
@@ -141,9 +138,7 @@ export interface UserDataSchema extends ObjectMarkSchema {
   _particleSystem: ParticleSystem;
   gaussianSplat: { src: string; numSplats: number };
   _animMixer: THREE.AnimationMixer;
-  _animClips: Map<string, THREE.AnimationClip>;
   _availableClips: string[];
-  _animationRuntime: AnimationRuntimeInspection;
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
@@ -195,9 +190,7 @@ export const UserDataKeys = {
   _particleSystem: '_particleSystem',
   gaussianSplat: 'gaussianSplat',
   _animMixer: '_animMixer',
-  _animClips: '_animClips',
   _availableClips: '_availableClips',
-  _animationRuntime: '_animationRuntime',
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',
   __shadeUnlit: '__shadeUnlit',

package/src/viewport/content-bounds.ts

@@ -71,6 +71,7 @@ export function traverseContent(
 /** Scratch for one node's transformed geometry box — this module is synchronous
  *  and single-threaded, so one instance serves every call. */
 const nodeBox = new THREE.Box3();
+const frameMatrix = new THREE.Matrix4();
 
 /**
  * Is this box a measurement at all?
@@ -139,10 +140,15 @@ function expandByInstances(
   target: THREE.Box3,
   node: THREE.InstancedMesh,
   geometryBox: THREE.Box3,
+  frame: THREE.Matrix4 | null,
 ): void {
   for (let index = 0; index < node.count; index++) {
     node.getMatrixAt(index, instanceMatrix);
-    instanceBox.copy(geometryBox).applyMatrix4(instanceMatrix).applyMatrix4(node.matrixWorld);
+    // ONE transform into the target space: a box carried through two is re-boxed twice, and a
+    // rotated object's box grows at each step.
+    instanceMatrix.premultiply(node.matrixWorld);
+    if (frame) instanceMatrix.premultiply(frame);
+    instanceBox.copy(geometryBox).applyMatrix4(instanceMatrix);
     if (!isFiniteBox(instanceBox)) continue;
     target.union(instanceBox);
   }
@@ -162,16 +168,26 @@ function expandByInstances(
  * `InstancedMesh` is the one node three's own rule gets wrong for a LIVE world;
  * see {@link expandByInstances}.
  */
-function expandByNodeGeometry(target: THREE.Box3, node: THREE.Object3D): void {
+function expandByNodeGeometry(
+  target: THREE.Box3,
+  node: THREE.Object3D,
+  frame: THREE.Matrix4 | null = null,
+): void {
   const geometry = (node as THREE.Mesh).geometry as THREE.BufferGeometry | undefined;
   if (!geometry) return;
   const local = localRenderableBox(node, geometry);
   if (!local) return;
   if ((node as THREE.InstancedMesh).isInstancedMesh) {
-    expandByInstances(target, node as THREE.InstancedMesh, local);
+    expandByInstances(target, node as THREE.InstancedMesh, local, frame);
     return;
   }
-  nodeBox.copy(local).applyMatrix4(node.matrixWorld);
+  if (frame) {
+    // One transform, for the same reason as the instances above.
+    frameMatrix.multiplyMatrices(frame, node.matrixWorld);
+    nodeBox.copy(local).applyMatrix4(frameMatrix);
+  } else {
+    nodeBox.copy(local).applyMatrix4(node.matrixWorld);
+  }
   if (!isFiniteBox(nodeBox)) return;
   target.union(nodeBox);
 }
@@ -329,6 +345,24 @@ export function contentWorldBounds(
   return expandBoxByContent(target, object);
 }
 
+/**
+ * `object`'s content box in a FRAME — `worldToFrame` carries world space into it (the
+ * inverse of the object's own `matrixWorld` gives its own axes, the box a rotated object's
+ * selection turns with in Godot). Same walk as {@link contentWorldBounds}.
+ */
+export function contentBoundsInFrame(
+  object: THREE.Object3D,
+  worldToFrame: THREE.Matrix4,
+  target: THREE.Box3 = new THREE.Box3(),
+): THREE.Box3 {
+  target.makeEmpty();
+  traverseContent(object, (node) => {
+    node.updateWorldMatrix(false, false);
+    expandByNodeGeometry(target, node, worldToFrame);
+  });
+  return target;
+}
+
 /**
  * The Bounds diagnostic's twelve-edge box, drawn on {@link contentWorldBounds}
  * rather than `BoxHelper`'s own `setFromObject`.

package/src/viewport/environment.ts

@@ -1,5 +1,7 @@
 import * as THREE from 'three';
 import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
+import { EXRLoader } from 'three/examples/jsm/loaders/EXRLoader.js';
+import { HDRLoader } from 'three/examples/jsm/loaders/HDRLoader.js';
 
 /** A baked IBL environment and the handle that frees its render target. */
 export interface StandardEnvironment {
@@ -24,3 +26,17 @@ export function createStandardEnvironment(renderer: THREE.WebGLRenderer): Standa
     pmrem.dispose();
   }
 }
+
+/**
+ * An environment image (`@volter/editor-sdk/kit/environment-images`) as an equirectangular
+ * texture in scene-referred light. Read as half float: a sun past white stays bright, and half
+ * float filters linearly where full float cannot (phones).
+ */
+export async function loadEnvironmentImage(url: string, format: 'exr' | 'hdr'): Promise<THREE.DataTexture> {
+  const loader = format === 'exr' ? new EXRLoader() : new HDRLoader();
+  loader.setDataType(THREE.HalfFloatType);
+  const texture = await loader.loadAsync(url);
+  texture.mapping = THREE.EquirectangularReflectionMapping;
+  texture.colorSpace = THREE.LinearSRGBColorSpace;
+  return texture;
+}