reze-engine 0.59.0 → 0.60.0

package/dist/shaders/materials/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AA4BA,eAAO,MAAM,oBAAoB,QAsJhC,CAAC;AA8HF,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAGD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,orMAgHzB,CAAA;AAQD,eAAO,MAAM,4BAA4B,QAC0D,CAAA"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AA4BA,eAAO,MAAM,oBAAoB,QA0JhC,CAAC;AA8HF,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAGD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,orMAgHzB,CAAA;AAQD,eAAO,MAAM,4BAA4B,QAC0D,CAAA"}

package/dist/shaders/materials/common.js

@@ -143,9 +143,13 @@ struct LightVP { viewProj: array<mat4x4f, ${SHADOW_CASCADES.length}>, };
 @group(0) @binding(8) var worldEnvTexture: texture_2d<f32>;
 // binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).
 @group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
-// Light this model receives beyond the world's — see Engine.setModelFill. Zero
-// for a model nobody gave one, which leaves its ambient exactly the world's.
-@group(1) @binding(1) var<uniform> modelFill: vec4f;
+// The light this model takes apart from the scene's — see Engine.setModelFill
+// and Engine.setModelSun. fill is added to its ambient, zero for a model
+// nobody gave one; sun replaces the scene's sun colour while its w is set,
+// which is how a stage keeps the daylight its game lit it by while the cast
+// keeps the key the scene set for them.
+struct ModelLight { fill: vec4f, sun: vec4f }
+@group(1) @binding(1) var<uniform> modelLight: ModelLight;
 @group(2) @binding(0) var diffuseTexture: texture_2d<f32>;
 @group(2) @binding(1) var<uniform> material: MaterialUniforms;
 // Reserved for future sphere/toon graph nodes; graphs that don't read them get the

package/dist/shadow-cascades.d.ts

@@ -1,45 +1,95 @@
-type ShadowCascade = {
-    /** World units across the ortho box, both axes. */
-    span: number;
-    /** How far behind the target the light's eye sits, along -sunDir. */
-    back: number;
-    /** Ortho near/far, in world units from that eye. */
-    near: number;
-    far: number;
+/**
+ * THE SUN'S SHADOW FOLLOWS THE CAMERA, the way Blender's does.
+ *
+ * Each cascade is fitted every frame to a slice of the view frustum: the near
+ * one to the stretch around what the camera is looking at, the far one to the
+ * whole of what it sees. Whatever is in view is in a cascade, and whatever
+ * could throw a shadow onto it is in the cascade's depth range, which is fitted
+ * to the scene's bounds along the light. A room forty metres across with its
+ * window frames behind the camera shadows its floor as the game does; a lone
+ * dancer on an empty floor keeps a crisp near map.
+ *
+ * The earlier shape was two fixed boxes around the camera target, 64 and 256
+ * units across, and a stage reached past them: the floor near the windows lay
+ * outside every box and was drawn lit, the shadows stopping at the box's edge
+ * in a straight line.
+ *
+ * INVARIANT the sampler and the cull both lean on: the outer cascade CONTAINS
+ * the inner one. The sampler falls from cascade 0 to 1 at the box edge, which
+ * is only seamless if 1 covers where 0 ends, and the cull tests the OUTERMOST
+ * frustum alone. Both hold because the outer slice is the whole frustum, of
+ * which the inner slice is a part, and both take the same depth range.
+ * tests/shadow-cascades.test.mjs pins it.
+ */
+export type ShadowCascade = {
     /** Texels per side of this cascade's map — sets the snap quantum. */
     mapSize: number;
 };
+export declare const SHADOW_CASCADES: readonly ShadowCascade[];
+/** How far past the camera's point of interest the near cascade reaches, in
+ *  world units: the dancer and the floor around her, at the near map's texel. */
+export declare const NEAR_REACH = 40;
+/** The view the cascades are fitted to: the camera's eye and basis (world
+ *  space, left-handed, +Z forward as the projection is), its vertical field of
+ *  view, aspect and clip planes, and how far away the thing it looks at is. */
+export type ShadowView = {
+    eye: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    right: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    up: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    forward: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    fov: number;
+    aspect: number;
+    near: number;
+    far: number;
+    /** Distance from the eye to the camera target, along the view. */
+    focus: number;
+};
+/** World-space box around everything drawn, or null for an empty scene. */
+export type ShadowBounds = {
+    min: [number, number, number];
+    max: [number, number, number];
+} | null;
+type XYZ = {
+    x: number;
+    y: number;
+    z: number;
+};
 /**
- * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
- * each cascade's box must CONTAIN the previous one (same snapped target, wider
- * span, deeper reach), because
- *
- *   - the sampler falls from cascade i to i+1 at the box edge, which is only
- *     seamless if i+1 covers where i ends, and
- *   - the cull tests ONE frustum — the outermost — and the rasterizer clips
- *     each cascade to its own box. That is the same argument that made
- *     single-volume shadow culling exact: anything rejected was contributing
- *     nothing anywhere. Concentric containment is what keeps it true for a
- *     LIST. tests/shadow-cascades.test.mjs pins it.
+ * Where each cascade's slice of the view starts and ends, as distances along
+ * the view: [near, split] and [near, farFit]. The far end is where the scene
+ * ends, so an empty floor with a dancer on it keeps a short, sharp frustum
+ * rather than the camera's far plane.
  */
-export declare const SHADOW_CASCADES: readonly ShadowCascade[];
+export declare function cascadeSlices(view: ShadowView, bounds: ShadowBounds): [number, number][];
+/** The eight corners of a slice, for tests and for the fit's own checks. */
+export declare function sliceCorners(view: ShadowView, n: number, f: number): XYZ[];
 /**
- * One cascade's view-projection, following the camera target.
- *
- * The target is snapped to this cascade's OWN texel quantum in the light's
- * right/up plane, so a moving volume doesn't shimmer its shadow edges while
- * running — each cascade snaps to its own grid, coarser maps snapping coarser.
+ * One cascade's view-projection: an orthographic box around the slice's
+ * sphere, snapped to the map's texel grid in the light's right/up plane so a
+ * moving camera doesn't shimmer its shadow edges, and reaching along the light
+ * from the nearest thing in the scene to the farthest, so everything that
+ * could cast into the slice does.
  *
  * Writes the 16 floats into `out` at `offset` and returns `out`.
  */
-export declare function buildShadowVP(target: {
-    x: number;
-    y: number;
-    z: number;
-}, sunDirection: {
-    x: number;
-    y: number;
-    z: number;
-}, cascade: ShadowCascade, out: Float32Array, offset: number): Float32Array;
+export declare function fitShadowVP(view: ShadowView, slice: [number, number], sunDirection: XYZ, bounds: ShadowBounds, cascade: ShadowCascade, out: Float32Array, offset: number): Float32Array;
+/** Every cascade's view-projection in a row, inner to outer. */
+export declare function buildShadowCascades(view: ShadowView, sunDirection: XYZ, bounds: ShadowBounds, out: Float32Array): Float32Array;
 export {};
 //# sourceMappingURL=shadow-cascades.d.ts.map

package/dist/shadow-cascades.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shadow-cascades.d.ts","sourceRoot":"","sources":["../src/shadow-cascades.ts"],"names":[],"mappings":"AAeA,KAAK,aAAa,GAAG;IACnB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAWnD,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3C,YAAY,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,MAAM,GACb,YAAY,CA4Bd"}
+{"version":3,"file":"shadow-cascades.d.ts","sourceRoot":"","sources":["../src/shadow-cascades.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAA2C,CAAA;AAE/F;iFACiF;AACjF,eAAO,MAAM,UAAU,KAAK,CAAA;AAE5B;;+EAE+E;AAC/E,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACxC,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,EAAE,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,OAAO,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG;IAAE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAAA;AAElG,KAAK,GAAG,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAkBxF;AAwBD,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE,CAc1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACvB,YAAY,EAAE,GAAG,EACjB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,MAAM,GACb,YAAY,CA0Cd;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,GAAG,YAAY,CAI9H"}

package/dist/shadow-cascades.js

@@ -1,70 +1,116 @@
-// The shadow volumes, as data — a list the engine iterates rather than one
-// hardcoded box, so a second cascade is a list entry and not a rewrite.
-//
-// Pure math, its own module for the same reason param-track.ts is: the engine
-// class needs a GPU to construct, and the one thing that ever goes WRONG with a
-// shadow volume is arithmetic — a snap that stops snapping, an eye that lands
-// inside the near plane. Headless tests can hold this half to golden values.
-//
-// The arithmetic is the shipped single-volume code, operation for operation:
-// float addition is not associative, so "the same formula, reordered" is not
-// the same matrix, and cascade 0 must be BIT-IDENTICAL to the volume every
-// published scene was lit by.
 import { Mat4, Vec3 } from "./math";
+export const SHADOW_CASCADES = [{ mapSize: 4096 }, { mapSize: 2048 }];
+/** How far past the camera's point of interest the near cascade reaches, in
+ *  world units: the dancer and the floor around her, at the near map's texel. */
+export const NEAR_REACH = 40;
 /**
- * The list, inner to outer. INVARIANT the sampler and the cull both lean on:
- * each cascade's box must CONTAIN the previous one (same snapped target, wider
- * span, deeper reach), because
- *
- *   - the sampler falls from cascade i to i+1 at the box edge, which is only
- *     seamless if i+1 covers where i ends, and
- *   - the cull tests ONE frustum — the outermost — and the rasterizer clips
- *     each cascade to its own box. That is the same argument that made
- *     single-volume shadow culling exact: anything rejected was contributing
- *     nothing anywhere. Concentric containment is what keeps it true for a
- *     LIST. tests/shadow-cascades.test.mjs pins it.
+ * Where each cascade's slice of the view starts and ends, as distances along
+ * the view: [near, split] and [near, farFit]. The far end is where the scene
+ * ends, so an empty floor with a dancer on it keeps a short, sharp frustum
+ * rather than the camera's far plane.
  */
-export const SHADOW_CASCADES = [
-    // The shipped volume: 64 units at 4096² ≈ 64 texels/unit — crisp contact
-    // shadows on the ground catcher (2048 read visibly blurry).
-    { span: 64, back: 72, near: 1, far: 140, mapSize: 4096 },
-    // The stage volume: 4× the span on each side, so a set piece 100 units out
-    // still throws and receives shade instead of popping lit at the near box's
-    // edge. 2048² over 256 units ≈ 8 texels/unit — soft, and read at distances
-    // where soft is what a shadow looks like anyway. 16 MB where the near map
-    // is 64. Depth reach scales with the span (same eye direction, deeper box),
-    // keeping the containment invariant checkable from the specs alone.
-    { span: 256, back: 288, near: 1, far: 560, mapSize: 2048 },
-];
+export function cascadeSlices(view, bounds) {
+    let farFit = view.near + 200;
+    if (bounds) {
+        let deepest = 0;
+        for (let i = 0; i < 8; i++) {
+            const cx = (i & 1 ? bounds.max : bounds.min)[0] - view.eye.x;
+            const cy = (i & 2 ? bounds.max : bounds.min)[1] - view.eye.y;
+            const cz = (i & 4 ? bounds.max : bounds.min)[2] - view.eye.z;
+            deepest = Math.max(deepest, cx * view.forward.x + cy * view.forward.y + cz * view.forward.z);
+        }
+        farFit = deepest + 1;
+    }
+    farFit = Math.min(view.far, Math.max(view.near + 1, farFit));
+    const split = Math.min(farFit, Math.max(view.near + 8, view.focus + NEAR_REACH));
+    return [
+        [view.near, split],
+        [view.near, farFit],
+    ];
+}
+/** The bounding sphere of a frustum slice: on the view axis, at the depth that
+ *  balances the near and far rectangles' corners. */
+function sliceSphere(view, n, f) {
+    const t = Math.tan(view.fov / 2);
+    const k2 = t * t * (1 + view.aspect * view.aspect);
+    let depth;
+    let radius;
+    if (k2 >= (f - n) / (f + n)) {
+        depth = f;
+        radius = f * Math.sqrt(k2);
+    }
+    else {
+        depth = 0.5 * (f + n) * (1 + k2);
+        radius = 0.5 * Math.sqrt((f - n) * (f - n) + 2 * (f * f + n * n) * k2 + (f + n) * (f + n) * k2 * k2);
+    }
+    const center = new Vec3(view.eye.x + view.forward.x * depth, view.eye.y + view.forward.y * depth, view.eye.z + view.forward.z * depth);
+    return { center, radius };
+}
+/** The eight corners of a slice, for tests and for the fit's own checks. */
+export function sliceCorners(view, n, f) {
+    const out = [];
+    for (const d of [n, f]) {
+        const h = d * Math.tan(view.fov / 2);
+        const w = h * view.aspect;
+        for (const sy of [-1, 1])
+            for (const sx of [-1, 1])
+                out.push({
+                    x: view.eye.x + view.forward.x * d + view.right.x * w * sx + view.up.x * h * sy,
+                    y: view.eye.y + view.forward.y * d + view.right.y * w * sx + view.up.y * h * sy,
+                    z: view.eye.z + view.forward.z * d + view.right.z * w * sx + view.up.z * h * sy,
+                });
+    }
+    return out;
+}
 /**
- * One cascade's view-projection, following the camera target.
- *
- * The target is snapped to this cascade's OWN texel quantum in the light's
- * right/up plane, so a moving volume doesn't shimmer its shadow edges while
- * running — each cascade snaps to its own grid, coarser maps snapping coarser.
+ * One cascade's view-projection: an orthographic box around the slice's
+ * sphere, snapped to the map's texel grid in the light's right/up plane so a
+ * moving camera doesn't shimmer its shadow edges, and reaching along the light
+ * from the nearest thing in the scene to the farthest, so everything that
+ * could cast into the slice does.
  *
  * Writes the 16 floats into `out` at `offset` and returns `out`.
  */
-export function buildShadowVP(target, sunDirection, cascade, out, offset) {
+export function fitShadowVP(view, slice, sunDirection, bounds, cascade, out, offset) {
     const dir = new Vec3(sunDirection.x, sunDirection.y, sunDirection.z);
     dir.normalize();
     const up = Math.abs(dir.y) > 0.99 ? new Vec3(0, 0, -1) : new Vec3(0, 1, 0);
-    const t = new Vec3(target.x, target.y, target.z);
     const right = Vec3.crossInto(up, dir, new Vec3(0, 0, 0)).normalize();
     const upv = Vec3.crossInto(dir, right, new Vec3(0, 0, 0));
-    const texel = cascade.span / cascade.mapSize;
-    const tr = Math.round(t.dot(right) / texel) * texel;
-    const tu = Math.round(t.dot(upv) / texel) * texel;
-    const td = t.dot(dir);
+    const { center, radius } = sliceSphere(view, slice[0], slice[1]);
+    // A texel of the map, in world units; the radius is rounded up onto the
+    // grid too, so the box's size does not drift with the fov by fractions.
+    const texel = Math.max((2 * radius) / cascade.mapSize, 1e-4);
+    const half = Math.ceil(radius / texel) * texel;
+    const tr = Math.round(center.dot(right) / texel) * texel;
+    const tu = Math.round(center.dot(upv) / texel) * texel;
+    const td = center.dot(dir);
     const snapped = new Vec3(right.x * tr + upv.x * tu + dir.x * td, right.y * tr + upv.y * tu + dir.y * td, right.z * tr + upv.z * tu + dir.z * td);
-    const eye = new Vec3(snapped.x - dir.x * cascade.back, snapped.y - dir.y * cascade.back, snapped.z - dir.z * cascade.back);
-    const view = Mat4.lookAt(eye, snapped, up);
-    const half = cascade.span / 2;
-    // The shadow map keeps the NON-reversed convention (orthographicLh maps z to
-    // [0,1] front-to-back) — reversing it buys nothing for an ortho box and the
-    // +2 pipeline depth bias is signed against this direction.
-    const proj = Mat4.orthographicLh(-half, half, -half, half, cascade.near, cascade.far);
-    const vp = proj.multiply(view);
-    out.set(vp.values, offset);
+    // Along the light: from the scene's nearest point to its farthest, with a
+    // margin so a caster on the box's own face is not clipped. With nothing to
+    // fit, the sphere itself.
+    let zmin = td - half;
+    let zmax = td + half;
+    if (bounds) {
+        for (let i = 0; i < 8; i++) {
+            const z = (i & 1 ? bounds.max : bounds.min)[0] * dir.x + (i & 2 ? bounds.max : bounds.min)[1] * dir.y + (i & 4 ? bounds.max : bounds.min)[2] * dir.z;
+            zmin = Math.min(zmin, z);
+            zmax = Math.max(zmax, z);
+        }
+    }
+    const margin = 2 + 0.02 * (zmax - zmin);
+    const back = td - zmin + margin;
+    const far = back + (zmax - td) + margin;
+    const eye = new Vec3(snapped.x - dir.x * back, snapped.y - dir.y * back, snapped.z - dir.z * back);
+    const viewM = Mat4.lookAt(eye, snapped, up);
+    const proj = Mat4.orthographicLh(-half, half, -half, half, 1, far + 1);
+    out.set(proj.multiply(viewM).values, offset);
+    return out;
+}
+/** Every cascade's view-projection in a row, inner to outer. */
+export function buildShadowCascades(view, sunDirection, bounds, out) {
+    const slices = cascadeSlices(view, bounds);
+    for (let i = 0; i < SHADOW_CASCADES.length; i++)
+        fitShadowVP(view, slices[i], sunDirection, bounds, SHADOW_CASCADES[i], out, i * 16);
     return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -44,7 +44,7 @@ import {
   type SimClock,
 } from "./effect-schedule"
 import { parentKeySpan, type ModelParentKey } from "./parent-keys"
-import { SHADOW_CASCADES, buildShadowVP } from "./shadow-cascades"
+import { SHADOW_CASCADES, buildShadowCascades, type ShadowBounds, type ShadowView } from "./shadow-cascades"
 import { REFLECTION_DEBUG_WGSL, buildMirrorCamera, planeFromPointNormal } from "./reflection"
 import { MIRROR_MASK_DOWNSAMPLE_WGSL, MIRROR_MAT_BYTES, mirrorShaderWgsl, mirrorShadowWgsl } from "./shaders/passes/mirror"
 import { packHalf, type HdrImage } from "./hdr"
@@ -866,8 +866,10 @@ interface ModelInstance {
   shadowDrawCalls: DrawCall[]
   shadowBindGroups: GPUBindGroup[]
   mainPerInstanceBindGroup: GPUBindGroup
-  /** Its own fill, when setModelFill gave it one. */
-  fillBuffer: GPUBuffer | null
+  /** Its own light — fill and sun — when setModelFill or setModelSun gave it
+   *  one: a 32-byte ModelLight, and the CPU copy it is written from. */
+  lightBuffer: GPUBuffer | null
+  modelLight: Float32Array | null
   pickPerInstanceBindGroup: GPUBindGroup
   pickDrawCalls: PickDrawCall[]
   /** Environment geometry added via addStage — no physics, no IK, and it
@@ -2459,7 +2461,7 @@ export class Engine {
   private depthReadView: GPUTextureView | null = null
   private compositeUniformBuffer!: GPUBuffer
   // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-  // 11 × vec4f — see the viewU comment in composite.ts. The last one is the
+  // 15 × vec4f — see the viewU comment in composite.ts. The last one is the
   // camera's world position, which is what lets a foreground effect turn the
   // depth it is handed into a PLACE (bgWorldPos) rather than a distance.
   private readonly compositeUniformData = new Float32Array(60)
@@ -7307,8 +7309,8 @@ export class Engine {
     )
 
     this.noFillBuffer = this.device.createBuffer({
-      label: "model fill (none)",
-      size: 16,
+      label: "model light (none)",
+      size: 32,
       usage: GPUBufferUsage.UNIFORM,
     })
 
@@ -7422,7 +7424,7 @@ export class Engine {
           visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
           buffer: { type: "read-only-storage" },
         },
-        // The model's own fill — see setModelFill.
+        // The model's own light — see setModelFill and setModelSun.
         { binding: 1, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
       ],
     })
@@ -8018,7 +8020,7 @@ export class Engine {
     // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
     this.compositeUniformBuffer = this.device.createBuffer({
       label: "composite view uniforms",
-      // 11 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
+      // 15 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
       // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
       // (time, _, canvas width, canvas height) for user effects · three grade
       // vectors (CDL offset+contrast, power+saturation, slope+flag) · camera
@@ -10753,39 +10755,66 @@ export class Engine {
    * for the models the host counts as cast.
    */
   setModelFill(name: string, fill: Vec3 | null): boolean {
+    return this.writeModelLight(name, 0, fill)
+  }
+
+  /**
+   * A model's own sun: the colour and strength the scene's sun has FOR THIS
+   * MODEL, in place of the scene's. Null gives it the scene's sun back.
+   *
+   * The other half of lighting a stage and its cast apart. A game's stage is
+   * lit by its own daylight — Aether Gazer's kitchen at twenty times white —
+   * while its characters take a key light of their own that the stage never
+   * states. So a stage carries the sun it was lit by, and the scene's sun
+   * stays the cast's. Direction and shadow are still the scene's: one sun
+   * casts, and it casts the same way on both.
+   */
+  setModelSun(name: string, sun: Vec3 | null): boolean {
+    return this.writeModelLight(name, 4, sun)
+  }
+
+  /** One half of a model's light, at `at` (0 the fill, 4 the sun) in its
+   *  ModelLight; w says whether that half is set. Both null releases the
+   *  buffer and the model takes the shared zero stand-in again. */
+  private writeModelLight(name: string, at: 0 | 4, value: Vec3 | null): boolean {
     const inst = this.modelInstances.get(name)
     if (!inst || !this.device) return false
-    if (!fill) {
-      if (!inst.fillBuffer) return true
-      const retired = inst.fillBuffer
-      inst.fillBuffer = null
+    const light = inst.modelLight ?? new Float32Array(8)
+    light.set(value ? [value.x, value.y, value.z, 1] : [0, 0, 0, 0], at)
+    const any = light[3] > 0 || light[7] > 0
+    if (!any) {
+      if (!inst.lightBuffer) return true
+      const retired = inst.lightBuffer
+      inst.lightBuffer = null
+      inst.modelLight = null
       inst.mainPerInstanceBindGroup = this.perInstanceBindGroup(name, inst.skinMatrixBuffer, null)
       this.bundlesDirty = true
       // Retired once the GPU is done with it: an encoded frame may still name it.
       void this.device.queue.onSubmittedWorkDone().then(() => retired.destroy())
       return true
     }
-    if (!inst.fillBuffer) {
-      inst.fillBuffer = this.device.createBuffer({
-        label: `${name}: fill`,
-        size: 16,
+    inst.modelLight = light
+    if (!inst.lightBuffer) {
+      inst.lightBuffer = this.device.createBuffer({
+        label: `${name}: light`,
+        size: 32,
         usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
       })
-      inst.mainPerInstanceBindGroup = this.perInstanceBindGroup(name, inst.skinMatrixBuffer, inst.fillBuffer)
+      inst.mainPerInstanceBindGroup = this.perInstanceBindGroup(name, inst.skinMatrixBuffer, inst.lightBuffer)
       this.bundlesDirty = true
     }
-    this.device.queue.writeBuffer(inst.fillBuffer, 0, new Float32Array([fill.x, fill.y, fill.z, 0]))
+    this.device.queue.writeBuffer(inst.lightBuffer, 0, light.buffer as ArrayBuffer)
     return true
   }
 
-  /** The per-model group: its skinning matrices and its fill, or the zero stand-in. */
-  private perInstanceBindGroup(name: string, skinMatrixBuffer: GPUBuffer, fill: GPUBuffer | null): GPUBindGroup {
+  /** The per-model group: its skinning matrices and its light, or the zero stand-in. */
+  private perInstanceBindGroup(name: string, skinMatrixBuffer: GPUBuffer, light: GPUBuffer | null): GPUBindGroup {
     return this.device.createBindGroup({
       label: `${name}: main per-instance bind group`,
       layout: this.mainPerInstanceBindGroupLayout,
       entries: [
         { binding: 0, resource: { buffer: skinMatrixBuffer } },
-        { binding: 1, resource: { buffer: fill ?? this.noFillBuffer } },
+        { binding: 1, resource: { buffer: light ?? this.noFillBuffer } },
       ],
     })
   }
@@ -10819,7 +10848,7 @@ export class Engine {
     for (const buf of inst.gpuBuffers) {
       buf.destroy()
     }
-    inst.fillBuffer?.destroy()
+    inst.lightBuffer?.destroy()
     // Per-group StyleUniforms buffers aren't in gpuBuffers (allocated post-load).
     for (const install of inst.styleGroups.values()) this.destroyInstall(install)
     this.modelInstances.delete(name)
@@ -12511,6 +12540,55 @@ export class Engine {
     }
     if (this.cullModelBuffer) this.device.queue.writeBuffer(this.cullModelBuffer, 0, data.buffer as ArrayBuffer)
     this.updateCasterSphere(data)
+    this.updateShadowSceneBounds(data, flags)
+  }
+
+  /**
+   * The box around everything visible, from the same numbers the cull reads:
+   * a rigid model's per-draw boxes through its matrix, a posed model's sphere.
+   * The shadow cascades reach along the light across it.
+   */
+  private updateShadowSceneBounds(data: Float32Array, flags: Uint32Array): void {
+    let minX = Infinity, minY = Infinity, minZ = Infinity
+    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity
+    for (let i = 0; i < this.cullDraws.length; i++) {
+      const f = i * 8
+      const mi = this.cullMetaU32[f + 3]
+      const o = mi * Engine.CULL_MODEL_FLOATS
+      const mf = flags[o + 20]
+      if ((mf & Engine.CULL_MODEL_VISIBLE) === 0) continue
+      if ((mf & Engine.CULL_MODEL_RIGID) !== 0) {
+        const cx = (this.cullMetaF32[f] + this.cullMetaF32[f + 4]) * 0.5
+        const cy = (this.cullMetaF32[f + 1] + this.cullMetaF32[f + 5]) * 0.5
+        const cz = (this.cullMetaF32[f + 2] + this.cullMetaF32[f + 6]) * 0.5
+        const ex = (this.cullMetaF32[f + 4] - this.cullMetaF32[f]) * 0.5
+        const ey = (this.cullMetaF32[f + 5] - this.cullMetaF32[f + 1]) * 0.5
+        const ez = (this.cullMetaF32[f + 6] - this.cullMetaF32[f + 2]) * 0.5
+        const wx = data[o] * cx + data[o + 4] * cy + data[o + 8] * cz + data[o + 12]
+        const wy = data[o + 1] * cx + data[o + 5] * cy + data[o + 9] * cz + data[o + 13]
+        const wz = data[o + 2] * cx + data[o + 6] * cy + data[o + 10] * cz + data[o + 14]
+        const gx = Math.abs(data[o]) * ex + Math.abs(data[o + 4]) * ey + Math.abs(data[o + 8]) * ez
+        const gy = Math.abs(data[o + 1]) * ex + Math.abs(data[o + 5]) * ey + Math.abs(data[o + 9]) * ez
+        const gz = Math.abs(data[o + 2]) * ex + Math.abs(data[o + 6]) * ey + Math.abs(data[o + 10]) * ez
+        minX = Math.min(minX, wx - gx); maxX = Math.max(maxX, wx + gx)
+        minY = Math.min(minY, wy - gy); maxY = Math.max(maxY, wy + gy)
+        minZ = Math.min(minZ, wz - gz); maxZ = Math.max(maxZ, wz + gz)
+      } else {
+        const r = data[o + 19]
+        if (!(r > 0)) continue
+        minX = Math.min(minX, data[o + 16] - r); maxX = Math.max(maxX, data[o + 16] + r)
+        minY = Math.min(minY, data[o + 17] - r); maxY = Math.max(maxY, data[o + 17] + r)
+        minZ = Math.min(minZ, data[o + 18] - r); maxZ = Math.max(maxZ, data[o + 18] + r)
+      }
+    }
+    if (!Number.isFinite(minX)) {
+      this.shadowSceneBounds = null
+      return
+    }
+    const b = this.shadowSceneBounds ?? { min: [0, 0, 0], max: [0, 0, 0] }
+    b.min[0] = minX; b.min[1] = minY; b.min[2] = minZ
+    b.max[0] = maxX; b.max[1] = maxY; b.max[2] = maxZ
+    this.shadowSceneBounds = b
   }
 
   /**
@@ -13364,7 +13442,8 @@ export class Engine {
       shadowDrawCalls: [],
       shadowBindGroups,
       mainPerInstanceBindGroup,
-      fillBuffer: null,
+      lightBuffer: null,
+      modelLight: null,
       pickPerInstanceBindGroup,
       pickDrawCalls: [],
       isStage,
@@ -13790,25 +13869,60 @@ export class Engine {
   /** How much shadow the sun casts — see SunOptions.shadow. Full until told. */
   private sunShadow = 1
   private shadowLightVPDirty = true
-  // Last shadow-volume center, to skip recomputes while nothing moves.
-  private readonly shadowCenter = new Vec3(0, 11, 0)
+  /** The cascades as last uploaded, to skip the upload while nothing moved:
+   *  the fit snaps to the map's texels, so a still camera fits the same box. */
+  private readonly shadowLightVPLast = new Float32Array(16 * SHADOW_CASCADES.length)
+  /** Everything drawn, in world space, as writeCullModels last saw it. The
+   *  cascades reach along the light from its nearest face to its farthest, so
+   *  a window frame behind the camera casts onto the floor in front of it. */
+  private shadowSceneBounds: ShadowBounds = null
+  private readonly shadowView: ShadowView = {
+    eye: { x: 0, y: 0, z: 0 },
+    right: { x: 1, y: 0, z: 0 },
+    up: { x: 0, y: 1, z: 0 },
+    forward: { x: 0, y: 0, z: 1 },
+    fov: 1,
+    aspect: 1,
+    near: 1,
+    far: 100,
+    focus: 10,
+  }
 
   private updateShadowLightVP() {
-    // The volumes follow the camera target so a character carried far from the
-    // origin by code-driven root motion stays inside the lit frustum. The
-    // volume MATH lives in shadow-cascades.ts, where it is testable without a
-    // GPU; this method owns only the dirty-tracking and the upload.
+    // THE CASCADES FOLLOW THE CAMERA — fitted every frame to what it sees, the
+    // way Blender's sun shadow is, with their depth fitted to the scene. The
+    // fit MATH lives in shadow-cascades.ts, where it is testable without a
+    // GPU; this method gathers the view and owns the upload.
+    const v = this.shadowView
+    const view = this.camera.getViewMatrix().values
+    const eye = this.camera.getEyePosition()
+    v.eye.x = eye.x
+    v.eye.y = eye.y
+    v.eye.z = eye.z
+    // lookAt writes the basis as the view's rows: right, up, forward.
+    v.right.x = view[0]
+    v.right.y = view[4]
+    v.right.z = view[8]
+    v.up.x = view[1]
+    v.up.y = view[5]
+    v.up.z = view[9]
+    v.forward.x = view[2]
+    v.forward.y = view[6]
+    v.forward.z = view[10]
+    v.fov = this.camera.fov
+    v.aspect = this.camera.aspect
+    v.near = this.camera.near
+    v.far = this.camera.far
     const t = this.camera.target
-    const moved =
-      Math.abs(t.x - this.shadowCenter.x) > 1e-3 ||
-      Math.abs(t.y - this.shadowCenter.y) > 1e-3 ||
-      Math.abs(t.z - this.shadowCenter.z) > 1e-3
-    if (!this.shadowLightVPDirty && !moved) return
-    this.shadowLightVPDirty = false
-    this.shadowCenter.setXYZ(t.x, t.y, t.z)
+    v.focus = Math.hypot(t.x - eye.x, t.y - eye.y, t.z - eye.z)
 
+    buildShadowCascades(v, this.sun.direction, this.shadowSceneBounds, this.shadowLightVPMatrix)
+    let same = !this.shadowLightVPDirty
+    for (let i = 0; same && i < this.shadowLightVPMatrix.length; i++) same = this.shadowLightVPMatrix[i] === this.shadowLightVPLast[i]
+    if (same) return
+    this.shadowLightVPDirty = false
+    this.shadowLightVPLast.set(this.shadowLightVPMatrix)
     for (let i = 0; i < SHADOW_CASCADES.length; i++) {
-      buildShadowVP(t, this.sun.direction, SHADOW_CASCADES[i], this.shadowLightVPMatrix, i * 16)
       this.device.queue.writeBuffer(this.shadowCascadeVPBuffers[i], 0, this.shadowLightVPMatrix, i * 16, 16)
     }
     this.device.queue.writeBuffer(this.shadowLightVPBuffer, 0, this.shadowLightVPMatrix)