three-realtime-rt 0.4.2 → 0.5.0

package/src/RTLightingPass.js

@@ -75,6 +75,18 @@ uniform float uEnvIntensity;
 uniform float uFrame;
 uniform float uEps;
 uniform bool uGIEnabled;
+// EXPERIMENTAL: when an external ReSTIR GI pass supplies the 1-bounce indirect
+// (added downstream at the denoise stage), skip the inline GI trace so it isn't
+// counted twice. A uniform, NOT a sampler — the lighting pass is already at the
+// WebGL2 16-sampler minimum and cannot take another.
+uniform bool uExternalGI;
+
+// BVH traversal-cost heatmap (outputMode 7). When uCostView is on, main() writes
+// the per-pixel shadow-ray node-visit count (gBvhVisits, from bvhAnyHit.glsl.js)
+// through costPalette() into the irradiance attachment INSTEAD of the accumulated
+// lighting — bypassing temporal blending — so the debug view reads the raw cost.
+uniform bool uCostView;
+uniform float uCostScale; // multiplies the visit count before the palette (default 1/96)
 
 // Procedural sky (when enabled, replaces the flat env colour as the "miss" term
 // for GI rays — this is what gives natural outdoor bounce light).
@@ -541,13 +553,13 @@ vec3 analyticGlint(vec3 P, vec3 refl) {
 
 // Glass: Fresnel-weighted blend of a surface reflection and a two-interface
 // refraction (enter at P, march to the exit surface, refract again).
-vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough) {
+vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough, float ior) {
   vec3 refl = glossyReflect(V, N, rough);
   vec3 reflRad = dot(refl, N) > 0.0
     ? traceRadiance(P + N * uEps, refl, true) + analyticGlint(P, refl)
     : vec3(0.0);
 
-  float eta = 1.0 / uIor;
+  float eta = 1.0 / ior;
   vec3 rd = refract(V, N, eta);
   if (rd == vec3(0.0)) return reflRad; // total internal reflection at entry
   float fres = schlick(clamp(-dot(V, N), 0.0, 1.0), eta);
@@ -563,7 +575,7 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough) {
     vec3 xN = normalize(attr.xyz);
     if (dot(xN, rd) > 0.0) xN = -xN;
     vec3 xP = ro + rd * dist;
-    vec3 rd2 = refract(rd, xN, uIor);
+    vec3 rd2 = refract(rd, xN, ior);
     if (rd2 == vec3(0.0)) rd2 = reflect(rd, xN);
     refrRad = traceRadiance(xP - xN * uEps, rd2, true);
   } else {
@@ -574,6 +586,26 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough) {
   return mix(refrRad, reflRad, fres);
 }
 
+// Compact cold->hot ramp for the BVH-cost heatmap. Piecewise mix of five
+// anchors (deep blue -> green -> yellow -> red -> white) over four equal
+// segments — cheap, no textures, no extra samplers. t is the normalised cost
+// (visit count * uCostScale), clamped to [0,1]; saturating at white = the most
+// expensive pixels.
+vec3 costPalette(float t) {
+  t = clamp(t, 0.0, 1.0);
+  const vec3 c0 = vec3(0.02, 0.05, 0.45); // cold: cheap (few boxes)
+  const vec3 c1 = vec3(0.05, 0.55, 0.25); // green
+  const vec3 c2 = vec3(0.95, 0.85, 0.10); // yellow
+  const vec3 c3 = vec3(0.90, 0.10, 0.05); // red
+  const vec3 c4 = vec3(1.00, 1.00, 1.00); // hot: expensive (many boxes)
+  float s = t * 4.0;
+  vec3 col = mix(c0, c1, clamp(s, 0.0, 1.0));
+  col = mix(col, c2, clamp(s - 1.0, 0.0, 1.0));
+  col = mix(col, c3, clamp(s - 2.0, 0.0, 1.0));
+  col = mix(col, c4, clamp(s - 3.0, 0.0, 1.0));
+  return col;
+}
+
 void main() {
   vec4 wp = texture(uGWorldPos, vUv);
   if (wp.w < 0.5) {
@@ -599,6 +631,10 @@ void main() {
   float transmission = (matW >= 2.0 && matW < 4.0) ? clamp(matW - 2.0, 0.0, 1.0) : 0.0;
   float metal = matW < 2.0 ? matW : 0.0;
   float rough = clamp(wp.w - 1.0, 0.0, 1.0);
+  // Per-material IOR rides the [3,4) glass sub-band (full-transmission glass, see
+  // GBufferPass). Below 3 (partial glass) or non-glass, fall back to the global
+  // rt.ior uniform. material.ior wins whenever it was encoded. (Task 2)
+  float ior = (matW >= 3.0 && matW < 4.0) ? (1.0 + (matW - 3.0)) : uIor;
 
   // Cook-Torrance specular state for this primary surface. gWantSpec gates the
   // GGX term to PRIMARY direct lighting only (GI-bounce direct light, below,
@@ -608,6 +644,11 @@ void main() {
   gSpecRough = rough;
   gWantSpec = true;
 
+  // Reset the shadow-ray traversal-cost counter for this pixel. It accumulates
+  // across every occluded() call below (direct, GI, reflection, glass) and is
+  // read once at the end when uCostView is on (see the cost-heatmap branch).
+  gBvhVisits = 0;
+
   // --- direct lighting ---
   // ReSTIR: shade the reservoir's winner with one visibility ray (flat cost in
   // light count). Stochastic: one blind random sample. Full: one shadow ray
@@ -646,7 +687,10 @@ void main() {
   vec3 indirect = vec3(0.0);
   vec3 blendBehind = vec3(0.0);
   bool wantBehind = uBlendEnabled && blend;
-  bool wantGI = uGIEnabled && !wantBehind
+  // uExternalGI (experimental ReSTIR GI): the GIReservoirPass supplies the
+  // bounce, so the inline GI ray is skipped — but the blend continuation is
+  // NOT GI and must keep tracing regardless.
+  bool wantGI = uGIEnabled && !uExternalGI && !wantBehind
     && (!uGIHalfRate || (((px.x + px.y + int(uFrame)) & 1) == 0));
   if (wantBehind || wantGI) {
     vec3 Vv = normalize(P - uCameraPos);
@@ -685,7 +729,7 @@ void main() {
   // --- traced glass: Fresnel reflection + two-interface refraction ---
   if (uRefrEnabled && transmission > 0.001) {
     vec3 V = normalize(P - uCameraPos);
-    sampleIrr = mix(sampleIrr, glassRadiance(P, N, V, rough), transmission);
+    sampleIrr = mix(sampleIrr, glassRadiance(P, N, V, rough, ior), transmission);
   }
 
   // --- alpha blend: straight-through view continuation ---
@@ -772,6 +816,17 @@ void main() {
   // the fresh sample is used as-is.
   vec3 blended = mix(history, sampleIrr, 1.0 / count);
   outIrradiance = vec4(blended, count);
+
+  // BVH traversal-cost heatmap (outputMode 7). Overwrite the accumulated
+  // lighting with the palette-mapped shadow-ray node-visit count for this pixel.
+  // Alpha is forced to 1.0 so temporal history never builds on the cost image
+  // (each frame is a fresh snapshot), and the specular attachment is cleared so
+  // the composite's cost branch shows the palette alone. Uniform branch: when
+  // uCostView is off this is skipped and the writes above stand unchanged.
+  if (uCostView) {
+    outIrradiance = vec4(costPalette(float(gBvhVisits) * uCostScale), 1.0);
+    outSpecular = vec4(0.0);
+  }
 }
 `;
 
@@ -930,6 +985,9 @@ export class RTLightingPass {
         uFrame: { value: 0 },
         uEps: { value: 1e-3 },
         uGIEnabled: { value: true },
+        uExternalGI: { value: false },
+        uCostView: { value: false },
+        uCostScale: { value: 1 / 96 },
         uSkyEnabled: { value: false },
         uSunDir: { value: new THREE.Vector3(0.4, 0.8, 0.45).normalize() },
         uSunColor: { value: new THREE.Color(1.0, 0.9, 0.75) },

package/src/RealtimeRaytracer.js

@@ -7,6 +7,7 @@ import { CompositePass } from "./CompositePass.js";
 import { TAAPass } from "./TAAPass.js";
 import { VolumetricPass } from "./VolumetricPass.js";
 import { RestirPass } from "./RestirPass.js";
+import { GIReservoirPass } from "./GIReservoirPass.js";
 import { CopyPass } from "./CopyPass.js";
 
 // Van der Corput / Halton radical inverse — deterministic low-discrepancy
@@ -423,8 +424,15 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.compiled = null;
     this.frame = 0;
 
-    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular */
+    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular, 7 bvh cost */
     this.outputMode = 0;
+    /**
+     * BVH-cost heatmap scale (outputMode 7): the per-pixel shadow-ray node-visit
+     * count is multiplied by this before the palette, so 1/costScale visits map
+     * to the hot (white) end. Default 1/96 — ~96 visits saturate. Live-tunable
+     * (the demo's "cost scale" slider drives it).
+     */
+    this.costScale = options.costScale ?? 1 / 96;
     /** Environment (sky) color used for GI rays that miss + composite background. */
     this.envColor = options.envColor ?? new THREE.Color(0.03, 0.04, 0.06);
     this.envIntensity = options.envIntensity ?? 1.0;
@@ -552,6 +560,13 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.taa = options.taa ?? true;
     /** Fresh-sample weight in the TAA blend (lower = smoother/more AA, more lag). */
     this.taaBlend = options.taaBlend ?? 0.1;
+    /**
+     * Scales the TAA sub-pixel jitter amplitude. Set this to your canvas scale
+     * when you render a reduced drawing buffer CSS-stretched to the screen
+     * (canvasScaleHook), so the jitter stays constant in SCREEN pixels instead
+     * of being magnified by the stretch (visible wobble at low quality).
+     */
+    this.taaJitterScale = options.taaJitterScale ?? 1;
 
     /**
      * Volumetric lighting — real "god rays": single-scatter fog integrated
@@ -582,6 +597,22 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.restir = options.restir ?? true;
     this.restirPass = new RestirPass(this._scaledW, this._scaledH);
 
+    /**
+     * EXPERIMENTAL — ReSTIR GI (v1, temporal-only): per-pixel reservoirs reuse
+     * the 1-bounce global-illumination sample across frames (at the reprojected
+     * same-surface point, no spatial reuse / no Jacobian). Runs in a standalone
+     * pass with its own sampler budget; when on, the lighting pass skips its
+     * inline GI trace and this pass's resolved GI is added at the denoise stage.
+     * Only meaningful when `gi` is on, and injected via the à-trous denoise, so
+     * it requires `denoise` (denoiseIterations >= 1). Default OFF. Its mean
+     * matches the inline GI path — see GIReservoirPass. Live-toggleable.
+     */
+    this.restirGI = options.restirGI ?? false;
+    /** Temporal M-cap for the ReSTIR GI reservoir (staleness limit). */
+    this.restirGIMCap = options.restirGIMCap ?? 20;
+    this.giReservoirPass = new GIReservoirPass(this._scaledW, this._scaledH);
+    this._giMissWarned = false;
+
     /** Distance fog (composited in linear space before tonemap). */
     this.fog = {
       enabled: options.fog?.enabled ?? false,
@@ -703,6 +734,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.rtPass.setCompiledScene(this.compiled);
     this.volumetricPass.setCompiledScene(this.compiled);
     this.restirPass.setCompiledScene(this.compiled);
+    this.giReservoirPass.setCompiledScene(this.compiled);
     this.resetAccumulation();
     return this.compiled;
   }
@@ -728,6 +760,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.rtPass.setCompiledScene(this.compiled);
     this.volumetricPass.setCompiledScene(this.compiled);
     this.restirPass.setCompiledScene(this.compiled);
+    this.giReservoirPass.setCompiledScene(this.compiled);
   }
 
   resetAccumulation() {
@@ -831,6 +864,11 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
       // clear them.
       this.restirPass.setSize(sw, sh);
       this.restirPass.clearHistory(this.renderer);
+      // Reservoir GI history is packed (hit position + M + radiance + W) —
+      // invalid to linearly resample — but reconverges in a few frames, so
+      // reallocate and clear like the DI reservoirs.
+      this.giReservoirPass.setSize(sw, sh);
+      this.giReservoirPass.clearHistory(this.renderer);
     }
 
     // Full-res / canvas-res targets: only touched on a real canvas resize (a
@@ -976,8 +1014,15 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     // too — otherwise the raw buffers visibly shake.
     if (this.taa && this.outputMode === 0) {
       this._jitterIndex = (this._jitterIndex + 1) % 16;
-      const jx = (halton(this._jitterIndex + 1, 2) - 0.5) * 2 / this._width;
-      const jy = (halton(this._jitterIndex + 1, 3) - 0.5) * 2 / this._height;
+      // taaJitterScale: when the app renders a REDUCED drawing buffer and CSS-
+      // stretches it to the screen (the canvas-scale ladder), a half-buffer-pixel
+      // jitter is magnified by the stretch and reads as visible screen wobble.
+      // The app sets this to its canvas scale (see canvasScaleHook) so the
+      // jitter stays constant in SCREEN pixels — slightly less sub-pixel AA
+      // coverage at low canvas scales, in exchange for a steady image.
+      const js = this.taaJitterScale;
+      const jx = (halton(this._jitterIndex + 1, 2) - 0.5) * 2 * js / this._width;
+      const jy = (halton(this._jitterIndex + 1, 3) - 0.5) * 2 * js / this._height;
       proj.elements[8] += jx;
       proj.elements[9] += jy;
       // Where this jitter moves the image, in UV space: elements[8/9] multiply
@@ -999,6 +1044,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
       this.rtPass.clearHistory(this.renderer);
       this.volumetricPass.clearHistory(this.renderer);
       this.restirPass.clearHistory(this.renderer);
+      this.giReservoirPass.clearHistory(this.renderer);
       this._needsClear = false;
     }
 
@@ -1010,11 +1056,28 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     rtU.uEnvColor.value.copy(this.envColor);
     rtU.uEnvIntensity.value = this.envIntensity;
     rtU.uEps.value = this.eps;
+    rtU.uCostView.value = this.outputMode === 7;
+    rtU.uCostScale.value = this.costScale;
     rtU.uTemporalReprojection.value = this.temporalReprojection;
     rtU.uMaxHistory.value = this.maxHistory;
     rtU.uFireflyClamp.value = this.fireflyClamp > 0 ? this.fireflyClamp : 1e6;
     rtU.uGIEnabled.value = this.gi;
     rtU.uGIHalfRate.value = this.giHalfRate;
+    // ReSTIR GI (experimental) supplies the 1-bounce indirect externally when
+    // on; the lighting pass then skips its inline GI trace so it isn't double
+    // counted. It's injected at the denoise stage, so it needs denoise on.
+    const giExternal =
+      this.restirGI && this.gi && this.denoise && this.denoiseIterations > 0;
+    rtU.uExternalGI.value = giExternal;
+    if (this.restirGI && this.gi && !giExternal && !this._giMissWarned) {
+      console.info(
+        "[three-realtime-rt] restirGI is on but denoise is off — ReSTIR GI is " +
+          "injected during the à-trous denoise, so enable denoise " +
+          "(denoiseIterations >= 1) to see its contribution."
+      );
+      this._giMissWarned = true;
+    }
+    if (giExternal) this._giMissWarned = false;
     rtU.uEmissiveCount.value = this.emissiveNEE ? this.compiled.emissiveTriCount : 0;
     rtU.uEmissiveCDF.value = this.emissiveImportance;
     rtU.uReflEnabled.value = this.reflections;
@@ -1048,17 +1111,53 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
         this.eps
       );
     }
+    // 2b. ReSTIR GI reservoirs (experimental). Runs after the lighting pass's
+    // inline GI is skipped (uExternalGI); the resolved GI is added at denoise.
+    let giTex = null;
+    if (giExternal) {
+      this.giReservoirPass.setEmissiveCount(
+        this.emissiveNEE ? this.compiled.emissiveTriCount : 0
+      );
+      giTex = this.giReservoirPass.render(
+        this.renderer,
+        this.gbuffer,
+        this._prevViewProj,
+        this._camWorldPos,
+        this.frame,
+        this.eps,
+        {
+          fireflyClamp: this.fireflyClamp > 0 ? this.fireflyClamp : 1e6,
+          mCap: this.restirGIMCap,
+          emissiveCDF: this.emissiveImportance,
+          envColor: this.envColor,
+          envIntensity: this.envIntensity,
+          skyEnabled: this.sky.enabled,
+          sunDir: this.sky.sunDir,
+          sunColor: this.sky.sunColor,
+          skyZenith: this.sky.zenith,
+          skyHorizon: this.sky.horizon,
+          skyIntensity: this.sky.intensity,
+        }
+      );
+    }
+
     let { irradiance, specular } = this.rtPass.render(this.renderer, this.gbuffer, this.frame, reservoirTex);
 
-    // 3. denoise (display-only: history keeps accumulating raw samples)
-    if (this.denoise && this.denoiseIterations > 0) {
+    // 3. denoise (display-only: history keeps accumulating raw samples). The
+    // experimental ReSTIR GI (giTex) is added on the first à-trous iteration —
+    // downstream of the lighting pass's temporal history, so it never
+    // double-counts through it. The bvh-cost heatmap (mode 7) is a per-pixel
+    // debug signal, not lighting — the edge-aware blur would smear its bands,
+    // so it bypasses the denoiser (which also keeps the GI add out of mode 7).
+    if (this.denoise && this.denoiseIterations > 0 && this.outputMode !== 7) {
       irradiance = this.denoisePass.render(
         this.renderer,
         irradiance,
         this.gbuffer,
         this._camWorldPos,
         this.eps,
-        this.denoiseIterations
+        this.denoiseIterations,
+        giTex
       );
     }
 
@@ -1179,6 +1278,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.taaPass.dispose();
     this.volumetricPass.dispose();
     this.restirPass.dispose();
+    this.giReservoirPass.dispose();
     this._sceneColor.dispose();
     this._copyPass.dispose();
     if (this.compiled) this.compiled.dispose();

package/src/SceneCompiler.js

@@ -45,6 +45,9 @@ export class CompiledScene {
     // True when any dynamic segment is CPU-deformed (rtDeforming) — such segments
     // read their live geometry every frame and force a per-frame normal upload.
     this.hasDeforming = false;
+    // True when any dynamic segment is a SkinnedMesh — CPU-skinned every frame
+    // (shape changes each frame, so it forces a per-frame normal upload too).
+    this.hasSkinned = false;
 
     this.materialsTex = null;
     this.materials = [];
@@ -58,6 +61,7 @@ export class CompiledScene {
     this._m3 = new THREE.Matrix3();
     this._normalFrame = 0;
     this._dynBuildVolume = null; // world-volume of the dynamic set at build time
+    this._skinVec = new THREE.Vector3(); // reused per-vertex temp for CPU skinning
   }
 
   /**
@@ -81,7 +85,69 @@ export class CompiledScene {
       let o = seg.start * 3;
       let p = seg.start * 4;
 
-      if (seg.deforming) {
+      if (seg.skinned) {
+        // Animated SkinnedMesh: CPU-skin the SOURCE vertices with three's own
+        // applyBoneTransform (bindMatrix + bone weights/matrices), then expand
+        // through the de-index mapping into the merged triangle soup. In r160
+        // applyBoneTransform/getVertexPosition return the vertex in the mesh's
+        // LOCAL (bind-relative) space — NOT world — so matrixWorld is still
+        // applied here, exactly like the rigid/deforming paths.
+        const mesh = seg.mesh;
+        // Keep the skeleton's bone texture coherent for the raster (G-buffer)
+        // path; applyBoneTransform itself reads bone.matrixWorld, which the app
+        // must have posed (mixer.update + a world-matrix update) before this call.
+        if (mesh.skeleton) mesh.skeleton.update();
+        const local = seg.skinnedLocal;   // Float32Array(srcVertexCount * 3)
+        const tmp = this._skinVec;
+        const srcN = seg.srcVertexCount;
+        // 1. Skin each UNIQUE source vertex ONCE (O(verts x 4 bones)); shared
+        //    triangle-soup slots then reuse the cached result.
+        for (let sv = 0; sv < srcN; sv++) {
+          mesh.getVertexPosition(sv, tmp); // bind pos -> skinned LOCAL space
+          local[sv * 3] = tmp.x;
+          local[sv * 3 + 1] = tmp.y;
+          local[sv * 3 + 2] = tmp.z;
+        }
+        const map = seg.indexMap; // null = identity (non-indexed source)
+        // 2. Expand to the merged layout and transform to world.
+        for (let i = 0; i < seg.count; i++) {
+          const sv = map ? map[i] : i;
+          const x = local[sv * 3], y = local[sv * 3 + 1], z = local[sv * 3 + 2];
+          const wx = m[0] * x + m[4] * y + m[8] * z + m[12];
+          const wy = m[1] * x + m[5] * y + m[9] * z + m[13];
+          const wz = m[2] * x + m[6] * y + m[10] * z + m[14];
+          pos[o] = wx;
+          pos[o + 1] = wy;
+          pos[o + 2] = wz;
+          if (wx < minX) minX = wx; if (wx > maxX) maxX = wx;
+          if (wy < minY) minY = wy; if (wy > maxY) maxY = wy;
+          if (wz < minZ) minZ = wz; if (wz > maxZ) maxZ = wz;
+          o += 3;
+        }
+        // 3. PER-FACE normals from the skinned world triangles — the merged
+        //    layout is already a de-indexed triangle soup, so each face's 3
+        //    slots get the same geometric normal (flat-shaded). Secondary rays
+        //    (shadows/GI) only need the geometry to be right; primary visibility
+        //    still gets smooth normals from the raster path. This skips
+        //    CPU-skinning the normal attribute entirely.
+        let fp = seg.start * 4;
+        for (let i = 0; i < seg.count; i += 3) {
+          const b = (seg.start + i) * 3;
+          const ax = pos[b], ay = pos[b + 1], az = pos[b + 2];
+          const e1x = pos[b + 3] - ax, e1y = pos[b + 4] - ay, e1z = pos[b + 5] - az;
+          const e2x = pos[b + 6] - ax, e2y = pos[b + 7] - ay, e2z = pos[b + 8] - az;
+          let nx = e1y * e2z - e1z * e2y;
+          let ny = e1z * e2x - e1x * e2z;
+          let nz = e1x * e2y - e1y * e2x;
+          const il = 1.0 / (Math.hypot(nx, ny, nz) || 1);
+          nx *= il; ny *= il; nz *= il;
+          packed[fp] = nx; packed[fp + 1] = ny; packed[fp + 2] = nz;       // v0
+          packed[fp + 4] = nx; packed[fp + 5] = ny; packed[fp + 6] = nz;   // v1
+          packed[fp + 8] = nx; packed[fp + 9] = ny; packed[fp + 10] = nz;  // v2
+          // packed[fp + 3|7|11] (matIndex) never changes
+          fp += 12;
+        }
+      } else if (seg.deforming) {
         // CPU-deformed mesh (water/cloth): read the LIVE geometry every frame
         // and expand it back to the merged de-indexed layout through the mapping
         // snapshotted at compile time. `indexMap` (the source geometry's index
@@ -178,10 +244,11 @@ export class CompiledScene {
     }
     this.dynamicBvhUniform.updateFrom(this.dynamicBvh);
     // Normals only feed GI-bounce shading off movers — amortize their upload for
-    // rigid movers. Deforming meshes change shape (not just orientation) every
-    // frame, so their normals must go up every frame or the shading lags the
-    // silhouette; one deforming segment forces the whole (shared) upload.
-    if (this.hasDeforming || this._normalFrame++ % 8 === 0) {
+    // rigid movers. Deforming and skinned meshes change shape (not just
+    // orientation) every frame, so their normals must go up every frame or the
+    // shading lags the silhouette; one such segment forces the whole (shared)
+    // upload.
+    if (this.hasDeforming || this.hasSkinned || this._normalFrame++ % 8 === 0) {
       this.dynamicAttrTex.updateFrom(this.dynamicPackedAttr);
     }
   }
@@ -197,7 +264,7 @@ export class CompiledScene {
   }
 }
 
-function extractMeshGeometry(mesh, materialIndex) {
+function extractMeshGeometry(mesh) {
   const indexed = mesh.geometry.index;
   const src = indexed ? mesh.geometry.toNonIndexed() : mesh.geometry.clone();
 
@@ -211,8 +278,9 @@ function extractMeshGeometry(mesh, materialIndex) {
   geo.applyMatrix4(mesh.matrixWorld); // bake world transform
 
   const count = geo.getAttribute("position").count;
-  const mi = new Float32Array(count).fill(materialIndex);
-  geo.setAttribute("materialIndex", new THREE.BufferAttribute(mi, 1));
+  // The per-vertex materialIndex attribute is filled by resolveGroups (which the
+  // caller runs with the shared materials table), so a multi-material mesh gets
+  // its groups mapped to distinct materials rather than a single flat index.
 
   // For CPU-deformed (rtDeforming) meshes we re-read the LIVE geometry each
   // frame. The merged BVH is de-indexed triangle soup, so record how to expand
@@ -226,6 +294,45 @@ function extractMeshGeometry(mesh, materialIndex) {
   return { geo, localPos, localNorm, count, indexMap, srcVertexCount };
 }
 
+// Fill the per-vertex materialIndex for a (possibly multi-material) mesh and
+// return the material ranges for per-group emissive collection. Groups on the
+// INDEXED geometry are ranges over the index buffer; toNonIndexed() lays vertices
+// out in index order, so a group's [start, start+count) maps to the SAME range of
+// de-indexed vertices (identity for an already-non-indexed source). Each group's
+// material is registered in the shared table via registerMaterial.
+function resolveMeshMaterials(mesh, count, registerMaterial) {
+  const isArray = Array.isArray(mesh.material);
+  const groups = mesh.geometry.groups;
+  const matIdx = new Float32Array(count);
+  const ranges = [];
+  if (isArray && groups && groups.length > 0) {
+    // Ungrouped vertices (if any) default to material[0].
+    const base = mesh.material[0];
+    matIdx.fill(registerMaterial(base));
+    for (const g of groups) {
+      const gm = mesh.material[g.materialIndex] ?? base;
+      if (gm.transparent) {
+        throw new Error(
+          "three-realtime-rt: a transparent group material on a multi-material " +
+          "mesh is not supported for BVH tracing (transparent surfaces use the " +
+          "out-of-BVH straight-through blend path, which is per-mesh). Split the " +
+          `transparent group (materialIndex ${g.materialIndex}) into its own mesh.`
+        );
+      }
+      const gi = registerMaterial(gm);
+      const start = Math.max(0, g.start);
+      const end = Math.min(count, g.start + g.count);
+      for (let v = start; v < end; v++) matIdx[v] = gi;
+      ranges.push({ start, vcount: end - start, material: gm });
+    }
+  } else {
+    const mat = isArray ? mesh.material[0] : mesh.material;
+    matIdx.fill(registerMaterial(mat));
+    ranges.push({ start: 0, vcount: count, material: mat });
+  }
+  return { matIdx, ranges };
+}
+
 // Effective emissive colour (already scaled by intensity), or null if the
 // material doesn't emit. Matches the shading table's emissiveMap exclusion.
 function emissiveColor(mat) {
@@ -304,10 +411,14 @@ function buildSceneDataTexture(materials, emissiveTris) {
 }
 
 // Collect world-space triangles of an emissive mesh for the NEE light list.
-// `geo` is already non-indexed and world-baked by extractMeshGeometry.
-function collectEmissiveTriangles(geo, emit, out) {
+// `geo` is already non-indexed and world-baked by extractMeshGeometry. An
+// optional [vStart, vCount) vertex range restricts collection to one material
+// group (ranges are triangle-aligned, so this stays whole-triangle).
+function collectEmissiveTriangles(geo, emit, out, vStart = 0, vCount = -1) {
   const pos = geo.getAttribute("position").array;
-  for (let i = 0; i + 8 < pos.length; i += 9) {
+  const begin = vStart * 3;
+  const end = vCount < 0 ? pos.length : Math.min(pos.length, (vStart + vCount) * 3);
+  for (let i = begin; i + 9 <= end; i += 9) {
     const e1 = [pos[i + 3] - pos[i], pos[i + 4] - pos[i + 1], pos[i + 5] - pos[i + 2]];
     const e2 = [pos[i + 6] - pos[i], pos[i + 7] - pos[i + 1], pos[i + 8] - pos[i + 2]];
     const cx = e1[1] * e2[2] - e1[2] * e2[1];
@@ -372,35 +483,67 @@ export function compileScene(scene, options = {}) {
   let dynVertexOffset = 0;
   const tmpGeoms = []; // to dispose after merge
 
+  const registerMaterial = (m) => {
+    let i = materials.indexOf(m);
+    if (i < 0) { i = materials.length; materials.push(m); }
+    return i;
+  };
+
   scene.traverse((obj) => {
     if (!obj.isMesh || !obj.geometry || !obj.visible || obj.userData.rtExclude) return;
-    const mat = Array.isArray(obj.material) ? obj.material[0] : obj.material;
+    const isArray = Array.isArray(obj.material);
+    const rep = isArray ? obj.material[0] : obj.material;
     // Transparent surfaces must not act as opaque occluders — e.g.
     // LittlestTokyo's glass display case (texture-alpha, opacity 1) would put
     // the whole model in shadow. Alpha-textured glass can't be cheaply tested,
     // so ANY transparent material is skipped like rtExclude (still
     // rasterized). alphaTest cut-outs (transparent: false) stay occluders.
-    if (mat.transparent) return;
-    let mi = materials.indexOf(mat);
-    if (mi < 0) { mi = materials.length; materials.push(mat); }
+    if (rep.transparent) return;
 
-    const extracted = extractMeshGeometry(obj, mi);
+    const isDynamic = dynamicSet && dynamicSet.has(obj);
+    // Opt-in CPU deformation: the mesh must be BOTH in dynamicMeshes AND carry
+    // userData.rtDeforming, and its live geometry is read every frame.
+    const deforming = isDynamic && obj.userData.rtDeforming === true;
+    const hasGroups = isArray && obj.geometry.groups && obj.geometry.groups.length > 0;
+    // Multi-material groups are supported on static and rigid-dynamic meshes; the
+    // deforming rebake path assumes a single contiguous material range per merged
+    // segment, so reject the combination clearly rather than mis-shade it.
+    if (hasGroups && deforming) {
+      throw new Error(
+        "three-realtime-rt: multi-material groups on a CPU-deforming (rtDeforming) " +
+        "mesh are not supported — the per-frame live-geometry rebake assumes one " +
+        "material range. Use groups on a static or rigid-dynamic mesh, or split the " +
+        "deforming mesh into one mesh per material."
+      );
+    }
+
+    const extracted = extractMeshGeometry(obj);
     tmpGeoms.push(extracted.geo);
+    // Map groups → per-vertex material indices (registers each group material in
+    // the shared table) and get the ranges for per-group emissive collection.
+    const { matIdx, ranges } = resolveMeshMaterials(obj, extracted.count, registerMaterial);
+    extracted.geo.setAttribute("materialIndex", new THREE.BufferAttribute(matIdx, 1));
     // Static emissive meshes become NEE area lights (sampled directly with
     // shadow rays instead of waiting for a GI ray to stumble into them).
     // Dynamic emitters are left out — their world-space triangles would go
-    // stale — so they keep lighting the old way, via GI-ray hits.
-    const isDynamic = dynamicSet && dynamicSet.has(obj);
+    // stale — so they keep lighting the old way, via GI-ray hits. Each emissive
+    // GROUP contributes its own range.
     if (!isDynamic) {
-      const emit = emissiveColor(mat);
-      if (emit) collectEmissiveTriangles(extracted.geo, emit, emissiveTris);
+      for (const r of ranges) {
+        const emit = emissiveColor(r.material);
+        if (emit) collectEmissiveTriangles(extracted.geo, emit, emissiveTris, r.start, r.vcount);
+      }
     }
     if (isDynamic) {
       dynamicGeoms.push(extracted.geo);
-      // Opt-in CPU deformation: the mesh must be BOTH in dynamicMeshes AND carry
-      // userData.rtDeforming, and its live geometry is read every frame.
-      const deforming = obj.userData.rtDeforming === true;
+      // A SkinnedMesh is auto-detected (no userData flag): it is CPU-skinned from
+      // its live skeleton pose every frame. Opt-in CPU deformation (water/cloth)
+      // instead requires userData.rtDeforming and reads live geometry. The two are
+      // mutually exclusive; skinning wins if a mesh is somehow both.
+      const skinned = obj.isSkinnedMesh === true;
+      const deforming = !skinned && obj.userData.rtDeforming === true;
       if (deforming) compiled.hasDeforming = true;
+      if (skinned) compiled.hasSkinned = true;
       compiled.dynamic.push({
         mesh: obj,
         start: dynVertexOffset,
@@ -408,9 +551,15 @@ export function compileScene(scene, options = {}) {
         localPos: extracted.localPos,
         localNorm: extracted.localNorm,
         deforming,
+        skinned,
         liveGeometry: deforming ? obj.geometry : null,
-        indexMap: deforming ? extracted.indexMap : null,
-        srcVertexCount: deforming ? extracted.srcVertexCount : 0,
+        // Skinned and deforming segments both expand live/source vertices back
+        // into the merged de-indexed layout through this mapping.
+        indexMap: deforming || skinned ? extracted.indexMap : null,
+        srcVertexCount: deforming || skinned ? extracted.srcVertexCount : 0,
+        // Cache of per-source-vertex skinned LOCAL positions (skinned segs only),
+        // filled each frame so shared triangle-soup slots reuse one skin solve.
+        skinnedLocal: skinned ? new Float32Array(extracted.srcVertexCount * 3) : null,
       });
       dynVertexOffset += extracted.count;
     } else {

package/src/bvhAnyHit.glsl.js

@@ -35,6 +35,17 @@
 
 export const BVH_ANY_HIT_GLSL = /* glsl */ `
 
+// Traversal-cost instrumentation. Counts how many BVH nodes the current pixel's
+// shadow rays visit this frame — the raw signal behind the "bvh cost" heatmap
+// debug view (outputMode 7). RTLightingPass main() zeroes it at the top of the
+// pixel and reads it after all shadow rays have run; it accumulates across every
+// bvhIntersectAnyHit call (both BVH levels, every light / GI / reflection ray).
+// When uCostView is off the count is written nowhere, so shading is unaffected —
+// the only cost is one integer add per popped node. Initialised to 0 so the
+// VolumetricPass program (which shares this GLSL but never reads the counter)
+// still compiles and runs unchanged.
+int gBvhVisits = 0;
+
 // Returns true if ANY triangle in the BVH is hit by the ray within (0, maxDist).
 // Unordered traversal with early-out; no closest-hit bookkeeping.
 bool bvhIntersectAnyHit( BVH bvh, vec3 rayOrigin, vec3 rayDirection, float maxDist ) {
@@ -54,6 +65,10 @@ bool bvhIntersectAnyHit( BVH bvh, vec3 rayOrigin, vec3 rayDirection, float maxDi
 		uint currNodeIndex = stack[ ptr ];
 		ptr --;
 
+		// One node visited (popped + tested). Counts pruned nodes too — that IS
+		// the traversal cost the heatmap visualises.
+		gBvhVisits ++;
+
 		// prune: skip nodes the ray misses or whose entry distance is already past maxDist
 		float boundsHitDistance;
 		if (