@volter/editor-threejs 0.5.57

package/src/asset-loaders.ts

@@ -0,0 +1,242 @@
+/**
+ * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
+ * `.animgraph.json` loader — removed by E5; see
+ * packages/threejs-runtime/src/animation/xstate-animation-binding.ts.)
+ *
+ * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
+ * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
+ * (entity-factory, scene-sync). Previously this logic was duplicated across six
+ * sites with three separate GLTF caches and four GLTFLoader instances, so fixes
+ * (DRACO wiring, the `__sharedGeometry` clone-safety tag, skybox handling) did
+ * not propagate. Everything funnels through the shared loaders in `../loader`
+ * (`gltfLoader` is DRACO-wired — CB2 — and `textureLoader` shares the engine
+ * LoadingManager / asset-prefix rewrite).
+ *
+ * Cache lifetime / P1.8: these caches are intentionally module-level and persist
+ * ACROSS hot-reloads / scene switches (they are NOT cleared on every scene load).
+ * This is deliberate: (1) it makes repeated Play→Stop→Play cheap, and (2) it
+ * underpins the `__sharedGeometry` contract from P0.2 — GLTF clones share the
+ * cached source geometry, so clearing mid-session would orphan live clones. The
+ * caches are keyed by URL, so loading the SAME asset N times is bounded (one
+ * entry per distinct URL, not per load). They are released only on full runtime
+ * teardown via {@link clearAssetCaches}.
+ */
+
+import type { SplatMesh } from '@sparkjsdev/spark';
+import * as THREE from 'three';
+import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
+import { AssetParseError } from './asset-parse-error';
+import { setUserData } from './ecs/user-data';
+import { gltfLoader, resolveUrl, textureLoader } from './loader';
+
+const textureCache = new Map<string, THREE.Texture>();
+const gltfCache = new Map<
+  string,
+  Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }>
+>();
+const splatBytesCache = new Map<string, Promise<Uint8Array>>();
+
+/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
+export function loadTexture(url: string): THREE.Texture {
+  const cached = textureCache.get(url);
+  if (cached) return cached;
+  const tex = textureLoader.load(url);
+  textureCache.set(url, tex);
+  return tex;
+}
+
+/**
+ * Load a GLTF/GLB and return a fresh, disposal-safe clone (+ the source's
+ * animation clips). DRACO decoding is handled by the shared `gltfLoader`.
+ *
+ * Clone-safety contract (P0.2 — load-bearing, tested):
+ * `SkeletonUtils.clone` shares geometry AND materials with the cached source.
+ * We give each clone its OWN materials (so scene cleanup can dispose them
+ * without corrupting the cache) and tag every mesh `userData.__sharedGeometry`
+ * so cleanup (engine create-runtime fullCleanup + editor scene-sync
+ * disposeObject3D) skips disposing the shared geometry buffers.
+ */
+export function loadGLTF(
+  url: string,
+): Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }> {
+  let cached = gltfCache.get(url);
+  if (!cached) {
+    cached = new Promise((resolve, reject) => {
+      gltfLoader.load(
+        url,
+        (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }),
+        undefined,
+        (err) => reject(err),
+      );
+    });
+    gltfCache.set(url, cached);
+  }
+  return cached.then((entry) => {
+    const scene = SkeletonUtils.clone(entry.scene) as THREE.Group;
+    scene.traverse((child) => {
+      if (child instanceof THREE.Mesh) {
+        child.material = Array.isArray(child.material)
+          ? child.material.map((m) => m.clone())
+          : child.material.clone();
+        setUserData(child, '__sharedGeometry', true);
+      }
+    });
+    return { scene, animations: entry.animations };
+  });
+}
+
+/**
+ * Load one native Gaussian-splat asset as Spark's own Object3D.
+ *
+ * The URL cache stores immutable source bytes, not a live SplatMesh: every scene
+ * entity needs its own transformable/disposable Object3D, while repeated uses of
+ * the same SPZ must not download the multi-megabyte source more than once.
+ * Spark stays a lazy chunk so games without splats do not pay its bundle cost.
+ */
+export async function loadSplat(url: string, providedBytes?: Uint8Array): Promise<SplatMesh> {
+  let bytes = splatBytesCache.get(url);
+  if (!bytes && providedBytes) {
+    bytes = Promise.resolve(providedBytes);
+    splatBytesCache.set(url, bytes);
+  }
+  if (!bytes) {
+    bytes = fetch(resolveUrl(url)).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(
+          `Failed to load Gaussian splat: ${url} (${response.status} ${response.statusText})`,
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    });
+    splatBytesCache.set(url, bytes);
+  }
+
+  try {
+    const [{ SplatMesh }, fileBytes] = await Promise.all([import('@sparkjsdev/spark'), bytes]);
+    const mesh = new SplatMesh({ fileBytes, fileName: url, raycastable: true });
+    await mesh.initialized;
+    setUserData(mesh, 'gaussianSplat', { src: url, numSplats: mesh.numSplats });
+    const bounds = mesh.getBoundingBox();
+    if (!bounds.isEmpty()) {
+      // Three's generic Box3.setFromObject only understands geometry-bearing
+      // Object3Ds. Spark intentionally renders without THREE.BufferGeometry,
+      // so give editor/runtime framing a hidden, non-pickable bounds proxy.
+      // It is infrastructure, never authored hierarchy or rendered content.
+      // Include a framing margin. This proxy is consumed by generic editor
+      // focus/selection bounds, while inspectors continue to report Spark's
+      // exact Gaussian bounds directly.
+      const size = bounds.getSize(new THREE.Vector3()).multiplyScalar(1.5);
+      const center = bounds.getCenter(new THREE.Vector3());
+      const proxy = new THREE.Mesh(new THREE.BoxGeometry(size.x, size.y, size.z));
+      proxy.name = '__vgai_splat_bounds';
+      proxy.position.copy(center);
+      proxy.visible = false;
+      proxy.raycast = () => {};
+      setUserData(proxy, 'engineInternal', true);
+      mesh.add(proxy);
+    }
+    return mesh;
+  } catch (error) {
+    // A failed fetch must be retryable after the source is repaired or the
+    // network recovers; successful source bytes remain cached across instances.
+    splatBytesCache.delete(url);
+    throw error;
+  }
+}
+
+/**
+ * Resolve a single named node inside an already-loaded glTF scene graph (F4,
+ * `mesh.node`). Pure and headlessly testable — no fetch, no cache lookups;
+ * callers pass the `scene` they already got from {@link loadGLTF}.
+ *
+ * The returned node is the SAME object (and shares the SAME geometry) as
+ * found in `scene` — nothing is cloned or copied out. `scene` is already a
+ * fresh `SkeletonUtils.clone()` per {@link loadGLTF}'s clone-safety contract,
+ * so mutating/detaching the returned node is safe.
+ *
+ * Atomic-subtree guard: a `SkinnedMesh` cannot be lifted out of its armature
+ * (its skeleton/bind matrices reference sibling bone nodes elsewhere in the
+ * hierarchy), so resolving a node that IS a SkinnedMesh, or that CONTAINS one,
+ * throws a loud `AssetParseError` instead of silently producing broken skinning.
+ */
+export function resolveGltfNode(
+  scene: THREE.Object3D,
+  nodeName: string,
+  src: string,
+): THREE.Object3D {
+  const node = scene.getObjectByName(nodeName);
+  if (!node) {
+    throw new AssetParseError(
+      [
+        {
+          code: 'custom',
+          path: ['mesh', 'node'],
+          message: `glTF "${src}" has no node named "${nodeName}" (getObjectByName found nothing)`,
+        },
+      ],
+      src,
+    );
+  }
+
+  const isSkinned = (o: THREE.Object3D) => (o as THREE.SkinnedMesh).isSkinnedMesh;
+  let containsSkinned = isSkinned(node);
+  if (!containsSkinned) {
+    node.traverse((child) => {
+      if (isSkinned(child)) containsSkinned = true;
+    });
+  }
+  if (containsSkinned) {
+    throw new AssetParseError(
+      [
+        {
+          code: 'custom',
+          path: ['mesh', 'node'],
+          message:
+            `glTF "${src}" node "${nodeName}" is (or contains) a SkinnedMesh — a skinned mesh ` +
+            'cannot be lifted out of its armature (atomic-subtree rule). Reference the whole ' +
+            'file instead of a `node`, or bake/export a non-skinned sub-asset.',
+        },
+      ],
+      src,
+    );
+  }
+
+  return node;
+}
+
+/**
+ * Clear the module-level GLTF / texture caches. Call on full runtime teardown
+ * (create-runtime fullCleanup / hot-reload) to release cached GPU resources
+ * and avoid leaking across editor Play sessions. See the lifetime note at the
+ * top of this file for why these are NOT cleared per scene load.
+ *
+ * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
+ * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
+ * also clears that env cache.
+ */
+export function clearAssetCaches(): void {
+  textureCache.clear();
+  gltfCache.clear();
+  splatBytesCache.clear();
+}
+
+/**
+ * Drop the cached entry for ONE asset URL after its bytes changed on disk
+ * (editor asset-optimization write-back — W4a). Existing clones keep their
+ * shared geometry alive (the cache entry only owns the lookup, not the
+ * buffers), and the next `loadGLTF`/`loadTexture` for this URL re-fetches the
+ * rewritten file instead of serving stale bytes.
+ */
+export function invalidateCachedAsset(url: string): void {
+  textureCache.delete(url);
+  gltfCache.delete(url);
+}
+
+/**
+ * Test-only: current sizes of the module-level caches. Used by the P1.8 headless
+ * test to assert caches stay bounded (one entry per distinct asset URL) across
+ * repeated loads of the same scene, rather than growing per load.
+ */
+export function assetCacheSizes(): { textures: number; gltf: number; splat: number } {
+  return { textures: textureCache.size, gltf: gltfCache.size, splat: splatBytesCache.size };
+}

package/src/asset-parse-error.ts

@@ -0,0 +1,29 @@
+/**
+ * The GENERIC fetched-asset parse error.
+ *
+ * Every authored asset format the engine validates at fetch time throws this
+ * when Zod rejects the payload, naming the offending file (T4.6). It lives
+ * here — beside `loader.ts`/`assets.ts` — rather than inside a format module so
+ * every caller (currently the input-map loader in `input/input-manager.ts`)
+ * does not have to reach into an unrelated subsystem for it.
+ *
+ * The name says ASSET, not scene: an `.inputmap.json` failure is not a scene
+ * failure, and the class covers every structured fetched asset.
+ */
+
+import type { ZodIssue } from 'zod';
+
+export class AssetParseError extends Error {
+  readonly issues: ZodIssue[];
+  /** The offending file's path/URL, when the caller knows it (T4.6). */
+  readonly filePath?: string | undefined;
+
+  constructor(issues: ZodIssue[], filePath?: string) {
+    const msg = issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+    const header = filePath ? `Asset validation failed (${filePath}):` : 'Asset validation failed:';
+    super(`${header}\n${msg}`);
+    this.name = 'AssetParseError';
+    this.issues = issues;
+    this.filePath = filePath;
+  }
+}

package/src/capture/output-pass.ts

@@ -0,0 +1,36 @@
+/** Shared Three capture mechanics; this entry must not import host or contribution code. */
+import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+
+/** Three renders ordinary offscreen targets in linear space without tone
+ * mapping. Both scene and document captures resolve their half-float scene
+ * target through this pass before reading display pixels.
+ *
+ * One pass lives for the page, shared by every capture. Its uniforms/defines
+ * follow the supplied renderer on each render; reusing the pass avoids
+ * compiling another full-screen program on every screenshot or thumbnail.
+ */
+let outputPass: OutputPass | null = null;
+const unassociateAlphaUniform = { value: false };
+
+export function viewportCaptureOutputPass(unassociateAlpha = false): OutputPass {
+  if (!outputPass) {
+    outputPass = new OutputPass();
+    Object.assign(outputPass.uniforms, { unassociateAlpha: unassociateAlphaUniform });
+    // Render targets contain associated linear RGB; PNG/ImageData require
+    // straight display RGB. Resolve alpha before Three's own display transform.
+    outputPass.material.fragmentShader = outputPass.material.fragmentShader
+      .replace(
+        'uniform sampler2D tDiffuse;',
+        'uniform sampler2D tDiffuse;\nuniform bool unassociateAlpha;',
+      )
+      .replace(
+        'gl_FragColor = texture2D( tDiffuse, vUv );',
+        `gl_FragColor = texture2D( tDiffuse, vUv );
+        if (unassociateAlpha && gl_FragColor.a != 0.0) {
+          gl_FragColor.rgb /= gl_FragColor.a;
+        }`,
+      );
+  }
+  unassociateAlphaUniform.value = unassociateAlpha;
+  return outputPass;
+}

package/src/capture/scene.ts

@@ -0,0 +1,146 @@
+/** Capture an already isolated scene. The caller owns the scene and camera;
+ * this function owns its renderer lease and targets for one synchronous draw. */
+import * as THREE from 'three';
+import { acquireInspectorPreviewRenderer } from '../viewport/preview-renderer';
+import { viewportCaptureOutputPass } from './output-pass';
+
+export interface SceneCaptureOptions {
+  width: number;
+  height: number;
+  transparent?: boolean;
+  toneMapping?: THREE.ToneMapping;
+  exposure?: number;
+}
+
+export interface LinearCaptureFrame {
+  readonly pixels: Uint16Array;
+  readonly width: number;
+  readonly height: number;
+}
+
+function capture(
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  options: SceneCaptureOptions,
+  linear: true,
+): LinearCaptureFrame;
+function capture(
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  options: SceneCaptureOptions,
+  linear: false,
+): string;
+function capture(
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  options: SceneCaptureOptions,
+  linear: boolean,
+): string | LinearCaptureFrame {
+  if (
+    !Number.isFinite(options.width) ||
+    !Number.isFinite(options.height) ||
+    options.width < 1 ||
+    options.height < 1
+  )
+    throw new Error('Scene capture requires finite positive dimensions');
+  const width = Math.min(2048, Math.round(options.width));
+  const height = Math.min(2048, Math.round(options.height));
+  const scale = linear ? 1 : 2;
+  const renderWidth = width * scale;
+  const renderHeight = height * scale;
+  const lease = acquireInspectorPreviewRenderer();
+  const renderer = lease.renderer;
+  const previous = {
+    target: renderer.getRenderTarget(),
+    toneMapping: renderer.toneMapping,
+    exposure: renderer.toneMappingExposure,
+    colorSpace: renderer.outputColorSpace,
+    shadows: renderer.shadowMap.enabled,
+    shadowType: renderer.shadowMap.type,
+    clearColor: renderer.getClearColor(new THREE.Color()),
+    clearAlpha: renderer.getClearAlpha(),
+    background: scene.background,
+  };
+  let hdr: THREE.WebGLRenderTarget | undefined;
+  let display: THREE.WebGLRenderTarget | undefined;
+  let completed = false;
+  try {
+    hdr = new THREE.WebGLRenderTarget(renderWidth, renderHeight, { type: THREE.HalfFloatType });
+    renderer.shadowMap.enabled = true;
+    renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    renderer.outputColorSpace = THREE.SRGBColorSpace;
+    renderer.toneMapping = options.toneMapping ?? THREE.NoToneMapping;
+    renderer.toneMappingExposure = options.exposure ?? 1;
+    renderer.setClearColor(0, options.transparent ? 0 : 1);
+    if (options.transparent) scene.background = null;
+    renderer.setRenderTarget(hdr);
+    renderer.clear();
+    renderer.render(scene, camera);
+    if (linear) {
+      const pixels = new Uint16Array(renderWidth * renderHeight * 4);
+      renderer.readRenderTargetPixels(hdr, 0, 0, renderWidth, renderHeight, pixels);
+      completed = true;
+      return { pixels, width, height };
+    }
+    display = new THREE.WebGLRenderTarget(renderWidth, renderHeight);
+    viewportCaptureOutputPass(options.transparent === true).render(
+      renderer,
+      display,
+      hdr,
+      0,
+      false,
+    );
+    const pixels = new Uint8Array(renderWidth * renderHeight * 4);
+    renderer.readRenderTargetPixels(display, 0, 0, renderWidth, renderHeight, pixels);
+    const full = document.createElement('canvas');
+    full.width = renderWidth;
+    full.height = renderHeight;
+    const context = full.getContext('2d');
+    if (!context) throw new Error('Scene capture could not create an image canvas');
+    const image = context.createImageData(renderWidth, renderHeight);
+    const stride = renderWidth * 4;
+    for (let y = 0; y < renderHeight; y++)
+      image.data.set(
+        pixels.subarray((renderHeight - 1 - y) * stride, (renderHeight - y) * stride),
+        y * stride,
+      );
+    context.putImageData(image, 0, 0);
+    const output = document.createElement('canvas');
+    output.width = width;
+    output.height = height;
+    const outputContext = output.getContext('2d');
+    if (!outputContext) throw new Error('Scene capture could not create an output canvas');
+    outputContext.drawImage(full, 0, 0, width, height);
+    const imageUrl = output.toDataURL('image/png');
+    completed = true;
+    return imageUrl;
+  } finally {
+    scene.background = previous.background;
+    renderer.setRenderTarget(previous.target);
+    renderer.toneMapping = previous.toneMapping;
+    renderer.toneMappingExposure = previous.exposure;
+    renderer.outputColorSpace = previous.colorSpace;
+    renderer.shadowMap.enabled = previous.shadows;
+    renderer.shadowMap.type = previous.shadowType;
+    renderer.setClearColor(previous.clearColor, previous.clearAlpha);
+    display?.dispose();
+    hdr?.dispose();
+    lease.release({ discard: !completed });
+  }
+}
+
+export function captureSceneLinear(
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  options: SceneCaptureOptions,
+): LinearCaptureFrame {
+  return capture(scene, camera, options, true);
+}
+
+export function captureSceneImage(
+  scene: THREE.Scene,
+  camera: THREE.Camera,
+  options: SceneCaptureOptions,
+): string {
+  return capture(scene, camera, options, false);
+}

package/src/ecs/object-marks.ts

@@ -0,0 +1,75 @@
+/**
+ * Structural object marks shared by runtime producers and Three editor tools.
+ * Keep this contract native and dependency-free except for Three's types: a
+ * bounds/layer reader must not load physics, animation or editor contracts.
+ * The full user-data registry extends this schema and reuses these same keys.
+ */
+import type { Object3D } from 'three';
+
+/** The kinds of editor helper objects tagged via `editorHelperType`. */
+export type EditorHelperType =
+  | 'lights'
+  | 'cameras'
+  | 'audio'
+  | 'colliders'
+  // Joint anchor/axis/limit gizmos (W2a) — distinct from 'colliders' so the
+  // viewport's per-type visibility filter can toggle them independently.
+  | 'joints'
+  // LOD distance rings (W2b) — one ring per `mesh.lod` level, radius = the
+  // level's camera-distance threshold in world units.
+  | 'lod'
+  | 'splines'
+  // 'particles' tags the LIVE three.quarks emitter Object3D itself (so the
+  // editor's helper machinery skips disposing it); 'particle-shape' tags the
+  // editor's emitter-shape WIREFRAME (W1b) — they must stay distinct: sweeping
+  // "particles"-tagged children would detach the running emitter, and quarks
+  // self-disposes any system whose emitter leaves the scene.
+  | 'particles'
+  | 'particle-shape'
+  | 'pivot'
+  | 'navmesh'
+  | 'constraints'
+  | 'reflection-probes'
+  | 'trigger-volumes'
+  | 'skeletons'
+  // A package's own helper kind, shown through the editor's viewport door
+  // (`host.viewport.setHelper`): the host lists the kinds it toggles by name,
+  // any other follows the master Helpers toggle.
+  | (string & {});
+
+export interface ObjectMarkSchema {
+  editorHelperType: EditorHelperType;
+  skeletonVisible: boolean;
+  skeletonEnabled: boolean;
+  engineInternal: boolean;
+  editorHelper: boolean;
+  vgaiComponentRoot: string;
+  vgaiBuiltInternal: boolean;
+}
+
+export const ObjectMarkKeys = {
+  editorHelperType: 'editorHelperType',
+  skeletonVisible: 'skeletonVisible',
+  skeletonEnabled: 'skeletonEnabled',
+  engineInternal: 'engineInternal',
+  editorHelper: 'editorHelper',
+  vgaiComponentRoot: 'vgaiComponentRoot',
+  vgaiBuiltInternal: 'vgaiBuiltInternal',
+} as const satisfies Record<keyof ObjectMarkSchema, string>;
+
+export function getObjectMark<K extends keyof ObjectMarkSchema>(
+  object: Object3D | null | undefined,
+  key: K,
+): ObjectMarkSchema[K] | undefined {
+  return object
+    ? (object.userData[ObjectMarkKeys[key]] as ObjectMarkSchema[K] | undefined)
+    : undefined;
+}
+
+export function setObjectMark<K extends keyof ObjectMarkSchema>(
+  object: Object3D,
+  key: K,
+  value: ObjectMarkSchema[K],
+): void {
+  object.userData[ObjectMarkKeys[key]] = value;
+}