reze-engine 0.58.0 → 0.58.2

package/src/engine.ts

@@ -59,6 +59,7 @@ import {
   type SceneFormats,
 } from "./shaders/passes/scene-contract"
 import {
+  LIGHT_GRID_BASE,
   LIGHT_HEADER,
   LIGHT_STRIDE,
   LIGHTS_FLOATS,
@@ -66,6 +67,7 @@ import {
   buildLightEmitShader,
   hasLightEmit,
 } from "./shaders/lights"
+import { buildLightGrid } from "./light-grid"
 import { groundShaderWgsl, GROUND_NOISE_BAKE_WGSL, GROUND_NOISE_SIZE } from "./shaders/passes/ground"
 import { outlineShaderWgsl, RZ_OUTLINE_DISSOLVE_OFFSET } from "./shaders/passes/outline"
 import { transparentDepthPrepassWgsl } from "./shaders/passes/depth-prepass"
@@ -113,9 +115,13 @@ import {
 import {
   buildParticleComputeShader,
   buildParticleRenderShader,
+  PARTICLE_LIGHT_BINDING,
+  PARTICLE_POINTS_BINDING,
   particleEntryPoints,
   PARTICLE_STRIDE,
 } from "./shaders/passes/particles"
+import { MAX_EFFECT_POINTS, POINTS_FLOATS } from "./shaders/points-api"
+import { bonesWithPrefix, pointsData, writeBonePoint } from "./effect-points"
 import {
   SIM_FORMAT,
   GRID_MAX,
@@ -1446,6 +1452,10 @@ interface EffectParticles {
     renderBinds: [GPUBindGroup, GPUBindGroup]
     mirrorRenderBinds: [GPUBindGroup, GPUBindGroup]
   }
+  /** `#points`: the bone-name prefix and the buffer its matches are written
+   *  to each frame. Null when the effect declared none — it then reads the
+   *  engine's empty fallback. */
+  points: { prefix: string; buffer: GPUBuffer; data: Float32Array } | null
 }
 
 /**
@@ -2497,9 +2507,20 @@ export class Engine {
    *  Allocated once at full size and zero-filled, so "no lights" is a count of
    *  zero rather than an absent binding. */
   private lightsBuffer!: GPUBuffer
-  private lightsData!: Float32Array<ArrayBuffer>
-  /** Just the header, for rewriting the total without touching a record. */
+  /** What a particle effect with no `#points` reads at its points binding: a
+   *  count of zero. One buffer for all of them — nothing ever writes it. */
+  private pointsFallback!: GPUBuffer
+  /** Per model, per prefix, the bones `#points` matched. A rig's bones never
+   *  change after load, so the names are walked once rather than every frame. */
+  private pointBones = new WeakMap<Model, Map<string, number[]>>()
+  /** The CPU copy, from construction rather than init: a host sets a scene's
+   *  lamps as soon as its state exists, which can be before the device. */
+  private lightsData = new Float32Array(LIGHTS_FLOATS)
+  /** The same bytes as words — the grid's lamp bits are u32, not floats. */
+  private lightsWords = new Uint32Array(this.lightsData.buffer)
+  /** Just the header: the counts and the grid's placement. */
   private lightHeader = new Float32Array(LIGHT_HEADER)
+  private lightHeaderWords = new Uint32Array(this.lightHeader.buffer)
   /** How many of the slots belong to the DOCUMENT. Effects get what follows. */
   private docLightCount = 0
   private castData!: Float32Array<ArrayBuffer>
@@ -4863,6 +4884,7 @@ export class Engine {
       paramsBuffer?.destroy()
       particles?.buffer.destroy()
       particles?.uniform.destroy()
+      particles?.points?.buffer.destroy()
       grid?.textures[0].destroy()
       grid?.textures[1].destroy()
       grid?.uniform.destroy()
@@ -5247,6 +5269,17 @@ export class Engine {
       cover: particleEntryPoints(wgsl).cover,
     }
     const prepass = src.blend === "cutout" && src.cover
+    const points = d.points
+      ? {
+          prefix: d.points,
+          buffer: this.device.createBuffer({
+            label: `points "${d.points}"`,
+            size: POINTS_FLOATS * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+          }),
+          data: pointsData(),
+        }
+      : null
     // Sparks want to spawn where a trail is, so the particle stages see the same
     // cast buffer the trail draw reads.
     const cast = {
@@ -5273,9 +5306,15 @@ export class Engine {
     }
 
     const computeModule = await compile(buildParticleComputeShader(src, cast), "particle compute")
-    if (Array.isArray(computeModule)) return { ok: false, diagnostics: computeModule }
+    if (Array.isArray(computeModule)) {
+      points?.buffer.destroy()
+      return { ok: false, diagnostics: computeModule }
+    }
     const renderModule = await compile(buildParticleRenderShader(src, cast), "particle render")
-    if (Array.isArray(renderModule)) return { ok: false, diagnostics: renderModule }
+    if (Array.isArray(renderModule)) {
+      points?.buffer.destroy()
+      return { ok: false, diagnostics: renderModule }
+    }
 
     // COPY_DST so a scheduled effect can empty its pool when its window starts.
     const buffer = this.device.createBuffer({
@@ -5300,7 +5339,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 +5359,28 @@ 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 named points, ALWAYS, for the grid's reason: the accessor is
+          // compiled in whether or not the effect declared #points.
+          { binding: PARTICLE_POINTS_BINDING, visibility, buffer: { type: "read-only-storage" 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 +5395,22 @@ 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 },
+            { binding: PARTICLE_POINTS_BINDING, resource: { buffer: points?.buffer ?? this.pointsFallback } },
+            ...(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 —
@@ -5407,6 +5471,7 @@ export class Engine {
       if (scoped) {
         buffer.destroy()
         uniform.destroy()
+        points?.buffer.destroy()
         return { ok: false, diagnostics: [scoped.message] }
       }
       return {
@@ -5422,23 +5487,25 @@ 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),
           }),
+          points,
         },
       }
     } catch (e) {
       await this.device.popErrorScope()
       buffer.destroy()
       uniform.destroy()
+      points?.buffer.destroy()
       return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] }
     }
   }
@@ -5569,6 +5636,7 @@ export class Engine {
       this.device.queue.writeBuffer(e.lights.uniform, 0, e.lights.data.buffer as ArrayBuffer)
     }
     this.lightHeader[0] = Math.min(next, MAX_LIGHTS)
+    this.lightHeader[1] = this.docLightCount
     this.device.queue.writeBuffer(this.lightsBuffer, 0, this.lightHeader)
   }
 
@@ -5629,6 +5697,7 @@ export class Engine {
       p.counts[2] = p.count
       p.counts[3] = this.particleFrame++
       this.device.queue.writeBuffer(p.uniform, 0, p.data.buffer as ArrayBuffer)
+      if (p.points) this.writePoints(p.points)
       const cp = encoder.beginComputePass({ label: "particles" })
       cp.setPipeline(p.compute)
       cp.setBindGroup(0, p.computeBinds[e.grid?.parity ?? 0])
@@ -5637,6 +5706,35 @@ export class Engine {
     }
   }
 
+  /**
+   * Every bone matching an effect's `#points` prefix, on every visible model,
+   * posed and placed this frame. Every frame rather than on load: a candle a
+   * character carries moves with the hand, and a stage can be moved.
+   *
+   * The order is the models' order, then rig order — stable while nothing is
+   * added or removed, so particle i stays on point i and a flame does not
+   * jump to another wick between frames.
+   */
+  private writePoints(points: { prefix: string; buffer: GPUBuffer; data: Float32Array }): void {
+    let n = 0
+    for (const inst of this.modelInstances.values()) {
+      const m = inst.model
+      if (!m.visible) continue
+      let byPrefix = this.pointBones.get(m)
+      if (!byPrefix) this.pointBones.set(m, (byPrefix = new Map()))
+      let bones = byPrefix.get(points.prefix)
+      const rig = m.getSkeleton().bones
+      if (!bones) byPrefix.set(points.prefix, (bones = bonesWithPrefix(rig, points.prefix)))
+      for (const i of bones) {
+        if (n >= MAX_EFFECT_POINTS) break
+        const world = m.getBoneWorldMatrixAt(i)
+        if (world) writeBonePoint(points.data, n++, world, rig[i].tail, m)
+      }
+    }
+    points.data[0] = n
+    this.device.queue.writeBuffer(points.buffer, 0, points.data.buffer as ArrayBuffer, 0, (4 + n * 8) * 4)
+  }
+
   /** Draw the pool. Inside the scene pass, so it is depth-tested and pre-bloom. */
   private renderParticles(pass: GPURenderPassEncoder, view: "camera" | "mirror"): void {
     for (const e of this.effects) {
@@ -6029,6 +6127,7 @@ export class Engine {
     for (const e of this.effects) {
       e.particles?.buffer.destroy()
       e.particles?.uniform.destroy()
+      e.particles?.points?.buffer.destroy()
       e.particles = null
     }
   }
@@ -7387,8 +7486,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) =>
@@ -7464,15 +7565,21 @@ export class Engine {
 
     // BEFORE the bind group below, which binds it. Full size from the start:
     // every material pipeline binds this, so sizing it to the light count would
-    // mean rebuilding bind groups whenever a scene gained a lamp. Zero-filled,
-    // and float 0 is a count of 0.
-    this.lightsData = new Float32Array(LIGHTS_FLOATS)
+    // mean rebuilding bind groups whenever a scene gained a lamp. Uploaded from
+    // the CPU copy, which holds any lamps set before the device existed; the
+    // header after it, from the one writer that owns it.
     this.lightsBuffer = this.device.createBuffer({
       label: "positional lights",
       size: this.lightsData.byteLength,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
     })
     this.device.queue.writeBuffer(this.lightsBuffer, 0, this.lightsData)
+    this.allocateLightSlots()
+    this.pointsFallback = this.device.createBuffer({
+      label: "no points",
+      size: 16,
+      usage: GPUBufferUsage.STORAGE,
+    })
     // BEFORE the per-frame groups, which bind it. The composite needs this 1x1
     // stand-in too, and it used to be created with the composite's own
     // resources further down — far enough down that a material group built up
@@ -10023,6 +10130,20 @@ export class Engine {
       this.lightsData[b + 14] = 0
       this.lightsData[b + 15] = 0
     }
+    // The grid, from the records as STORED — normalised aim, clamped reach, the
+    // cosines in f32 — so it indexes exactly what the shader will evaluate.
+    const grid = buildLightGrid(
+      list.map((_, i) => {
+        const b = LIGHT_HEADER + i * LIGHT_STRIDE
+        const d = this.lightsData
+        return { x: d[b], y: d[b + 1], z: d[b + 2], radius: d[b + 3], ax: d[b + 8], ay: d[b + 9], az: d[b + 10], cosOuter: d[b + 11] }
+      }),
+    )
+    this.lightHeader.set(grid.origin, 4)
+    this.lightHeader[7] = 1 / grid.cell
+    this.lightHeaderWords.set(grid.dims, 8)
+    this.lightHeaderWords.set(grid.outside, 12)
+    this.lightsWords.set(grid.cells, LIGHT_GRID_BASE)
     // The CPU copy is written either way; only the upload needs a device. A
     // scene whose lamps arrive before init keeps them, and init uploads them.
     if (list.length && this.device && this.lightsBuffer) {
@@ -10033,6 +10154,13 @@ export class Engine {
         LIGHT_HEADER * 4,
         list.length * LIGHT_STRIDE * 4,
       )
+      this.device.queue.writeBuffer(
+        this.lightsBuffer,
+        LIGHT_GRID_BASE * 4,
+        this.lightsData.buffer as ArrayBuffer,
+        LIGHT_GRID_BASE * 4,
+        grid.cells.byteLength,
+      )
     }
     // The effects' bases move when the document's count does; the header —
     // count included — is written there.
@@ -12380,6 +12508,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 +15520,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/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