@volter/threejs-runtime 0.5.65

package/src/render/light-camera-factory.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared light + camera factory — the ONE place light/camera fallbacks are
+ * decided, and it decides them by READING `DEFAULTS.light`/`DEFAULTS.camera`.
+ *
+ * A second copy hardcoding the same literals (color '#ffffff', fov 60, near
+ * 0.1, far 1000) would agree by luck rather than by construction, and any
+ * edit to either copy — or to `DEFAULTS` — would silently diverge.
+ *
+ * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
+ * from a `LightDescriptor`/`CameraDescriptor` descriptor, reading its fallbacks from
+ * `DEFAULTS` (the single source of truth for scene default values — see
+ * `defaults.ts`). Both the loader and the editor import it, so they
+ * can no longer disagree.
+ */
+
+import * as THREE from 'three';
+// Area lights. `RectAreaLight` requires its LTC lookup-texture uniforms
+// initialized once before the first instance is constructed; three.js ships
+// that setup as an addon, not part of core. Imported via the
+// `three/addons/*` alias (package.json `exports`: `"./addons/*":
+// "./examples/jsm/*"` — the identical file as
+// `three/examples/jsm/lights/RectAreaLightUniformsLib.js`) because a literal
+// `/examples/` specifier trips this repo's game/editor-example import guard —
+// a same-substring false positive against our own `src/examples/` convention,
+// unrelated to three.js's addon folder naming.
+import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
+import type { CameraDescriptor } from '../asset-formats/camera';
+import type { LightDescriptor } from '../asset-formats/light';
+import { DEFAULTS } from '../defaults';
+
+let rectAreaLightUniformsInitialized = false;
+
+/** Build a Three.js light from a `LightDescriptor` descriptor. */
+export function createLight(def: LightDescriptor): THREE.Light {
+  const d = DEFAULTS.light;
+  const color = def.color ?? d.color;
+  const intensity = def.intensity ?? d.intensity;
+
+  switch (def.type) {
+    case 'directional':
+      return new THREE.DirectionalLight(color, intensity);
+    case 'point':
+      return new THREE.PointLight(
+        color,
+        intensity,
+        def.distance ?? d.distance,
+        def.decay ?? d.decay,
+      );
+    case 'spot': {
+      const light = new THREE.SpotLight(
+        color,
+        intensity,
+        def.distance ?? d.distance,
+        def.angle ?? d.angle,
+        def.penumbra ?? d.penumbra,
+      );
+      light.decay = def.decay ?? d.decay;
+      return light;
+    }
+    case 'hemisphere':
+      return new THREE.HemisphereLight(color, def.groundColor ?? d.groundColor, intensity);
+    case 'area': {
+      // No shadow map is ever wired for this light (RectAreaLight does not
+      // support shadows in three.js — see the honesty note on the schema
+      // field's .describe(); degrade loudly, not silently).
+      if (!rectAreaLightUniformsInitialized) {
+        RectAreaLightUniformsLib.init();
+        rectAreaLightUniformsInitialized = true;
+      }
+      return new THREE.RectAreaLight(
+        color,
+        intensity,
+        def.width ?? d.width,
+        def.height ?? d.height,
+      );
+    }
+    default:
+      return new THREE.DirectionalLight(color, intensity);
+  }
+}
+
+/** Build a Three.js camera from a `CameraDescriptor` descriptor. */
+export function createCamera(def: CameraDescriptor): THREE.Camera {
+  const d = DEFAULTS.camera;
+  const aspect = (def.width ?? d.width) / (def.height ?? d.height);
+  if (def.type === 'orthographic') {
+    const size = def.orthoSize ?? d.orthoSize;
+    return new THREE.OrthographicCamera(
+      -size * aspect,
+      size * aspect,
+      size,
+      -size,
+      def.near ?? d.near,
+      def.far ?? d.far,
+    );
+  }
+  return new THREE.PerspectiveCamera(
+    def.fov ?? d.fov,
+    aspect,
+    def.near ?? d.near,
+    def.far ?? d.far,
+  );
+}

package/src/render/matcap-texture.ts

@@ -0,0 +1,92 @@
+import * as THREE from 'three';
+
+/**
+ * The neutral matcap sphere, DRAWN rather than shipped.
+ *
+ * A matcap is just a picture of a lit sphere sampled by view-space normal, so
+ * there is nothing to vendor: the same three numbers a shader would use
+ * (key, fill, rim) evaluated once per texel produce the image. Keeping it
+ * procedural means the diagnostic look has no binary asset, no license, no
+ * provenance row, and no way to go missing from a build.
+ *
+ * The look is deliberately CLAY: one warm key from the upper left, a cool
+ * fill from the lower right, a tight rim, and a broad soft highlight — the
+ * neutral sculpting material whose whole job is to let form read without
+ * colour, texture or authored lighting getting a vote.
+ */
+
+const SIZE = 256;
+
+/** sRGB transfer curve — the canvas holds display-referred bytes. */
+function encode(value: number): number {
+  const c = Math.min(1, Math.max(0, value));
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+
+function normalize(x: number, y: number, z: number): [number, number, number] {
+  const length = Math.hypot(x, y, z) || 1;
+  return [x / length, y / length, z / length];
+}
+
+export function drawNeutralMatcap(size = SIZE): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = size;
+  canvas.height = size;
+  const context = canvas.getContext('2d');
+  if (!context) return canvas;
+  const image = context.createImageData(size, size);
+
+  const key = normalize(-0.45, 0.62, 0.64);
+  const fill = normalize(0.65, -0.35, 0.5);
+  // View direction is +Z for a matcap: the sphere is drawn facing the camera.
+  const half = normalize(key[0], key[1], key[2] + 1);
+  const base = [0.7, 0.69, 0.68];
+  const fillColor = [0.34, 0.4, 0.52];
+  const rimColor = [0.85, 0.88, 1];
+
+  for (let py = 0; py < size; py++) {
+    for (let px = 0; px < size; px++) {
+      const nx = (px + 0.5) / size / 0.5 - 1;
+      const ny = 1 - (py + 0.5) / size / 0.5;
+      const r2 = nx * nx + ny * ny;
+      // Outside the unit disc a matcap is never sampled by a facing surface,
+      // but bilinear filtering reaches one texel past the silhouette. Clamp
+      // to the rim normal so the edge stays the rim colour instead of
+      // bleeding whatever happened to be there.
+      const clamped = r2 > 1;
+      const scale = clamped ? 1 / Math.sqrt(r2) : 1;
+      const x = nx * scale;
+      const y = ny * scale;
+      const z = clamped ? 0 : Math.sqrt(Math.max(0, 1 - r2));
+
+      const diffuse = Math.max(0, x * key[0] + y * key[1] + z * key[2]);
+      const fillTerm = Math.max(0, x * fill[0] + y * fill[1] + z * fill[2]);
+      const specular = Math.max(0, x * half[0] + y * half[1] + z * half[2]) ** 42 * 0.5;
+      const rim = (1 - z) ** 3.2 * 0.4;
+
+      const offset = (py * size + px) * 4;
+      for (let channel = 0; channel < 3; channel++) {
+        const lit =
+          base[channel]! * (0.16 + 0.8 * diffuse) +
+          fillColor[channel]! * 0.3 * fillTerm +
+          rimColor[channel]! * rim +
+          specular;
+        image.data[offset + channel] = Math.round(encode(lit) * 255);
+      }
+      image.data[offset + 3] = 255;
+    }
+  }
+  context.putImageData(image, 0, 0);
+  return canvas;
+}
+
+/** The drawn sphere as a ready-to-sample texture. Callers own disposal. */
+export function createNeutralMatcapTexture(size = SIZE): THREE.CanvasTexture {
+  const texture = new THREE.CanvasTexture(drawNeutralMatcap(size));
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.minFilter = THREE.LinearFilter;
+  texture.magFilter = THREE.LinearFilter;
+  texture.generateMipmaps = false;
+  texture.needsUpdate = true;
+  return texture;
+}

package/src/render/material-factory.ts

@@ -0,0 +1,201 @@
+import * as THREE from 'three';
+import type { MaterialDescriptor } from '../asset-formats/material';
+import type { MeshDescriptor } from '../asset-formats/mesh';
+import { loadTexture } from '../asset-loaders';
+import { DEFAULTS } from '../defaults';
+
+/**
+ * Single source of truth for turning a `MeshDescriptor` / `MaterialDescriptor` descriptor
+ * into Three.js geometry/material. Both the runtime scene-loader and the editor's
+ * entity-factory import these, so the editor preview renders exactly what the game
+ * renders (the WYSIWYG guarantee). Previously these were
+ * copy-pasted in two places and had to be hand-synced — any new material feature
+ * added to one and not the other silently broke that guarantee.
+ *
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward type-based switch with fallback args
+export function createGeometry(mesh: MeshDescriptor): THREE.BufferGeometry {
+  const args = mesh.args ?? [];
+  switch (mesh.type) {
+    case 'box':
+      return new THREE.BoxGeometry(args[0] ?? 1, args[1] ?? 1, args[2] ?? 1);
+    case 'sphere':
+      return new THREE.SphereGeometry(args[0] ?? 0.5, args[1] ?? 32, args[2] ?? 16);
+    case 'plane':
+      // args[2]/args[3] (width/height segments) matter for vertex-displacing
+      // materials (e.g. the Water shader) — they used to be silently dropped,
+      // which collapsed the water demo to a 2-triangle quad.
+      return new THREE.PlaneGeometry(args[0] ?? 1, args[1] ?? 1, args[2] ?? 1, args[3] ?? 1);
+    case 'cylinder':
+      return new THREE.CylinderGeometry(
+        args[0] ?? 0.5,
+        args[1] ?? 0.5,
+        args[2] ?? 1,
+        args[3] ?? 32,
+      );
+    case 'capsule':
+      return new THREE.CapsuleGeometry(args[0] ?? 0.5, args[1] ?? 1, args[2] ?? 4, args[3] ?? 16);
+    default:
+      return new THREE.BoxGeometry(1, 1, 1);
+  }
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: flat type-based switch building Three materials
+export function createMaterial(mat?: MaterialDescriptor): THREE.Material {
+  if (!mat) return new THREE.MeshStandardMaterial({ color: DEFAULTS.material.color });
+
+  // Only include texture props when actually defined (Three.js warns on undefined values)
+  const textures: {
+    map?: THREE.Texture;
+    normalMap?: THREE.Texture;
+    emissiveMap?: THREE.Texture;
+    aoMap?: THREE.Texture;
+    lightMap?: THREE.Texture;
+    roughnessMap?: THREE.Texture;
+    metalnessMap?: THREE.Texture;
+  } = {};
+  if (mat.map) textures.map = loadTexture(mat.map);
+  if (mat.normalMap) textures.normalMap = loadTexture(mat.normalMap);
+  if (mat.emissiveMap) textures.emissiveMap = loadTexture(mat.emissiveMap);
+  if (mat.aoMap) textures.aoMap = loadTexture(mat.aoMap);
+  if (mat.lightMap) textures.lightMap = loadTexture(mat.lightMap);
+  if (mat.roughnessMap) textures.roughnessMap = loadTexture(mat.roughnessMap);
+  if (mat.metalnessMap) textures.metalnessMap = loadTexture(mat.metalnessMap);
+
+  // R1c — every fallback below reads DEFAULTS.material.* instead of
+  // duplicating its value as a bare literal, so DEFAULTS stays the single
+  // source of truth for what an omitted field renders as (see
+  // `material-factory.test.ts`'s
+  // "omitted-field" locks, which fail if either copy drifts from the other).
+  const dMat = DEFAULTS.material;
+  const sideValue = mat.side ?? dMat.side;
+  const side =
+    sideValue === 'back'
+      ? THREE.BackSide
+      : sideValue === 'double'
+        ? THREE.DoubleSide
+        : THREE.FrontSide;
+  const opacity = mat.opacity ?? dMat.opacity;
+  const transparent = mat.transparent ?? dMat.transparent;
+
+  switch (mat.type) {
+    case 'basic':
+      return new THREE.MeshBasicMaterial({
+        color: mat.color ?? dMat.color,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        opacity,
+        transparent,
+        side,
+      });
+    case 'toon':
+      return new THREE.MeshToonMaterial({
+        color: mat.color ?? dMat.color,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        emissive: mat.emissive ?? dMat.emissive,
+        emissiveIntensity: mat.emissiveIntensity ?? dMat.emissiveIntensity,
+        opacity,
+        transparent,
+        side,
+      });
+    case 'physical':
+      return new THREE.MeshPhysicalMaterial({
+        color: mat.color ?? dMat.color,
+        metalness: mat.metalness ?? dMat.metalness,
+        roughness: mat.roughness ?? dMat.roughness,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        emissive: mat.emissive ?? dMat.emissive,
+        emissiveIntensity: mat.emissiveIntensity ?? dMat.emissiveIntensity,
+        opacity,
+        transparent,
+        side,
+        flatShading: mat.flatShading ?? dMat.flatShading,
+        // Clearcoat
+        ...(mat.clearcoat
+          ? {
+              clearcoat: mat.clearcoat.clearcoat,
+              clearcoatRoughness:
+                mat.clearcoat.clearcoatRoughness ?? dMat.clearcoat.clearcoatRoughness,
+              ...(mat.clearcoat.clearcoatMap
+                ? { clearcoatMap: loadTexture(mat.clearcoat.clearcoatMap) }
+                : {}),
+              ...(mat.clearcoat.clearcoatRoughnessMap
+                ? { clearcoatRoughnessMap: loadTexture(mat.clearcoat.clearcoatRoughnessMap) }
+                : {}),
+            }
+          : {}),
+        // Transmission — `thickness` used to hardcode a literal `0` here,
+        // silently diverging from DEFAULTS.material.transmission.thickness
+        // (0.5, per the editor's Transmission inspector default). Fixed:
+        // read DEFAULTS directly, like every other fallback in this file.
+        ...(mat.transmission
+          ? {
+              transmission: mat.transmission.transmission,
+              ior: mat.transmission.ior ?? dMat.transmission.ior,
+              thickness: mat.transmission.thickness ?? dMat.transmission.thickness,
+              ...(mat.transmission.attenuationColor
+                ? { attenuationColor: new THREE.Color(mat.transmission.attenuationColor) }
+                : {}),
+              attenuationDistance: mat.transmission.attenuationDistance ?? Infinity,
+              ...(mat.transmission.transmissionMap
+                ? { transmissionMap: loadTexture(mat.transmission.transmissionMap) }
+                : {}),
+            }
+          : {}),
+        // Sheen
+        ...(mat.sheen
+          ? {
+              sheen: mat.sheen.sheen,
+              sheenColor: new THREE.Color(mat.sheen.sheenColor ?? dMat.sheen.sheenColor),
+              sheenRoughness: mat.sheen.sheenRoughness ?? dMat.sheen.sheenRoughness,
+              ...(mat.sheen.sheenColorMap
+                ? { sheenColorMap: loadTexture(mat.sheen.sheenColorMap) }
+                : {}),
+              ...(mat.sheen.sheenRoughnessMap
+                ? { sheenRoughnessMap: loadTexture(mat.sheen.sheenRoughnessMap) }
+                : {}),
+            }
+          : {}),
+        // Iridescence
+        ...(mat.iridescence
+          ? {
+              iridescence: mat.iridescence.iridescence,
+              iridescenceIOR: mat.iridescence.iridescenceIOR ?? dMat.iridescence.iridescenceIOR,
+              iridescenceThicknessRange:
+                mat.iridescence.iridescenceThicknessRange ??
+                dMat.iridescence.iridescenceThicknessRange,
+              ...(mat.iridescence.iridescenceMap
+                ? { iridescenceMap: loadTexture(mat.iridescence.iridescenceMap) }
+                : {}),
+              ...(mat.iridescence.iridescenceThicknessMap
+                ? {
+                    iridescenceThicknessMap: loadTexture(mat.iridescence.iridescenceThicknessMap),
+                  }
+                : {}),
+            }
+          : {}),
+        // Displacement
+        ...(mat.displacementMap ? { displacementMap: loadTexture(mat.displacementMap) } : {}),
+        ...(mat.displacementScale !== undefined
+          ? { displacementScale: mat.displacementScale }
+          : {}),
+        ...(mat.displacementBias !== undefined ? { displacementBias: mat.displacementBias } : {}),
+      });
+    default:
+      return new THREE.MeshStandardMaterial({
+        color: mat.color ?? dMat.color,
+        metalness: mat.metalness ?? dMat.metalness,
+        roughness: mat.roughness ?? dMat.roughness,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        emissive: mat.emissive ?? dMat.emissive,
+        emissiveIntensity: mat.emissiveIntensity ?? dMat.emissiveIntensity,
+        opacity,
+        transparent,
+        side,
+        flatShading: mat.flatShading ?? dMat.flatShading,
+      });
+  }
+}

package/src/render/mesh-shadow.ts

@@ -0,0 +1,18 @@
+import * as THREE from 'three';
+
+/**
+ * Apply the authored mesh-shadow contract to every renderable in a model.
+ *
+ * Primitive scene entities contain one Mesh, while glTF entities usually
+ * contain a Group with many Mesh/SkinnedMesh descendants. Keeping this walk
+ * shared prevents editor preview and runtime Play from disagreeing by source
+ * format.
+ */
+export function setMeshShadowEnabled(root: THREE.Object3D, enabled: boolean | undefined): void {
+  if (enabled === undefined) return;
+  root.traverse((object) => {
+    if (!(object instanceof THREE.Mesh)) return;
+    object.castShadow = enabled;
+    object.receiveShadow = enabled;
+  });
+}