@volter/blender-engine 0.1.148 → 0.1.149

package/browser/three/blender-runtime-lighting.ts

@@ -1,38 +1,9 @@
 /**
- * The scene's own lights, and the Model document's SOLID-MODE STUDIO.
- *
- * TWO LIGHTING STATES, the same split Blender makes between its solid viewport
- * and a render. Modeling is lit by Blender's four view-locked studio lights
- * ({@link ViewportLighting}), so a model reads the same however it is orbited
- * while it is being built; a RENDER is lit by the scene's own lights, because
- * that is what the script placed them for. `setRendered` switches between
- * them, and a render capture is the only caller that asks for the second.
- *
- * The studio lives here rather than in the standard viewport dressing because
- * it is BLENDER's, not the editor's: the dressing's key is one warm light in
- * the world, and Solid mode's is four in view space with no world light at
- * all. The Model document turns the dressing's key AND its IBL off and hands
- * this group over as its `dressing.viewLocked` instead.
- *
- * UNITS. The frame states Blender's own values — watts, radians, metres — and
- * the conversion to three.js's photometric intensities happens here, derived
- * rather than tuned:
- *
- * - POINT and SPOT. Blender spreads `energy` watts over the whole sphere, so
- *   irradiance at distance d is P/(4πd²); three.js gives I/d². Hence I = P/4π.
- * - SUN. `energy` is already an irradiance (W/m²) and a directional light's
- *   intensity is the same quantity, so it passes through.
- * - AREA. P watts leave an area A into a hemisphere, so the radiance is
- *   P/(Aπ), which is what `RectAreaLight.intensity` means. A DISK or ELLIPSE
- *   has no rectangular equivalent, so it becomes the rectangle of EQUAL AREA:
- *   the total emission is right and the shape of a soft shadow's edge is not.
- *
- * SHADOWS follow `use_shadow`, the same flag Cycles reads. A shadow MAP is not
- * a traced shadow: its softness comes from filtering a depth buffer rather than
- * from the light's physical size, so `shadow_soft_size` and a sun's `angle`
- * still reach the frame and still change nothing. A RectAreaLight casts none at
- * all — three.js has no shadow for it — and that is left as it is rather than
- * faked with a substitute light the scene never declared.
+ * Manage Blender scene lights and the document’s view-locked Solid studio. setRendered selects
+ * authored lighting; Solid mode uses the studio provided as dressing.viewLocked. Convert Blender’s
+ * energy units to three.js intensity here: point and spot P/(4π), sun irradiance unchanged, and
+ * area radiance P/(Aπ). Area shapes use equal-area rectangles; shadow support follows the
+ * presentation’s light-specific paths.
  */
 import * as THREE from 'three';
 import {presenterChanged} from './blender-presenter-change';
@@ -111,8 +82,10 @@ const areaExtent = (data: LightData): [number, number] => {
   return [size, size];
 };
 
-/** The three.js light for one Blender light datablock, or `null` when the
- *  existing light is already the right kind and was updated in place. */
+/** A sun's shadow map, on a side: the World's suns and the scene's own. */
+export const SUN_SHADOW_MAP_SIZE = 2048;
+
+/** Build or update the three.js light for one Blender light datablock. */
 export function buildLight(data: LightData, existing: THREE.Light | null): THREE.Light {
   const reuse = <T extends THREE.Light>(
     ctor: new () => T,
@@ -126,6 +99,14 @@ export function buildLight(data: LightData, existing: THREE.Light | null): THREE
     light.intensity = data.energy;
     light.color.setRGB(data.color[0], data.color[1], data.color[2], THREE.LinearSRGBColorSpace);
     light.castShadow = data.use_shadow;
+    // The World's sun's map size (`WorldBackground.compose`), not three's 512: a sun's map is
+    // fitted over everything the camera sees (`blender-runtime-shadows.ts`). Three allocates the
+    // map once, so a size it does not have yet replaces the map.
+    if (light.shadow.mapSize.x !== SUN_SHADOW_MAP_SIZE || light.shadow.mapSize.y !== SUN_SHADOW_MAP_SIZE) {
+      light.shadow.mapSize.set(SUN_SHADOW_MAP_SIZE, SUN_SHADOW_MAP_SIZE);
+      light.shadow.map?.dispose();
+      light.shadow.map = null;
+    }
     return light;
   }
   if (data.type === 'POINT') {
@@ -187,8 +168,8 @@ export function fitShadow(light: THREE.Light, centre: THREE.Vector3, radius: num
   camera.updateProjectionMatrix();
 }
 
-/** A Blender light aims down its own -Z; a three.js directional/spot/area
- *  light aims at a target object. The target rides one unit down that axis. */
+/** Aim directional and spot targets one unit down the authored -Z axis.
+ *  Area lights emit along their own -Z without a target. */
 export function aimLight(light: THREE.Light, node: THREE.Object3D): void {
   // The parent owns the authored transform; directional/spot defaults are offset.
   light.position.set(0, 0, 0);
@@ -251,54 +232,8 @@ export const SOLID_LIGHTS: readonly {
   },
 ];
 
-/**
- * THE ONE CALIBRATED NUMBER in the studio, and it is one gain over all four
- * lights — their RELATIVE strengths, directions and wraps are Blender's own
- * and nothing here tunes them apart.
- *
- * It absorbs two things this side cannot state exactly. First, the workbench's
- * own normalization: Blender's shader is `Σ diffuseᵢ · wrap(N·Lᵢ)` times the
- * viewport colour PLUS a specular term over `brdf_approx`, and the measured
- * frame comes out at ~0.88 of the diffuse sum alone. Second, the stage's tone
- * curve: the editor renders through ACES (`StageHost`), Blender's viewport
- * through AgX, and near middle grey the two differ by a near-constant factor
- * (checked both ways: with one gain ACES lands the three faces within 4 levels
- * and AgX within 3, so the curve is NOT what row 1's 13-vs-30 spread was made
- * of and the stage keeps its own operator).
- *
- * THE ROUNDS, on a `cyclotron create` scaffold driven through `cyclotron
- * screenshot editor`, 30x30 means (std 0 — every patch inside one flat face)
- * of the factory cube's three visible faces against Blender 5.2's own frame,
- * (141,143,145) top / (129,131,131) left / (111,112,113) front:
- *
- *   0.74, ACES -> (148,150,151) (138,140,140) (108,110,110)  worst 9
- *   0.70, ACES -> (144,146,147) (134,136,136) (105,106,106)  worst 7, spread 39
- *   0.69, AgX  -> (138,139,139) (131,132,133) (112,113,113)  worst 6, spread 26
- *
- * Blender's own spread is 30. The ACES rounds are what says the tone curve
- * was carrying the rest of row 1's defect: at ANY gain the operator holds the
- * shading range 30% wider than Blender's, which is why the document names its
- * own (`ToolViewportDressing.toneMapping`).
- *
- * WHAT IS LEFT, measured rather than guessed: the top face reads 3 to 6
- * levels dark and slightly warm. Blender's workbench couples its specular to
- * its diffuse — the same cube with `show_specular_highlight` off renders
- * BRIGHTER, (146,148,149)/(136,138,138)/(114,115,116) against
- * (142,144,145)/(130,132,132)/(112,113,113) with it on — and three's BRDF has
- * no such coupling, nor a second colour per light to carry
- * `specular_color`. Closing that is a shader of our own, not a light rig.
- */
-/*
- * SURFACES NO LONGER TAKE THIS RIG IN SOLID: they are drawn by Blender's own function
- * (`blender-workbench-material.ts`), which reproduces Blender on the faces a single gain could
- * not (a face square to the view: 158-160 against Blender's 161, where this rig gave 143). The rig
- * still lights what that function does not draw (volume boxes). WHAT THE MEASUREMENT SHOWED about
- * the rounds above: the three-face reference frames match Blender's function under the STANDARD
- * view transform (function: 147/136/116 against 144/132/113; under AgX, 151/142/126), so they were
- * made under Standard, and the gain was absorbing a view-transform difference, not a shading one.
- * Blender's factory transform is AgX (`--factory-startup`: `view_transform` AgX), which the stage
- * uses.
- */
+/** One gain across the studio lights; relative strengths, directions and wraps remain Blender’s. */
+/* Solid surfaces use blender-workbench-material.ts. This rig lights content outside that shader, including volume boxes, under the stage’s view transform. */
 const SOLID_STUDIO_GAIN = 0.69;
 
 /**
@@ -437,10 +372,10 @@ export type WorldExpression =
     }
   | {
       kind: 'sky';
-      sky_model?: 'SINGLE_SCATTERING' | 'MULTIPLE_SCATTERING' | undefined;
-      sun_disc?: boolean | undefined;
-      sun_size?: number | undefined;
-      sun_intensity?: number | undefined;
+      sky_model: 'SINGLE_SCATTERING' | 'MULTIPLE_SCATTERING';
+      sun_disc: boolean;
+      sun_size: number;
+      sun_intensity: number;
       sun_elevation: number;
       sun_rotation: number;
       altitude: number;
@@ -537,10 +472,10 @@ const worldExpression: z.ZodType<WorldExpression> = z.lazy(() =>
     z
       .object({
         kind: z.literal('sky'),
-        sky_model: z.enum(['SINGLE_SCATTERING', 'MULTIPLE_SCATTERING']).optional(),
-        sun_disc: z.boolean().optional(),
-        sun_size: scalar.optional(),
-        sun_intensity: scalar.optional(),
+        sky_model: z.enum(['SINGLE_SCATTERING', 'MULTIPLE_SCATTERING']),
+        sun_disc: z.boolean(),
+        sun_size: scalar,
+        sun_intensity: scalar,
         sun_elevation: scalar,
         sun_rotation: scalar,
         altitude: scalar,
@@ -574,36 +509,10 @@ export const worldSchema = worldRadiance
   })
   .strict();
 
-/** Compile once; the texture loop only evaluates directions in Blender's Z-up basis. */
-
-/** Sampled world radiance, by the description that produced it.
- *
- * Sampling is 32,768 texels and, for a SKY, each texel runs the
- * multiple-scattering model -- synchronously, on the page's main thread.
- * MEASURED: a capture of a scene with a sky world cost 15.4s against 0.03s for
- * the same scene with a plain background, and three identical captures in a row
- * each paid it in full. That is why the page froze solid during a replay and
- * why the photograph was SLOWER than the Cycles path trace it is compared
- * against (15.4s vs 7.6s) -- for a screenshot.
- *
- * The DATA is cached rather than the texture, because `clear()` disposes
- * textures and a disposed texture must never be handed out again; a Uint16Array
- * survives disposal and uploading it again is free. Keyed by the description
- * itself, so any change to the sky (or to strength) rebuilds and an unchanged
- * one never does. A handful of entries covers the background/lighting pair a
- * split world needs without letting the map grow with the session. */
+/** Cache sampled world-radiance arrays by description. Arrays survive texture disposal and can be uploaded into a new texture; bounded entries cover split background and lighting worlds. */
 const WORLD_FIELD_CACHE_LIMIT = 4;
 const worldFieldCache = new Map<string, Float32Array>();
 
-/** Sky derivations still running. `worldReady()` is what a RENDER awaits, the
- *  same way it already awaits `lightingReady()` and `texturesReady()` -- a
- *  photograph gets one chance and must not catch a half-built sky. */
-const pendingWorld = new Set<Promise<void>>();
-
-export async function worldReady(): Promise<void> {
-  while (pendingWorld.size > 0) await Promise.all([...pendingWorld]);
-}
-
 function worldTexture(
   expression: WorldExpression,
   strength: number,
@@ -611,11 +520,9 @@ function worldTexture(
 ): THREE.DataTexture {
   const width = 256,
     height = 128;
-  // KEYED ON THE EXPRESSION ALONE. Strength is a multiplier applied per texel
-  // below, so it cannot change what the field SAMPLES -- only what they are
-  // scaled by. Keying on it too made a strength-only change re-derive the whole
-  // sky, and made a world split by `Is Camera Ray` (one sky, two strengths)
-  // build that sky TWICE where once would do.
+  // Cache unscaled field samples by expression and any camera coordinates.
+  // Strength is applied per texture, so background and lighting branches at
+  // different strengths share the same sampled sky.
   const windowCoordinates = usesWindowCoordinates(expression);
   if (windowCoordinates && !camera)
     throw new Error('World Window coordinates need a render camera');
@@ -626,19 +533,7 @@ function worldTexture(
   ]);
   const cached = worldFieldCache.get(key);
   if (cached !== undefined) return worldDataTexture(cached, strength, width, height);
-  // SYNCHRONOUS, AND THAT IS THE POINT. The expensive half -- each Sky Texture's
-  // 512x256 multiple-scattering precompute -- has already been derived in the
-  // worker and primed into `blender-sky`'s cache by the time anything calls
-  // this; see `WorldBackground.apply`. What is left here is 32,768 bilinear
-  // lookups, which is milliseconds.
-  //
-  // It stays synchronous because the alternative is what shipped once and was
-  // taken back out (#6609): the texture handed out EMPTY and filled when the
-  // worker answered, with the capture racing the fill. Measured on pixels, a
-  // fresh sky rendered to 716 bytes and moving the sun produced the
-  // byte-identical empty image. A render gets one chance. Nothing here ever
-  // hands out a texture it has not already filled; the waiting happens one level
-  // up, where `pendingWorld` can hold the capture.
+  // Sky precomputation is primed by the worker before this synchronous sampling pass. Return only filled textures; WorldBackground.ready holds captures until the preparation finishes.
   const windowPoint = new THREE.Vector3();
   const projected = new THREE.Vector4();
   const projection = camera
@@ -671,9 +566,6 @@ function worldTexture(
   return worldDataTexture(samples, strength, width, height);
 }
 
-/** One sampled field, scaled, as a texture. The samples are UNSCALED and shared
- *  between textures; the multiply and the half-float conversion happen here, so
- *  two strengths over one sky cost one derivation and two cheap passes. */
 /** Scale and convert, in one pass. The multiply happens BEFORE the half-float
  *  conversion, or a dim fill branch would quantise against a bright backdrop's
  *  range. */
@@ -692,6 +584,8 @@ function writeScaled(
   }
 }
 
+/** Scale shared radiance samples into a texture, using float32 when the scaled
+ *  field exceeds half-float range. */
 function worldDataTexture(
   samples: Float32Array,
   strength: number,
@@ -724,7 +618,6 @@ export type WorldData = z.infer<typeof worldSchema>;
  * Constants and linked colors use the same radiometric path. The environment
  * samples the field at 256×128; features below a texel are filtered. */
 export class WorldBackground {
-  lightingTexture():THREE.Texture|null {return this.environmentTexture??this.texture;}
   readonly solarLights: THREE.DirectionalLight[] = [];
   private readonly solarDirections = new Map<THREE.DirectionalLight, THREE.Vector3>();
 
@@ -763,23 +656,7 @@ export class WorldBackground {
    *  after the world moved on knows it is stale and composes nothing. */
   private generation = 0;
 
-  /**
-   * THE ASYNC SEAM, and the only one.
-   *
-   * Every Sky Texture in this world is derived in a worker BEFORE anything is
-   * composed. When all of them are already in `blender-sky`'s cache the whole
-   * apply runs synchronously, exactly as it did inline. When any is missing,
-   * composition is DEFERRED behind the worker and the promise is registered in
-   * `pendingWorld` SYNCHRONOUSLY, before this method returns -- which is what
-   * makes it impossible for a caller to reach `worldReady()` in between.
-   * `BlenderRuntimeView.setRendered` awaits `worldReady()` AFTER the applies for
-   * this reason, and that ordering must not move.
-   *
-   * The failure this is shaped against (#6609) was a texture handed out empty
-   * and filled later. Here nothing is handed out early at all: until the sky
-   * exists, `scene.background` is simply not assigned, and the capture that
-   * awaits `worldReady()` cannot run until it is.
-   */
+  /** Prepare missing sky textures in the worker and publish pending synchronously before returning. Assign the composed background only after preparation; captures await ready after apply. */
   apply(root: THREE.Object3D, world: WorldData | null, camera?: THREE.Camera): void {
     this.clear();
     this.pending = null;
@@ -812,22 +689,18 @@ export class WorldBackground {
       presenterChanged();
     })();
     this.pending = pending;
-    pendingWorld.add(pending);
-    // Both arms, or a rejection here is an unhandled one; `worldReady()` still
-    // awaits `pending` itself, so the failure reaches the capture LOUDLY rather
-    // than leaving it to photograph a scene with no sky.
-    void pending.then(
-      () => pendingWorld.delete(pending),
-      () => pendingWorld.delete(pending),
-    );
+    // Handled here, or a rejection nobody has awaited yet is an unhandled one;
+    // `ready()` still awaits `pending` itself, so the failure reaches the
+    // capture LOUDLY rather than leaving it to photograph a scene with no sky.
+    pending.catch(() => {});
   }
 
   private compose(
     scene: THREE.Scene,
     world: WorldData,
     expression: WorldExpression,
-    camera?: THREE.Camera,
-    root?: THREE.Object3D,
+    camera: THREE.Camera | undefined,
+    root: THREE.Object3D,
   ): void {
     this.texture = worldTexture(expression, world.strength, camera);
     if (usesWindowCoordinates(expression)) {
@@ -853,11 +726,8 @@ export class WorldBackground {
     } else {
       scene.background = this.texture;
     }
-    // Replace the document environment so the model is not lit twice. When
-    // `Is Camera Ray` split the world, what LIGHTS the scene is a different
-    // radiance from what the camera photographs -- `19-tram-stop` lights at
-    // 0.30 behind a 0.95 backdrop -- and three keeps the two apart, so using
-    // the backdrop here would light that scene three times too brightly.
+    // Replace the document environment. A world split by `Is Camera Ray`
+    // supplies separate lighting and backdrop radiance.
     const { lighting } = world;
     const lightingExpression = lighting?.shader ?? lighting?.color ?? expression;
     const solar = worldSolarIrradiance(lightingExpression);
@@ -866,15 +736,15 @@ export class WorldBackground {
         lighting?.strength ?? world.strength, camera)
       : null;
     scene.environment = this.environmentTexture ?? this.texture;
-    root?.updateMatrixWorld(true);
+    root.updateMatrixWorld(true);
     for (const {direction, irradiance} of solar) {
       const light = new THREE.DirectionalLight(0xffffff, lighting?.strength ?? world.strength);
       light.name = 'BlenderWorldSun';
       light.color.setRGB(irradiance.x, irradiance.y, irradiance.z, THREE.LinearSRGBColorSpace);
       light.position.copy(direction);
-      if (root) light.position.transformDirection(root.matrixWorld);
+      light.position.transformDirection(root.matrixWorld);
       light.castShadow = true;
-      light.shadow.mapSize.set(2048, 2048);
+      light.shadow.mapSize.set(SUN_SHADOW_MAP_SIZE, SUN_SHADOW_MAP_SIZE);
       scene.add(light, light.target);
       this.solarLights.push(light);
       this.solarDirections.set(light, direction.clone());

package/browser/three/blender-runtime-shadows.ts

@@ -71,7 +71,8 @@ export function fitModelDirectionalShadow(
   );
   const size = bounds.getSize(new THREE.Vector3());
   const epsilon = Math.max(size.length() * 1e-6, Number.EPSILON);
-  // PCFSoft reaches two texels per axis; the normal offset can move the
+  // PCF (r186: five taps on a disk of `shadow.radius`, 1 texel, each a
+  // hardware 2x2 compare) reaches two texels per axis; the normal offset can move the
   // lookup another 2*sqrt(2) texels. Reserve that same footprint for both
   // the map and the casters that can contribute to its edge samples.
   const support = 2 + 2 * Math.SQRT2;
@@ -110,3 +111,188 @@ export function fitModelDirectionalShadow(
   camera.updateProjectionMatrix();
   light.shadow.normalBias = normalBias;
 }
+
+/**
+ * HOW FAR A POINT OR SPOT LIGHT REACHES, as EEVEE cuts it off (`Light::attenuation_radius_get`): where its power,
+ * falling with the square of the distance, drops under the scene's light threshold, sqrt(max colour · watts / 100 /
+ * threshold) metres, at EEVEE's default threshold (0.01, which the frame does not carry), so sqrt(max colour · watts).
+ * In three.js's terms the watts are 4π times the intensity (`blender-runtime-lighting.ts`). A three.js cut-off
+ * (`distance`), when one is set, is a reach too.
+ */
+export function perspectiveLightReach(light: THREE.PointLight | THREE.SpotLight): number {
+  const watts = 4 * Math.PI * Math.max(0, light.intensity);
+  const reach = Math.sqrt(Math.max(light.color.r, light.color.g, light.color.b, 0) * watts / 100 / EEVEE_LIGHT_THRESHOLD);
+  return light.distance > 0 ? Math.min(light.distance, reach) : reach;
+}
+
+/** EEVEE's default light threshold (`scene.eevee.light_threshold`): below it a light lights nothing. */
+const EEVEE_LIGHT_THRESHOLD = 0.01;
+
+/** Find the farthest visible shadow receiver, skipping boxes whose farthest corner cannot improve the current result. Return a one-point array, or an empty array when no receiver is visible. */
+export function farthestVisibleReceiver(boxes: readonly THREE.Box3[], frustum: THREE.Frustum,
+  from: THREE.Vector3): THREE.Vector3[] {
+  // A box's farthest corner from `from`: on each axis, the face farther from it.
+  const farthest = (box: THREE.Box3): number => box.isEmpty() ? -1 : Math.hypot(
+    Math.max(Math.abs(box.min.x - from.x), Math.abs(box.max.x - from.x)),
+    Math.max(Math.abs(box.min.y - from.y), Math.abs(box.max.y - from.y)),
+    Math.max(Math.abs(box.min.z - from.z), Math.abs(box.max.z - from.z)));
+  const reach = boxes.map((box) => ({ box, far: farthest(box) })).sort((a, b) => b.far - a.far);
+  let best = -1;
+  let point: THREE.Vector3 | null = null;
+  for (const { box, far } of reach) {
+    if (far <= best) break;
+    for (const candidate of visibleShadowReceivers(box, frustum)) {
+      const distance = candidate.distanceTo(from);
+      if (distance > best) { best = distance; point = candidate; }
+    }
+  }
+  return point ? [point] : [];
+}
+
+/** Size a point or spot light’s normal offset from a shadow-map texel at its farthest visible lit receiver. With no receiver, use the nearer of the light’s reach and far plane. Point maps have 90-degree faces; spot maps span 2 × angle × focus. */
+export function fitPerspectiveShadowBias(
+  light: THREE.PointLight | THREE.SpotLight,
+  receivers: readonly THREE.Vector3[],
+): void {
+  if (!light.castShadow) return;
+  const position = light.getWorldPosition(new THREE.Vector3());
+  const far = (light.shadow.camera as THREE.PerspectiveCamera).far;
+  const reach = Math.min(perspectiveLightReach(light), far);
+  let distance = 0;
+  for (const point of receivers) distance = Math.max(distance, point.distanceTo(position));
+  distance = distance > 0 ? Math.min(distance, reach) : reach;
+  const half = (light as THREE.SpotLight).isSpotLight
+    ? Math.min((light as THREE.SpotLight).angle * (light.shadow as THREE.SpotLightShadow).focus, Math.PI / 2 - 1e-3)
+    : Math.PI / 4;
+  const size = Math.max(1, Math.min(light.shadow.mapSize.x, light.shadow.mapSize.y));
+  const texel = (2 * distance * Math.tan(half)) / size;
+  light.shadow.normalBias = 2 * Math.SQRT2 * texel;
+}
+
+const RECEIVER_VERTEX = /* glsl */ `
+#include <common>
+#include <batching_pars_vertex>
+#include <morphtarget_pars_vertex>
+#include <skinning_pars_vertex>
+#include <logdepthbuf_pars_vertex>
+#include <clipping_planes_pars_vertex>
+varying vec3 vReceiver;
+void main() {
+  #include <batching_vertex>
+  #include <skinbase_vertex>
+  #include <morphinstance_vertex>
+  #include <begin_vertex>
+  #include <morphtarget_vertex>
+  #include <skinning_vertex>
+  #include <project_vertex>
+  #include <logdepthbuf_vertex>
+  #include <clipping_planes_vertex>
+  vReceiver = mvPosition.xyz;
+}
+`;
+
+const RECEIVER_FRAGMENT = /* glsl */ `
+varying vec3 vReceiver;
+#include <logdepthbuf_pars_fragment>
+#include <clipping_planes_pars_fragment>
+void main() {
+  #include <clipping_planes_fragment>
+  #include <logdepthbuf_fragment>
+  gl_FragColor = vec4(vReceiver, 1.0);
+}
+`;
+
+/** Samples across the drawing's width; the height keeps the drawing's aspect. */
+const RECEIVER_SAMPLES = 256;
+
+/**
+ * Fit sun shadows to the surfaces visible through the drawing camera, following EEVEE’s
+ * receiver-depth approach. Render view-space positions at a small sample grid spanning the
+ * drawing’s edges, then return those samples in world space. Hidden surfaces are excluded so the
+ * geometry behind them can contribute.
+ */
+export class VisibleReceivers {
+  private target: THREE.WebGLRenderTarget | null = null;
+  private pixels = new Float32Array(0);
+  private readonly camera = new THREE.Camera();
+  private readonly material = new THREE.ShaderMaterial({
+    name: 'Blender visible receivers',
+    vertexShader: RECEIVER_VERTEX,
+    fragmentShader: RECEIVER_FRAGMENT,
+  });
+
+  /** World-space points of what `camera` sees of `scene`; empty when nothing (or no readable
+   *  float target) answered, which a caller treats as "no samples". */
+  sample(
+    renderer: THREE.WebGLRenderer,
+    scene: THREE.Scene,
+    camera: THREE.Camera,
+    hidden: readonly THREE.Object3D[],
+  ): THREE.Vector3[] {
+    const output = renderer.getRenderTarget();
+    const size = output ? new THREE.Vector2(output.width, output.height) : renderer.getDrawingBufferSize(new THREE.Vector2());
+    const width = RECEIVER_SAMPLES;
+    const height = Math.max(2, Math.round((RECEIVER_SAMPLES * size.y) / Math.max(1, size.x)));
+    this.target ??= new THREE.WebGLRenderTarget(width, height, {
+      type: THREE.FloatType, minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter,
+      generateMipmaps: false, depthBuffer: true,
+    });
+    if (this.target.width !== width || this.target.height !== height) this.target.setSize(width, height);
+    // The outermost sample centres on the drawing's own edges: scaling the projection's x and y
+    // by (n - 1) / n puts sample i of n at (2i + 1 - n) / (n - 1) in the drawing's NDC.
+    camera.updateMatrixWorld();
+    const probe = this.camera;
+    probe.matrixAutoUpdate = false;
+    probe.matrix.copy(camera.matrixWorld);
+    probe.matrixWorld.copy(camera.matrixWorld);
+    probe.matrixWorldInverse.copy(camera.matrixWorld).invert();
+    probe.projectionMatrix.copy(camera.projectionMatrix)
+      .premultiply(new THREE.Matrix4().makeScale((width - 1) / width, (height - 1) / height, 1));
+    probe.projectionMatrixInverse.copy(probe.projectionMatrix).invert();
+    probe.layers.mask = camera.layers.mask;
+    const count = width * height * 4;
+    if (this.pixels.length !== count) this.pixels = new Float32Array(count);
+    this.pixels.fill(0);
+    const visible = hidden.map((object) => object.visible);
+    const background = scene.background;
+    const override = scene.overrideMaterial;
+    const autoClear = renderer.autoClear;
+    const shadows = renderer.shadowMap.enabled;
+    const clearColor = renderer.getClearColor(new THREE.Color());
+    const clearAlpha = renderer.getClearAlpha();
+    try {
+      for (const object of hidden) object.visible = false;
+      scene.background = null;
+      scene.overrideMaterial = this.material;
+      renderer.autoClear = false;
+      renderer.shadowMap.enabled = false;
+      renderer.setRenderTarget(this.target);
+      renderer.setClearColor(0x000000, 0);
+      renderer.clear(true, true, false);
+      renderer.render(scene, probe);
+      renderer.readRenderTargetPixels(this.target, 0, 0, width, height, this.pixels);
+    } finally {
+      hidden.forEach((object, index) => { object.visible = visible[index]!; });
+      scene.background = background;
+      scene.overrideMaterial = override;
+      renderer.autoClear = autoClear;
+      renderer.shadowMap.enabled = shadows;
+      renderer.setClearColor(clearColor, clearAlpha);
+      renderer.setRenderTarget(output);
+    }
+    const points: THREE.Vector3[] = [];
+    for (let i = 0; i < width * height; i++) {
+      if (this.pixels[i * 4 + 3]! === 0) continue;
+      points.push(new THREE.Vector3(this.pixels[i * 4]!, this.pixels[i * 4 + 1]!, this.pixels[i * 4 + 2]!)
+        .applyMatrix4(camera.matrixWorld));
+    }
+    return points;
+  }
+
+  dispose(): void {
+    this.target?.dispose();
+    this.target = null;
+    this.material.dispose();
+    this.pixels = new Float32Array(0);
+  }
+}

package/browser/three/blender-runtime-skeleton.ts

@@ -74,8 +74,57 @@ export function skinGeometry(geometry: THREE.BufferGeometry, skin: FrameSkin): v
   geometry.userData['blenderSkin'] = { armature: skin.armature, groups: [...skin.groups] };
 }
 
+/**
+ * A SKINNED MESH'S REACH: how far any of its vertices lies from a bone that moves it, at the bind.
+ * Skinning moves a vertex rigidly with each bone and blends the results, so wherever the bones go,
+ * every vertex stays within this distance of the space the bones span. `fitBounds` makes the
+ * frame's bounding sphere from it.
+ */
+function skinReach(skinned: THREE.SkinnedMesh): number {
+  const position = skinned.geometry.getAttribute('position');
+  const index = skinned.geometry.getAttribute('skinIndex');
+  const weight = skinned.geometry.getAttribute('skinWeight');
+  if (!position || !index || !weight) return Infinity;
+  const joints = skinned.skeleton.boneInverses.map((inverse) =>
+    new THREE.Vector3().setFromMatrixPosition(inverse.clone().invert()));
+  const vertex = new THREE.Vector3();
+  let reach = 0;
+  for (let i = 0; i < position.count; i++) {
+    vertex.fromBufferAttribute(position, i).applyMatrix4(skinned.bindMatrix);
+    for (let k = 0; k < 4; k++) {
+      if (weight.getComponent(i, k) <= 0) continue;
+      const joint = joints[index.getComponent(i, k)];
+      if (joint) reach = Math.max(reach, vertex.distanceTo(joint));
+    }
+  }
+  return reach;
+}
+
 export class RuntimeSkeletons {
   #rigs = new Map<string, Rig>();
+  /** Every mesh `bind` skinned, with its reach (`skinReach`). */
+  #bound = new Map<THREE.SkinnedMesh, number>();
+  readonly #box = new THREE.Box3();
+  readonly #point = new THREE.Vector3();
+  readonly #inverse = new THREE.Matrix4();
+
+  /** Refresh skinned-mesh culling spheres from current world-space bone positions plus each mesh’s reach. prepareDraw calls this after updateMatrixWorld. */
+  fitBounds(): void {
+    for (const [skinned, reach] of this.#bound) {
+      // Disable culling for detached meshes and skins whose reach cannot be read.
+      if (!skinned.parent) { skinned.frustumCulled = false; this.#bound.delete(skinned); continue; }
+      if (!Number.isFinite(reach)) { skinned.frustumCulled = false; continue; }
+      const box = this.#box.makeEmpty();
+      for (const bone of skinned.skeleton.bones) box.expandByPoint(this.#point.setFromMatrixPosition(bone.matrixWorld));
+      const sphere = skinned.boundingSphere ?? (skinned.boundingSphere = new THREE.Sphere());
+      box.getBoundingSphere(sphere);
+      sphere.radius += reach;
+      // Into the mesh's own space, where three reads the sphere (`Frustum.intersectsObject`).
+      this.#inverse.copy(skinned.matrixWorld).invert();
+      sphere.applyMatrix4(this.#inverse);
+      skinned.frustumCulled = true;
+    }
+  }
 
   /** The rig of one armature, or null when the frame names none by that name. */
   rig(armature: string): ArmatureRig | null {
@@ -130,7 +179,7 @@ export class RuntimeSkeletons {
         rig = { armature: name, object, root, still, bones, structure, pose: new Map(), poseKey: '', action: null };
         this.#rigs.set(name, rig);
       }
-      rig.action = armature.action ?? null;
+      rig.action = armature.action;
       const poseKey = armature.bones.map((bone) => bone.matrix.flat().join(',')).join(';');
       if (poseKey !== rig.poseKey) {
         rig.poseKey = poseKey;
@@ -196,11 +245,14 @@ export class RuntimeSkeletons {
     // A re-export rebinds the same mesh: its old skeleton's bone texture goes with it.
     (skinned.skeleton as THREE.Skeleton | undefined)?.dispose();
     skinned.bind(new THREE.Skeleton(bones, inverses), mesh.matrixWorld.clone());
+    if (skinned !== mesh) this.#bound.delete(mesh as THREE.SkinnedMesh);
+    this.#bound.set(skinned, skinReach(skinned));
     return skinned;
   }
 
   dispose(): void {
     for (const rig of this.#rigs.values()) rig.root.removeFromParent();
     this.#rigs.clear();
+    this.#bound.clear();
   }
 }