reze-engine 0.58.0 → 0.58.1

package/dist/shaders/passes/trails.js

@@ -10,6 +10,7 @@ import { EFFECT_SUBJECT_VEC4S } from "../cast-layout";
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api";
 import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract";
 import { idApi } from "../id-api";
+import { sceneLightApi } from "../scene-light-api";
 /**
  * Sub-segments drawn between each pair of recorded samples.
  *
@@ -247,7 +248,7 @@ fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
         gridReadApi(0, 8, 9, src.gridSize) +
         // Stubbed: this module cannot read an attachment the scene pass writes — see
         // id-api.ts. The author's whole file compiles here, so the names must exist.
-        idApi(false, 0, 0) + castDistanceStub() +
+        idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) +
         "\n// ── user effect ──\n" +
         src.wgsl +
         /* wgsl */ `

package/dist/shaders/scene-light-api.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The world's light at a surface facing n — the flat colour, or the installed
+ * HDRI's irradiance (sh[0].w = 1), evaluated from folded SH coefficients (see
+ * ibl.ts for the folding; the shader is a plain polynomial in the normal).
+ *
+ * Written against whichever name the module gives the light uniform, so the
+ * materials, the ground and an effect all evaluate one polynomial.
+ */
+export declare const worldAmbientWgsl: (u: string) => string;
+/**
+ * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ *
+ * Shared with the materials, so an effect's shadow and her own shadow soften
+ * alike. The sampler is linear-filtered, which makes each tap a 2×2 bilinear
+ * compare. Unrolled — Safari's Metal backend doesn't unroll nested shadow
+ * loops reliably. The body expects `ndc` in scope and returns.
+ */
+export declare const pcf9: (map: string, ts: string, sampler?: string) => string;
+/** Bindings the real accessors take, from `binding` upward. */
+export declare const SCENE_LIGHT_API_BINDINGS = 5;
+/**
+ * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
+ * caster's shadow, soft in between.
+ *
+ * `rzWorldAmbient(n)`: the world's light arriving at a surface facing `n` —
+ * the materials' own ambient, so an effect's shade can match hers.
+ *
+ * With `on`, declares five bindings from `binding`:
+ *   +0 the light uniform (ambient, the sun — direction, and in .w the shadow
+ *      switch — and the HDRI's irradiance)
+ *   +1 the cascade view-projections, then the caster sphere
+ *   +2 the near cascade's map   +3 the far cascade's map
+ *   +4 the comparison sampler
+ *
+ * It takes a POINT and no normal. The materials' sampleShadow also rejects a
+ * surface facing away from the sun, which is right for skin and wrong for a
+ * blade of grass or a petal: those are thin, lit through, and shaded by their
+ * own N·L. The point is nudged toward the sun instead, which lifts a blade's
+ * root off a stage floor that casts into the same map.
+ */
+export declare function sceneLightApi(on: boolean, group: number, binding: number): string;
+//# sourceMappingURL=scene-light-api.d.ts.map

package/dist/shaders/scene-light-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-light-api.d.ts","sourceRoot":"","sources":["../../src/shaders/scene-light-api.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,MAAM,WAazC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,gBAAyB,WActE,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2DjF"}

package/dist/shaders/scene-light-api.js

@@ -0,0 +1,144 @@
+import { SHADOW_CASCADES } from "../shadow-cascades";
+// The scene's own light, as an effect author sees it: the sun's shadow and the
+// world's ambient.
+//
+// A lawn standing in a character's shadow has to darken where the floor under
+// it does, or the figure floats: the ground catcher draws her shadow, and the
+// blades drawn over it hide it. And the shade has to be the SCENE'S shade — her
+// shaded side takes the world's colour, and a lawn shaded by its own guess
+// reads as a patch of different flowers beside her. Both are already computed
+// for the materials every frame; this hands the same lookups to effects.
+//
+// Bound for real in the particle SHADING stage only. That is where geometry an
+// effect draws inside the scene pass is shaded, and the shadow pass has already
+// run by then. Every other module that compiles the author's file gets stubs:
+// rzShadow answers 1, lit, which is what a point with no occlusion information
+// is — the same answer sampleShadow gives outside every cascade — and
+// rzWorldAmbient answers black, no light.
+/**
+ * The world's light at a surface facing n — the flat colour, or the installed
+ * HDRI's irradiance (sh[0].w = 1), evaluated from folded SH coefficients (see
+ * ibl.ts for the folding; the shader is a plain polynomial in the normal).
+ *
+ * Written against whichever name the module gives the light uniform, so the
+ * materials, the ground and an effect all evaluate one polynomial.
+ */
+export const worldAmbientWgsl = (u) => /* wgsl */ `
+fn rzWorldAmbient(n: vec3f) -> vec3f {
+  if (${u}.sh[0].w < 0.5) { return ${u}.ambientColor.xyz; }
+  let x = n.x;
+  let y = n.y;
+  let z = n.z;
+  let c = ${u}.sh[0].xyz
+    + ${u}.sh[1].xyz * y + ${u}.sh[2].xyz * z + ${u}.sh[3].xyz * x
+    + ${u}.sh[4].xyz * (x * y) + ${u}.sh[5].xyz * (y * z)
+    + ${u}.sh[6].xyz * (3.0 * z * z - 1.0) + ${u}.sh[7].xyz * (x * z)
+    + ${u}.sh[8].xyz * (x * x - y * y);
+  return max(c, vec3f(0.0));
+}
+`;
+/**
+ * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ *
+ * Shared with the materials, so an effect's shadow and her own shadow soften
+ * alike. The sampler is linear-filtered, which makes each tap a 2×2 bilinear
+ * compare. Unrolled — Safari's Metal backend doesn't unroll nested shadow
+ * loops reliably. The body expects `ndc` in scope and returns.
+ */
+export const pcf9 = (map, ts, sampler = "shadowSampler") => /* wgsl */ `
+  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  let cmpZ = ndc.z - 0.001;
+  let ts = ${ts};
+  let s00 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, -ts), cmpZ);
+  let s10 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0, -ts), cmpZ);
+  let s20 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, -ts), cmpZ);
+  let s01 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, 0.0), cmpZ);
+  let s11 = textureSampleCompareLevel(${map}, ${sampler}, suv, cmpZ);
+  let s21 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, 0.0), cmpZ);
+  let s02 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts,  ts), cmpZ);
+  let s12 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0,  ts), cmpZ);
+  let s22 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts,  ts), cmpZ);
+  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+`;
+/** Bindings the real accessors take, from `binding` upward. */
+export const SCENE_LIGHT_API_BINDINGS = 5;
+/**
+ * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
+ * caster's shadow, soft in between.
+ *
+ * `rzWorldAmbient(n)`: the world's light arriving at a surface facing `n` —
+ * the materials' own ambient, so an effect's shade can match hers.
+ *
+ * With `on`, declares five bindings from `binding`:
+ *   +0 the light uniform (ambient, the sun — direction, and in .w the shadow
+ *      switch — and the HDRI's irradiance)
+ *   +1 the cascade view-projections, then the caster sphere
+ *   +2 the near cascade's map   +3 the far cascade's map
+ *   +4 the comparison sampler
+ *
+ * It takes a POINT and no normal. The materials' sampleShadow also rejects a
+ * surface facing away from the sun, which is right for skin and wrong for a
+ * blade of grass or a petal: those are thin, lit through, and shaded by their
+ * own N·L. The point is nudged toward the sun instead, which lifts a blade's
+ * root off a stage floor that casts into the same map.
+ */
+export function sceneLightApi(on, group, binding) {
+    if (!on) {
+        return /* wgsl */ `
+fn rzShadow(p: vec3f) -> f32 { return 1.0; }
+fn rzWorldAmbient(n: vec3f) -> vec3f { return vec3f(0.0); }
+`;
+    }
+    const n = SHADOW_CASCADES.length;
+    return /* wgsl */ `
+// The light uniform, as the materials lay it out; lights[0] is the sun.
+struct _RzSceneLight { direction: vec4f, color: vec4f, }
+struct _RzSceneLightU { ambientColor: vec4f, lights: array<_RzSceneLight, 4>, sh: array<vec4f, 9>, }
+// The cascades' matrices, inner to outer, then every caster in one sphere
+// (x, y, z, radius): radius 0 = nothing casts, negative = do not test.
+struct _RzShadowBlock { viewProj: array<mat4x4f, ${n}>, casters: vec4f, }
+@group(${group}) @binding(${binding}) var<uniform> _rzLight: _RzSceneLightU;
+@group(${group}) @binding(${binding + 1}) var<uniform> _rzShadowVP: _RzShadowBlock;
+@group(${group}) @binding(${binding + 2}) var _rzShadowNear: texture_depth_2d;
+@group(${group}) @binding(${binding + 3}) var _rzShadowFar: texture_depth_2d;
+@group(${group}) @binding(${binding + 4}) var _rzShadowCmp: sampler_comparison;
+
+fn _rzShadowNearTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowNear", `1.0 / ${SHADOW_CASCADES[0].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn _rzShadowFarTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowFar", `1.0 / ${SHADOW_CASCADES[n - 1].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn rzShadow(p: vec3f) -> f32 {
+  // The scene's one shadow switch, on the sun — see sampleShadow.
+  let castAmt = _rzLight.lights[0].direction.w;
+  if (castAmt <= 0.0) { return 1.0; }
+  let toSun = normalize(-_rzLight.lights[0].direction.xyz);
+  // Can anything cast onto this point at all? The ground's test, for the same
+  // two reasons: most of a lawn is nowhere near her, and a scene with no
+  // models never renders the map, whose untouched zeroes compare as shadowed.
+  let cs = _rzShadowVP.casters;
+  if (cs.w == 0.0) { return 1.0; }
+  if (cs.w > 0.0) {
+    let toCaster = cs.xyz - p;
+    let along = dot(toCaster, toSun);
+    let perp = length(toCaster - toSun * along);
+    if (along <= -cs.w || perp > cs.w) { return 1.0; }
+  }
+  let q = p + toSun * 0.08;
+  let c0 = _rzShadowVP.viewProj[0] * vec4f(q, 1.0);
+  let n0 = c0.xyz / max(c0.w, 1e-6);
+  if (all(abs(n0.xy) < vec2f(0.98)) && n0.z > 0.0 && n0.z < 1.0) {
+    return mix(1.0, _rzShadowNearTaps(n0), castAmt);
+  }
+  let c1 = _rzShadowVP.viewProj[${n - 1}] * vec4f(q, 1.0);
+  let n1 = c1.xyz / max(c1.w, 1e-6);
+  if (all(abs(n1.xy) < vec2f(0.98)) && n1.z > 0.0 && n1.z < 1.0) {
+    return mix(1.0, _rzShadowFarTaps(n1), castAmt);
+  }
+  return 1.0;
+}
+${worldAmbientWgsl("_rzLight")}`;
+}

package/dist/shaders/shadow-api.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ *
+ * Shared with the materials, so an effect's shadow and her own shadow soften
+ * alike. The sampler is linear-filtered, which makes each tap a 2×2 bilinear
+ * compare. Unrolled — Safari's Metal backend doesn't unroll nested shadow
+ * loops reliably. The body expects `ndc` in scope and returns.
+ */
+export declare const pcf9: (map: string, ts: string, sampler?: string) => string;
+/** Bindings the real accessor takes, from `binding` upward. */
+export declare const SHADOW_API_BINDINGS = 5;
+/**
+ * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
+ * caster's shadow, soft in between.
+ *
+ * With `on`, declares five bindings from `binding`:
+ *   +0 the light uniform (the sun's direction, and in .w the shadow switch)
+ *   +1 the cascade view-projections, then the caster sphere
+ *   +2 the near cascade's map   +3 the far cascade's map
+ *   +4 the comparison sampler
+ *
+ * It takes a POINT and no normal. The materials' sampleShadow also rejects a
+ * surface facing away from the sun, which is right for skin and wrong for a
+ * blade of grass or a petal: those are thin, lit through, and shaded by their
+ * own N·L. The point is nudged toward the sun instead, which lifts a blade's
+ * root off a stage floor that casts into the same map.
+ */
+export declare function shadowApi(on: boolean, group: number, binding: number): string;
+//# sourceMappingURL=shadow-api.d.ts.map

package/dist/shaders/shadow-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-api.d.ts","sourceRoot":"","sources":["../../src/shaders/shadow-api.ts"],"names":[],"mappings":"AAcA;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,gBAAyB,WActE,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAyD7E"}

package/dist/shaders/shadow-api.js

@@ -0,0 +1,112 @@
+import { SHADOW_CASCADES } from "../shadow-cascades";
+// The sun's shadow, as an effect author sees it.
+//
+// A lawn standing in a character's shadow has to darken where the floor under
+// it does, or the figure floats: the ground catcher draws her shadow, and the
+// blades drawn over it hide it. The map is already there — the materials and
+// the ground read it every frame — so this hands the same lookup to effects.
+//
+// Bound for real in the particle SHADING stage only. That is where geometry an
+// effect draws inside the scene pass is shaded, and the shadow pass has already
+// run by then. Every other module that compiles the author's file gets the
+// stub, which answers 1: lit is what a point with no occlusion information is,
+// the same answer sampleShadow gives outside every cascade.
+/**
+ * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ *
+ * Shared with the materials, so an effect's shadow and her own shadow soften
+ * alike. The sampler is linear-filtered, which makes each tap a 2×2 bilinear
+ * compare. Unrolled — Safari's Metal backend doesn't unroll nested shadow
+ * loops reliably. The body expects `ndc` in scope and returns.
+ */
+export const pcf9 = (map, ts, sampler = "shadowSampler") => /* wgsl */ `
+  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  let cmpZ = ndc.z - 0.001;
+  let ts = ${ts};
+  let s00 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, -ts), cmpZ);
+  let s10 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0, -ts), cmpZ);
+  let s20 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, -ts), cmpZ);
+  let s01 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, 0.0), cmpZ);
+  let s11 = textureSampleCompareLevel(${map}, ${sampler}, suv, cmpZ);
+  let s21 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, 0.0), cmpZ);
+  let s02 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts,  ts), cmpZ);
+  let s12 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0,  ts), cmpZ);
+  let s22 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts,  ts), cmpZ);
+  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+`;
+/** Bindings the real accessor takes, from `binding` upward. */
+export const SHADOW_API_BINDINGS = 5;
+/**
+ * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
+ * caster's shadow, soft in between.
+ *
+ * With `on`, declares five bindings from `binding`:
+ *   +0 the light uniform (the sun's direction, and in .w the shadow switch)
+ *   +1 the cascade view-projections, then the caster sphere
+ *   +2 the near cascade's map   +3 the far cascade's map
+ *   +4 the comparison sampler
+ *
+ * It takes a POINT and no normal. The materials' sampleShadow also rejects a
+ * surface facing away from the sun, which is right for skin and wrong for a
+ * blade of grass or a petal: those are thin, lit through, and shaded by their
+ * own N·L. The point is nudged toward the sun instead, which lifts a blade's
+ * root off a stage floor that casts into the same map.
+ */
+export function shadowApi(on, group, binding) {
+    if (!on) {
+        return /* wgsl */ `
+fn rzShadow(p: vec3f) -> f32 { return 1.0; }
+`;
+    }
+    const n = SHADOW_CASCADES.length;
+    return /* wgsl */ `
+// The first two vec4s of the light uniform: world ambient, then the sun.
+struct _RzShadowSun { ambient: vec4f, direction: vec4f, }
+// The cascades' matrices, inner to outer, then every caster in one sphere
+// (x, y, z, radius): radius 0 = nothing casts, negative = do not test.
+struct _RzShadowBlock { viewProj: array<mat4x4f, ${n}>, casters: vec4f, }
+@group(${group}) @binding(${binding}) var<uniform> _rzShadowSun: _RzShadowSun;
+@group(${group}) @binding(${binding + 1}) var<uniform> _rzShadowVP: _RzShadowBlock;
+@group(${group}) @binding(${binding + 2}) var _rzShadowNear: texture_depth_2d;
+@group(${group}) @binding(${binding + 3}) var _rzShadowFar: texture_depth_2d;
+@group(${group}) @binding(${binding + 4}) var _rzShadowCmp: sampler_comparison;
+
+fn _rzShadowNearTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowNear", `1.0 / ${SHADOW_CASCADES[0].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn _rzShadowFarTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowFar", `1.0 / ${SHADOW_CASCADES[n - 1].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn rzShadow(p: vec3f) -> f32 {
+  // The scene's one shadow switch, on the sun — see sampleShadow.
+  let castAmt = _rzShadowSun.direction.w;
+  if (castAmt <= 0.0) { return 1.0; }
+  let toSun = normalize(-_rzShadowSun.direction.xyz);
+  // Can anything cast onto this point at all? The ground's test, for the same
+  // two reasons: most of a lawn is nowhere near her, and a scene with no
+  // models never renders the map, whose untouched zeroes compare as shadowed.
+  let cs = _rzShadowVP.casters;
+  if (cs.w == 0.0) { return 1.0; }
+  if (cs.w > 0.0) {
+    let toCaster = cs.xyz - p;
+    let along = dot(toCaster, toSun);
+    let perp = length(toCaster - toSun * along);
+    if (along <= -cs.w || perp > cs.w) { return 1.0; }
+  }
+  let q = p + toSun * 0.08;
+  let c0 = _rzShadowVP.viewProj[0] * vec4f(q, 1.0);
+  let n0 = c0.xyz / max(c0.w, 1e-6);
+  if (all(abs(n0.xy) < vec2f(0.98)) && n0.z > 0.0 && n0.z < 1.0) {
+    return mix(1.0, _rzShadowNearTaps(n0), castAmt);
+  }
+  let c1 = _rzShadowVP.viewProj[${n - 1}] * vec4f(q, 1.0);
+  let n1 = c1.xyz / max(c1.w, 1e-6);
+  if (all(abs(n1.xy) < vec2f(0.98)) && n1.z > 0.0 && n1.z < 1.0) {
+    return mix(1.0, _rzShadowFarTaps(n1), castAmt);
+  }
+  return 1.0;
+}
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.58.0",
+  "version": "0.58.1",
   "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

@@ -113,6 +113,7 @@ import {
 import {
   buildParticleComputeShader,
   buildParticleRenderShader,
+  PARTICLE_LIGHT_BINDING,
   particleEntryPoints,
   PARTICLE_STRIDE,
 } from "./shaders/passes/particles"
@@ -5300,7 +5301,7 @@ export class Engine {
     // Declaring one set of flags for both layouts is what made the pipeline
     // layout invalid, and the error surfaces later and unhelpfully as "invalid
     // due to a previous error".
-    const layoutFor = (storage: GPUBufferBindingType, visibility: number) =>
+    const layoutFor = (storage: GPUBufferBindingType, visibility: number, shadow: boolean) =>
       this.device.createBindGroupLayout({
         entries: [
           { binding: 0, visibility, buffer: { type: storage } },
@@ -5320,13 +5321,25 @@ export class Engine {
           // author calls it or not. With no grid it is the 1x1 of zeroes.
           { binding: 8, visibility, texture: { sampleType: "float" as const } },
           { binding: 9, visibility, sampler: { type: "filtering" as const } },
+          // The scene's light, for rzShadow and rzWorldAmbient — the shading
+          // stage only; the compute module compiles the stubs. See
+          // scene-light-api.ts.
+          ...(shadow
+            ? [
+                { binding: PARTICLE_LIGHT_BINDING, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" as const } },
+                { binding: PARTICLE_LIGHT_BINDING + 1, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" as const } },
+                { binding: PARTICLE_LIGHT_BINDING + 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "depth" as const } },
+                { binding: PARTICLE_LIGHT_BINDING + 3, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "depth" as const } },
+                { binding: PARTICLE_LIGHT_BINDING + 4, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "comparison" as const } },
+              ]
+            : []),
         ],
       })
     /** One per GRID PARITY, for the reason rebuildFieldBindGroup gives: the grid
      *  alternates which texture is current, and rebuilding a single group every
      *  frame is waste for a change that only ever toggles between two known
      *  states. Both entries are the same view when there is no grid. */
-    const bindFor = (layout: GPUBindGroupLayout, camera: GPUBuffer) =>
+    const bindFor = (layout: GPUBindGroupLayout, camera: GPUBuffer, shadow: boolean) =>
       [0, 1].map((parity) =>
         this.device.createBindGroup({
           layout,
@@ -5341,12 +5354,21 @@ export class Engine {
             ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
             { binding: 8, resource: grid ? grid.read[parity] : this.simFallbackView },
             { binding: 9, resource: this.simSampler },
+            ...(shadow
+              ? [
+                  { binding: PARTICLE_LIGHT_BINDING, resource: { buffer: this.lightUniformBuffer } },
+                  { binding: PARTICLE_LIGHT_BINDING + 1, resource: { buffer: this.shadowLightVPBuffer } },
+                  { binding: PARTICLE_LIGHT_BINDING + 2, resource: this.shadowMapDepthViews[0] },
+                  { binding: PARTICLE_LIGHT_BINDING + 3, resource: this.shadowMapDepthViews[SHADOW_CASCADES.length - 1] },
+                  { binding: PARTICLE_LIGHT_BINDING + 4, resource: this.shadowComparisonSampler },
+                ]
+              : []),
           ],
         }),
       ) as [GPUBindGroup, GPUBindGroup]
 
-    const computeLayout = layoutFor("storage", GPUShaderStage.COMPUTE)
-    const renderLayout = layoutFor("read-only-storage", GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT)
+    const computeLayout = layoutFor("storage", GPUShaderStage.COMPUTE, false)
+    const renderLayout = layoutFor("read-only-storage", GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, true)
 
     // Additive keeps the destination and adds to it, and leaves alpha alone, so
     // a glow does not claim coverage it never occluded. The MASK sums with it —
@@ -5422,16 +5444,16 @@ export class Engine {
           counts: uniformView.uints,
           compute,
           computeLayout,
-          computeBinds: bindFor(computeLayout, this.cameraUniformBuffer),
+          computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false),
           depth,
           render,
           renderLayout,
-          renderBinds: bindFor(renderLayout, this.cameraUniformBuffer),
-          mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer),
+          renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true),
+          mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true),
           rebind: () => ({
-            computeBinds: bindFor(computeLayout, this.cameraUniformBuffer),
-            renderBinds: bindFor(renderLayout, this.cameraUniformBuffer),
-            mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer),
+            computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false),
+            renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true),
+            mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true),
           }),
         },
       }
@@ -7387,8 +7409,10 @@ export class Engine {
       },
     })
 
+    // The matrices, then one vec4: the caster sphere, which effects' rzShadow
+    // tests before any tap. The materials and the ground bind the matrices only.
     this.shadowLightVPBuffer = this.device.createBuffer({
-      size: 64 * SHADOW_CASCADES.length,
+      size: 64 * SHADOW_CASCADES.length + 16,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
     this.shadowCascadeVPBuffers = SHADOW_CASCADES.map((_, i) =>
@@ -12380,6 +12404,22 @@ export class Engine {
     this.device.queue.writeBuffer(this.groundShadowMaterialBuffer, 40, gb.subarray(10, 11) as Float32Array<ArrayBuffer>)
   }
 
+  /** The caster sphere as last written after the cascade matrices; NaN so the
+   *  first frame always writes. */
+  private shadowCastersWritten = new Float32Array([NaN, NaN, NaN, NaN])
+
+  /**
+   * The same sphere, into the cascade block after its matrices — rzShadow's
+   * copy. There whether or not a ground exists: a lawn is often the only floor.
+   */
+  private writeShadowCasters(): void {
+    const w = this.shadowCastersWritten
+    const c = this.casterSphere
+    if (w[0] === c[0] && w[1] === c[1] && w[2] === c[2] && w[3] === c[3]) return
+    w.set(c)
+    this.device.queue.writeBuffer(this.shadowLightVPBuffer, 64 * SHADOW_CASCADES.length, c as Float32Array<ArrayBuffer>)
+  }
+
   /**
    * Push this frame's caster sphere into the ground's uniform.
    *
@@ -15376,6 +15416,7 @@ export class Engine {
     if (hasModels) this.dispatchCull(encoder)
     // After the cull, which is what recomputes the spheres it unions.
     this.writeGroundCasterSphere()
+    this.writeShadowCasters()
     this.writeGroundDress()
 
     // After the cull, because a rebuild there can reallocate the argument

package/src/shaders/lights.ts

@@ -38,6 +38,7 @@ import { midiApi } from "./midi-api"
 import { lyricsApi } from "./lyrics-api"
 import { clockApi, trailSlotsApi, viewportApi } from "./passes/hosted-api"
 import { idApi } from "./id-api"
+import { sceneLightApi, worldAmbientWgsl } from "./scene-light-api"
 
 /** Floats before the first record. One is the count; the rest keep the records
  *  vec4-aligned, which is what lets a future pass read them as vec4s. */
@@ -84,29 +85,8 @@ struct RzLight {
 }
 `
 
-/**
- * The world's light at a surface facing n — the flat colour, or the installed
- * HDRI's irradiance (sh[0].w = 1), evaluated from folded SH coefficients (see
- * ibl.ts for the folding; the shader is a plain polynomial in the normal).
- *
- * One string included by every module that declares LightUniforms with the sh
- * block — the hosted-api lesson: a helper defined in some modules and not
- * others is a compile error waiting for the first file that crosses them.
- */
-export const WORLD_AMBIENT_WGSL = /* wgsl */ `
-fn rzWorldAmbient(n: vec3f) -> vec3f {
-  if (light.sh[0].w < 0.5) { return light.ambientColor.xyz; }
-  let x = n.x;
-  let y = n.y;
-  let z = n.z;
-  let c = light.sh[0].xyz
-    + light.sh[1].xyz * y + light.sh[2].xyz * z + light.sh[3].xyz * x
-    + light.sh[4].xyz * (x * y) + light.sh[5].xyz * (y * z)
-    + light.sh[6].xyz * (3.0 * z * z - 1.0) + light.sh[7].xyz * (x * z)
-    + light.sh[8].xyz * (x * x - y * y);
-  return max(c, vec3f(0.0));
-}
-`
+/** rzWorldAmbient against the materials' and the ground's `light` uniform. */
+export const WORLD_AMBIENT_WGSL = worldAmbientWgsl("light")
 
 /** Does this source define the emit mount? */
 export function hasLightEmit(wgsl: string): boolean {
@@ -184,7 +164,7 @@ ${viewportApi("viewU[6].w")}
 ${trailSlotsApi(cast.trailCount)}
 // The id accessors, stubbed: this module cannot read an attachment the
 // scene pass writes. See id-api.ts — the author's whole file compiles here.
-${idApi(false, 0, 0) + castDistanceStub()}
+${idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0)}
 // The dials the author declared, if any. A lamp is exactly the thing someone
 // retunes — its colour and its reach — so an emitter reads params like every
 // other mount rather than being the one place a #param resolves to nothing.

package/src/shaders/materials/common.ts

@@ -1,6 +1,7 @@
 import { sceneFsOutWgsl } from "../passes/scene-contract"
 import { lightsApi } from "../lights"
 import { SHADOW_CASCADES } from "../../shadow-cascades"
+import { pcf9 } from "../scene-light-api"
 import { WORLD_AMBIENT_WGSL } from "../lights"
 
 // Shared WGSL blocks concatenated by every material shader.
@@ -175,8 +176,8 @@ fn safe_normal(nIn: vec3f) -> vec3f {
 `;
 
 // ─── Shadow sampler (3×3 PCF, cascade-selected) ─────────────────────
-// Normal-bias 0.08, depth-bias 0.001 NDC. Unrolled — Safari's Metal backend
-// doesn't unroll nested shadow loops reliably. Texel sizes are interpolated
+// Normal-bias 0.08, depth-bias 0.001 NDC; the kernel is pcf9 in scene-light-api.ts,
+// shared with effects. Texel sizes are interpolated
 // from SHADOW_CASCADES so they cannot go stale the way the hardcoded 1/2048
 // once did (PCF taps landed TWO texels apart after the map grew to 4096,
 // quantizing self-shadow edges into crawling gray squares).
@@ -188,21 +189,6 @@ fn safe_normal(nIn: vec3f) -> vec3f {
 // far plane the comparison failed against every stored depth, silently
 // shadowing any stage deeper than the box.
 
-const pcf9 = (map: string, ts: string) => /* wgsl */ `
-  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
-  let cmpZ = ndc.z - 0.001;
-  let ts = ${ts};
-  let s00 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);
-  let s10 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);
-  let s20 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, -ts), cmpZ);
-  let s01 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);
-  let s11 = textureSampleCompareLevel(${map}, shadowSampler, suv, cmpZ);
-  let s21 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);
-  let s02 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);
-  let s12 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);
-  let s22 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts,  ts), cmpZ);
-  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
-`
 
 const SAMPLE_SHADOW_WGSL = /* wgsl */ `
 

package/src/shaders/passes/composite.ts

@@ -6,6 +6,7 @@ import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewpor
 import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "../cast-layout"
 import { audioApi } from "../audio-api"
 import { idApi } from "../id-api"
+import { sceneLightApi } from "../scene-light-api"
 import { castDistanceApi, CAST_FIELD_DIV } from "./cast-distance"
 import { lyricsApi, lyricsTextApi } from "../lyrics-api"
 import { midiApi } from "../midi-api"
@@ -722,6 +723,7 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
     viewportApi("viewU[6].w") +
     trailSlotsApi(effect.trailCount) +
     idApi(effect.ids === true, 0, 23) +
+    sceneLightApi(false, 0, 0) +
     // Distance to the cast, in SCREEN pixels: the field is half-res, so a field
     // texel is CAST_FIELD_DIV of them and the accessor scales on the way out.
     // An author writes the width they mean and never learns how it is built.

package/src/shaders/passes/grid.ts

@@ -8,6 +8,7 @@ import { SCENE_TAP_STUB } from "../scene-tap"
 import { type CastLayout } from "./particles"
 import { clockApi, trailSlotsApi, viewportApi } from "./hosted-api"
 import { idApi } from "../id-api"
+import { sceneLightApi } from "../scene-light-api"
 
 // A persistent grid an effect can step and read: the one thing an effect could
 // not have before, which is MEMORY.
@@ -168,6 +169,7 @@ fn rzGrid(uv: vec2f) -> vec4f { return rzGridPrev(uv); }
     // Stubbed: this module cannot read an attachment the scene pass writes — see
     // id-api.ts. The author's whole file compiles here, so the names must exist.
     idApi(false, 0, 0) +
+    sceneLightApi(false, 0, 0) +
     // Inlined rather than imported from cast-distance, and NOT for tidiness.
     //
     // This module and composite.ts import each other — grid takes

package/src/shaders/passes/particles.ts

@@ -10,6 +10,7 @@ import { EFFECT_SUBJECT_VEC4S } from "../cast-layout"
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
 import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract"
 import { idApi } from "../id-api"
+import { sceneLightApi } from "../scene-light-api"
 // GPU particles for user effects: a compute step and an instanced quad draw.
 //
 // Its own shader MODULE rather than more source spliced into composite.ts, for
@@ -106,6 +107,9 @@ type ParticleSource = {
   gridSize: number
 }
 
+/** Where the shading stage's five scene-light bindings start — see scene-light-api.ts. */
+export const PARTICLE_LIGHT_BINDING = 10
+
 /** Bytes per particle. Explicitly padded — see the struct below. */
 export const PARTICLE_STRIDE = 48
 
@@ -207,7 +211,7 @@ ${src.paramsDecl}
     PRELUDE +
     // Stubbed: this module cannot read an attachment the scene pass writes — see
     // id-api.ts. The author's whole file compiles here, so the names must exist.
-    idApi(false, 0, 0) + castDistanceStub() +
+    idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `
@@ -282,6 +286,9 @@ ${src.paramsDecl}
     // Stubbed: this module cannot read an attachment the scene pass writes — see
     // id-api.ts. The author's whole file compiles here, so the names must exist.
     idApi(false, 0, 0) + castDistanceStub() +
+    // The sun's shadow and the world's ambient, for real: the shadow pass has
+    // run by the time this draws, inside the scene pass. See scene-light-api.ts.
+    sceneLightApi(true, 0, PARTICLE_LIGHT_BINDING) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `