reze-engine 0.58.1 → 0.58.3

package/src/light-grid.ts

@@ -0,0 +1,139 @@
+import { LIGHT_GRID_CELLS, LIGHT_MASK_WORDS } from "./shaders/lights"
+
+// Which document lamps can reach which part of the world, so a fragment walks
+// only those.
+//
+// A uniform grid in WORLD space, built on the CPU whenever the document's lamps
+// change. Each cell holds one bit per lamp — 128 lamps is one vec4u — set when
+// the lamp's sphere, and its cone for a spot, can touch the cell. A fragment
+// finds its cell from its world position and loops the set bits.
+//
+// WORLD SPACE rather than screen tiles, because the answer then belongs to the
+// lamps and not to a camera: the mirror pass, an export at another resolution
+// and a preview all read the same grid with no per-view work, and it is rebuilt
+// only when a lamp moves, never per frame.
+//
+// THE BOX is where the lamps cluster — their positions padded by the median
+// reach — not the union of every sphere. One stage spot reaching 300 units
+// would otherwise stretch the box across the whole set, and a fixed cell budget
+// spread over it leaves cells wider than the small lamps they are meant to
+// separate. A lamp whose reach leaves the box also sets its bit in the OUTSIDE
+// mask, which is what a fragment beyond the box reads, so nothing is lost at
+// the edge; it is only coarser there.
+//
+// CONSERVATIVE, never exact: a bit may be set in a cell the lamp does not
+// light, never missing from one it does. A missing bit is a hole in the light;
+// a spare one is a few instructions.
+
+/** One document lamp, as the grid sees it. */
+export type GridLamp = {
+  x: number
+  y: number
+  z: number
+  radius: number
+  /** Unit aim, away from the lamp. Zero for a point lamp. */
+  ax: number
+  ay: number
+  az: number
+  /** Cosine of the half-angle. -1 for a point lamp, which covers everything. */
+  cosOuter: number
+}
+
+export type LightGrid = {
+  origin: [number, number, number]
+  /** Edge length of one cubic cell, world units. */
+  cell: number
+  dims: [number, number, number]
+  /** The lamps that reach past the box, for fragments outside it. */
+  outside: Uint32Array
+  /** LIGHT_MASK_WORDS words per cell, x fastest, then y, then z. */
+  cells: Uint32Array
+}
+
+function setBit(words: Uint32Array, base: number, lamp: number): void {
+  words[base + (lamp >> 5)] |= 1 << (lamp & 31)
+}
+
+export function buildLightGrid(lamps: GridLamp[], maxCells = LIGHT_GRID_CELLS): LightGrid {
+  const outside = new Uint32Array(LIGHT_MASK_WORDS)
+  const live = lamps
+    .map((l, i) => ({ l, i }))
+    .filter(({ l }) => l.radius > 0 && [l.x, l.y, l.z, l.radius].every(Number.isFinite))
+  if (!live.length) return { origin: [0, 0, 0], cell: 1, dims: [0, 0, 0], outside, cells: new Uint32Array(0) }
+
+  const radii = live.map(({ l }) => l.radius).sort((a, b) => a - b)
+  const pad = radii[radii.length >> 1]
+  const min = [Infinity, Infinity, Infinity]
+  const max = [-Infinity, -Infinity, -Infinity]
+  for (const { l } of live) {
+    const p = [l.x, l.y, l.z]
+    for (let k = 0; k < 3; k++) {
+      min[k] = Math.min(min[k], p[k] - pad)
+      max[k] = Math.max(max[k], p[k] + pad)
+    }
+  }
+  const extent = [max[0] - min[0], max[1] - min[1], max[2] - min[2]]
+  let cell = Math.cbrt((extent[0] * extent[1] * extent[2]) / maxCells)
+  let dims: [number, number, number]
+  // ceil() rounds every axis up, so the first guess can overshoot the budget by
+  // a few percent; widen the cell until it fits.
+  for (;;) {
+    dims = [0, 1, 2].map((k) => Math.max(1, Math.ceil(extent[k] / cell))) as [number, number, number]
+    if (dims[0] * dims[1] * dims[2] <= maxCells) break
+    cell *= 1.02
+  }
+  const cells = new Uint32Array(dims[0] * dims[1] * dims[2] * LIGHT_MASK_WORDS)
+  // Half the cell's diagonal: the sphere a spot's cone is tested against.
+  const halfDiagonal = (cell * Math.sqrt(3)) / 2
+
+  for (const { l, i } of live) {
+    // A hair of slack on the reach: the shader finds its cell in f32 from a
+    // reciprocal, the builder in f64 from a division, and a fragment on a cell
+    // face may land in either neighbour.
+    const r = l.radius + cell * 1e-4
+    const p = [l.x, l.y, l.z]
+    const lo = [0, 0, 0]
+    const hi = [0, 0, 0]
+    let leaves = false
+    for (let k = 0; k < 3; k++) {
+      const a = Math.floor((p[k] - r - min[k]) / cell)
+      const b = Math.floor((p[k] + r - min[k]) / cell)
+      if (a < 0 || b >= dims[k]) leaves = true
+      lo[k] = Math.max(a, 0)
+      hi[k] = Math.min(b, dims[k] - 1)
+    }
+    if (leaves) setBit(outside, 0, i)
+    if (lo[0] > hi[0] || lo[1] > hi[1] || lo[2] > hi[2]) continue
+
+    const spot = l.cosOuter > -1
+    const outer = Math.acos(Math.min(Math.max(l.cosOuter, -1), 1))
+    for (let z = lo[2]; z <= hi[2]; z++) {
+      for (let y = lo[1]; y <= hi[1]; y++) {
+        for (let x = lo[0]; x <= hi[0]; x++) {
+          const b0 = [min[0] + x * cell, min[1] + y * cell, min[2] + z * cell]
+          // The sphere against the cell's box: the nearest point of the box.
+          let d2 = 0
+          for (let k = 0; k < 3; k++) {
+            const q = Math.min(Math.max(p[k], b0[k]), b0[k] + cell)
+            d2 += (q - p[k]) * (q - p[k])
+          }
+          if (d2 > r * r) continue
+          if (spot) {
+            // The cone against the cell's bounding sphere: the cell can be lit
+            // when the angle to its centre is within the cone's half-angle plus
+            // the angle that sphere subtends.
+            const v = [b0[0] + cell / 2 - p[0], b0[1] + cell / 2 - p[1], b0[2] + cell / 2 - p[2]]
+            const len = Math.hypot(v[0], v[1], v[2])
+            if (len > halfDiagonal) {
+              const limit = outer + Math.asin(halfDiagonal / len)
+              const cos = (v[0] * l.ax + v[1] * l.ay + v[2] * l.az) / len
+              if (limit < Math.PI && Math.acos(Math.min(Math.max(cos, -1), 1)) > limit) continue
+            }
+          }
+          setBit(cells, ((z * dims[1] + y) * dims[0] + x) * LIGHT_MASK_WORDS, i)
+        }
+      }
+    }
+  }
+  return { origin: [min[0], min[1], min[2]], cell, dims, outside, cells }
+}

package/src/model.ts

@@ -140,6 +140,11 @@ export interface Bone {
   appendMove?: boolean
   /** 軸制限: this bone rotates ONLY about this axis (the twist bones use it). */
   fixedAxis?: [number, number, number]
+  /** Where the bone's tail sits at rest, as an offset from its head — the
+   *  direction a PMX editor draws it pointing. PMX states it either as that
+   *  offset or as another bone to point at; both arrive here as the offset.
+   *  An effect reading named points takes it as the point's length and way. */
+  tail?: [number, number, number]
   /** 変形階層: MMD poses whole layers in order, not bones in array order.
    *  Parsed but not yet honoured — distinct from Model's `deformOrder`, which is
    *  this engine's parent-before-child traversal. */
@@ -1096,6 +1101,13 @@ export class Model {
     return this.runtimeSkeleton.worldMatrices[idx].values
   }
 
+  /** A bone's posed matrix by INDEX — model space, column-major, the live
+   *  array. For walking bones that share a name, which the name lookup
+   *  collapses to one. Null past the end. */
+  getBoneWorldMatrixAt(index: number): Float32Array | null {
+    return this.runtimeSkeleton.worldMatrices[index]?.values ?? null
+  }
+
   // World bone origin (world matrix col3); unknown name → null
   getBoneWorldPosition(boneName: string): Vec3 | null {
     const idx = this.runtimeSkeleton.nameIndex[boneName]

package/src/pmx-loader.ts

@@ -357,6 +357,8 @@ export class PmxLoader {
         ikLinks?: IKLink[]
         fixedAxis?: [number, number, number]
         deformLayer?: number
+        tailOffset?: [number, number, number]
+        tailBone?: number
       }
       const abs: AbsBone[] = new Array(count)
       // PMX 2.x bone flags (best-effort common masks)
@@ -378,14 +380,14 @@ export class PmxLoader {
         const deformLayer = this.getInt32() // 変形階層
         const flags = this.getUint16()
 
-        // Tail: bone index or offset vector3
+        // Tail: bone index or offset vector3. Kept either way — the bone it
+        // names is resolved to an offset once every head is known.
+        let tailOffset: [number, number, number] | undefined
+        let tailBone: number | undefined
         if ((flags & FLAG_TAIL_IS_BONE) !== 0) {
-          this.getNonVertexIndex(this.boneIndexSize)
+          tailBone = this.getNonVertexIndex(this.boneIndexSize)
         } else {
-          // tail offset vec3
-          this.getFloat32()
-          this.getFloat32()
-          this.getFloat32()
+          tailOffset = [this.getFloat32(), this.getFloat32(), this.getFloat32()]
         }
 
         // Append transform (inherit/ratio)
@@ -475,10 +477,14 @@ export class PmxLoader {
           ikIteration,
           ikLimitAngle,
           ikLinks,
+          tailOffset,
+          tailBone,
         }
       }
       for (let i = 0; i < count; i++) {
         const a = abs[i]
+        const to = a.tailBone !== undefined && a.tailBone >= 0 && a.tailBone < count ? abs[a.tailBone] : null
+        const tail: [number, number, number] | undefined = to ? [to.x - a.x, to.y - a.y, to.z - a.z] : a.tailOffset
         const boneData: Bone = {
           name: a.name,
           parentIndex: a.parent,
@@ -497,6 +503,7 @@ export class PmxLoader {
           ikIteration: a.ikIteration,
           ikLimitAngle: a.ikLimitAngle,
           ikLinks: a.ikLinks,
+          ...(tail ? { tail } : {}),
         }
         bones.push(boneData)
       }

package/src/shaders/cast-layout.ts

@@ -23,8 +23,10 @@ export const EFFECT_SUBJECT_VEC4S = 4
  *
  * 8 was reachable, and quietly: two effects each wanting two hands, two feet and
  * a head is ten, so the second one silently lost its ribbons to a diagnostic
- * nobody was reading. 16 is double the headroom for 131KB of storage buffer,
- * where 8 cost 66KB.
+ * nobody was reading. 16 held until an effect traced a HAND: an outline through
+ * every finger reads fifteen bones a hand, thirty for the pair, before any other
+ * effect in the scene asks for one. 48 is that and room beside it, for 393KB of
+ * storage buffer where 16 cost 131KB.
  *
  * The cost really is only that. The per-frame upload is bounded by the last
  * TRAILED slot, not by this cap (see the writeBuffer in updateCastBuffer), so a
@@ -39,7 +41,7 @@ export const EFFECT_SUBJECT_VEC4S = 4
  * scene's anchor count grows, which is a different feature from raising a number
  * that was never load-bearing.
  */
-export const EFFECT_ANCHORS = 16
+export const EFFECT_ANCHORS = 48
 /**
  * Path samples kept per trailed anchor — 128 at the 60Hz sampling rate is a
  * ~2.1 second ribbon.

package/src/shaders/directives.ts

@@ -57,6 +57,9 @@ export type EffectDirectives = {
   particles: number
   lights: number
   grid: number
+  /** `#points <prefix>`: every bone on every model whose name starts with it,
+   *  as rzPoint(i) in the particle stages. Null when the file declares none. */
+  points: string | null
   bloom: boolean
   /** This effect takes the cast apart — the host reads the timing. */
   dissolve: boolean
@@ -111,6 +114,7 @@ const SPEC = {
   particles: 1,
   lights: 1,
   grid: 1,
+  points: 1,
   bloom: 0,
   dissolve: 0,
   mirror: 0,
@@ -168,6 +172,7 @@ export function parseDirectives(wgsl: string): DirectiveResult {
     particles: 0,
     lights: 0,
     grid: 0,
+    points: null,
     bloom: false,
     dissolve: false,
     ground: null,
@@ -285,6 +290,9 @@ export function parseDirectives(wgsl: string): DirectiveResult {
       case "dissolve":
         d.dissolve = true
         return
+      case "points":
+        d.points = args[0]
+        return
       case "mirror":
         d.mirror = true
         return

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.
@@ -39,10 +48,11 @@ 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
 /**
@@ -56,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.
@@ -164,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() + sceneLightApi(false, 0, 0)}
+${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.
@@ -229,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.
  *
@@ -287,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/passes/composite.ts

@@ -7,6 +7,7 @@ import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLE
 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"
@@ -724,6 +725,7 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
     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

@@ -9,6 +9,7 @@ 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.
@@ -170,6 +171,7 @@ fn rzGrid(uv: vec2f) -> vec4f { return rzGridPrev(uv); }
     // 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