three-realtime-rt 0.4.0 → 0.5.0

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
@@ -242,6 +243,72 @@ export class RealtimeRaytracer {
     }
   }
 
+  /**
+   * FUNCTIONAL probe: can this context actually DRAW into a 2-attachment
+   * half-float MRT? A checkFramebufferStatus probe is not enough — WebKit
+   * (every iOS browser) reports the framebuffer complete and then renders
+   * black, which killed the whole lighting pass on iPhone/iPad in 0.4.0.
+   * So: render one 2-output quad into a tiny fp16 MRT, resolve attachment 0
+   * into an RGBA8 target through a sampler, and read the pixel back. Only a
+   * round-trip that returns the written value counts as support.
+   */
+  static _specMrtSupported(renderer) {
+    let mrt, out, mat, copy, quad, scene2, cam;
+    const prevTarget = renderer.getRenderTarget();
+    try {
+      mrt = new THREE.WebGLMultipleRenderTargets(2, 2, 2, {
+        format: THREE.RGBAFormat,
+        type: THREE.HalfFloatType,
+        depthBuffer: false,
+        stencilBuffer: false,
+      });
+      for (const tex of mrt.texture) tex.generateMipmaps = false;
+      out = new THREE.WebGLRenderTarget(2, 2, { depthBuffer: false, stencilBuffer: false });
+      const vert = `out vec2 vUv; void main(){ vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }`;
+      mat = new THREE.ShaderMaterial({
+        glslVersion: THREE.GLSL3,
+        vertexShader: vert,
+        fragmentShader: `precision highp float;
+layout(location = 0) out vec4 o0; layout(location = 1) out vec4 o1;
+void main(){ o0 = vec4(0.5, 0.25, 0.75, 1.0); o1 = vec4(0.125); }`,
+        depthTest: false,
+        depthWrite: false,
+      });
+      copy = new THREE.ShaderMaterial({
+        glslVersion: THREE.GLSL3,
+        vertexShader: vert,
+        fragmentShader: `precision highp float; in vec2 vUv; out vec4 outColor;
+uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
+        uniforms: { uTex: { value: mrt.texture[0] } },
+        depthTest: false,
+        depthWrite: false,
+      });
+      scene2 = new THREE.Scene();
+      cam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+      quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), mat);
+      quad.frustumCulled = false;
+      scene2.add(quad);
+      renderer.setRenderTarget(mrt);
+      renderer.render(scene2, cam);
+      quad.material = copy;
+      renderer.setRenderTarget(out);
+      renderer.render(scene2, cam);
+      const px = new Uint8Array(4);
+      renderer.readRenderTargetPixels(out, 0, 0, 1, 1, px);
+      // 0.5 -> ~128; accept a generous tolerance (fp16 + dithering).
+      return Math.abs(px[0] - 128) < 24 && Math.abs(px[1] - 64) < 24;
+    } catch {
+      return false;
+    } finally {
+      renderer.setRenderTarget(prevTarget);
+      if (quad) quad.geometry.dispose();
+      if (mat) mat.dispose();
+      if (copy) copy.dispose();
+      if (mrt) mrt.dispose();
+      if (out) out.dispose();
+    }
+  }
+
   /**
    * Companion settings for a given lighting resolution. LOW resolution wants
    * MORE denoise passes, not fewer — the filter runs at lighting res so extra
@@ -325,8 +392,22 @@ export class RealtimeRaytracer {
     if (!mixedPrecision) {
       console.info("three-realtime-rt: mixed fp16/fp32 G-buffer not supported here — using fp32 for all targets.");
     }
+    // Functional probe, not just a status check: WebKit (all iOS browsers)
+    // reports the 2-attachment fp16 MRT complete but silently renders black,
+    // which blanks the whole lighting pass. On such devices the lighting pass
+    // runs single-attachment (0.3.x layout): the specular buffer is disabled
+    // and blend surfaces degrade to opaque — everything else keeps working.
+    this.specMRTSupported = RealtimeRaytracer._specMrtSupported(renderer);
+    if (!this.specMRTSupported) {
+      console.info(
+        "three-realtime-rt: multi-attachment lighting buffer failed the draw probe here " +
+          "(WebKit/iOS) — specular buffer disabled, alpha-blend surfaces render opaque."
+      );
+    }
     this.gbuffer = new GBufferPass(this._width, this._height, { mixedPrecision });
-    this.rtPass = new RTLightingPass(this._scaledW, this._scaledH);
+    this.rtPass = new RTLightingPass(this._scaledW, this._scaledH, {
+      specMRT: this.specMRTSupported,
+    });
     this.denoisePass = new DenoisePass(this._scaledW, this._scaledH);
     // Separate à-trous instance for the specular buffer (its own ping-pong
     // targets, so the specular denoise cannot clobber the irradiance result).
@@ -343,8 +424,15 @@ export class RealtimeRaytracer {
     this.compiled = null;
     this.frame = 0;
 
-    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive */
+    /** 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;
@@ -472,6 +560,13 @@ export class RealtimeRaytracer {
     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
@@ -502,6 +597,22 @@ export class RealtimeRaytracer {
     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,
@@ -623,6 +734,7 @@ export class RealtimeRaytracer {
     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;
   }
@@ -648,6 +760,7 @@ export class RealtimeRaytracer {
     this.rtPass.setCompiledScene(this.compiled);
     this.volumetricPass.setCompiledScene(this.compiled);
     this.restirPass.setCompiledScene(this.compiled);
+    this.giReservoirPass.setCompiledScene(this.compiled);
   }
 
   resetAccumulation() {
@@ -751,6 +864,11 @@ export class RealtimeRaytracer {
       // 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
@@ -896,8 +1014,15 @@ export class RealtimeRaytracer {
     // 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
@@ -919,6 +1044,7 @@ export class RealtimeRaytracer {
       this.rtPass.clearHistory(this.renderer);
       this.volumetricPass.clearHistory(this.renderer);
       this.restirPass.clearHistory(this.renderer);
+      this.giReservoirPass.clearHistory(this.renderer);
       this._needsClear = false;
     }
 
@@ -930,11 +1056,28 @@ export class RealtimeRaytracer {
     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;
@@ -968,17 +1111,53 @@ export class RealtimeRaytracer {
         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
       );
     }
 
@@ -1099,6 +1278,7 @@ export class RealtimeRaytracer {
     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 (