reze-engine 0.56.9 → 0.56.11

package/dist/shaders/lights.js

@@ -10,21 +10,26 @@ import { SCENE_TAP_STUB } from "./scene-tap";
 // 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.
+// 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.
 //
 // LAYOUT. A 4-float header (count, then padding that keeps the records
-// vec4-aligned), then MAX_LIGHTS records of 8 floats:
+// vec4-aligned), then MAX_LIGHTS records of 16 floats — four vec4s:
 //
-//   [0..2] position, world space      [3] radius
+//   [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
 //
 // 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.
+// that can disagree.
+//
+// A POINT LIGHT IS A SPOT WITH NO CONE, and that is how the loop stays
+// branchless: it stores aim (0,0,0) and both cosines at -1, which makes the
+// cone term below saturate to exactly 1. `type` says which a light is for
+// anyone reading the buffer; the shading never asks.
 import { castDistanceStub } from "./passes/cast-distance";
 import { audioApi } from "./audio-api";
 import { midiApi } from "./midi-api";
@@ -35,14 +40,15 @@ import { idApi } from "./id-api";
  *  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;
+export const LIGHT_STRIDE = 16;
 /**
- * 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.
+ * The cap. The loop below runs per fragment over the lights a scene has, so
+ * this bounds the worst case rather than the ordinary one — and it has to clear
+ * a game stage: a Unity rip of one arrives with thirty-odd point lights, which
+ * the old ceiling of sixteen cut in half. Past this the extras are dropped.
+ * Clustering is what replaces it when a scene wants hundreds.
  */
-export const MAX_LIGHTS = 16;
+export const MAX_LIGHTS = 48;
 /** Floats in the whole buffer. */
 export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE;
 /**
@@ -199,6 +205,19 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
   _rzLightsOut[b + 4u] = c.x;
   _rzLightsOut[b + 5u] = c.y;
   _rzLightsOut[b + 6u] = c.z;
+  // An effect emits POINT lights: RzLight carries no aim, and widening it would
+  // fail to compile every emitter already written against it. The rest of the
+  // record is written anyway — these slots are reused frame to frame, and a spot
+  // the document placed here last frame would otherwise keep its cone.
+  _rzLightsOut[b + 7u] = 0.0;
+  _rzLightsOut[b + 8u] = 0.0;
+  _rzLightsOut[b + 9u] = 0.0;
+  _rzLightsOut[b + 10u] = 0.0;
+  _rzLightsOut[b + 11u] = -1.0;
+  _rzLightsOut[b + 12u] = -1.0;
+  _rzLightsOut[b + 13u] = 0.0;
+  _rzLightsOut[b + 14u] = 0.0;
+  _rzLightsOut[b + 15u] = 0.0;
 }
 `;
 }
@@ -228,6 +247,19 @@ fn rzLightColor(i: u32) -> vec3f {
   return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
 }
 
+/** 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]);
+}
+
+/** 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]);
+}
+
 /**
  * Every positional light's contribution at a surface point, as light — not as a
  * finished colour. Multiply by whatever the surface's albedo is.
@@ -257,14 +289,25 @@ fn rzLightsDiffuse(p: vec3f, n: vec3f) -> vec3f {
   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, d / max(dist, 1e-4)), 0.0);
+    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;
-    acc = acc + rzLightColor(i) * (ndl * falloff * falloff);
+    // 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);
   }
   return acc;
 }

package/dist/shaders/materials/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,oBAAoB,QAmIhC,CAAC;AAiIF,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAGD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,orMAgHzB,CAAA;AAQD,eAAO,MAAM,4BAA4B,QAC0D,CAAA"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,oBAAoB,QA4IhC,CAAC;AAiIF,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAGD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,orMAgHzB,CAAA;AAQD,eAAO,MAAM,4BAA4B,QAC0D,CAAA"}

package/dist/shaders/materials/common.js

@@ -28,7 +28,16 @@ struct CameraUniforms {
   view: mat4x4f,
   projection: mat4x4f,
   viewPos: vec3f,
-  _padding: f32,
+  /** Render-target height in device pixels. */
+  viewportHeight: f32,
+  /** The scene clock in seconds — what the time node reads. Paused with the
+   *  transport and stepped exactly by an export, so an animated material lands
+   *  in the file where it stood on screen. (No backticks in here: this WGSL
+   *  lives in a template literal and one would end it.) */
+  time: f32,
+  // NOTHING AFTER THIS. A trailing vec3f aligns to 16 and pushes the struct to
+  // 176 bytes against a 160-byte buffer, which fails validation on every
+  // pipeline at once; ending on the f32 rounds the struct to exactly 160.
 };
 
 struct Light {

package/dist/shaders/passes/cast-distance.d.ts

@@ -19,7 +19,11 @@ export declare const CAST_FIELD_DIV = 1;
  *
  * The ground, a stage and a media plane all write ids exactly as she does, so
  * seeding "anything drawn" would grow a border around the floor: a rectangle
- * round the frame rather than a sticker. Only the subject ids seed.
+ * round the frame rather than a sticker. The subject ids seed, and so do the
+ * props': a sword in her hand is part of her silhouette. A prop left out is a
+ * HOLE in the seeds wherever it covers her, and the field grows into it from
+ * her side, so the border ran round the inside of the prop instead of the
+ * outside.
  */
 export declare function buildCastSeedShader(samples: number): string;
 /**

package/dist/shaders/passes/cast-distance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cast-distance.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/cast-distance.ts"],"names":[],"mappings":"AA0CA;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;kEAEkE;AAClE,eAAO,MAAM,gBAAgB,EAAE,gBAA8B,CAAA;AAC7D;;8DAE8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,gBAA6B,CAAA;AAE5D;uDACuD;AACvD,eAAO,MAAM,oBAAoB,EAAE,gBAA4B,CAAA;AAE/D,iFAAiF;AACjF,eAAO,MAAM,cAAc,IAAI,CAAA;AAgB/B;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAyE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA4B5C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CA4B/C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAmC/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC"}
+{"version":3,"file":"cast-distance.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/cast-distance.ts"],"names":[],"mappings":"AA0CA;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;kEAEkE;AAClE,eAAO,MAAM,gBAAgB,EAAE,gBAA8B,CAAA;AAC7D;;8DAE8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,gBAA6B,CAAA;AAE5D;uDACuD;AACvD,eAAO,MAAM,oBAAoB,EAAE,gBAA4B,CAAA;AAE/D,iFAAiF;AACjF,eAAO,MAAM,cAAc,IAAI,CAAA;AAgB/B;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAqF3D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA4B5C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CA4B/C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAmC/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC"}

package/dist/shaders/passes/cast-distance.js

@@ -74,7 +74,11 @@ fn vs(@builtin(vertex_index) i: u32) -> VSOut {
  *
  * The ground, a stage and a media plane all write ids exactly as she does, so
  * seeding "anything drawn" would grow a border around the floor: a rectangle
- * round the frame rather than a sticker. Only the subject ids seed.
+ * round the frame rather than a sticker. The subject ids seed, and so do the
+ * props': a sword in her hand is part of her silhouette. A prop left out is a
+ * HOLE in the seeds wherever it covers her, and the field grows into it from
+ * her side, so the border ran round the inside of the prop instead of the
+ * outside.
  */
 export function buildCastSeedShader(samples) {
     return (
@@ -85,6 +89,9 @@ const RZ_ID_SAMPLES: i32 = ${samples};
 
 @group(0) @binding(0) var _rzIdTex: texture_multisampled_2d<u32>;
 @group(0) @binding(1) var<storage, read> _rzCast: array<vec4f>;
+/** The visible props' object ids, count first. Props are not subjects, so the
+ *  cast buffer does not carry them. */
+@group(0) @binding(2) var<storage, read> _rzSeedProps: array<u32>;
 
 // The two cast accessors this pass needs, spelled out rather than pulled in.
 // CAST_API brings subjects, trails, anchors and their aliases with it, and a
@@ -100,6 +107,17 @@ fn rzSubjectId(i: i32) -> u32 {
   if (i < 0 || i >= rzSubjectCount()) { return 0u; }
   return u32(_rzCast[i * ${EFFECT_SUBJECT_VEC4S} + 1].w);
 }
+/** Does this object seed the field: a subject, or a prop. */
+fn rzSeeds(o: u32, subjects: i32) -> bool {
+  for (var i = 0; i < subjects; i++) {
+    if (o == rzSubjectId(i)) { return true; }
+  }
+  let props = min(_rzSeedProps[0], arrayLength(&_rzSeedProps) - 1u);
+  for (var j = 1u; j <= props; j++) {
+    if (o == _rzSeedProps[j]) { return true; }
+  }
+  return false;
+}
 
 ${FULLSCREEN_VS}
 
@@ -133,9 +151,7 @@ fn fs(@builtin(position) pos: vec4f) -> SeedOut {
   for (var sample = 0; sample < RZ_ID_SAMPLES; sample++) {
     let o = textureLoad(_rzIdTex, p, sample).y;
     if (o == 0u) { continue; }
-    for (var i = 0; i < n; i++) {
-      if (o == rzSubjectId(i)) { covered += 1.0; break; }
-    }
+    if (rzSeeds(o, n)) { covered += 1.0; }
   }
   var out: SeedOut;
   out.coverage = covered / f32(RZ_ID_SAMPLES);
@@ -254,7 +270,7 @@ export function castDistanceApi(group, tex, samp, scale) {
  *
  * There is no ceiling. A pixel on the far side of the frame gets the real
  * number. The ground, a stage and a media plane are not the cast and do not
- * seed it.
+ * seed it. A prop does: what she holds is inside her border.
  *
  * Screen pixels whatever the field's own resolution is, so an author writes the
  * width they mean and never has to know how this is built. uv is the effect's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.56.9",
+  "version": "0.56.11",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -826,9 +826,10 @@ interface ModelInstance {
   /**
    * A PROP: a PMX object a character holds or wears — a microphone, a fan, a
    * sword. The third answer beside stage and plane. It keeps what a cast member
-   * has that scenery does not (physics, outlines, its own clip) and drops what
-   * makes one a performer: no effect subject id, no seeding of the scene clock,
-   * no bone picking. Like a card it leaves the floor alone. See addProp.
+   * has that scenery does not (physics, outlines, its own clip, a place in the
+   * cast's silhouette for rzCastDistance) and drops what makes one a performer:
+   * no effect subject id, no seeding of the scene clock, no bone picking. Like a
+   * card it leaves the floor alone. See addProp.
    */
   isProp: boolean
   /** Who this model hangs from, or null. Any model can: a prop by design, a
@@ -1593,6 +1594,23 @@ interface EffectInstance {
   trails: EffectTrails | null
 }
 
+/**
+ * A light the DOCUMENT places, as setLights takes it.
+ *
+ * `aim` is what separates the two kinds: with one the light is a spot pointing
+ * that way, without one it is a point light. Angles are the whole cone in
+ * degrees, the way a fixture and every DCC states them.
+ */
+export type SceneLight = {
+  position: XYZ
+  color: XYZ
+  intensity?: number
+  radius?: number
+  aim?: XYZ
+  angle?: number
+  innerAngle?: number
+}
+
 export class Engine {
   private static instance: Engine | null = null
 
@@ -1611,7 +1629,7 @@ export class Engine {
   // `!` field here is genuinely absent until init() — this one no longer is.
   private camera: Camera
   private cameraUniformBuffer!: GPUBuffer
-  private cameraMatrixData = new Float32Array(36)
+  private cameraMatrixData = new Float32Array(40)
   // Blender-style scene config groups (resolved from EngineOptions)
   private world!: { color: Vec3; strength: number }
   private sun!: { color: Vec3; strength: number; direction: Vec3 }
@@ -1993,6 +2011,10 @@ export class Engine {
   private castStepBindGroups: GPUBindGroup[] = []
   private castResolveBindGroup: GPUBindGroup | null = null
   private castStepStrideBuffers: GPUBuffer[] = []
+  /** The visible props' object ids for the seed pass, count in slot 0. Grown in
+   *  powers of two; see writeCastSeedProps. */
+  private castSeedPropBuffer: GPUBuffer | null = null
+  private castSeedPropData = new Uint32Array(8)
   /** Does anything installed actually read the field? Set from the effect list. */
   private castDistanceWanted = false
 
@@ -3690,14 +3712,7 @@ export class Engine {
     const strides: number[] = []
     for (let k = 1 << Math.ceil(Math.log2(Math.max(w, h))); k >= 1; k >>= 1) strides.push(k)
 
-    this.castSeedBindGroup = this.device.createBindGroup({
-      label: "cast distance seed",
-      layout: this.castSeedPipeline.getBindGroupLayout(0),
-      entries: [
-        { binding: 0, resource: this.idView! },
-        { binding: 1, resource: { buffer: this.castBuffer } },
-      ],
-    })
+    this.createCastSeedBindGroup()
     strides.forEach((stride, i) => {
       const buf = this.device!.createBuffer({
         label: `cast distance stride ${stride}`,
@@ -3729,6 +3744,59 @@ export class Engine {
     })
   }
 
+  /** The seed pass's inputs: the id attachment, the cast, and the prop ids. */
+  private createCastSeedBindGroup(): void {
+    const device = this.device!
+    if (!this.castSeedPropBuffer) {
+      this.castSeedPropBuffer = device.createBuffer({
+        label: "cast distance prop seeds",
+        size: this.castSeedPropData.byteLength,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      })
+      device.queue.writeBuffer(this.castSeedPropBuffer, 0, this.castSeedPropData)
+    }
+    this.castSeedBindGroup = device.createBindGroup({
+      label: "cast distance seed",
+      layout: this.castSeedPipeline!.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: this.idView! },
+        { binding: 1, resource: { buffer: this.castBuffer } },
+        { binding: 2, resource: { buffer: this.castSeedPropBuffer } },
+      ],
+    })
+  }
+
+  /**
+   * Which props seed the field this frame: every visible one.
+   *
+   * A prop is not a subject — nothing follows it and no effect reads its bones —
+   * but it is part of her silhouette. Uploaded only when the list changes.
+   */
+  private writeCastSeedProps(): void {
+    let n = 0
+    this.forEachInstance((inst) => {
+      if (inst.isProp && inst.model.visible) n++
+    })
+    let data = this.castSeedPropData
+    let changed = data[0] !== n
+    if (n + 1 > data.length) {
+      data = new Uint32Array(1 << Math.ceil(Math.log2(n + 1)))
+      this.castSeedPropData = data
+      this.castSeedPropBuffer?.destroy()
+      this.castSeedPropBuffer = null
+      this.createCastSeedBindGroup()
+      changed = true
+    }
+    data[0] = n
+    let i = 1
+    this.forEachInstance((inst) => {
+      if (!inst.isProp || !inst.model.visible) return
+      if (data[i] !== inst.objectId) changed = true
+      data[i++] = inst.objectId
+    })
+    if (changed) this.device!.queue.writeBuffer(this.castSeedPropBuffer!, 0, data)
+  }
+
   /**
    * The flood, encoded once a frame before the field pass reads it.
    *
@@ -3738,6 +3806,7 @@ export class Engine {
    */
   private encodeCastDistance(encoder: GPUCommandEncoder): void {
     if (!this.castDistanceWanted || !this.castSeedBindGroup || !this.castResolveBindGroup) return
+    this.writeCastSeedProps()
     const seed = encoder.beginRenderPass({
       label: "cast distance (seed)",
       colorAttachments: [
@@ -9325,12 +9394,17 @@ export class Engine {
    * keep the meaning the caller gave them, which is the same rule the anchor
    * table follows. Passing none (or an empty list) turns the layer off and the
    * scene renders exactly as it did before lights existed.
+   *
+   * A light with an `aim` is a SPOT: it reaches only inside `angle`, full
+   * inside `innerAngle`, and the two are degrees from the axis the way every
+   * tool states a cone. Without one it is a point light, which the shading
+   * spells as a cone that covers everything rather than as a second case.
    */
   setLights(
     /** Structural {x,y,z} rather than the Vec3 class, the same choice effect
      *  params make: a scene document's JSON passes straight in, and so does a
      *  literal typed into a console. Vec3 satisfies it either way. */
-    lights: { position: XYZ; color: XYZ; intensity?: number; radius?: number }[] | null,
+    lights: SceneLight[] | null,
   ): void {
     const list = (lights ?? []).slice(0, MAX_LIGHTS)
     this.docLightCount = list.length
@@ -9357,7 +9431,25 @@ export class Engine {
       this.lightsData[b + 4] = Math.max(l.color.x * k, 0)
       this.lightsData[b + 5] = Math.max(l.color.y * k, 0)
       this.lightsData[b + 6] = Math.max(l.color.z * k, 0)
-      // [b + 7] is `type`, reserved: every light is a point light today.
+      // A spot only where an aim was given AND it points somewhere: a zero
+      // vector cannot be normalised, and a cone around nothing would light
+      // nothing at all — a light that vanishes because its aim was left at the
+      // default is worse than one that shines everywhere.
+      const len = l.aim ? Math.hypot(l.aim.x, l.aim.y, l.aim.z) : 0
+      this.lightsData[b + 7] = len > 0 ? 1 : 0
+      this.lightsData[b + 8] = len > 0 ? l.aim!.x / len : 0
+      this.lightsData[b + 9] = len > 0 ? l.aim!.y / len : 0
+      this.lightsData[b + 10] = len > 0 ? l.aim!.z / len : 0
+      // Half-angles in degrees, as cosines. Ordered so the outer edge is never
+      // inside the inner one — a cone written the other way round would divide
+      // by a negative span and light its own rim instead of its middle.
+      const outer = len > 0 ? Math.cos((Math.min(Math.max(l.angle ?? 45, 0), 179) / 2) * (Math.PI / 180)) : -1
+      const inner = len > 0 ? Math.cos((Math.min(Math.max(l.innerAngle ?? (l.angle ?? 45) * 0.8, 0), 179) / 2) * (Math.PI / 180)) : -1
+      this.lightsData[b + 11] = outer
+      this.lightsData[b + 12] = Math.max(inner, outer)
+      this.lightsData[b + 13] = 0
+      this.lightsData[b + 14] = 0
+      this.lightsData[b + 15] = 0
     }
     if (list.length) {
       this.device.queue.writeBuffer(
@@ -9466,6 +9558,8 @@ export class Engine {
       inst.styleGroups.clear()
     })
     this.zeroStyleBuffer?.destroy()
+    this.castSeedPropBuffer?.destroy()
+    this.castSeedPropBuffer = null
     this.releaseCullBuffers()
     this.cullFrustaBuffer?.destroy()
     this.cullFrustaBuffer = null
@@ -15811,6 +15905,11 @@ export class Engine {
     // shader derives the full viewport (width via projection aspect) for its
     // babylon-mmd constant-pixel edge extrusion.
     this.cameraMatrixData[35] = this.canvas.height
+    // The SCENE clock, which is what a material may animate on: it pauses with
+    // the transport and an export steps it exactly, so a ripple is in the same
+    // place in the file as it was on screen. Wall time would drift between the
+    // two. The buffer was already allocated at 40 floats; this is one of them.
+    this.cameraMatrixData[36] = this.sceneClock
     this.device.queue.writeBuffer(this.cameraUniformBuffer, 0, this.cameraMatrixData)
 
     // 360 backdrop: the composite reconstructs each pixel's view ray from the

package/src/graph/registry.ts

@@ -132,6 +132,16 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     outputs: { color: "color", alpha: "float" },
     contextOutputs: { color: "tex_color", alpha: "tex_s.a" },
   },
+  // The scene clock, in seconds. A material is otherwise a function of position
+  // alone — this is what lets one SCROLL: ripples on water, a conveyor, a sign.
+  // It is the same clock the effects read, so a paused scene holds still and an
+  // export steps it frame by frame.
+  time: {
+    inputs: {},
+    outputs: { value: "float" },
+    contextOutputs: { value: "camera.time" },
+  },
+
   geometry: {
     inputs: {},
     outputs: {

package/src/index.ts

@@ -14,6 +14,7 @@ export {
   type MaterialPreset,
   type MaterialPresetMap,
   type ModelTransform,
+  type SceneLight,
   type ModelAttachment,
   type GizmoDragEvent,
   type GizmoDragCallback,

package/src/reflection.ts

@@ -156,5 +156,8 @@ export function buildMirrorCamera(
   out[33] = camera[33] - t * ny
   out[34] = camera[34] - t * nz
   out[35] = camera[35]
+  // The clock, unfolded: a mirrored draw of an animated material must be at the
+  // same instant as the one it reflects, or the ripples disagree across the pane.
+  out[36] = camera[36]
   return out
 }

package/src/shaders/lights.ts

@@ -10,21 +10,26 @@ import { SCENE_TAP_STUB } from "./scene-tap"
 // 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.
+// 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.
 //
 // LAYOUT. A 4-float header (count, then padding that keeps the records
-// vec4-aligned), then MAX_LIGHTS records of 8 floats:
+// vec4-aligned), then MAX_LIGHTS records of 16 floats — four vec4s:
 //
-//   [0..2] position, world space      [3] radius
+//   [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
 //
 // 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.
+// that can disagree.
+//
+// A POINT LIGHT IS A SPOT WITH NO CONE, and that is how the loop stays
+// branchless: it stores aim (0,0,0) and both cosines at -1, which makes the
+// cone term below saturate to exactly 1. `type` says which a light is for
+// anyone reading the buffer; the shading never asks.
 
 import { castDistanceStub } from "./passes/cast-distance"
 import { audioApi } from "./audio-api"
@@ -37,14 +42,15 @@ import { idApi } from "./id-api"
  *  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
+export const LIGHT_STRIDE = 16
 /**
- * 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.
+ * The cap. The loop below runs per fragment over the lights a scene has, so
+ * this bounds the worst case rather than the ordinary one — and it has to clear
+ * a game stage: a Unity rip of one arrives with thirty-odd point lights, which
+ * the old ceiling of sixteen cut in half. Past this the extras are dropped.
+ * Clustering is what replaces it when a scene wants hundreds.
  */
-export const MAX_LIGHTS = 16
+export const MAX_LIGHTS = 48
 /** Floats in the whole buffer. */
 export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
 
@@ -210,6 +216,19 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
   _rzLightsOut[b + 4u] = c.x;
   _rzLightsOut[b + 5u] = c.y;
   _rzLightsOut[b + 6u] = c.z;
+  // An effect emits POINT lights: RzLight carries no aim, and widening it would
+  // fail to compile every emitter already written against it. The rest of the
+  // record is written anyway — these slots are reused frame to frame, and a spot
+  // the document placed here last frame would otherwise keep its cone.
+  _rzLightsOut[b + 7u] = 0.0;
+  _rzLightsOut[b + 8u] = 0.0;
+  _rzLightsOut[b + 9u] = 0.0;
+  _rzLightsOut[b + 10u] = 0.0;
+  _rzLightsOut[b + 11u] = -1.0;
+  _rzLightsOut[b + 12u] = -1.0;
+  _rzLightsOut[b + 13u] = 0.0;
+  _rzLightsOut[b + 14u] = 0.0;
+  _rzLightsOut[b + 15u] = 0.0;
 }
 `
 }
@@ -240,6 +259,19 @@ fn rzLightColor(i: u32) -> vec3f {
   return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
 }
 
+/** 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]);
+}
+
+/** 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]);
+}
+
 /**
  * Every positional light's contribution at a surface point, as light — not as a
  * finished colour. Multiply by whatever the surface's albedo is.
@@ -269,14 +301,25 @@ fn rzLightsDiffuse(p: vec3f, n: vec3f) -> vec3f {
   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, d / max(dist, 1e-4)), 0.0);
+    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;
-    acc = acc + rzLightColor(i) * (ndl * falloff * falloff);
+    // 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);
   }
   return acc;
 }

package/src/shaders/materials/common.ts

@@ -31,7 +31,16 @@ struct CameraUniforms {
   view: mat4x4f,
   projection: mat4x4f,
   viewPos: vec3f,
-  _padding: f32,
+  /** Render-target height in device pixels. */
+  viewportHeight: f32,
+  /** The scene clock in seconds — what the time node reads. Paused with the
+   *  transport and stepped exactly by an export, so an animated material lands
+   *  in the file where it stood on screen. (No backticks in here: this WGSL
+   *  lives in a template literal and one would end it.) */
+  time: f32,
+  // NOTHING AFTER THIS. A trailing vec3f aligns to 16 and pushes the struct to
+  // 176 bytes against a 160-byte buffer, which fails validation on every
+  // pipeline at once; ending on the f32 rounds the struct to exactly 160.
 };
 
 struct Light {