three-realtime-rt 0.4.2 → 0.5.0

package/README.md

@@ -182,6 +182,35 @@ Lighting is traced at half resolution by default and reconstructed by a joint
 bilateral upsample + the denoiser + TAA — the same "render few pixels, rebuild
 temporally" idea DLSS uses, done with hand-written math.
 
+### Debug views
+
+Set `rt.outputMode` (the demo's **view** dropdown) to inspect a single stage
+instead of the composited image:
+
+| Mode | View | Shows |
+|------|------|-------|
+| `0` | composite | Final tonemapped image (default). |
+| `1` | albedo | G-buffer base colour. |
+| `2` | normals | World-space normals, `×0.5 + 0.5`. |
+| `3` | irradiance | Demodulated diffuse lighting (direct + GI), pre-albedo. |
+| `4` | world pos | World position, `fract(p × 0.1)`. |
+| `5` | emissive | G-buffer emissive. |
+| `6` | specular | The dielectric specular buffer. |
+| `7` | **bvh cost** | Heatmap of how many BVH nodes this pixel's shadow rays visit. |
+
+**Reading the BVH-cost heatmap.** Mode 7 counts, per pixel, the total BVH nodes
+visited by every shadow ray the lighting pass casts that frame (the ReSTIR
+winner / stochastic / per-light rays, plus reflection and glass occlusion rays),
+and maps the count through a cold→hot palette: **blue is cheap** (few boxes),
+through green and yellow, to **red and white for the most expensive** pixels. Hot
+regions mean many box tests per shadow ray — dense or overlapping geometry, long
+thin triangles whose bounding boxes overlap wastefully, or rays skimming almost
+parallel to a surface (they thread a long corridor of the tree before they
+either hit or escape). It bypasses temporal blending and the denoiser, so it is a
+raw per-frame snapshot. `rt.costScale` sets the mapping (default `1/96`, so ~96
+visits saturate to white); the demo's **cost scale** slider drives it as
+"visits-to-saturate" so you can rescale the range to your scene.
+
 ## Moving objects (dynamic BVH)
 
 Mark meshes as dynamic and their motion casts **correct ray traced shadows** —
@@ -242,6 +271,48 @@ water plane) is O(dynamic tris) too — so **keep deforming meshes low-poly**. A
 `256×256` plane (~131k tris) will dominate the frame. The demo's mirror-water
 pool is a `48×48` plane.
 
+### Skinned meshes (animated characters)
+
+A `SkinnedMesh` is **auto-detected** — just list it in `dynamicMeshes` (no
+`userData` flag) and it is CPU-skinned into the dynamic BVH every frame, so an
+animated character casts a **traced shadow that moves with its gait** and
+rasterizes in its animated pose (not bind pose) in the G-buffer:
+
+```js
+rt.compileScene(scene, { dynamicMeshes: [...crates, foxMesh] }); // foxMesh.isSkinnedMesh
+
+// each frame:
+mixer.update(dt);                 // advance the AnimationMixer
+foxRoot.updateMatrixWorld(true);  // pose the skeleton (bones -> world matrices) NOW
+rt.updateDynamic();               // CPU-skins the live pose into the BVH
+rt.render(scene, camera);
+```
+
+- **Skin the pose before `updateDynamic()`.** The CPU skinning reads each bone's
+  `matrixWorld` (via three's `SkinnedMesh.applyBoneTransform` / `getVertexPosition`,
+  which apply the bind matrix, bone weights and bone matrices), so the skeleton
+  must be posed for this frame first. `mixer.update(dt)` then a forced
+  `updateMatrixWorld` on the character root does that — otherwise the traced
+  shadow lags the raster by a frame. (three r160's `applyBoneTransform` returns
+  the vertex in the mesh's **local/bind-relative** space; the tracer applies
+  `matrixWorld` itself, exactly like a rigid mover.)
+- **Two sampler-friendly shortcuts.** Skinning is done for the mesh's *unique*
+  source vertices once per frame (shared triangle-soup slots reuse the result),
+  and secondary-ray **normals are per-face** — recomputed from the skinned
+  triangle positions rather than CPU-skinning the normal attribute. Flat-shaded
+  secondary rays are indistinguishable for shadows/GI, and **primary visibility
+  still gets smooth normals from the raster path** (the G-buffer skins the normal
+  properly via three's own `skinnormal_vertex` chunk). If your character's
+  geometry ships without a `normal` attribute (some glTF do — e.g. the Khronos
+  Fox), call `geometry.computeVertexNormals()` once after load so the raster path
+  has bind-pose normals to skin.
+
+**Cost model.** CPU skinning is O(source verts × 4 bones) with zero per-vertex
+allocation, plus the usual O(dynamic tris) BVH refit and normal upload. Budget
+~**10–20k total skinned source vertices to stay sub-2 ms**; the demo's Fox is
+≈ 1.7k source verts and skins in ≈ 0.3 ms. As with any dynamic mesh, keep the
+skinned tris low and there is no static-world cost.
+
 ## Live lighting & sky
 
 Lights can be toggled, moved, and recoloured every frame without recompiling:
@@ -281,9 +352,11 @@ the honest map of what actually feeds the traced lighting.
 
 ### Materials
 
-Lighting reads the **first material only** on a multi-material mesh, pulling the
-scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lambert
-/ Phong contribute whatever of those fields they have).
+Lighting reads the scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial`
+(Basic / Lambert / Phong contribute whatever of those fields they have). A
+**multi-material mesh** (`mesh.material` is an array + `geometry.groups`) now feeds
+**every group's** material into both the G-buffer and the BVH (see the *2nd+
+material of a group* row).
 
 | Property | Feeds lighting? | Notes |
 |----------|-----------------|-------|
@@ -299,10 +372,10 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | `roughnessMap` | ✅ | `roughness × roughnessMap.g` (three.js convention) — sampled in the G-buffer. |
 | `metalnessMap` | ✅ | `metalness × metalnessMap.b` (a packed ORM texture works — G = roughness, B = metalness). |
 | `normalMap` | ✅ | Perturbs the shading normal via a screen-space cotangent frame (no tangent attribute needed); respects `material.normalScale`. |
-| `clearcoat`, `sheen`, `iridescence` | ❌ | Not modelled. |
-| vertex colors | ❌ | Not read into albedo. |
-| per-material `ior` | ❌ | Refraction uses the single **global** `rt.ior` (default 1.5), never `material.ior`. |
-| 2nd+ material of a group | ❌ | Only `material[0]` of a multi-material mesh reaches the G-buffer and BVH. |
+| `clearcoat`, `sheen`, `iridescence` | ❌ | Per-pixel lobe parameters have **no remaining G-buffer channel** — the 4-MRT WebGL2 guarantee is fully packed (see the `GBufferPass` layout comment), so these stay unmodelled rather than risk corrupting the packing; revisit if a WebGPU backend lands. |
+| vertex colors | ✅ | Geometry `color` attribute (3- or 4-component; `.rgb` used) multiplies into G-buffer albedo, gated so meshes without one render byte-identically. **Caveat:** secondary GI/reflection rays see the flat `material.color` (same as texture maps). |
+| per-material `ior` | ✅ | `MeshPhysicalMaterial.ior` refracts per material, encoded in the packed material word for fully-transmissive glass. Supported range **[1.0, 1.98]** (values clamp; the tight ceiling keeps the packed word clear of the alpha-blend boundary). `rt.ior` is the global fallback (partial-transmission glass + the default); **`material.ior` wins when present**. |
+| 2nd+ material of a group | ✅ | Each group material of a multi-material mesh (`mesh.material` array + `geometry.groups`) is registered separately in the G-buffer **and** the BVH, with per-vertex material indices; emissive group materials also join the NEE area-light list. **Limits:** opaque groups only (a transparent group throws — split it out); not supported on CPU-deforming (`rtDeforming`) meshes (throws). |
 
 ### Lights
 
@@ -339,7 +412,7 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 
 - **1-bounce GI + direct light.** No multi-bounce diffuse, no caustics, no specular-chain paths.
 - **Reflections** are a single traced bounce into a **diffuse-shaded** view of the world — no recursive mirror-in-mirror; a metal shows its surroundings, not a second full render.
-- **Refraction** is two-interface (front + back) with a single global IOR — convincing glass, not a spectral / dispersive renderer.
+- **Refraction** is two-interface (front + back). IOR is **per material** (`MeshPhysicalMaterial.ior`, encoded in the G-buffer for fully-transmissive glass, range [1.0, 1.98]); `rt.ior` is the global fallback. Convincing glass, not a spectral / dispersive renderer.
 - **Volumetric** is **single-scatter** god rays, not multiple-scattering fog.
 - **Transparency** is a **single-layer deferred blend**: a `transparent` surface writes as the nearest layer of the G-buffer and the lighting pass composites it over the geometry behind by tracing one straight-through ray. The behind-radiance is fully lit (direct + 1-bounce GI) and tinted by the pane's albedo. Overlapping transparent surfaces do **not** inter-sort (only the nearest is kept), and there is no per-pixel back-to-front over-blend of many layers as in raster three.js. Turn it off with `transparency: false` (blend surfaces then render fully opaque).
 
@@ -367,12 +440,14 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | `refraction` | `true` | Traced two-interface refraction for `MeshPhysicalMaterial.transmission` surfaces. |
 | `transparency` | `true` | Alpha-blended transparency: composite `transparent` meshes over the geometry behind them (single-layer, weighted by `opacity`, tinted by albedo). Needs the specular buffer (`specular: true`). Off = they render fully opaque. |
 | `restir` | `true` | ReSTIR direct lighting: per-pixel reservoirs with temporal + spatial reuse, one visibility ray regardless of light count. Flat cost in light count; cuts emissive area-light noise. |
-| `ior` | `1.5` | Index of refraction used by `refraction`. |
+| `restirGI` | `false` | **Experimental.** ReSTIR GI (v1, temporal-only): per-pixel reservoirs reuse the 1-bounce indirect sample across frames at the reprojected same-surface point (no spatial reuse). Runs in a standalone pass with its own sampler budget; the lighting pass then skips its inline GI trace and the resolved GI is added at the à-trous denoise stage — so it only takes effect when `gi` **and** `denoise` are also on. Its mean matches the inline GI path; convergence character differs. `restirGIMCap` (default `20`) tunes the temporal M-cap. |
+| `ior` | `1.5` | **Global fallback** index of refraction for `refraction`. A `MeshPhysicalMaterial.ior` overrides it per material (fully-transmissive glass, range [1.0, 1.98]); this value applies to partial-transmission glass and as the default. |
 | `volumetric` | *off* | Physically-based god rays: single-scatter fog, one BVH-shadowed light sample per lighting pixel per frame, temporally accumulated. `{ enabled, density, maxDist, zones }`, where `zones` is an optional array of up to 8 AABBs `{ min:[x,y,z], max:[x,y,z], density }` that add localized fog on top of (or instead of) the global `density`. |
 | `stochasticLights` | `true` | One direct shadow ray per pixel per frame (random source) instead of one per light. The governor turns it off once it has scaled resolution up on strong hardware. |
 | `temporalReprojection` | `true` | Keep samples across camera/object motion. |
 | `maxHistory` | `128` | History cap — higher is smoother, slower to react. |
 | `fireflyClamp` | `4.0` | Clamp on indirect luminance to suppress fireflies. |
+| `costScale` | `1/96` | BVH-cost heatmap scale for the `outputMode: 7` debug view (shadow-ray node-visit count × this, mapped through a cold→hot palette). See *Debug views*. |
 | `sky` | *off* | Procedural sky as background + GI ambient (see above). |
 | `fog` | *off* | Distance fog, composited before tonemap. |
 
@@ -528,6 +603,69 @@ JSON line to the console every 2s for automated scraping. The overscan control
 is **feature-detected** — it appears only when the loaded build exposes an
 `overscan` property.
 
+## Render self-test
+
+The renderer can pass every compile and framebuffer check and still draw a black
+screen — that is exactly what shipped in 0.4.0 on iOS (WebKit's GLSL-to-Metal
+translation silently broke at a 4th `traceRadiance` call site; clean compile, no
+console error, black output). The only defence against that class of failure is
+to **look at the pixels**, so the demo has a headless-friendly self-test.
+
+**In the browser:** load [`/?selftest=1`](examples/selftest.js). It forces the
+full lighting stack on (GI + emissive NEE + reflections + refraction, lighting at
+50%), renders the normal gallery scene, and after **90 rendered frames** reads
+the drawing buffer back and emits one JSON line to the console (`[selftest] …`)
+and into a hidden `#selftest-verdict` DOM node:
+
+```json
+{ "pass": true, "meanLum": 139.08, "irrLum": 169.73, "glErrors": 0,
+  "specMRT": true, "supported": true, "frames": 91, "ua": "…" }
+```
+
+The pass gate wants `meanLum` in `[12, 230]` (calibrated: a healthy composite of
+the gallery centre reads ~140 on desktop; a black screen reads ~0), `irrLum > 6`,
+`glErrors == 0` and `supported == true`.
+
+- `meanLum` / `irrLum` — mean Rec.709 luma (0–255) of the **centre 25%** of the
+  composite, and of the raw irradiance buffer (`outputMode 3`) for one frame. The
+  irradiance readback proves the **lighting** is alive, not just emissive geometry
+  surviving the composite (0.4.0's black image still showed emitters). A near-zero
+  reading is the black-screen class; the pass gate wants a lit mid-range value.
+- `glErrors` — count of nonzero `gl.getError()` samples (any nonzero fails).
+- `specMRT` / `supported` — the two capability fallbacks, for triage.
+
+The page keeps rendering after the verdict so a human can watch. This mode builds
+the renderer with `preserveDrawingBuffer: true` so the canvas can be read back;
+normal runs keep the cheaper default.
+
+**In CI:** `npm run test:render` ([`scripts/selftest.mjs`](scripts/selftest.mjs))
+starts vite on a free port and drives `?selftest=1` through Playwright across
+**chromium, firefox and webkit**, printing a pass/fail/skip table and exiting
+nonzero on any real failure (a documented environmental *skip* does not fail the
+suite). Playwright is loaded from a sibling checkout — see the top of the script.
+
+Machine-specific note (Windows + NVIDIA, the current dev box): the chromium leg
+runs **headed** with **`--use-angle=gl`**. ANGLE's default D3D11/FXC backend
+never finishes compiling the BVH megakernel here — headless chromium,
+headed+`--use-angle=d3d11` and system Chrome all freeze at ~3 frames with silent
+`VALIDATE_STATUS=false` storms — whereas the native NVIDIA GL backend compiles
+it in ~137ms. A visible chromium window on the desktop during the run is
+expected. On this box **firefox** and **webkit** come back `skip`: firefox
+renders through that same stalling ANGLE-D3D11 backend and exposes no native-GL
+switch, and Playwright's Windows webkit has no usable WebGL2 (context lost). Both
+would actually run on a real-GPU Linux runner with native GL; only chromium is
+required to pass here.
+
+**What this catches, and what it does not.** The matrix catches API / JavaScript
+/ GLSL-frontend divergence between engines, and any regression that blackens or
+errors the image on the engines it runs. It does **not** catch the original iOS
+bug: Playwright's `webkit` on Windows is the WPE/GTK WebKit build, **not Apple's
+Metal stack**, so it never exercises the GLSL-to-Metal code generator that
+actually failed. **Real-device iOS testing stays manual.** The field kit for that
+is on-device URL flags: `?diag=1` mirrors console errors onto the page (so a
+photo of an iPad is a usable bug report) and `?nospecmrt=1` forces the
+single-attachment WebKit fallback on any machine.
+
 ## Roadmap
 
 | Stage | Status | What |
@@ -543,7 +681,10 @@ is **feature-detected** — it appears only when the loaded build exposes an
 | 6b. Sampling | ✅ | Blue-noise sampling + ReSTIR direct lighting (temporal + spatial reuse) |
 | 6c. Any-hit shadows | ✅ | Unordered early-out BVH traversal for occlusion rays — same image, up to ~2× cheaper shadows |
 | 6d. PBR materials | ✅ | Cook-Torrance GGX dielectric specular + normal/roughness/metalness maps, alpha-blended transparency, deforming (water) meshes, overscan |
-| 7. Next | — | Skinned-mesh (animated) shadows; DDGI irradiance probes; ReSTIR GI (indirect reservoir reuse); WGSL / WebGPU backend; per-material IOR |
+| 6e. Skinned meshes | ✅ | Animated characters CPU-skinned into the dynamic BVH — moving traced shadows + animated raster pose |
+| 6f. Material completeness | ✅ | Vertex colors, per-material IOR, multi-material groups (clearcoat/sheen/iridescence documented as out of G-buffer budget) |
+| 6g. ReSTIR GI | 🧪 | **Experimental** (`restirGI`, off by default): temporal-only reservoir reuse of the 1-bounce indirect sample (v1 — no spatial reuse yet) |
+| 7. Next | — | DDGI irradiance probes; ReSTIR GI **spatial** reuse + sample validation; WGSL / WebGPU backend |
 
 ## Credits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-realtime-rt",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Turn-on ray traced lighting for three.js: a hybrid deferred renderer with BVH-traced soft shadows, one-bounce global illumination, temporal reprojection, an a-trous denoiser and TAA.",
   "type": "module",
   "main": "src/index.js",
@@ -17,6 +17,7 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "test:render": "node scripts/selftest.mjs",
     "deploy": "vite build && gh-pages -d dist -t"
   },
   "keywords": [

package/src/CompositePass.js

@@ -30,7 +30,9 @@ uniform vec2 uVolTexelSize;
 uniform bool uVolEnabled;
 uniform vec3 uBackgroundColor;
 // 0 composite, 1 albedo, 2 normal, 3 irradiance (direct+GI), 4 worldPos,
-// 5 emissive, 6 specular
+// 5 emissive, 6 specular, 7 bvh cost (heatmap of shadow-ray node visits — the
+// lighting pass wrote the palette into the irradiance buffer, so it shares the
+// mode-3 display path)
 uniform int uOutputMode;
 
 // joint bilateral upsample (lighting may be rendered below full resolution)
@@ -177,7 +179,9 @@ void main() {
 
   if (uOutputMode == 1) color = albedoRough.rgb;
   else if (uOutputMode == 2) color = N * 0.5 + 0.5;
-  else if (uOutputMode == 3) color = irradiance;
+  // 3 = irradiance, 7 = bvh cost heatmap: both live in the irradiance buffer
+  // (the lighting pass wrote the cost palette there when uCostView was on).
+  else if (uOutputMode == 3 || uOutputMode == 7) color = irradiance;
   else if (uOutputMode == 4) color = fract(wp.xyz * 0.1);
   else if (uOutputMode == 5) color = emissive;
   else if (uOutputMode == 6) color = specular;

package/src/DenoisePass.js

@@ -25,12 +25,29 @@ uniform float uEps;
 uniform float uLumSigma;
 uniform bool uBlendIsSpec;       // this instance filters the specular buffer
 
+// Optional additive input (EXPERIMENTAL ReSTIR GI): when uHasAdd is set, this
+// texture's rgb is ADDED to every irradiance tap so the à-trous filter smooths
+// the sum (the GI is injected here, downstream of the lighting pass's own
+// temporal history, so it never double-counts through that history). The add is
+// gated to the FIRST iteration by the caller (uStep == 1) — later iterations
+// read the already-summed result. When uHasAdd is false this is byte-identical
+// to the original filter (the alpha/history-count channel is never touched).
+uniform sampler2D uAddTex;
+uniform bool uHasAdd;
+
 float luminance(vec3 c) {
   return dot(c, vec3(0.299, 0.587, 0.114));
 }
 
+// Irradiance tap with the optional GI add folded into rgb (alpha untouched).
+vec4 sampleIrr(vec2 uv) {
+  vec4 c = texture(uIrradiance, uv);
+  if (uHasAdd) c.rgb += texture(uAddTex, uv).rgb;
+  return c;
+}
+
 void main() {
-  vec4 center = texture(uIrradiance, vUv);
+  vec4 center = sampleIrr(vUv);
   vec4 wp = texture(uGWorldPos, vUv);
   if (wp.w < 0.5) {
     outColor = center;
@@ -82,7 +99,7 @@ void main() {
         vec2 tuv = vUv + vec2(float(dx), float(dy)) * uTexelSize;
         if (tuv.x < 0.0 || tuv.x > 1.0 || tuv.y < 0.0 || tuv.y > 1.0) continue;
         if (texture(uGWorldPos, tuv).w < 0.5) continue;
-        maxL = max(maxL, luminance(texture(uIrradiance, tuv).rgb));
+        maxL = max(maxL, luminance(sampleIrr(tuv).rgb));
         found = 1.0;
       }
     }
@@ -104,7 +121,7 @@ void main() {
 
       vec4 g = texture(uGWorldPos, tuv);
       if (g.w < 0.5) continue;
-      vec4 s = texture(uIrradiance, tuv);
+      vec4 s = sampleIrr(tuv);
       vec3 Nt = normalize(texture(uGNormalMetal, tuv).xyz);
 
       float k = (dx == 0 || dy == 0) ? 2.0 : 1.0;
@@ -154,6 +171,8 @@ export class DenoisePass {
         uEps: { value: 1e-3 },
         uLumSigma: { value: 0.25 },
         uBlendIsSpec: { value: blendIsSpec },
+        uAddTex: { value: null },
+        uHasAdd: { value: false },
       },
       depthTest: false,
       depthWrite: false,
@@ -189,20 +208,29 @@ export class DenoisePass {
     this.targetB.setSize(width, height);
   }
 
-  /** Runs `iterations` à-trous passes; returns the final filtered texture. */
-  render(renderer, inputTexture, gbuffer, cameraPos, eps, iterations = 3) {
+  /**
+   * Runs `iterations` à-trous passes; returns the final filtered texture.
+   * `addTexture` (EXPERIMENTAL ReSTIR GI) is added to the input on the FIRST
+   * iteration only, so the filter smooths input + GI together; pass null to
+   * leave the filter byte-identical to before.
+   */
+  render(renderer, inputTexture, gbuffer, cameraPos, eps, iterations = 3, addTexture = null) {
     const u = this.material.uniforms;
     u.uGWorldPos.value = gbuffer.worldPos;
     u.uGNormalMetal.value = gbuffer.normalMetal;
     u.uTexelSize.value.set(1 / this._width, 1 / this._height);
     u.uCameraPos.value.copy(cameraPos);
     u.uEps.value = eps;
+    u.uAddTex.value = addTexture;
 
     let read = inputTexture;
     let write = this.targetA;
     for (let i = 0; i < iterations; i++) {
       u.uIrradiance.value = read;
       u.uStep.value = 1 << i;
+      // The GI add is applied once, on iteration 0 — later iterations read the
+      // already-summed intermediate, so adding again would double it.
+      u.uHasAdd.value = addTexture !== null && i === 0;
       renderer.setRenderTarget(write);
       renderer.render(this.scene, this.camera);
       read = write.texture;

package/src/GBufferPass.js

@@ -1,17 +1,50 @@
 import * as THREE from "three";
 
+// three defines USE_SKINNING and supplies the bindMatrix / bindMatrixInverse /
+// boneTexture uniforms + skinIndex / skinWeight attributes automatically when the
+// rendered object is a SkinnedMesh (this is a ShaderMaterial, not a
+// RawShaderMaterial, so it inherits three's default vertex prefix and #include
+// resolution). For a non-skinned mesh USE_SKINNING is undefined and every chunk
+// below collapses to nothing — the shader source is identical in both cases.
+// The chunks operate on `transformed` (position) and `objectNormal` (normal) in
+// the mesh's LOCAL/bind space, so we map our own variables in and out. The
+// skinned local position/normal then go through modelMatrix / uNormalMatrixWorld
+// exactly like the un-skinned path — matching the CPU BVH skinning in
+// SceneCompiler (both skin to local, then transform to world).
 const gbufferVert = /* glsl */ `
+#include <skinning_pars_vertex>
+
 out vec3 vWorldPos;
 out vec3 vWorldNormal;
 out vec2 vUvCoord;
+out vec3 vColor;
 
 uniform mat3 uNormalMatrixWorld;
 
 void main() {
-  vec4 wp = modelMatrix * vec4(position, 1.0);
+  vec3 transformed = position;
+  vec3 objectNormal = normal;
+  #include <skinbase_vertex>
+  #include <skinnormal_vertex>
+  #include <skinning_vertex>
+
+  vec4 wp = modelMatrix * vec4(transformed, 1.0);
   vWorldPos = wp.xyz;
-  vWorldNormal = normalize(uNormalMatrixWorld * normal);
+  vWorldNormal = normalize(uNormalMatrixWorld * objectNormal);
   vUvCoord = uv;
+  // Geometry vertex colours. three's shader prefix declares the built-in
+  // \`color\` attribute (vec3 or vec4) and sets USE_COLOR / USE_COLOR_ALPHA only
+  // when material.vertexColors is on — which we enable ONLY for meshes whose
+  // geometry actually carries a color attribute (see GBufferPass swap). A mesh
+  // without one compiles the else branch (white), so its albedo is byte-identical
+  // to before this varying existed. 4-component colours use .rgb.
+  #if defined( USE_COLOR_ALPHA )
+    vColor = color.rgb;
+  #elif defined( USE_COLOR )
+    vColor = color;
+  #else
+    vColor = vec3(1.0);
+  #endif
   gl_Position = projectionMatrix * viewMatrix * wp;
 }
 `;
@@ -27,11 +60,13 @@ layout(location = 3) out vec4 gEmissive;
 in vec3 vWorldPos;
 in vec3 vWorldNormal;
 in vec2 vUvCoord;
+in vec3 vColor;
 
 uniform vec3 uColor;
 uniform float uRoughness;
 uniform float uMetalness;
 uniform float uTransmission;
+uniform float uIor;
 uniform vec3 uEmissive;
 uniform sampler2D uMap;
 uniform bool uHasMap;
@@ -69,6 +104,7 @@ void main() {
   if (uHasMap) {
     albedo *= texture(uMap, vUvCoord).rgb;
   }
+  albedo *= vColor; // vertex colours (white when the mesh has no color attribute)
   vec3 emissive = uEmissive;
   if (uHasEmissiveMap) {
     emissive *= texture(uEmissiveMap, vUvCoord).rgb;
@@ -87,16 +123,34 @@ void main() {
   float metalness = uMetalness;
   if (uHasMetalnessMap) metalness *= texture(uMetalnessMap, vUvCoord).b;
   gAlbedoRough = vec4(albedo, roughness);
-  // .w is a packed material word in three disjoint ranges, so the lighting pass
-  // reads specular/glass/blend properties without an extra G-buffer sampler (it
-  // already sits at the WebGL2 16-sampler minimum):
-  //   [0,1] plain metalness   [2,3] transmissive glass (w - 2 = transmission)
-  //   [4,5] alpha blend (w - 4 = opacity). Blend wins: a transparent surface is
-  // kept out of the BVH and composited by the lighting pass, so it must never be
-  // read as glass even if the material also carries a transmission value.
-  float matWord = uBlend
-    ? 4.0 + uOpacity
-    : (uTransmission > 0.0 ? 2.0 + uTransmission : metalness);
+  // .w is a packed material word in disjoint ranges, so the lighting pass reads
+  // specular/glass/blend properties without an extra G-buffer sampler (it already
+  // sits at the WebGL2 16-sampler minimum — the reason per-material IOR rides
+  // here rather than in a third G-buffer texture the lighting pass would have to
+  // sample):
+  //   [0,1] plain metalness
+  //   (2,3] transmissive glass, PARTIAL: w - 2 = transmission (global rt.ior)
+  //   [3,4) transmissive glass, FULL (transmission >= ~1): w - 3 = ior - 1
+  //   [4,5] alpha blend: w - 4 = opacity
+  // Blend wins: a transparent surface is kept out of the BVH and composited by
+  // the lighting pass, so it must never be read as glass. Every EXISTING consumer
+  // decodes clamp(w - 2, 0, 1) as transmission, which saturates to 1.0 across the
+  // whole [3,4) band — so full glass keeps reading as fully transmissive there and
+  // only the lighting pass additionally recovers the per-material IOR (Task 2).
+  float matWord;
+  if (uBlend) {
+    matWord = 4.0 + uOpacity;
+  } else if (uTransmission > 0.0) {
+    if (uTransmission >= 0.99) {
+      // clamp (ior - 1) to [0, 0.98] so the word stays clear of the 4.0 blend
+      // boundary even after fp16 rounding of this channel; covers ior 1.0-1.98.
+      matWord = 3.0 + clamp(uIor - 1.0, 0.0, 0.98);
+    } else {
+      matWord = 2.0 + uTransmission; // partial glass: keep transmission, global ior
+    }
+  } else {
+    matWord = metalness;
+  }
   gNormalMetal = vec4(n, matWord);
   // .w packs the valid flag AND roughness: 0 = background, 1 + roughness
   // otherwise. Every consumer only tests w < 0.5, so this stays compatible.
@@ -184,46 +238,54 @@ export class GBufferPass {
     for (const t of this._targets) t.setSize(width, height);
   }
 
-  _gbufferMaterialFor(mesh) {
-    let material = this._materialCache.get(mesh);
-    if (!material) {
-      material = new THREE.ShaderMaterial({
-        glslVersion: THREE.GLSL3,
-        vertexShader: gbufferVert,
-        fragmentShader: gbufferFrag,
-        uniforms: {
-          uNormalMatrixWorld: { value: new THREE.Matrix3() },
-          uColor: { value: new THREE.Color(1, 1, 1) },
-          uRoughness: { value: 1.0 },
-          uMetalness: { value: 0.0 },
-          uTransmission: { value: 0.0 },
-          uEmissive: { value: new THREE.Color(0, 0, 0) },
-          uMap: { value: null },
-          uHasMap: { value: false },
-          uEmissiveMap: { value: null },
-          uHasEmissiveMap: { value: false },
-          uNormalMap: { value: null },
-          uHasNormalMap: { value: false },
-          uNormalScale: { value: new THREE.Vector2(1, 1) },
-          uRoughnessMap: { value: null },
-          uHasRoughnessMap: { value: false },
-          uMetalnessMap: { value: null },
-          uHasMetalnessMap: { value: false },
-          uBlend: { value: false },
-          uOpacity: { value: 1.0 },
-        },
-        side: THREE.FrontSide,
-      });
-      this._materialCache.set(mesh, material);
-    }
+  _makeGbufferMaterial(mesh) {
+    const material = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      vertexShader: gbufferVert,
+      fragmentShader: gbufferFrag,
+      uniforms: {
+        uNormalMatrixWorld: { value: new THREE.Matrix3() },
+        uColor: { value: new THREE.Color(1, 1, 1) },
+        uRoughness: { value: 1.0 },
+        uMetalness: { value: 0.0 },
+        uTransmission: { value: 0.0 },
+        uIor: { value: 1.5 },
+        uEmissive: { value: new THREE.Color(0, 0, 0) },
+        uMap: { value: null },
+        uHasMap: { value: false },
+        uEmissiveMap: { value: null },
+        uHasEmissiveMap: { value: false },
+        uNormalMap: { value: null },
+        uHasNormalMap: { value: false },
+        uNormalScale: { value: new THREE.Vector2(1, 1) },
+        uRoughnessMap: { value: null },
+        uHasRoughnessMap: { value: false },
+        uMetalnessMap: { value: null },
+        uHasMetalnessMap: { value: false },
+        uBlend: { value: false },
+        uOpacity: { value: 1.0 },
+      },
+      side: THREE.FrontSide,
+    });
+    // Enable the vertex-colour path ONLY when this mesh's geometry carries a
+    // color attribute. This drives three's USE_COLOR define (see gbufferVert), so
+    // a mesh without one writes byte-identical albedo. The material cache is
+    // per-mesh, so this per-mesh define variant is safe.
+    material.vertexColors = !!(mesh.geometry && mesh.geometry.getAttribute("color"));
+    return material;
+  }
 
-    // Sync properties from the user's material every frame (cheap).
-    const src = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+  // Sync properties from one user material into one gbuffer material (cheap; run
+  // every frame). `mesh` supplies the shared world normal matrix + side.
+  _syncGbufferMaterial(material, src, mesh) {
     const u = material.uniforms;
     if (src.color) u.uColor.value.copy(src.color);
     u.uRoughness.value = src.roughness ?? 1.0;
     u.uMetalness.value = src.metalness ?? 0.0;
     u.uTransmission.value = src.transmission ?? 0.0; // MeshPhysicalMaterial
+    // Per-material IOR (MeshPhysicalMaterial.ior; default 1.5). Encoded into the
+    // packed material word for fully-transmissive glass (see gbufferFrag).
+    u.uIor.value = src.ior ?? 1.5;
 
     if (src.emissive) {
       u.uEmissive.value
@@ -249,6 +311,30 @@ export class GBufferPass {
     u.uOpacity.value = src.opacity ?? 1.0;
     u.uNormalMatrixWorld.value.getNormalMatrix(mesh.matrixWorld);
     material.side = src.side ?? THREE.FrontSide;
+  }
+
+  // Returns the gbuffer material(s) for a mesh: a single ShaderMaterial, or — for
+  // a multi-material mesh (mesh.material is an array + geometry.groups) — an ARRAY
+  // of them, one per source material, index-aligned so three renders each group
+  // with its own gbuffer material natively.
+  _gbufferMaterialFor(mesh) {
+    if (Array.isArray(mesh.material)) {
+      let cached = this._materialCache.get(mesh);
+      if (!Array.isArray(cached) || cached.length !== mesh.material.length) {
+        cached = mesh.material.map(() => this._makeGbufferMaterial(mesh));
+        this._materialCache.set(mesh, cached);
+      }
+      for (let i = 0; i < mesh.material.length; i++) {
+        this._syncGbufferMaterial(cached[i], mesh.material[i], mesh);
+      }
+      return cached;
+    }
+    let material = this._materialCache.get(mesh);
+    if (!material || Array.isArray(material)) {
+      material = this._makeGbufferMaterial(mesh);
+      this._materialCache.set(mesh, material);
+    }
+    this._syncGbufferMaterial(material, mesh.material, mesh);
     return material;
   }