reze-engine 0.58.0 → 0.58.2

package/src/shaders/lights.ts

@@ -11,18 +11,27 @@ import { subjectMaskApi } from "./cast-api"
 // renderer that bolted a second key light onto a toon shader has shipped. A
 // light here brightens; it does not restate the shading.
 //
-// So there are no per-light shadows, no area lights and no clustering. The loop
-// runs over the lights a scene HAS, not over the cap, so a scene with four pays
-// for four; the cap only bounds the buffer and the worst case.
+// So there are no per-light shadows and no area lights. A fragment walks the
+// DOCUMENT's lamps through a world-space grid (see light-grid.ts): its cell
+// names the lamps that can reach it, so a stage rig of fifty costs each pixel
+// the handful standing near it. The lamps an EFFECT emits are placed by a
+// compute pass every frame, which the grid never sees, and are walked in full.
 //
-// LAYOUT. A 4-float header (count, then padding that keeps the records
-// vec4-aligned), then MAX_LIGHTS records of 16 floats — four vec4s:
+// LAYOUT, in 32-bit words, read by the shader as vec4u. A 16-word header:
+//
+//   [0] light count (f32)       [1] how many are the document's (f32)
+//   [4..6] grid origin (f32)    [7] 1 / cell edge (f32)
+//   [8..10] grid dims (u32)     [12..15] the OUTSIDE mask (u32 bits)
+//
+// then MAX_LIGHTS records of 16 floats — four vec4s:
 //
 //   [0..2] position, world space               [3] radius
 //   [4..6] colour PREMULTIPLIED by intensity   [7] type
 //   [8..10] aim, unit, pointing away from the light   [11] cos of the outer angle
 //   [12] cos of the inner angle                [13..15] spare
 //
+// then the grid: LIGHT_MASK_WORDS words of lamp bits per cell.
+//
 // Colour carries intensity because nothing reads them apart: every use is the
 // product, and storing two numbers that are only ever multiplied is two numbers
 // that can disagree.
@@ -38,10 +47,12 @@ 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"
+import { pointsApi } from "./points-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. */
-export const LIGHT_HEADER = 4
+/** Words before the first record: the counts, the grid's placement and the
+ *  outside mask, four vec4s — see the layout above. */
+export const LIGHT_HEADER = 16
 /** Floats per light — see the layout above. */
 export const LIGHT_STRIDE = 16
 /**
@@ -55,15 +66,20 @@ export const LIGHT_STRIDE = 16
  * interior brings a hundred or more, and the ceilings of sixteen and then
  * forty-eight each cut a real scene in half. Past this the extras are dropped.
  *
- * What it does NOT buy: a scene that genuinely lights a fragment from a hundred
- * lamps pays for a hundred iterations of the loop. The distance test below
- * rejects most of them in a few instructions, which is what makes a rig of this
- * size affordable at all; clustering is what replaces the linear walk when a
- * scene wants every one of them close enough to matter.
+ * A fragment pays for the document lamps its grid cell names, so the cost
+ * follows how many reach a place rather than how many the scene holds. It is
+ * also why the cap is 128: one vec4u of bits per cell.
  */
 export const MAX_LIGHTS = 128
-/** Floats in the whole buffer. */
-export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
+/** Words of lamp bits per grid cell — one bit per lamp the cap allows. */
+export const LIGHT_MASK_WORDS = MAX_LIGHTS / 32
+/** The grid's cell budget. 32k cells over a stage a couple of hundred units
+ *  across is a cell of about four — finer than the lamps it separates. */
+export const LIGHT_GRID_CELLS = 32768
+/** Where the grid starts, in words. */
+export const LIGHT_GRID_BASE = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
+/** Words in the whole buffer: header, records, grid. */
+export const LIGHTS_FLOATS = LIGHT_GRID_BASE + LIGHT_GRID_CELLS * LIGHT_MASK_WORDS
 
 /**
  * The RzLight struct, declared in EVERY module a user's source is spliced into.
@@ -84,29 +100,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 +179,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) + pointsApi(false)}
 // 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.
@@ -249,51 +244,55 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
 
 /** The rz*Light accessors, with the buffer declared at the given binding. */
 export function lightsApi(group: number, binding: number): string {
+  const R = LIGHT_HEADER / 4
+  const S = LIGHT_STRIDE / 4
   return /* wgsl */ `
-@group(${group}) @binding(${binding}) var<storage, read> _rzLights: array<f32>;
+// vec4u, so a record is four loads and a cell's lamp bits are one. Floats come
+// out through bitcast; the bits must NOT pass through f32 on the way, where a
+// mask that happens to spell a NaN is not guaranteed to survive a load.
+@group(${group}) @binding(${binding}) var<storage, read> _rzLights: array<vec4u>;
 
 const RZ_MAX_LIGHTS: u32 = ${MAX_LIGHTS}u;
 
 /** How many positional lights the scene has. Zero is the ordinary case. */
-fn rzLightCount() -> u32 { return min(u32(_rzLights[0]), RZ_MAX_LIGHTS); }
+fn rzLightCount() -> u32 { return min(u32(bitcast<f32>(_rzLights[0].x)), RZ_MAX_LIGHTS); }
+
+/** How many of them the document placed — the ones the grid indexes. */
+fn _rzLightDocCount() -> u32 { return min(u32(bitcast<f32>(_rzLights[0].y)), rzLightCount()); }
+
+/** One vec4 of light i's record. */
+fn _rzLightVec(i: u32, k: u32) -> vec4f { return bitcast<vec4f>(_rzLights[${R}u + i * ${S}u + k]); }
 
 /** Light i's world position. */
-fn rzLightPos(i: u32) -> vec3f {
-  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u;
-  return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
-}
+fn rzLightPos(i: u32) -> vec3f { return _rzLightVec(i, 0u).xyz; }
 
 /** How far light i reaches. Its falloff is zero AT this distance, not merely
- *  small, so the light has a bound a cull can be derived from later. */
-fn rzLightRadius(i: u32) -> f32 { return _rzLights[${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 3u]; }
+ *  small, which is the bound the grid is built from. */
+fn rzLightRadius(i: u32) -> f32 { return _rzLightVec(i, 0u).w; }
 
 /** Light i's colour, already multiplied by its intensity. */
-fn rzLightColor(i: u32) -> vec3f {
-  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 4u;
-  return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
-}
+fn rzLightColor(i: u32) -> vec3f { return _rzLightVec(i, 1u).xyz; }
 
 /** Where light i points, away from itself. The zero vector for a point light. */
-fn rzLightAim(i: u32) -> vec3f {
-  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 8u;
-  return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
-}
+fn rzLightAim(i: u32) -> vec3f { return _rzLightVec(i, 2u).xyz; }
 
 /** The cosines a spot fades between: x its outer edge, y its inner one. A point
  *  light stores (-1, -1), which saturates the cone term to 1. */
-fn rzLightCone(i: u32) -> vec2f {
-  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 11u;
-  return vec2f(_rzLights[b], _rzLights[b + 1u]);
+fn rzLightCone(i: u32) -> vec2f { return vec2f(_rzLightVec(i, 2u).w, _rzLightVec(i, 3u).x); }
+
+/** The document lamps that can reach p: its grid cell's bits, or the outside
+ *  mask beyond the grid. Written so a NaN position fails the inside test. */
+fn _rzLightCellMask(p: vec3f) -> vec4u {
+  let g = bitcast<vec4f>(_rzLights[1]);
+  let dims = _rzLights[2].xyz;
+  let c = floor((p - g.xyz) * g.w);
+  if (!(all(c >= vec3f(0.0)) && all(c < vec3f(dims)))) { return _rzLights[3]; }
+  let ci = vec3u(c);
+  return _rzLights[${LIGHT_GRID_BASE / 4}u + (ci.z * dims.y + ci.y) * dims.x + ci.x];
 }
 
 /**
- * Every positional light's contribution at a surface point, as light — not as a
- * finished colour. Multiply by whatever the surface's albedo is.
- *
- * WITH NO LIGHTS THIS RETURNS EXACTLY ZERO and the loop never runs, so a scene
- * that declares none is arithmetically identical to one compiled before lights
- * existed. That is the property the whole feature is gated on: adding this to
- * every material must cost nothing until someone asks for a light.
+ * One light's contribution at a surface point.
  *
  * FALLOFF IS RELATIVE TO THE RADIUS, and deliberately not physical.
  *
@@ -307,33 +306,67 @@ fn rzLightCone(i: u32) -> vec2f {
  * zero, and the curve between them is the same shape whatever the scene's
  * scale. Both dials now mean what they say, which for a composer beats being
  * right about photons. (1 - t²)² — smooth at both ends, exactly 0 at the
- * radius, so the bound a cull could be derived from is still real.
+ * radius, so the bound the grid is built from is real.
+ */
+fn _rzLightOne(i: u32, p: vec3f, n: vec3f) -> vec3f {
+  let pr = _rzLightVec(i, 0u);
+  let d = pr.xyz - p;
+  let dist = length(d);
+  // Out of reach before anything else is computed. The grid is conservative —
+  // a cell's bit means the lamp CAN reach part of it — so this still runs.
+  if (dist >= pr.w) { return vec3f(0.0); }
+  let toLight = d / max(dist, 1e-4);
+  // Facing the light, and nothing behind it. No wrap or half-lambert: this
+  // layer adds light, and a wrapped term would lift the shadow side, which is
+  // the ramp's business and not this one's.
+  let ndl = max(dot(n, toLight), 0.0);
+  if (ndl <= 0.0) { return vec3f(0.0); }
+  let t = clamp(dist / max(pr.w, 1e-4), 0.0, 1.0);
+  let falloff = 1.0 - t * t;
+  // How far inside the cone this point sits: 1 within the inner angle, 0 past
+  // the outer one, squared for the same soft edge the falloff has. A point
+  // light's (-1, -1) divides by the floor and clamps to 1, so it pays one
+  // dot product and no branch.
+  let cone = rzLightCone(i);
+  let aim = clamp((dot(-toLight, rzLightAim(i)) - cone.x) / max(cone.y - cone.x, 1e-4), 0.0, 1.0);
+  return rzLightColor(i) * (ndl * falloff * falloff * aim * aim);
+}
+
+/** The lamps named by one word of a cell's bits, lowest first. */
+fn _rzLightWord(bits0: u32, base: u32, p: vec3f, n: vec3f) -> vec3f {
+  var acc = vec3f(0.0);
+  var bits = bits0;
+  loop {
+    if (bits == 0u) { break; }
+    let i = base + firstTrailingBit(bits);
+    bits = bits & (bits - 1u);
+    acc = acc + _rzLightOne(i, p, n);
+  }
+  return acc;
+}
+
+/**
+ * Every positional light's contribution at a surface point, as light — not as a
+ * finished colour. Multiply by whatever the surface's albedo is.
+ *
+ * WITH NO LIGHTS THIS RETURNS EXACTLY ZERO and neither walk runs, so a scene
+ * that declares none is arithmetically identical to one compiled before lights
+ * existed. That is the property the whole feature is gated on: adding this to
+ * every material must cost nothing until someone asks for a light.
  */
 fn rzLightsDiffuse(p: vec3f, n: vec3f) -> vec3f {
   var acc = vec3f(0.0);
   let count = rzLightCount();
-  for (var i = 0u; i < count; i = i + 1u) {
-    let d = rzLightPos(i) - p;
-    let dist = length(d);
-    // Out of reach before anything else is computed. The falloff is already
-    // exactly zero at the radius, so this changes no pixel — it is what keeps a
-    // stage rig's far lamps off the bill at every fragment they do not light.
-    if (dist >= rzLightRadius(i)) { continue; }
-    let toLight = d / max(dist, 1e-4);
-    // Facing the light, and nothing behind it. No wrap or half-lambert: this
-    // layer adds light, and a wrapped term would lift the shadow side, which is
-    // the ramp's business and not this one's.
-    let ndl = max(dot(n, toLight), 0.0);
-    if (ndl <= 0.0) { continue; }
-    let t = clamp(dist / max(rzLightRadius(i), 1e-4), 0.0, 1.0);
-    let falloff = 1.0 - t * t;
-    // How far inside the cone this point sits: 1 within the inner angle, 0 past
-    // the outer one, squared for the same soft edge the falloff has. A point
-    // light's (-1, -1) divides by the floor and clamps to 1, so it pays one
-    // dot product and no branch.
-    let cone = rzLightCone(i);
-    let aim = clamp((dot(-toLight, rzLightAim(i)) - cone.x) / max(cone.y - cone.x, 1e-4), 0.0, 1.0);
-    acc = acc + rzLightColor(i) * (ndl * falloff * falloff * aim * aim);
+  let docs = _rzLightDocCount();
+  // The document's lamps: only those the grid says can reach this cell.
+  if (docs > 0u) {
+    let m = _rzLightCellMask(p);
+    acc = acc + _rzLightWord(m.x, 0u, p, n) + _rzLightWord(m.y, 32u, p, n) +
+      _rzLightWord(m.z, 64u, p, n) + _rzLightWord(m.w, 96u, p, n);
+  }
+  // The effects' lamps, which move every frame on the GPU: all of them.
+  for (var i = docs; i < count; i = i + 1u) {
+    acc = acc + _rzLightOne(i, p, n);
   }
   return acc;
 }

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,8 @@ 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 { pointsApi } from "../points-api"
 import { castDistanceApi, CAST_FIELD_DIV } from "./cast-distance"
 import { lyricsApi, lyricsTextApi } from "../lyrics-api"
 import { midiApi } from "../midi-api"
@@ -722,6 +724,8 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
     viewportApi("viewU[6].w") +
     trailSlotsApi(effect.trailCount) +
     idApi(effect.ids === true, 0, 23) +
+    sceneLightApi(false, 0, 0) +
+    pointsApi(false) +
     // 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,8 @@ 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"
+import { pointsApi } from "../points-api"
 
 // A persistent grid an effect can step and read: the one thing an effect could
 // not have before, which is MEMORY.
@@ -168,6 +170,8 @@ 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) +
+    pointsApi(false) +
     // 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,8 @@ 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"
+import { pointsApi } from "../points-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 +108,11 @@ 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
+/** The effect's named points (`#points`), in both stages — see points-api.ts. */
+export const PARTICLE_POINTS_BINDING = 15
+
 /** Bytes per particle. Explicitly padded — see the struct below. */
 export const PARTICLE_STRIDE = 48
 
@@ -207,7 +214,9 @@ ${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) +
+    // The named points, for real: particleInit is where a flame is put on a wick.
+    pointsApi(true, 0, PARTICLE_POINTS_BINDING) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `
@@ -282,6 +291,10 @@ ${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) +
+    pointsApi(true, 0, PARTICLE_POINTS_BINDING) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `

package/src/shaders/passes/trails.ts

@@ -10,6 +10,8 @@ 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"
+import { pointsApi } from "../points-api"
 // Ribbons along a bone's recorded path, drawn as geometry.
 //
 // This is the effect the whole geometry path was built for. As a fullscreen
@@ -301,7 +303,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) + pointsApi(false) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `

package/src/shaders/points-api.ts

@@ -0,0 +1,66 @@
+// Named points on the models, for an effect that puts something at each one.
+//
+//     #points flame
+//
+// gives the effect every bone whose name starts with `flame`, on every model in
+// the scene — a stage, its parts, a prop, a character — as RzPoint: where the
+// bone stands and where its tail points, in world space, this frame. A candle
+// stage carries a bone per wick; a flame effect draws one flame on each, sized
+// and stood up by the tail.
+//
+// BONES, because a bone is MMD's own word for a named point in a model. A stage
+// that brings its candles as bones needs no side file, a hand-made stage can
+// add them in any PMX editor, and a candle a character carries moves with the
+// hand that holds it.
+//
+// Not the cast's anchors: those name up to sixteen bones on four characters,
+// one bone per name. A stage is not a character, and fifty wicks share a
+// prefix rather than each having a name worth declaring.
+
+/** How many points one effect can read. A candlelit hall is fifty. */
+export const MAX_EFFECT_POINTS = 256
+
+/** Floats in a points buffer: a vec4 header (count), then two vec4s a point. */
+export const POINTS_FLOATS = 4 + MAX_EFFECT_POINTS * 8
+
+const STRUCT = /* wgsl */ `
+/** One named point: where the bone stands, and where its tail points to. */
+struct RzPoint {
+  pos: vec3f,
+  tip: vec3f,
+}
+`
+
+/**
+ * rzPointCount / rzPoint. `bound` is false in every module that cannot read the
+ * buffer — the author's whole file is spliced into each module it has a mount
+ * in, so the names must resolve there too, and there they read as no points.
+ */
+export function pointsApi(bound: boolean, group = 0, binding = 0): string {
+  if (!bound) {
+    return (
+      STRUCT +
+      /* wgsl */ `
+fn rzPointCount() -> u32 { return 0u; }
+fn rzPoint(i: u32) -> RzPoint { var p: RzPoint; return p; }
+`
+    )
+  }
+  return (
+    STRUCT +
+    /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzPoints: array<vec4f>;
+
+/** How many named points the scene has for this effect, this frame. */
+fn rzPointCount() -> u32 { return min(u32(_rzPoints[0].x), ${MAX_EFFECT_POINTS}u); }
+
+/** Point i, world space. */
+fn rzPoint(i: u32) -> RzPoint {
+  var p: RzPoint;
+  p.pos = _rzPoints[1u + i * 2u].xyz;
+  p.tip = _rzPoints[2u + i * 2u].xyz;
+  return p;
+}
+`
+  )
+}

package/src/shaders/scene-light-api.ts

@@ -0,0 +1,148 @@
+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: string) => /* 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: string, ts: string, 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: boolean, group: number, binding: number): string {
+  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")}`
+}