three-realtime-rt 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goldwin Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,394 @@
+# three-realtime-rt
+
+**Turn-on ray traced lighting for three.js.** Build your scene with ordinary
+three.js — meshes, `MeshStandardMaterial`, `PointLight` / `DirectionalLight` —
+then swap one render call and get BVH-traced **soft shadows**, **one-bounce
+global illumination**, **emissive-mesh area lights**, **mirror/glossy
+reflections**, **glass refraction**, **volumetric god rays** (BVH-shadowed
+single scatter, not a screen-space trick), a **procedural sky** that lights
+the scene, **ReSTIR many-light sampling** (flat cost in light count),
+**blue-noise sampling**, and real-time **temporal denoising + anti-aliasing**.
+Runs on plain WebGL2.
+
+The library ships as **untranspiled ES modules** (the `src/` folder) — it has no
+build step of its own, so you consume it through your bundler (Vite, webpack,
+esbuild, …) or a browser import map that resolves the bare `three` /
+`three-mesh-bvh` specifiers. MIT licensed. **Not on npm yet** — until the first
+release lands, install straight from the Git repo (see [Getting started](#getting-started)).
+
+### ▶ [Live demo](https://goldwinxs.github.io/three-realtime-rt/) — drag to orbit, drop the pile, toggle every feature.
+
+> **Support this project:** the [supporter pack on itch.io](https://goldwinxs.itch.io/three-realtime-rt-supporter-pack) gets you a ready-to-run starter template, all example scenes, and a 12-section deep-dive guide to how the whole pipeline works. The library itself is and stays MIT.
+
+![Ray traced room: emissive area light, reflections, glass, volumetric haze](docs/hero.png)
+
+Same scene, same camera, same lights — plain three.js (shadow maps + ACES) on
+the left, `rt.render` on the right:
+
+| Rasterized three.js | three-realtime-rt |
+|---|---|
+| ![raster](docs/compare-raster.jpg) | ![ray traced](docs/compare-rt.jpg) |
+
+## Getting started
+
+Install the library plus its two **peer dependencies** — you bring your own copy
+of `three` and `three-mesh-bvh`:
+
+```bash
+npm i three-realtime-rt three three-mesh-bvh
+```
+
+> **Not published to npm yet.** Until the first release, install from the repo:
+> `npm i github:GoldwinXS/three-realtime-rt three three-mesh-bvh`
+
+No bundler? [`standalone.html`](standalone.html) is a single copy-paste file
+that runs the raytracer via CDN import maps — open it from any static server.
+
+A complete, copy-pasteable minimal app — a lit sphere on a floor, one point light:
+
+```js
+import * as THREE from "three";
+import { RealtimeRaytracer } from "three-realtime-rt";
+
+// 1. An ordinary three.js renderer. Size it BEFORE constructing the raytracer —
+//    it reads the drawing-buffer size at construction.
+const renderer = new THREE.WebGLRenderer({ antialias: false });
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.setSize(window.innerWidth, window.innerHeight);
+document.body.appendChild(renderer.domElement);
+
+// 2. An ordinary scene: meshes with MeshStandardMaterial + a real light.
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(
+  60, window.innerWidth / window.innerHeight, 0.1, 100
+);
+camera.position.set(0, 2, 6);
+
+scene.add(new THREE.Mesh(
+  new THREE.SphereGeometry(1, 48, 48),
+  new THREE.MeshStandardMaterial({ color: 0xdddddd, roughness: 0.4, metalness: 0.0 })
+));
+const floor = new THREE.Mesh(
+  new THREE.PlaneGeometry(20, 20),
+  new THREE.MeshStandardMaterial({ color: 0x808080, roughness: 1.0 })
+);
+floor.rotation.x = -Math.PI / 2;
+floor.position.y = -1;
+scene.add(floor);
+
+const light = new THREE.PointLight(0xffffff, 40);   // PointLight / DirectionalLight (up to 16)
+light.position.set(3, 5, 2);
+scene.add(light);
+
+// 3. Turn on ray tracing.
+const rt = new RealtimeRaytracer(renderer);
+rt.compileScene(scene);              // builds the BVH + material/light tables
+
+// 4. Resize: pass DRAWING-BUFFER (device) pixels, not CSS pixels.
+addEventListener("resize", () => {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  const db = renderer.getDrawingBufferSize(new THREE.Vector2());
+  rt.setSize(db.x, db.y);
+});
+
+// 5. Render loop — replace renderer.render(scene, camera) with rt.render.
+function loop() {
+  requestAnimationFrame(loop);
+  rt.render(scene, camera);
+}
+loop();
+```
+
+On hardware that can't trace, `rt.render` transparently falls back to
+`renderer.render` — no capability branch needed (see [Running everywhere](#running-everywhere-capability-tiers)).
+
+### Integrating into an existing app
+
+A checklist for dropping the tracer into a scene you already have:
+
+1. **Swap the render call** — `renderer.render(scene, camera)` →
+   `rt.render(scene, camera)`. Construct the `RealtimeRaytracer` once, *after*
+   the renderer has its final size.
+2. **Compile once; recompile after structural changes** — `rt.compileScene(scene)`
+   bakes geometry into a static BVH and snapshots materials + emissive area
+   lights. Call it again after you add/remove meshes, swap geometry, or change a
+   material's `emissive` / `color` / `roughness` / `metalness`.
+3. **Declare movers** — pass moving meshes to
+   `rt.compileScene(scene, { dynamicMeshes: [...] })`, then call
+   `rt.updateDynamic()` each frame after you move them (e.g. after a physics
+   step). Skip it on frames where nothing moved.
+4. **Update lights when they change** — after moving, toggling (`.visible`),
+   recolouring or dimming a light, call `rt.updateLights(scene)`. No recompile.
+5. **Resize** — in your resize handler, after `renderer.setSize(...)`, call
+   `rt.setSize(width, height)` with **drawing-buffer (device) pixels**
+   (`renderer.getDrawingBufferSize(...)`).
+6. **Reset after jumps** — call `rt.resetAccumulation()` after a camera teleport
+   or a scene cut, so stale temporal history doesn't ghost.
+
+That's the whole integration. Everything below is optional.
+
+---
+
+## Why "hybrid deferred" (the "RTX on" model)
+
+Primary visibility is **rasterized** by three.js into a G-buffer — free, fast,
+and pixel-perfect on materials and textures. Only the *lighting* is ray traced,
+in a fragment shader, against a GPU BVH ([three-mesh-bvh]):
+
+1. **G-buffer pass** — MRT: albedo+roughness, world normal+metalness, world
+   position, emissive.
+2. **RT lighting pass** — per pixel: soft shadow rays to each light (area
+   sampled) + a 1-bounce cosine-weighted GI ray with next-event estimation. GI
+   rays that escape sample the **procedural sky**, so the sky is a soft area
+   light. **Emissive meshes are real area lights**: their triangles are sampled
+   directly (NEE with the area→solid-angle pdf), so a glowing panel casts soft
+   light and shadows instead of waiting for a lucky GI ray to hit it. Metallic
+   pixels trace a **mirror/glossy reflection ray**; transmissive pixels trace a
+   Fresnel-weighted **reflection + two-interface refraction**. Output is
+   *demodulated irradiance* (albedo divided out) so it denoises cleanly while
+   textures stay sharp.
+3. **Temporal reprojection** — motion-validated history keeps samples alive as
+   the camera and objects move.
+4. **À-trous denoise** — an edge-avoiding (SVGF-lite) wavelet filter guided by
+   the G-buffer, so 1 sample/pixel looks converged.
+5. **Composite** — `albedo × irradiance + emissive`, distance fog, ACES tonemap.
+6. **TAA** — sub-pixel jitter + a neighbourhood-clamped history resolve:
+   supersampled anti-aliasing that also clears disocclusion speckles. This is
+   the analytic (FSR2 / TAAU) approach, not a learned upscaler.
+
+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.
+
+## Moving objects (dynamic BVH)
+
+Mark meshes as dynamic and their motion casts **correct ray traced shadows** —
+the demo drops 40 rigid bodies (Rapier physics) that shadow each other and the
+ground in real time:
+
+```js
+rt.compileScene(scene, { dynamicMeshes: crates });  // meshes that will move
+
+// each frame, after you move them (e.g. after a physics step):
+rt.updateDynamic();       // re-bakes them into the BVH (refit) — cheap
+rt.render(scene, camera);
+```
+
+Under the hood this is a **two-level BVH**: static geometry lives in one BVH
+uploaded to the GPU once at compile time, dynamic meshes in a second small BVH
+that is re-baked and refit per frame. `updateDynamic()` therefore costs
+~1 ms for dozens of moving objects *regardless of how big the static world is* —
+skip it entirely on frames where nothing moved.
+
+## Live lighting & sky
+
+Lights can be toggled, moved, and recoloured every frame without recompiling:
+
+```js
+warmLight.visible = false;      // or change .color / .intensity / .position
+rt.updateLights(scene);         // re-reads the scene's lights
+```
+
+The procedural sky doubles as the ambient light source:
+
+```js
+const rt = new RealtimeRaytracer(renderer, {
+  sky: {
+    enabled: true,
+    sunDir: new THREE.Vector3(0.55, 0.62, 0.55).normalize(), // toward the sun
+    sunColor: new THREE.Color(1.0, 0.92, 0.78),
+    zenith:   new THREE.Color(0.20, 0.40, 0.72),
+    horizon:  new THREE.Color(0.78, 0.85, 0.92),
+    intensity: 1.0,
+  },
+  fog: { enabled: true, color: new THREE.Color(0.72, 0.8, 0.88), density: 0.03 },
+});
+```
+
+![Physics: 40 rigid bodies with dynamic ray traced shadows](docs/physics.png)
+
+## What is and isn't supported
+
+Primary visibility is ordinary rasterized three.js, so **whatever three.js draws,
+you still see** — transparency, blending, sorting, custom shaders and post effects
+behave exactly as normal. The ray tracer computes only the *lighting*, and it
+reads a deliberately small, fixed slice of the material and light model. This is
+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).
+
+| Property | Feeds lighting? | Notes |
+|----------|-----------------|-------|
+| `color` + `map` | ✅ | Albedo = `color × map.rgb`. Textures stay sharp (irradiance is demodulated, then re-multiplied). |
+| `roughness` | ✅ | **Scalar only.** Drives shadow / GI softness and reflection sharpness. |
+| `metalness` | ✅ | **Scalar only.** Metallic pixels trace a reflection ray. |
+| `emissive` | ✅ | A *static* emissive mesh becomes a real **area light** (NEE) — casts soft light + shadows. |
+| `emissiveMap` | ⚠️ visible only | A map-masked emissive **glows on screen** but the map **zeroes its area-light table** — it lights nothing. Use a flat `emissive` colour (no map) for an emitter that should illuminate. |
+| `transmission` (Physical) | ✅ | Glass: Fresnel reflection + two-interface refraction. |
+| `roughnessMap` / `metalnessMap` | ❌ | Only the scalar `roughness` / `metalness` are used; these maps are ignored by lighting. |
+| `normalMap` | ❌ | Lighting uses geometric normals; normal maps don't perturb shading. |
+| `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. |
+
+### Lights
+
+| Light | Supported | Notes |
+|-------|-----------|-------|
+| `PointLight` | ✅ | `light.userData.rtRadius` (default `0.15`) sets soft-shadow size. |
+| `DirectionalLight` | ✅ | `light.userData.rtRadius` (default `0.02`) sets sun softness; keep its direction in sync with `sky.sunDir`. |
+| Emissive meshes | ✅ static | Sampled directly as area lights. **Dynamic** emitters are *not* in the NEE list — they light only via GI-ray hits. |
+| `SpotLight` | ❌ | Ignored. |
+| `RectAreaLight` | ❌ | Use an emissive mesh instead. |
+| `HemisphereLight` / `AmbientLight` | ❌ | Ignored — the procedural `sky` (or `envColor`) provides ambient. |
+
+- Up to **16** point/directional lights (`MAX_LIGHTS`); further lights are dropped.
+- Moving, toggling, recolouring or dimming a light → `rt.updateLights(scene)` (cheap, no recompile).
+- Changing a mesh's **emissive** (it's an area light baked at compile time) → `rt.compileScene(...)` again.
+- Emissive area lights are capped at **256 triangles** (largest by area kept, with a console warning) — prefer low-poly emitter meshes.
+
+### Geometry & occlusion
+
+- Every non-excluded visible mesh is **merged into one static BVH at compile time**. Add / remove geometry → recompile.
+- Meshes that move must be declared via `dynamicMeshes` and driven with `updateDynamic()`. Anything not declared is treated as static — moving it on screen won't move its traced shadow.
+- **Transparent materials never occlude** (by design — a glass case shouldn't cast an opaque shadow). They still rasterize normally.
+- **`alphaTest` cut-outs** (`transparent: false`) *do* occlude — but as **full triangles**, not per-texel, so their shadows are blocky.
+- `mesh.userData.rtExclude = true` removes a mesh from the BVH entirely (it still rasterizes and gets lit) — handy for water / translucent surfaces.
+
+### Rendering model
+
+- **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.
+- **Volumetric** is **single-scatter** god rays, not multiple-scattering fog.
+- Because primary visibility is rasterized, **blending, sorting and transparency composite exactly like normal three.js** — the tracer never changes how your transparent surfaces layer.
+
+### Platform
+
+- Requires **WebGL2 + `EXT_color_buffer_float`**. Software rasterizers (SwiftShader / llvmpipe) are treated as unsupported.
+- On anything unsupported, `rt.supported === false` and `rt.render()` **falls back to `renderer.render()`** after one console warning — your app still runs everywhere. Branch yourself with `rt.supported` or `RealtimeRaytracer.isSupported(renderer)` if you want.
+- WebGL2 only; no WebGPU backend (on the roadmap).
+
+## Options
+
+| Option | Default | What |
+|--------|---------|------|
+| `renderScale` | `0.5` | Lighting resolution vs. the G-buffer. `1.0` = max quality. |
+| `taa` | `true` | Temporal anti-aliasing (jitter + neighbourhood clamp). |
+| `denoise` | `true` | Edge-aware à-trous denoiser. |
+| `gi` | `true` | 1-bounce global illumination (vs. direct-only). |
+| `emissiveNEE` | `true` | Sample static emissive meshes as area lights (next-event estimation). Off = emitters only light via lucky GI rays. |
+| `reflections` | `true` | Traced mirror/glossy reflections on metallic surfaces (sharpest at `renderScale: 1`). |
+| `refraction` | `true` | Traced two-interface refraction for `MeshPhysicalMaterial.transmission` surfaces. |
+| `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`. |
+| `volumetric` | *off* | Physically-based god rays: single-scatter fog, one BVH-shadowed light sample per lighting pixel per frame, temporally accumulated. `{ enabled, density, maxDist }`. |
+| `stochasticLights` | `false` | One direct shadow ray per pixel per frame (random source) instead of one per light. |
+| `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. |
+| `sky` | *off* | Procedural sky as background + GI ambient (see above). |
+| `fog` | *off* | Distance fog, composited before tonemap. |
+
+Per-light: set `light.userData.rtRadius` for soft-shadow size. Set
+`mesh.userData.rtExclude = true` to keep a mesh out of the BVH (it still
+rasterizes and gets lit — useful for water / translucent surfaces).
+Transparent materials never act as occluders (a glass case shouldn't cast an
+opaque shadow); `alphaTest` cut-outs still do.
+
+## Running everywhere (capability tiers)
+
+Nothing adaptive is imposed — everything below is **opt-in**:
+
+- **No usable GPU** (missing WebGL2 float targets, or a software rasterizer
+  like SwiftShader): the library logs one console warning and `rt.render()`
+  silently falls back to plain `renderer.render()`. Your app runs everywhere
+  with zero capability checks; query `rt.supported` or the static
+  `RealtimeRaytracer.isSupported(renderer)` if you want to branch yourself.
+- **Tier presets**: `RealtimeRaytracer.detectTier(renderer)` returns
+  `"none" | "mid" | "high"`, and `recommendedOptions(tier)` gives matching
+  constructor options — spread them, then override what you like:
+
+  ```js
+  const tier = RealtimeRaytracer.detectTier(renderer);
+  const rt = new RealtimeRaytracer(renderer, {
+    ...RealtimeRaytracer.recommendedOptions(tier),
+    targetFps: 55,
+  });
+  ```
+
+- **Adaptive quality** (`adaptiveQuality: true`, default **false**): continuous
+  dynamic resolution scaling. Watches real frame time and steers the lighting
+  resolution smoothly toward `targetFps` (in 5% steps with a cooldown), pairing
+  low resolutions with MORE denoise passes (they run at lighting res, so
+  they're nearly free exactly where they're needed) and stochastic direct
+  light. While enabled it drives `renderScale` / `stochasticLights` /
+  `denoiseIterations`; turn it off for manual control.
+- **`stochasticLights: true`** (default false): one direct shadow ray per
+  pixel per frame instead of one per light — the biggest ray-count lever for
+  many-light scenes and mobile GPUs.
+
+WebGPU: not used as a backend (this is a WebGL2 library); a WGSL compute
+backend is on the roadmap.
+
+## Running the demo
+
+```bash
+npm install
+npm run dev       # http://localhost:8115
+```
+
+The demo ([`examples/`](examples/)) is an ordinary three.js app — see
+[`examples/main.js`](examples/main.js) for the full, commented integration
+(scene → physics → compile → render loop). `npm run deploy` builds and publishes
+it to GitHub Pages.
+
+## Gallery & benchmarks
+
+[`gallery.html`](gallery.html) drops the raytracer into **stock glTF scenes it
+was never authored for** — LittlestTokyo, Lantern, Antique Camera, BoomBox,
+Corset, Water Bottle, and the Damaged Helmet — streamed straight from their
+public hosts (no assets committed). A one-button toggle A/Bs ray tracing against
+plain rasterized three.js with an fps + triangle readout, and a compact options
+strip exposes GI / emissive NEE / reflections / refraction / ReSTIR / denoise /
+TAA / volumetric plus lighting-resolution and auto-quality controls.
+
+[`bench.html?autorun=1`](bench.html) runs a matrix of feature configs with
+GPU-**fence-timed** frame costs and a temporal **ghosting metric**, writing each
+run's results to [`bench-results/`](bench-results/) for tracking regressions.
+
+## Roadmap
+
+| Stage | Status | What |
+|-------|--------|------|
+| 1. Core | ✅ | Scene→GPU sync, BVH, G-buffer, traced shadows + 1-bounce GI, accumulation |
+| 2. Reprojection | ✅ | Motion-validated history — samples survive camera motion |
+| 3. Denoiser | ✅ | Edge-avoiding à-trous (SVGF-lite) → clean 1spp |
+| 4. TAA | ✅ | Sub-pixel jitter + neighbourhood-clamped resolve → AA, no speckles |
+| 4b. Sky | ✅ | Procedural sky as background + GI ambient light source |
+| 5. Two-level BVH | ✅ | Static BVH uploaded once; movers in a small per-frame BVH → dynamic shadows at ~1 ms |
+| 5b. Area lights | ✅ | Emissive meshes sampled directly (NEE) — glowing panels cast soft light + shadows |
+| 6. Specular | ✅ | Mirror/glossy reflections on metals + two-interface glass refraction |
+| 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 |
+| 7. Publish | — | npm publish; refractive water; per-material IOR |
+
+## Credits
+
+- [three-mesh-bvh] by Garrett Johnson — the GPU BVH this is built on.
+- Inspired by [Erich Loftis'][erichlof] `THREE.js-PathTracing-Renderer`.
+- Demo models: Khronos glTF sample assets (Damaged Helmet, Duck).
+
+## License
+
+MIT © Goldwin Stewart
+
+[three-mesh-bvh]: https://github.com/gkjohnson/three-mesh-bvh
+[erichlof]: https://github.com/erichlof/THREE.js-PathTracing-Renderer

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "three-realtime-rt",
+  "version": "0.3.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",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "deploy": "vite build && gh-pages -d dist -t"
+  },
+  "keywords": [
+    "three",
+    "threejs",
+    "raytracing",
+    "path-tracing",
+    "global-illumination",
+    "webgl",
+    "bvh",
+    "denoiser",
+    "taa",
+    "renderer"
+  ],
+  "homepage": "https://goldwinxs.github.io/three-realtime-rt/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GoldwinXS/three-realtime-rt.git"
+  },
+  "author": "Goldwin Stewart",
+  "license": "MIT",
+  "peerDependencies": {
+    "three": ">=0.155.0",
+    "three-mesh-bvh": ">=0.7.0"
+  },
+  "devDependencies": {
+    "@dimforge/rapier3d-compat": "^0.14.0",
+    "gh-pages": "^6.3.0",
+    "three": "^0.160.1",
+    "three-mesh-bvh": "^0.7.8",
+    "vite": "^5.0.11"
+  }
+}

package/src/CompositePass.js

@@ -0,0 +1,214 @@
+import * as THREE from "three";
+import { SKY_GLSL } from "./sky.glsl.js";
+
+const fullscreenVert = /* glsl */ `
+out vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+
+const compositeFrag = /* glsl */ `
+precision highp float;
+
+layout(location = 0) out vec4 outColor;
+
+in vec2 vUv;
+
+${SKY_GLSL}
+
+uniform sampler2D uIrradiance;
+uniform sampler2D uGAlbedoRough;
+uniform sampler2D uGNormalMetal;
+uniform sampler2D uGWorldPos;
+uniform sampler2D uGEmissive;
+uniform sampler2D uVolumetric; // in-scattered light (lighting res, smooth)
+uniform bool uVolEnabled;
+uniform vec3 uBackgroundColor;
+// 0 composite, 1 albedo, 2 normal, 3 irradiance (direct+GI), 4 worldPos, 5 emissive
+uniform int uOutputMode;
+
+// joint bilateral upsample (lighting may be rendered below full resolution)
+uniform bool uUpsample;
+uniform vec2 uIrrTexelSize;
+uniform vec3 uCameraPos;
+
+// distance fog (applied in linear space, before tonemap)
+uniform bool uFogEnabled;
+uniform vec3 uFogColor;
+uniform float uFogDensity;
+
+// procedural sky background
+uniform bool uSkyEnabled;
+uniform mat4 uInvViewProj;
+uniform vec3 uSunDir;
+uniform vec3 uSunColor;
+uniform vec3 uSkyZenith;
+uniform vec3 uSkyHorizon;
+uniform float uSkyIntensity;
+
+// Reconstruct the world-space view ray for this pixel from the inverse VP.
+vec3 viewRay(vec2 uv) {
+  vec4 far = uInvViewProj * vec4(uv * 2.0 - 1.0, 1.0, 1.0);
+  return normalize(far.xyz / far.w - uCameraPos);
+}
+
+vec3 acesFilm(vec3 x) {
+  const float a = 2.51, b = 0.03, c = 2.43, d = 0.59, e = 0.14;
+  return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0);
+}
+
+// Upsample low-res irradiance to this full-res pixel: 4 nearest low-res taps,
+// bilinear weights modulated by geometric similarity (plane distance + normal)
+// so lighting never bleeds across depth or orientation discontinuities.
+vec3 sampleIrradiance(vec2 uv, vec3 P, vec3 N) {
+  if (!uUpsample) return texture(uIrradiance, uv).rgb;
+
+  float planeTol = 0.01 * distance(P, uCameraPos) + 1e-3;
+  vec2 base = uv / uIrrTexelSize - 0.5;
+  vec2 f = fract(base);
+  vec2 uv00 = (floor(base) + 0.5) * uIrrTexelSize;
+
+  vec3 sum = vec3(0.0);
+  float wsum = 0.0;
+  vec3 bestGeo = vec3(0.0);
+  float bestGeoW = -1.0;
+  vec3 bestBil = vec3(0.0);
+  float bestBilW = -1.0;
+  for (int dy = 0; dy <= 1; dy++) {
+    for (int dx = 0; dx <= 1; dx++) {
+      vec2 tuv = uv00 + vec2(float(dx), float(dy)) * uIrrTexelSize;
+      vec3 irr = texture(uIrradiance, tuv).rgb;
+      float bw = (dx == 0 ? 1.0 - f.x : f.x) * (dy == 0 ? 1.0 - f.y : f.y);
+      if (bw > bestBilW) { bestBilW = bw; bestBil = irr; }
+
+      vec4 g = texture(uGWorldPos, tuv);
+      if (g.w < 0.5) continue;
+      vec3 Nt = normalize(texture(uGNormalMetal, tuv).xyz);
+      float wPlane = exp(-abs(dot(g.xyz - P, N)) / planeTol);
+      float wN = pow(max(dot(N, Nt), 0.0), 16.0);
+      float gw = wPlane * wN;
+      // Track the geometrically most similar tap for the fallback below.
+      if (gw > bestGeoW) { bestGeoW = gw; bestGeo = irr; }
+      float w = bw * gw;
+      sum += irr * w;
+      wsum += w;
+    }
+  }
+  if (wsum > 1e-4) return sum / wsum;
+  // All combined weights died (thin silhouette). Falling back to the closest
+  // *bilinear* tap would pull lighting from the far side of the edge — under
+  // TAA jitter the chosen tap flickers, which reads as bright "rain drop"
+  // speckles on dark objects. Prefer the geometrically closest tap instead.
+  return bestGeoW >= 0.0 ? bestGeo : bestBil;
+}
+
+void main() {
+  vec4 wp = texture(uGWorldPos, vUv);
+  vec4 albedoRough = texture(uGAlbedoRough, vUv);
+  vec3 N = normalize(texture(uGNormalMetal, vUv).xyz);
+  vec3 irradiance = sampleIrradiance(vUv, wp.xyz, N);
+  vec3 emissive = texture(uGEmissive, vUv).rgb;
+
+  vec3 color;
+  if (wp.w < 0.5) {
+    // Background: the procedural sky (with sun), else fog colour, else flat.
+    if (uSkyEnabled) {
+      color = skyColor(viewRay(vUv), uSunDir, uSunColor, uSkyZenith, uSkyHorizon, uSkyIntensity);
+    } else {
+      color = uFogEnabled ? uFogColor : uBackgroundColor;
+    }
+  } else {
+    color = albedoRough.rgb * irradiance + emissive;
+    // Volumetric in-scatter (already radiance, not modulated by albedo). Fog
+    // is low-frequency, so a wide 5-tap blur costs nothing visually and eats
+    // most of the single-sample grain the accumulation hasn't averaged yet.
+    if (uVolEnabled) {
+      vec2 o = uIrrTexelSize * 1.5;
+      vec3 vol = texture(uVolumetric, vUv).rgb * 0.4
+        + texture(uVolumetric, vUv + vec2( o.x,  o.y)).rgb * 0.15
+        + texture(uVolumetric, vUv + vec2(-o.x,  o.y)).rgb * 0.15
+        + texture(uVolumetric, vUv + vec2( o.x, -o.y)).rgb * 0.15
+        + texture(uVolumetric, vUv + vec2(-o.x, -o.y)).rgb * 0.15;
+      color += vol;
+    }
+    if (uFogEnabled) {
+      float dist = distance(wp.xyz, uCameraPos);
+      float f = 1.0 - exp(-uFogDensity * uFogDensity * dist * dist);
+      color = mix(color, uFogColor, clamp(f, 0.0, 1.0));
+    }
+  }
+
+  if (uOutputMode == 1) color = albedoRough.rgb;
+  else if (uOutputMode == 2) color = N * 0.5 + 0.5;
+  else if (uOutputMode == 3) color = irradiance;
+  else if (uOutputMode == 4) color = fract(wp.xyz * 0.1);
+  else if (uOutputMode == 5) color = emissive;
+  else color = acesFilm(color);
+
+  outColor = vec4(pow(color, vec3(1.0 / 2.2)), 1.0);
+}
+`;
+
+/** Combines G-buffer albedo/emissive with accumulated irradiance, tonemaps, writes to screen. */
+export class CompositePass {
+  constructor() {
+    this.material = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      vertexShader: fullscreenVert,
+      fragmentShader: compositeFrag,
+      uniforms: {
+        uIrradiance: { value: null },
+        uGAlbedoRough: { value: null },
+        uGNormalMetal: { value: null },
+        uGWorldPos: { value: null },
+        uGEmissive: { value: null },
+        uVolumetric: { value: null },
+        uVolEnabled: { value: false },
+        uBackgroundColor: { value: new THREE.Color(0.01, 0.012, 0.02) },
+        uOutputMode: { value: 0 },
+        uUpsample: { value: false },
+        uIrrTexelSize: { value: new THREE.Vector2() },
+        uCameraPos: { value: new THREE.Vector3() },
+        uFogEnabled: { value: false },
+        uFogColor: { value: new THREE.Color(0.5, 0.6, 0.7) },
+        uFogDensity: { value: 0.05 },
+        uSkyEnabled: { value: false },
+        uInvViewProj: { value: new THREE.Matrix4() },
+        uSunDir: { value: new THREE.Vector3(0.4, 0.8, 0.45).normalize() },
+        uSunColor: { value: new THREE.Color(1.0, 0.9, 0.75) },
+        uSkyZenith: { value: new THREE.Color(0.18, 0.34, 0.62) },
+        uSkyHorizon: { value: new THREE.Color(0.7, 0.8, 0.9) },
+        uSkyIntensity: { value: 1.0 },
+      },
+      depthTest: false,
+      depthWrite: false,
+    });
+
+    this.scene = new THREE.Scene();
+    this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    this.quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), this.material);
+    this.quad.frustumCulled = false;
+    this.scene.add(this.quad);
+  }
+
+  render(renderer, irradianceTexture, gbuffer, background, target = null) {
+    const u = this.material.uniforms;
+    u.uIrradiance.value = irradianceTexture;
+    u.uGAlbedoRough.value = gbuffer.albedoRough;
+    u.uGNormalMetal.value = gbuffer.normalMetal;
+    u.uGWorldPos.value = gbuffer.worldPos;
+    u.uGEmissive.value = gbuffer.emissive;
+    if (background && background.isColor) {
+      u.uBackgroundColor.value.copy(background);
+    }
+    renderer.setRenderTarget(target);
+    renderer.render(this.scene, this.camera);
+  }
+
+  dispose() {
+    this.material.dispose();
+    this.quad.geometry.dispose();
+  }
+}