reze-engine 0.42.3 → 0.50.0

package/src/shaders/audio-api.ts

@@ -0,0 +1,82 @@
+// The audio data interface, as WGSL — shared verbatim by every effect module.
+//
+// The buffer is PRECOMPUTED for the whole track and sampled by time, never fed
+// live from an AnalyserNode. That is not an optimisation: an export steps the
+// engine frame by frame instead of playing in real time, so a live analyser
+// would return silence during a render and every audio-reactive effect would
+// quietly vanish from the exported video — the same class of bug the scene
+// clock exists to prevent. Layout: an 8-float header [frames, bands,
+// secondsPerFrame, audioTime, playing, 3 spare] then per frame
+// [level, onset, band0..bandN-1]. audioTime and playing are rewritten every frame by
+// whoever owns playback — the editor's audio clock, the viewer's, or the export
+// loop — so "now" is always the clock that is actually running.
+//
+// Every module binds the SAME buffer, so a spawn rule in a particle effect and
+// a bar in a background read identical numbers for the same instant.
+
+/** The rzAudio* accessors, with the buffer declared at the given binding. */
+export function audioApi(group: number, binding: number): string {
+  return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzAudio: array<f32>;
+
+/** Frames of analysis available; 0 when the scene has no audio. */
+fn rzAudioFrames() -> i32 { return i32(_rzAudio[0]); }
+/** 1 while the track is actually PLAYING, 0 paused or absent — so an effect can
+ *  go calm instead of oscillating over a frozen spectrum. */
+fn rzAudioPlaying() -> f32 { return select(0.0, _rzAudio[4], i32(_rzAudio[0]) > 0); }
+/** Where the track is NOW, in seconds — the clock rzAudioLevelAt offsets hang
+ *  from. An effect that detects an onset k seconds back can anchor a ring to
+ *  the ABSOLUTE moment of the hit and age it continuously. */
+fn rzAudioTime() -> f32 { return _rzAudio[3]; }
+/** Bands per frame — log-spaced, bass first. */
+fn rzAudioBandCount() -> i32 { return i32(_rzAudio[1]); }
+
+fn _rzAudioFrameAt(offset: f32) -> i32 {
+  let frames = i32(_rzAudio[0]);
+  let t = _rzAudio[3] + offset;
+  return clamp(i32(t / max(_rzAudio[2], 1e-5)), 0, frames - 1);
+}
+
+/**
+ * Loudness at now + offset seconds, 0..1.
+ *
+ * The offset is what makes a WAVEFORM drawable: a column at x samples the
+ * envelope at (x - 0.5) * window seconds, and the playhead is the centre of the
+ * screen by construction. Offsets past either end clamp to the track's edges.
+ */
+fn rzAudioLevelAt(offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2)];
+}
+
+/**
+ * The KICK track: how hard the bass is rising at now + offset, 0..1 —
+ * precomputed, so a beat-triggered effect is one comparison instead of a
+ * per-pixel history scan. Scan a short window of NEGATIVE offsets to find
+ * recent hits and age things from them (quantise the hit to the analysis grid
+ * so ages stay continuous).
+ */
+fn rzAudioOnsetAt(offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2) + 1];
+}
+fn rzAudioOnset() -> f32 { return rzAudioOnsetAt(0.0); }
+/** Loudness now, 0..1. */
+fn rzAudioLevel() -> f32 { return rzAudioLevelAt(0.0); }
+
+/** Band i at now + offset seconds, 0..1. Band 0 is the deepest bass. */
+fn rzAudioBandAt(i: i32, offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  if (i < 0 || i >= bands) { return 0.0; }
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2) + 2 + i];
+}
+/** Band i now — the visualiser call. */
+fn rzAudioBand(i: i32) -> f32 { return rzAudioBandAt(i, 0.0); }
+`
+}

package/src/shaders/cast-api.ts

@@ -0,0 +1,123 @@
+// The cast, as data — the sibling of the audio and score interfaces, and shaped
+// like them: one shared buffer, read through accessors, never touched directly.
+//
+// WHY THIS FILE EXISTS. There were two of these. The field, grid and lightEmit
+// modules read the cast through one implementation; the particle and trail
+// modules read the SAME BUFFER through another, written separately, and the
+// particle one had no rzAnchor at all — so a particle effect could ask where a
+// trail had been but not where a wrist is. Neither was wrong; they had simply
+// never been the same code, and the split was invisible until an effect used a
+// mount from each family and its own file stopped compiling in one of them.
+//
+// The two differed only in how the layout reached them: one baked the engine's
+// constants, the other took them as a CastLayout. Every caller of that layout
+// passed the same five constants, so the parameterisation described a freedom
+// that did not exist. Baking them makes this a constant string, which is what
+// lets both families share it without either one deciding the shape.
+//
+// WHAT A HOST MUST SUPPLY. Three names, and deliberately only three:
+//
+//   _rzCast          the buffer, at whatever binding the module puts it on
+//   _rzSlot(i)       the effect's local slot → the scene's, from its alias
+//   rzSubjectCount() how many subjects are live
+//
+// The last is a host's because the two families genuinely disagree on it: the
+// field module reads a count the engine wrote into the view uniform, and the
+// particle module scans the buffer, because it has no view uniform to read.
+// They agree in value. Unifying them would be a behaviour change to every
+// shipped effect for no gain, so the seam stays and is named here instead.
+
+import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "./cast-layout"
+
+export const CAST_API = /* wgsl */ `
+const RZ_SUBJECTS: i32 = ${EFFECT_SUBJECTS};
+const RZ_SAMPLES: i32 = ${EFFECT_TRAIL_SAMPLES};
+/** The anchor ADDRESS SPACE — how many an effect may declare, not how many it
+ *  did. RZ_TRAIL_SLOTS is the per-effect number and is not this one; the two
+ *  being one number was the old trail bug. */
+const RZ_MAX_ANCHORS: i32 = ${EFFECT_ANCHORS};
+const RZ_TRAIL_SAMPLES: i32 = ${EFFECT_TRAIL_SAMPLES};
+
+struct RzSubject {
+  /** On the FLOOR, under the body — where a ring or a magic circle belongs. */
+  root: vec3f,
+  /** At the hips, the middle of the body — where an aura belongs. */
+  center: vec3f,
+  /** Bounding sphere: xyz centre, w radius. Deliberately generous — cull with it. */
+  bounds: vec4f,
+  /** False past the end of the cast, and every field is then zero. */
+  valid: bool,
+}
+
+struct RzAnchor {
+  pos: vec3f,
+  /** World units per second, from the previous frame. Direction for a trail,
+   *  magnitude for anything that should react to how hard someone is moving. */
+  vel: vec3f,
+  /** The bone's forward axis — which way a foot points, where a head looks. */
+  fwd: vec3f,
+  /** False when this rig has no such bone. Check it: the alternative is drawing
+   *  a hand effect at the world origin on every model that spells it differently. */
+  valid: bool,
+}
+
+/** Which model this is, stable across a scene — for per-subject variation. */
+fn rzSubjectId(i: i32) -> u32 {
+  if (i < 0 || i >= rzSubjectCount()) { return 0u; }
+  return u32(_rzCast[i * 3 + 1].w);
+}
+
+fn rzSubject(i: i32) -> RzSubject {
+  var s: RzSubject;
+  s.valid = i >= 0 && i < rzSubjectCount();
+  if (!s.valid) { return s; }
+  let b = i * 3;
+  s.root = _rzCast[b].xyz;
+  s.center = _rzCast[b + 1].xyz;
+  s.bounds = _rzCast[b + 2];
+  return s;
+}
+
+/**
+ * Where a named bone is, this frame.
+ *
+ * The slot is the author's own: the Nth @anchor in their file, in the order
+ * they wrote them. _rzSlot turns that into the scene's address, which is what
+ * keeps two effects that both anchor to a wrist from reading each other's.
+ */
+fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
+  var a: RzAnchor;
+  a.valid = false;
+  let g = _rzSlot(slot);
+  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }
+  let b = ${EFFECT_SUBJECTS * 3} + (g * ${EFFECT_SUBJECTS} + subject) * 3;
+  a.valid = _rzCast[b].w > 0.5;
+  a.pos = _rzCast[b].xyz;
+  a.vel = _rzCast[b + 1].xyz;
+  a.fwd = _rzCast[b + 2].xyz;
+  return a;
+}
+
+/**
+ * How many samples of a path are recorded — 0 for an anchor that asked for no
+ * trail, and for one that has not moved yet.
+ *
+ * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those
+ * are different index spaces: storage is addressed by anchor slot, so an
+ * untrailed @anchor followed by a trailed one put the trail at index 1 with a
+ * bound of 1 and rzTrail returned zero — a ribbon that silently did not draw.
+ */
+fn rzTrailCount(subject: i32, slot: i32) -> i32 {
+  let g = _rzSlot(slot);
+  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }
+  return i32(_rzCast[${EFFECT_SUBJECTS * 3} + (g * ${EFFECT_SUBJECTS} + subject) * 3 + 2].w);
+}
+
+/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */
+fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
+  let n = rzTrailCount(subject, slot);
+  if (i < 0 || i >= n) { return vec4f(0.0); }
+  let base = ${EFFECT_TRAIL_BASE} + (_rzSlot(slot) * ${EFFECT_SUBJECTS} + subject) * RZ_TRAIL_SAMPLES;
+  return _rzCast[base + i];
+}
+`

package/src/shaders/cast-layout.ts

@@ -0,0 +1,20 @@
+/**
+ * The caps the cast buffer is built to, shared by every shader that reads it and
+ * by the engine that fills it. Interpolated into the WGSL rather than written
+ * twice: the layout arithmetic on both sides has to agree exactly, and two
+ * literals that must match are two literals that eventually will not.
+ *
+ * All three are MINIMUMS. Raising one breaks nothing, because effects read
+ * through accessors and loop to the count functions; lowering one does.
+ *
+ * THEIR OWN FILE, and it imports nothing: cast-api.ts needs them to write the
+ * accessors, composite.ts needs them for the rest of its module, and cast-api
+ * is spliced into composite. Left where they were, that is an import cycle,
+ * and the first thing to touch the cycle throws ReferenceError at module load —
+ * the whole engine failing to start on an import order nobody chose.
+ */
+export const EFFECT_SUBJECTS = 4
+export const EFFECT_ANCHORS = 8
+export const EFFECT_TRAIL_SAMPLES = 128
+/** vec4 slot where the trails begin — after the subjects and the anchors. */
+export const EFFECT_TRAIL_BASE = EFFECT_SUBJECTS * 3 + EFFECT_ANCHORS * EFFECT_SUBJECTS * 3

package/src/shaders/lights.ts

@@ -0,0 +1,280 @@
+// Positional lights, as data — the sibling of the cast, audio and score
+// interfaces, and shaped like them: one shared buffer, read through accessors,
+// never touched directly.
+//
+// WHAT THIS IS NOT. The sun is still the ONE key light and it still owns the
+// toon ramp. These are an ADDITIVE layer on top of whatever the material's
+// graph decided, and they deliberately do not re-ramp: two ramped terminators
+// crossing a cheek read as plastic, which is the failure every stylised
+// 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. At this
+// count a flat loop in the fragment shader is cheaper than anything that would
+// avoid it, and the cap is what keeps that true.
+//
+// LAYOUT. A 4-float header (count, then padding that keeps the records
+// vec4-aligned), then MAX_LIGHTS records of 8 floats:
+//
+//   [0..2] position, world space      [3] radius
+//   [4..6] colour PREMULTIPLIED by intensity   [7] type
+//
+// 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. `type` is reserved — every light is a point light today
+// and the loop does not branch on it, so it is honest padding rather than a
+// switch with one case.
+
+import { audioApi } from "./audio-api"
+import { midiApi } from "./midi-api"
+import { lyricsApi } from "./lyrics-api"
+import { clockApi, trailSlotsApi, viewportApi } from "./passes/hosted-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
+/** Floats per light — see the layout above. */
+export const LIGHT_STRIDE = 8
+/**
+ * The cap, and it is a real one: the loop below runs per fragment, so this is
+ * the number that decides whether lights are free or a cost. Sixteen is the
+ * bounded middle tier the design settled on — enough for a stage rig, far below
+ * the point where clustering would start to pay for itself.
+ */
+export const MAX_LIGHTS = 16
+/** Floats in the whole buffer. */
+export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
+
+/**
+ * `// @lights 3` — how many lights this effect emits.
+ *
+ * Declared, like every other mount: what the file says is what gets allocated,
+ * so an effect that emits none costs no slots and nobody pays for a cap they
+ * did not ask for. Clamped rather than rejected, the same choice `@particles`
+ * makes — an author asking for a hundred gets the most the engine will give and
+ * a scene that still runs.
+ */
+export function parseLightCount(wgsl: string, max: number): number {
+  const m = /^\s*\/\/\s*@lights\s+(\d+)\s*$/m.exec(wgsl)
+  if (!m) return 0
+  return Math.max(1, Math.min(max, parseInt(m[1], 10)))
+}
+
+/**
+ * The RzLight struct, declared in EVERY module a user's source is spliced into.
+ *
+ * One effect file goes into every module it has a mount in, so a foreground
+ * effect that also emits lights compiles its lightEmit inside the FIELD shader
+ * too — where nothing calls it, but it still has to resolve. Leaving the struct
+ * out of those modules is a compile error on a function the author was right to
+ * write, which is the same trap the grid's step-only half documents.
+ */
+export const RZ_LIGHT_STRUCT_WGSL = /* wgsl */ `
+/** What an effect returns for one of its lights. */
+struct RzLight {
+  pos: vec3f,
+  color: vec3f,
+  intensity: f32,
+  radius: f32,
+}
+`
+
+/**
+ * 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));
+}
+`
+
+/** Does this source define the emit mount? */
+export function hasLightEmit(wgsl: string): boolean {
+  return /\bfn\s+lightEmit\s*\(/.test(wgsl)
+}
+
+/**
+ * The compute module that runs an effect's lightEmit once per light per frame.
+ *
+ *     fn lightEmit(i: u32, time: f32) -> RzLight
+ *
+ * A COMPUTE stage rather than a CPU callback, and that is the whole point:
+ * Fireworks knows where its bursts are as a closed form in WGSL, and mirroring
+ * that on the CPU to place a light would be two derivations of one trajectory
+ * that drift apart. Emitting in the shader means the light is wherever the
+ * effect says it is, on the scene clock — which is also what makes it survive
+ * an offline export frame-stepped at a different rate.
+ *
+ * The author writes local index 0..n-1 and never learns the global one, the
+ * same aliasing the anchor table uses — so installing another effect ahead of
+ * this one moves its lights without touching its source.
+ *
+ * The base arrives in the UNIFORM rather than baked into the text. Baking it
+ * would mean recompiling every emitting effect the moment a scene gained or
+ * lost a document light, because that is what shifts the slots underneath
+ * them — a shader rebuild triggered by moving a lamp.
+ *
+ * The scene API arrives as a STRING rather than being imported, so this module
+ * depends on nothing that depends on it. That API is what lets a lamp aim at
+ * someone: Stage Lights points its beams at rzSubject().root, and a light that
+ * did not know where she was could only sit where the fixture hangs. It also
+ * brings RzLight, which is why this builder does not declare it again.
+ */
+export function buildLightEmitShader(
+  wgsl: string,
+  sceneApi: string,
+  cast: { trailCount: number },
+): string {
+  return /* wgsl */ `
+// read_write HERE and read-only in the material shaders. Different passes, so
+// the two never coexist: this compute runs before the scene pass that reads it.
+@group(0) @binding(0) var<storage, read_write> _rzLightsOut: array<f32>;
+// (time, base slot, count, _) — see buildLightEmitShader on why the base is
+// here and not in the text.
+@group(0) @binding(1) var<uniform> _rzLightU: vec4f;
+// The camera block and the cast — the two buffers the scene API reads. Same
+// contents the field and grid modules bind, so an effect's lightEmit sees the
+// scene exactly as its drawing half does.
+@group(0) @binding(2) var<uniform> viewU: array<vec4<f32>, 15>;
+@group(0) @binding(3) var<storage, read> _rzCast: array<vec4f>;
+${sceneApi}
+// Audio and score at 4 and 5, the same bindings the particle and trail modules
+// put them on. A lamp that pulses on the beat or lights on a note is the whole
+// point of a light an effect owns rather than one the document places, so this
+// is not compile-safety padding — it is the mount's reason to exist.
+${audioApi(0, 4)}
+${midiApi(0, 5)}
+${lyricsApi(0, 6)}
+// The rest of the hosted API. Every one of these is here because the AUTHOR'S
+// WHOLE FILE lands below, not because lightEmit needs it: a trail effect that
+// grows a lamp at its tip compiles its ribbon code in this module too. The math
+// helpers and the Particle struct are NOT repeated — they arrive with the scene
+// API above, and a second copy is a redefinition error in engine code.
+${clockApi("_rzLightU.x", "0.0")}
+// Canvas height — the same number the drawing modules read out of their camera
+// struct, both written from canvas.height, so this name means ONE value in
+// every module. Verified against the writers, not assumed: cameraMatrixData[35]
+// and viewU[6].w have the same source.
+${viewportApi("viewU[6].w")}
+${trailSlotsApi(cast.trailCount)}
+${wgsl}
+
+@compute @workgroup_size(64)
+fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  // The dispatch is sized to the count, but a workgroup is 64 wide and the
+  // count rarely is — the tail must not write into the next effect's slots.
+  if (i >= u32(_rzLightU.z)) { return; }
+  // Time is a PARAMETER, not an rzTime() call: this same source compiles
+  // inside the field, particle, trail and grid modules, and those already
+  // define rzTime differently or not at all. A parameter needs nothing from
+  // the module it lands in, which is why the field mounts take theirs too.
+  let l = lightEmit(i, _rzLightU.x);
+  // SANITIZED at the one write site, because lightEmit is HOSTED USER CODE and
+  // this buffer feeds every fragment of every material: one NaN position would
+  // poison the whole frame, and WGSL leaves max(NaN, 0) indeterminate, so it
+  // would not even fail the same way on every GPU. A light that fails the
+  // check writes zeros — radius 0 is off. Colour is clamped at zero on top:
+  // this layer is ADDITIVE, and a negative channel would darken what it lands
+  // on and can push HDR negative into bloom.
+  let finite = l.pos.x == l.pos.x && l.pos.y == l.pos.y && l.pos.z == l.pos.z &&
+    l.radius == l.radius && l.intensity == l.intensity &&
+    l.color.x == l.color.x && l.color.y == l.color.y && l.color.z == l.color.z;
+  let c = select(vec3f(0.0), max(l.color * l.intensity, vec3f(0.0)), finite);
+  let b = ${LIGHT_HEADER}u + (u32(_rzLightU.y) + i) * ${LIGHT_STRIDE}u;
+  _rzLightsOut[b] = select(0.0, l.pos.x, finite);
+  _rzLightsOut[b + 1u] = select(0.0, l.pos.y, finite);
+  _rzLightsOut[b + 2u] = select(0.0, l.pos.z, finite);
+  _rzLightsOut[b + 3u] = select(0.0, max(l.radius, 0.0), finite);
+  // Colour carries intensity, exactly as the CPU writer stores it — one product,
+  // one place, so the two producers cannot disagree about what a slot means.
+  _rzLightsOut[b + 4u] = c.x;
+  _rzLightsOut[b + 5u] = c.y;
+  _rzLightsOut[b + 6u] = c.z;
+}
+`
+}
+
+/** The rz*Light accessors, with the buffer declared at the given binding. */
+export function lightsApi(group: number, binding: number): string {
+  return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzLights: array<f32>;
+
+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); }
+
+/** 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]);
+}
+
+/** 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]; }
+
+/** 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]);
+}
+
+/**
+ * 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.
+ *
+ * FALLOFF IS RELATIVE TO THE RADIUS, and deliberately not physical.
+ *
+ * The first version windowed a real inverse-square, and it was unusable: 1/d²
+ * is measured in world units, an MMD character is about 18 of them tall, so a
+ * lamp two metres off her shoulder divided by 37 and an intensity of 4 landed
+ * as 0.06 — invisible. Radius and intensity were fighting, and intensity had no
+ * scale a person could learn.
+ *
+ * So: intensity is the brightness AT the light, radius is where it reaches
+ * 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.
+ */
+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);
+    // 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, d / max(dist, 1e-4)), 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;
+    acc = acc + rzLightColor(i) * (ndl * falloff * falloff);
+  }
+  return acc;
+}
+`
+}