reze-engine 0.58.0 → 0.58.2

package/dist/shaders/cast-api.d.ts

@@ -1,4 +1,4 @@
-export declare const CAST_API = "\nconst RZ_SUBJECTS: i32 = 4;\nconst RZ_SAMPLES: i32 = 128;\n/** The anchor ADDRESS SPACE \u2014 how many an effect may declare, not how many it\n *  did. RZ_TRAIL_SLOTS is the per-effect number and is not this one; the two\n *  being one number was the old trail bug. */\nconst RZ_MAX_ANCHORS: i32 = 16;\nconst RZ_TRAIL_SAMPLES: i32 = 128;\n\nstruct RzSubject {\n  /** On the FLOOR, under the body \u2014 where a ring or a magic circle belongs. */\n  root: vec3f,\n  /** At the hips, the middle of the body \u2014 where an aura belongs. */\n  center: vec3f,\n  /** Bounding sphere: xyz centre, w radius. Deliberately generous \u2014 cull with it. */\n  bounds: vec4f,\n  /**\n   * How much of this character is still THERE: 1 whole, 0 gone.\n   *\n   * What setModelDissolve last set on them, which the material pass has already\n   * acted on by the time an effect runs \u2014 so an effect drawing what LEAVES a\n   * dissolving body (sparks, ash, a ghost) reads the same number the body was\n   * taken apart with, rather than keeping a clock of its own and hoping the two\n   * agree. 1 on a scene that never dissolves anybody.\n   */\n  dissolve: f32,\n  /**\n   * Where she LOOKS: a unit direction from between the eyes, in world space.\n   * Exact while her eyes are on something (Engine.setEyeTracking); otherwise\n   * the motion's own eye turn undone through the range map \u2014 an eye bone\n   * turns a fraction of the way toward what it looks at, and this gives back\n   * the whole of it. An effect that should go where the look goes \u2014 a beam,\n   * a light \u2014 takes this rather than an eye bone's axis, and it holds in\n   * either mode. Zero, with looking false, only for a model without eyes.\n   */\n  gaze: vec3f,\n  looking: bool,\n  /** False past the end of the cast, and every field is then zero. */\n  valid: bool,\n}\n\nstruct RzAnchor {\n  pos: vec3f,\n  /** World units per second, from the previous frame. Direction for a trail,\n   *  magnitude for anything that should react to how hard someone is moving. */\n  vel: vec3f,\n  /** The bone's forward axis \u2014 which way a foot points, where a head looks. */\n  fwd: vec3f,\n  /** False when this rig has no such bone. Check it: the alternative is drawing\n   *  a hand effect at the world origin on every model that spells it differently. */\n  valid: bool,\n}\n\n/**\n * How many characters THIS EFFECT is on, up to four.\n *\n * Not how many the scene holds. An effect applies to the whole cast unless the\n * scene says otherwise (Engine.setEffectSubjects), and where it says otherwise\n * this counts only the models named \u2014 so an effect aimed at one dancer sees one\n * subject, at index 0, and an author who wrote a loop over the cast gets the\n * targeting for free.\n *\n * Which is the whole design: the FILTER IS IN THE INDEX SPACE, not in the\n * shaders. There is no mask an effect can read, because an effect asking \"am I\n * allowed on this one\" is an effect that can get the answer wrong, and 18 of the\n * shipped built-ins would have had to be rewritten to ask at all.\n */\nfn rzSubjectCount() -> i32 {\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var i = 0; i < live; i++) {\n    if ((mask & (1u << u32(i))) != 0u) { n++; }\n  }\n  return n;\n}\n\n/** This effect's i-th subject \u2192 the scene's slot, or -1 past its own count.\n *  Every accessor below goes through it, which is what keeps one effect's\n *  subject 1 from being another's. */\nfn _rzSubjectSlot(i: i32) -> i32 {\n  if (i < 0) { return -1; }\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var s = 0; s < live; s++) {\n    if ((mask & (1u << u32(s))) == 0u) { continue; }\n    if (n == i) { return s; }\n    n++;\n  }\n  return -1;\n}\n\n/** Which model this is, stable across a scene \u2014 for per-subject variation. */\nfn rzSubjectId(i: i32) -> u32 {\n  let g = _rzSubjectSlot(i);\n  if (g < 0) { return 0u; }\n  return u32(_rzCast[g * 4 + 1].w);\n}\n\nfn rzSubject(i: i32) -> RzSubject {\n  var s: RzSubject;\n  let g = _rzSubjectSlot(i);\n  s.valid = g >= 0;\n  if (!s.valid) { return s; }\n  let b = g * 4;\n  s.root = _rzCast[b].xyz;\n  s.dissolve = _rzCast[b].w;\n  s.center = _rzCast[b + 1].xyz;\n  s.bounds = _rzCast[b + 2];\n  s.gaze = _rzCast[b + 3].xyz;\n  s.looking = _rzCast[b + 3].w > 0.5;\n  return s;\n}\n\n/**\n * Where a named bone is, this frame.\n *\n * The slot is the author's own: the Nth #anchor in their file, in the order\n * they wrote them. _rzSlot turns that into the scene's address, which is what\n * keeps two effects that both anchor to a wrist from reading each other's.\n */\nfn rzAnchor(subject: i32, slot: i32) -> RzAnchor {\n  var a: RzAnchor;\n  a.valid = false;\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }\n  let b = 16 + (g * 4 + s) * 3;\n  a.valid = _rzCast[b].w > 0.5;\n  a.pos = _rzCast[b].xyz;\n  a.vel = _rzCast[b + 1].xyz;\n  a.fwd = _rzCast[b + 2].xyz;\n  return a;\n}\n\n/**\n * How many samples of a path are recorded \u2014 0 for an anchor that asked for no\n * trail, and for one that has not moved yet.\n *\n * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those\n * are different index spaces: storage is addressed by anchor slot, so an\n * untrailed #anchor followed by a trailed one put the trail at index 1 with a\n * bound of 1 and rzTrail returned zero \u2014 a ribbon that silently did not draw.\n */\nfn rzTrailCount(subject: i32, slot: i32) -> i32 {\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }\n  return i32(_rzCast[16 + (g * 4 + s) * 3 + 2].w);\n}\n\n/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */\nfn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {\n  let n = rzTrailCount(subject, slot);\n  if (i < 0 || i >= n) { return vec4f(0.0); }\n  let base = 208 + (_rzSlot(slot) * 4 + _rzSubjectSlot(subject)) * RZ_TRAIL_SAMPLES;\n  return _rzCast[base + i];\n}\n";
+export declare const CAST_API = "\nconst RZ_SUBJECTS: i32 = 4;\nconst RZ_SAMPLES: i32 = 128;\n/** The anchor ADDRESS SPACE \u2014 how many an effect may declare, not how many it\n *  did. RZ_TRAIL_SLOTS is the per-effect number and is not this one; the two\n *  being one number was the old trail bug. */\nconst RZ_MAX_ANCHORS: i32 = 48;\nconst RZ_TRAIL_SAMPLES: i32 = 128;\n\nstruct RzSubject {\n  /** On the FLOOR, under the body \u2014 where a ring or a magic circle belongs. */\n  root: vec3f,\n  /** At the hips, the middle of the body \u2014 where an aura belongs. */\n  center: vec3f,\n  /** Bounding sphere: xyz centre, w radius. Deliberately generous \u2014 cull with it. */\n  bounds: vec4f,\n  /**\n   * How much of this character is still THERE: 1 whole, 0 gone.\n   *\n   * What setModelDissolve last set on them, which the material pass has already\n   * acted on by the time an effect runs \u2014 so an effect drawing what LEAVES a\n   * dissolving body (sparks, ash, a ghost) reads the same number the body was\n   * taken apart with, rather than keeping a clock of its own and hoping the two\n   * agree. 1 on a scene that never dissolves anybody.\n   */\n  dissolve: f32,\n  /**\n   * Where she LOOKS: a unit direction from between the eyes, in world space.\n   * Exact while her eyes are on something (Engine.setEyeTracking); otherwise\n   * the motion's own eye turn undone through the range map \u2014 an eye bone\n   * turns a fraction of the way toward what it looks at, and this gives back\n   * the whole of it. An effect that should go where the look goes \u2014 a beam,\n   * a light \u2014 takes this rather than an eye bone's axis, and it holds in\n   * either mode. Zero, with looking false, only for a model without eyes.\n   */\n  gaze: vec3f,\n  looking: bool,\n  /** False past the end of the cast, and every field is then zero. */\n  valid: bool,\n}\n\nstruct RzAnchor {\n  pos: vec3f,\n  /** World units per second, from the previous frame. Direction for a trail,\n   *  magnitude for anything that should react to how hard someone is moving. */\n  vel: vec3f,\n  /** The bone's forward axis \u2014 which way a foot points, where a head looks. */\n  fwd: vec3f,\n  /** False when this rig has no such bone. Check it: the alternative is drawing\n   *  a hand effect at the world origin on every model that spells it differently. */\n  valid: bool,\n}\n\n/**\n * How many characters THIS EFFECT is on, up to four.\n *\n * Not how many the scene holds. An effect applies to the whole cast unless the\n * scene says otherwise (Engine.setEffectSubjects), and where it says otherwise\n * this counts only the models named \u2014 so an effect aimed at one dancer sees one\n * subject, at index 0, and an author who wrote a loop over the cast gets the\n * targeting for free.\n *\n * Which is the whole design: the FILTER IS IN THE INDEX SPACE, not in the\n * shaders. There is no mask an effect can read, because an effect asking \"am I\n * allowed on this one\" is an effect that can get the answer wrong, and 18 of the\n * shipped built-ins would have had to be rewritten to ask at all.\n */\nfn rzSubjectCount() -> i32 {\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var i = 0; i < live; i++) {\n    if ((mask & (1u << u32(i))) != 0u) { n++; }\n  }\n  return n;\n}\n\n/** This effect's i-th subject \u2192 the scene's slot, or -1 past its own count.\n *  Every accessor below goes through it, which is what keeps one effect's\n *  subject 1 from being another's. */\nfn _rzSubjectSlot(i: i32) -> i32 {\n  if (i < 0) { return -1; }\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var s = 0; s < live; s++) {\n    if ((mask & (1u << u32(s))) == 0u) { continue; }\n    if (n == i) { return s; }\n    n++;\n  }\n  return -1;\n}\n\n/** Which model this is, stable across a scene \u2014 for per-subject variation. */\nfn rzSubjectId(i: i32) -> u32 {\n  let g = _rzSubjectSlot(i);\n  if (g < 0) { return 0u; }\n  return u32(_rzCast[g * 4 + 1].w);\n}\n\nfn rzSubject(i: i32) -> RzSubject {\n  var s: RzSubject;\n  let g = _rzSubjectSlot(i);\n  s.valid = g >= 0;\n  if (!s.valid) { return s; }\n  let b = g * 4;\n  s.root = _rzCast[b].xyz;\n  s.dissolve = _rzCast[b].w;\n  s.center = _rzCast[b + 1].xyz;\n  s.bounds = _rzCast[b + 2];\n  s.gaze = _rzCast[b + 3].xyz;\n  s.looking = _rzCast[b + 3].w > 0.5;\n  return s;\n}\n\n/**\n * Where a named bone is, this frame.\n *\n * The slot is the author's own: the Nth #anchor in their file, in the order\n * they wrote them. _rzSlot turns that into the scene's address, which is what\n * keeps two effects that both anchor to a wrist from reading each other's.\n */\nfn rzAnchor(subject: i32, slot: i32) -> RzAnchor {\n  var a: RzAnchor;\n  a.valid = false;\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }\n  let b = 16 + (g * 4 + s) * 3;\n  a.valid = _rzCast[b].w > 0.5;\n  a.pos = _rzCast[b].xyz;\n  a.vel = _rzCast[b + 1].xyz;\n  a.fwd = _rzCast[b + 2].xyz;\n  return a;\n}\n\n/**\n * How many samples of a path are recorded \u2014 0 for an anchor that asked for no\n * trail, and for one that has not moved yet.\n *\n * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those\n * are different index spaces: storage is addressed by anchor slot, so an\n * untrailed #anchor followed by a trailed one put the trail at index 1 with a\n * bound of 1 and rzTrail returned zero \u2014 a ribbon that silently did not draw.\n */\nfn rzTrailCount(subject: i32, slot: i32) -> i32 {\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }\n  return i32(_rzCast[16 + (g * 4 + s) * 3 + 2].w);\n}\n\n/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */\nfn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {\n  let n = rzTrailCount(subject, slot);\n  if (i < 0 || i >= n) { return vec4f(0.0); }\n  let base = 592 + (_rzSlot(slot) * 4 + _rzSubjectSlot(subject)) * RZ_TRAIL_SAMPLES;\n  return _rzCast[base + i];\n}\n";
 /**
  * Which subjects this effect applies to, as WGSL — the second of the two names a
  * mount owes CAST_API (`_rzCastLive` is the first, and a mount with a view

package/dist/shaders/cast-layout.d.ts

@@ -23,8 +23,10 @@ export declare 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 declare 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 declare const EFFECT_ANCHORS = 16;
+export declare const EFFECT_ANCHORS = 48;
 /**
  * Path samples kept per trailed anchor — 128 at the 60Hz sampling rate is a
  * ~2.1 second ribbon.

package/dist/shaders/cast-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cast-layout.d.ts","sourceRoot":"","sources":["../../src/shaders/cast-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,cAAc,KAAK,CAAA;AAChC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,QAAgF,CAAA"}
+{"version":3,"file":"cast-layout.d.ts","sourceRoot":"","sources":["../../src/shaders/cast-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,cAAc,KAAK,CAAA;AAChC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,QAAgF,CAAA"}

package/dist/shaders/cast-layout.js

@@ -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/dist/shaders/directives.d.ts

@@ -29,6 +29,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;

package/dist/shaders/directives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../src/shaders/directives.ts"],"names":[],"mappings":"AA8BA,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IAC3C,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,GAAG,CAAC,CAAA;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE;;;;iFAI6E;IAC7E,aAAa,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;IAC9C,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;4CAOwC;IACxC,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACjE;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAmBD;;;+BAG+B;AAC/B,eAAO,MAAM,cAAc,QAAmC,CAAA;AAG9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAA8B,CAAA;AAmBzD,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhF,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CA2K7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD"}
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../src/shaders/directives.ts"],"names":[],"mappings":"AA8BA,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACjD,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IAC3C,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,GAAG,CAAC,CAAA;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE;;;;iFAI6E;IAC7E,aAAa,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;IAC9C,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ;kFAC8E;IAC9E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;4CAOwC;IACxC,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACjE;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAoBD;;;+BAG+B;AAC/B,eAAO,MAAM,cAAc,QAAmC,CAAA;AAG9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAA8B,CAAA;AAmBzD,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhF,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CA+K7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/dist/shaders/directives.js

@@ -37,6 +37,7 @@ const SPEC = {
     particles: 1,
     lights: 1,
     grid: 1,
+    points: 1,
     bloom: 0,
     dissolve: 0,
     mirror: 0,
@@ -88,6 +89,7 @@ export function parseDirectives(wgsl) {
         particles: 0,
         lights: 0,
         grid: 0,
+        points: null,
         bloom: false,
         dissolve: false,
         ground: null,
@@ -204,6 +206,9 @@ export function parseDirectives(wgsl) {
             case "dissolve":
                 d.dissolve = true;
                 return;
+            case "points":
+                d.points = args[0];
+                return;
             case "mirror":
                 d.mirror = true;
                 return;

package/dist/shaders/lights.d.ts

@@ -1,6 +1,6 @@
-/** 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 declare 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 declare const LIGHT_HEADER = 16;
 /** Floats per light — see the layout above. */
 export declare const LIGHT_STRIDE = 16;
 /**
@@ -14,14 +14,19 @@ export declare 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 declare const MAX_LIGHTS = 128;
-/** Floats in the whole buffer. */
+/** Words of lamp bits per grid cell — one bit per lamp the cap allows. */
+export declare const LIGHT_MASK_WORDS: number;
+/** 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 declare const LIGHT_GRID_CELLS = 32768;
+/** Where the grid starts, in words. */
+export declare const LIGHT_GRID_BASE: number;
+/** Words in the whole buffer: header, records, grid. */
 export declare const LIGHTS_FLOATS: number;
 /**
  * The RzLight struct, declared in EVERY module a user's source is spliced into.
@@ -33,16 +38,8 @@ export declare const LIGHTS_FLOATS: number;
  * write, which is the same trap the grid's step-only half documents.
  */
 export declare const RZ_LIGHT_STRUCT_WGSL = "\n/** What an effect returns for one of its lights. */\nstruct RzLight {\n  pos: vec3f,\n  color: vec3f,\n  intensity: f32,\n  radius: f32,\n}\n";
-/**
- * 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 declare const WORLD_AMBIENT_WGSL = "\nfn rzWorldAmbient(n: vec3f) -> vec3f {\n  if (light.sh[0].w < 0.5) { return light.ambientColor.xyz; }\n  let x = n.x;\n  let y = n.y;\n  let z = n.z;\n  let c = light.sh[0].xyz\n    + light.sh[1].xyz * y + light.sh[2].xyz * z + light.sh[3].xyz * x\n    + light.sh[4].xyz * (x * y) + light.sh[5].xyz * (y * z)\n    + light.sh[6].xyz * (3.0 * z * z - 1.0) + light.sh[7].xyz * (x * z)\n    + light.sh[8].xyz * (x * x - y * y);\n  return max(c, vec3f(0.0));\n}\n";
+/** rzWorldAmbient against the materials' and the ground's `light` uniform. */
+export declare const WORLD_AMBIENT_WGSL: string;
 /** Does this source define the emit mount? */
 export declare function hasLightEmit(wgsl: string): boolean;
 /**

package/dist/shaders/lights.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../src/shaders/lights.ts"],"names":[],"mappings":"AAyCA;yEACyE;AACzE,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,+CAA+C;AAC/C,eAAO,MAAM,YAAY,KAAK,CAAA;AAC9B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,MAAM,CAAA;AAC7B,kCAAkC;AAClC,eAAO,MAAM,aAAa,QAA2C,CAAA;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,qJAQhC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,idAa9B,CAAA;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAC5B,UAAU,SAAK,GACd,MAAM,CAoGR;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA0FhE"}
+{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../src/shaders/lights.ts"],"names":[],"mappings":"AAoDA;uDACuD;AACvD,eAAO,MAAM,YAAY,KAAK,CAAA;AAC9B,+CAA+C;AAC/C,eAAO,MAAM,YAAY,KAAK,CAAA;AAC9B;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,MAAM,CAAA;AAC7B,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,QAAkB,CAAA;AAC/C;0EAC0E;AAC1E,eAAO,MAAM,gBAAgB,QAAQ,CAAA;AACrC,uCAAuC;AACvC,eAAO,MAAM,eAAe,QAA2C,CAAA;AACvE,wDAAwD;AACxD,eAAO,MAAM,aAAa,QAAwD,CAAA;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,qJAQhC,CAAA;AAED,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,QAA4B,CAAA;AAE3D,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAC5B,UAAU,SAAK,GACd,MAAM,CAoGR;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgIhE"}

package/dist/shaders/lights.js

@@ -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.
@@ -37,9 +46,11 @@ import { midiApi } from "./midi-api";
 import { lyricsApi } from "./lyrics-api";
 import { clockApi, trailSlotsApi, viewportApi } from "./passes/hosted-api";
 import { idApi } from "./id-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;
+import { sceneLightApi, worldAmbientWgsl } from "./scene-light-api";
+import { pointsApi } from "./points-api";
+/** 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;
 /**
@@ -53,15 +64,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.
  *
@@ -80,29 +96,8 @@ struct RzLight {
   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));
-}
-`;
+/** rzWorldAmbient against the materials' and the ground's `light` uniform. */
+export const WORLD_AMBIENT_WGSL = worldAmbientWgsl("light");
 /** Does this source define the emit mount? */
 export function hasLightEmit(wgsl) {
     return /\bfn\s+lightEmit\s*\(/.test(wgsl);
@@ -173,7 +168,7 @@ ${viewportApi("viewU[6].w")}
 ${trailSlotsApi(cast.trailCount)}
 // The id accessors, stubbed: this module cannot read an attachment the
 // scene pass writes. See id-api.ts — the author's whole file compiles here.
-${idApi(false, 0, 0) + castDistanceStub()}
+${idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false)}
 // The dials the author declared, if any. A lamp is exactly the thing someone
 // retunes — its colour and its reach — so an emitter reads params like every
 // other mount rather than being the one place a #param resolves to nothing.
@@ -237,51 +232,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, binding) {
+    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.
  *
@@ -295,33 +294,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/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,QAmJhC,CAAC;AA6IF,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":"AA4BA,eAAO,MAAM,oBAAoB,QAmJhC,CAAC;AA8HF,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

@@ -1,6 +1,7 @@
 import { sceneFsOutWgsl } from "../passes/scene-contract";
 import { lightsApi } from "../lights";
 import { SHADOW_CASCADES } from "../../shadow-cascades";
+import { pcf9 } from "../scene-light-api";
 import { WORLD_AMBIENT_WGSL } from "../lights";
 // Shared WGSL blocks concatenated by every material shader.
 // Splits the boilerplate (uniform structs, bind group layout, skinning VS, PCF shadow)
@@ -171,8 +172,8 @@ fn safe_normal(nIn: vec3f) -> vec3f {
 
 `;
 // ─── Shadow sampler (3×3 PCF, cascade-selected) ─────────────────────
-// Normal-bias 0.08, depth-bias 0.001 NDC. Unrolled — Safari's Metal backend
-// doesn't unroll nested shadow loops reliably. Texel sizes are interpolated
+// Normal-bias 0.08, depth-bias 0.001 NDC; the kernel is pcf9 in scene-light-api.ts,
+// shared with effects. Texel sizes are interpolated
 // from SHADOW_CASCADES so they cannot go stale the way the hardcoded 1/2048
 // once did (PCF taps landed TWO texels apart after the map grew to 4096,
 // quantizing self-shadow edges into crawling gray squares).
@@ -183,21 +184,6 @@ fn safe_normal(nIn: vec3f) -> vec3f {
 // merely a default: the old single-volume path clamped, and past the light's
 // far plane the comparison failed against every stored depth, silently
 // shadowing any stage deeper than the box.
-const pcf9 = (map, ts) => /* wgsl */ `
-  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
-  let cmpZ = ndc.z - 0.001;
-  let ts = ${ts};
-  let s00 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);
-  let s10 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);
-  let s20 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, -ts), cmpZ);
-  let s01 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);
-  let s11 = textureSampleCompareLevel(${map}, shadowSampler, suv, cmpZ);
-  let s21 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);
-  let s02 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);
-  let s12 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);
-  let s22 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts,  ts), cmpZ);
-  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
-`;
 const SAMPLE_SHADOW_WGSL = /* wgsl */ `
 
 fn sampleShadowNear(ndc: vec3f) -> f32 {

package/dist/shaders/passes/composite.d.ts

@@ -97,7 +97,7 @@ type CompositeEffectSource = {
  * Depends on `viewU` and `_rzCast` being declared by the including module, and
  * on nothing else: no textures, no samplers.
  */
-export declare const EFFECT_SCENE_API = "\n// \u2500\u2500 The effect API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// Named rz*, for the engine. The prefix earns its place twice: user code is\n// concatenated into THIS module, so an unprefixed rzAnchor() would collide with\n// exactly the helper an author would write, and the old bg* prefix stopped being\n// true in 0.41.0 when effects gained a mount over the finished frame.\n//\n// The bg* names below are permanent aliases, not a deprecation with an end date.\n// A published link is immutable, so a scene pinned to a bg* effect has to keep\n// compiling forever. They are one-line and inlined; no new function gets one.\n\n/** Canvas size in pixels \u2014 for aspect correction. */\nfn rzResolution() -> vec2f { return viewU[6].zw; }\n\n/** The camera's world position. */\nfn rzCameraPos() -> vec3f { return viewU[10].xyz; }\n\n/** How many characters the SCENE holds, up to four \u2014 the number the cast api\n *  narrows to this effect's own subjects. See subjectMaskApi. */\nfn _rzCastLive() -> i32 { return i32(viewU[10].w); }\n\n/**\n * A world point as the camera sees it: xy the uv it lands on, z its distance\n * along the VIEW AXIS in metres.\n *\n * The exact inverse of the ray this pass builds per pixel, so it is the cheap way\n * to work with anything anchored in the world. Marching a curve or a trail in 3D\n * costs a distance evaluation per sample per pixel; projecting its points once\n * and measuring in 2D costs a subtraction, which is the difference between a\n * ribbon that runs at 4K and one that does not.\n *\n * z is directly comparable to the depth handed to foreground(), so occlusion is\n * a single test: draw where your z is nearer than the scene's. It is returned\n * SIGNED and unclamped \u2014 behind the camera is negative, and worth rejecting\n * before you use the uv, which is meaningless there.\n */\nfn rzProject(p: vec3f) -> vec3f {\n  let d = p - viewU[10].xyz;\n  let z = dot(d, viewU[5].xyz);\n  // Guard only the divide. z itself is returned as it is, so the caller can see\n  // the sign; clamping it here would put points behind the lens on the horizon.\n  let inv = 1.0 / select(z, 1e-4, z < 1e-4);\n  let ndc = vec2f(dot(d, viewU[3].xyz) * inv / viewU[3].w, dot(d, viewU[4].xyz) * inv / viewU[4].w);\n  return vec3f(ndc * 0.5 + 0.5, z);\n}\n\nfn rzCamPos() -> vec3f { return rzCameraPos(); }\nfn rzCameraRight() -> vec3f { return viewU[3].xyz; }\nfn rzCameraUp() -> vec3f { return viewU[4].xyz; }\nfn rzCameraForward() -> vec3f { return viewU[5].xyz; }\n\n// The cast \u2014 subjects, anchors, trails \u2014 is CAST_API, shared verbatim with the\n// particle and trail modules. It used to be written out here, a second time, and\n// the two copies had drifted: this one had rzAnchor and that one did not.\n\nconst RZ_SUBJECTS: i32 = 4;\nconst RZ_SAMPLES: i32 = 128;\n/** The anchor ADDRESS SPACE \u2014 how many an effect may declare, not how many it\n *  did. RZ_TRAIL_SLOTS is the per-effect number and is not this one; the two\n *  being one number was the old trail bug. */\nconst RZ_MAX_ANCHORS: i32 = 16;\nconst RZ_TRAIL_SAMPLES: i32 = 128;\n\nstruct RzSubject {\n  /** On the FLOOR, under the body \u2014 where a ring or a magic circle belongs. */\n  root: vec3f,\n  /** At the hips, the middle of the body \u2014 where an aura belongs. */\n  center: vec3f,\n  /** Bounding sphere: xyz centre, w radius. Deliberately generous \u2014 cull with it. */\n  bounds: vec4f,\n  /**\n   * How much of this character is still THERE: 1 whole, 0 gone.\n   *\n   * What setModelDissolve last set on them, which the material pass has already\n   * acted on by the time an effect runs \u2014 so an effect drawing what LEAVES a\n   * dissolving body (sparks, ash, a ghost) reads the same number the body was\n   * taken apart with, rather than keeping a clock of its own and hoping the two\n   * agree. 1 on a scene that never dissolves anybody.\n   */\n  dissolve: f32,\n  /**\n   * Where she LOOKS: a unit direction from between the eyes, in world space.\n   * Exact while her eyes are on something (Engine.setEyeTracking); otherwise\n   * the motion's own eye turn undone through the range map \u2014 an eye bone\n   * turns a fraction of the way toward what it looks at, and this gives back\n   * the whole of it. An effect that should go where the look goes \u2014 a beam,\n   * a light \u2014 takes this rather than an eye bone's axis, and it holds in\n   * either mode. Zero, with looking false, only for a model without eyes.\n   */\n  gaze: vec3f,\n  looking: bool,\n  /** False past the end of the cast, and every field is then zero. */\n  valid: bool,\n}\n\nstruct RzAnchor {\n  pos: vec3f,\n  /** World units per second, from the previous frame. Direction for a trail,\n   *  magnitude for anything that should react to how hard someone is moving. */\n  vel: vec3f,\n  /** The bone's forward axis \u2014 which way a foot points, where a head looks. */\n  fwd: vec3f,\n  /** False when this rig has no such bone. Check it: the alternative is drawing\n   *  a hand effect at the world origin on every model that spells it differently. */\n  valid: bool,\n}\n\n/**\n * How many characters THIS EFFECT is on, up to four.\n *\n * Not how many the scene holds. An effect applies to the whole cast unless the\n * scene says otherwise (Engine.setEffectSubjects), and where it says otherwise\n * this counts only the models named \u2014 so an effect aimed at one dancer sees one\n * subject, at index 0, and an author who wrote a loop over the cast gets the\n * targeting for free.\n *\n * Which is the whole design: the FILTER IS IN THE INDEX SPACE, not in the\n * shaders. There is no mask an effect can read, because an effect asking \"am I\n * allowed on this one\" is an effect that can get the answer wrong, and 18 of the\n * shipped built-ins would have had to be rewritten to ask at all.\n */\nfn rzSubjectCount() -> i32 {\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var i = 0; i < live; i++) {\n    if ((mask & (1u << u32(i))) != 0u) { n++; }\n  }\n  return n;\n}\n\n/** This effect's i-th subject \u2192 the scene's slot, or -1 past its own count.\n *  Every accessor below goes through it, which is what keeps one effect's\n *  subject 1 from being another's. */\nfn _rzSubjectSlot(i: i32) -> i32 {\n  if (i < 0) { return -1; }\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var s = 0; s < live; s++) {\n    if ((mask & (1u << u32(s))) == 0u) { continue; }\n    if (n == i) { return s; }\n    n++;\n  }\n  return -1;\n}\n\n/** Which model this is, stable across a scene \u2014 for per-subject variation. */\nfn rzSubjectId(i: i32) -> u32 {\n  let g = _rzSubjectSlot(i);\n  if (g < 0) { return 0u; }\n  return u32(_rzCast[g * 4 + 1].w);\n}\n\nfn rzSubject(i: i32) -> RzSubject {\n  var s: RzSubject;\n  let g = _rzSubjectSlot(i);\n  s.valid = g >= 0;\n  if (!s.valid) { return s; }\n  let b = g * 4;\n  s.root = _rzCast[b].xyz;\n  s.dissolve = _rzCast[b].w;\n  s.center = _rzCast[b + 1].xyz;\n  s.bounds = _rzCast[b + 2];\n  s.gaze = _rzCast[b + 3].xyz;\n  s.looking = _rzCast[b + 3].w > 0.5;\n  return s;\n}\n\n/**\n * Where a named bone is, this frame.\n *\n * The slot is the author's own: the Nth #anchor in their file, in the order\n * they wrote them. _rzSlot turns that into the scene's address, which is what\n * keeps two effects that both anchor to a wrist from reading each other's.\n */\nfn rzAnchor(subject: i32, slot: i32) -> RzAnchor {\n  var a: RzAnchor;\n  a.valid = false;\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }\n  let b = 16 + (g * 4 + s) * 3;\n  a.valid = _rzCast[b].w > 0.5;\n  a.pos = _rzCast[b].xyz;\n  a.vel = _rzCast[b + 1].xyz;\n  a.fwd = _rzCast[b + 2].xyz;\n  return a;\n}\n\n/**\n * How many samples of a path are recorded \u2014 0 for an anchor that asked for no\n * trail, and for one that has not moved yet.\n *\n * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those\n * are different index spaces: storage is addressed by anchor slot, so an\n * untrailed #anchor followed by a trailed one put the trail at index 1 with a\n * bound of 1 and rzTrail returned zero \u2014 a ribbon that silently did not draw.\n */\nfn rzTrailCount(subject: i32, slot: i32) -> i32 {\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }\n  return i32(_rzCast[16 + (g * 4 + s) * 3 + 2].w);\n}\n\n/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */\nfn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {\n  let n = rzTrailCount(subject, slot);\n  if (i < 0 || i >= n) { return vec4f(0.0); }\n  let base = 208 + (_rzSlot(slot) * 4 + _rzSubjectSlot(subject)) * RZ_TRAIL_SAMPLES;\n  return _rzCast[base + i];\n}\n\n\n// The hashes, the noise and rzFalloff \u2014 EFFECT_MATH_API, the same text the\n// particle and trail modules get. The field module used to be missing most of\n// it, so a helper an author wrote for one mount failed to compile in another\n// for no reason visible in the file.\n\nfn rzHash11(x: f32) -> f32 {\n  var p = fract(x * 0.1031);\n  p = p * (p + 33.33);\n  return fract(p * (p + p));\n}\nfn rzHash21(p: vec2f) -> f32 {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);\n  p3 = p3 + dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\n/** Three independent randoms from one seed \u2014 the usual need when spawning. */\nfn rzHash13(x: f32) -> vec3f {\n  return vec3f(rzHash11(x), rzHash11(x + 17.13), rzHash11(x + 41.71));\n}\n/**\n * Compact-support falloff: 1 at the centre, exactly 0 at r, smooth between.\n *\n * It reaches exactly zero rather than merely getting small, because a glow that\n * never quite ends has to be culled somewhere, and culling it wherever it looks\n * close enough is what put a visible hard edge on the first halo effect.\n */\nfn rzFalloff(d: f32, r: f32) -> f32 {\n  let x = clamp(d / max(r, 1e-6), 0.0, 1.0);\n  let f = 1.0 - x;\n  return f * f * f;\n}\nfn rzHash31(p: vec3f) -> f32 {\n  var p3 = fract(p * 0.1031);\n  p3 = p3 + dot(p3, p3.zyx + 31.32);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfn rzValueNoise(p: vec3f) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u = f * f * (3.0 - 2.0 * f);\n  let n000 = rzHash31(i);\n  let n100 = rzHash31(i + vec3f(1.0, 0.0, 0.0));\n  let n010 = rzHash31(i + vec3f(0.0, 1.0, 0.0));\n  let n110 = rzHash31(i + vec3f(1.0, 1.0, 0.0));\n  let n001 = rzHash31(i + vec3f(0.0, 0.0, 1.0));\n  let n101 = rzHash31(i + vec3f(1.0, 0.0, 1.0));\n  let n011 = rzHash31(i + vec3f(0.0, 1.0, 1.0));\n  let n111 = rzHash31(i + vec3f(1.0, 1.0, 1.0));\n  let x00 = mix(n000, n100, u.x);\n  let x10 = mix(n010, n110, u.x);\n  let x01 = mix(n001, n101, u.x);\n  let x11 = mix(n011, n111, u.x);\n  return mix(mix(x00, x10, u.y), mix(x01, x11, u.y), u.z);\n}\n/** Divergence-free flow \u2014 the field a wisp of smoke follows without a solver. */\nfn rzCurlNoise(p: vec3f) -> vec3f {\n  let e = 0.1;\n  let dx = vec3f(e, 0.0, 0.0);\n  let dy = vec3f(0.0, e, 0.0);\n  let dz = vec3f(0.0, 0.0, e);\n  let x0 = rzValueNoise(p - dx); let x1 = rzValueNoise(p + dx);\n  let y0 = rzValueNoise(p - dy); let y1 = rzValueNoise(p + dy);\n  let z0 = rzValueNoise(p - dz); let z1 = rzValueNoise(p + dz);\n  return normalize(vec3f((y1 - y0) - (z1 - z0), (z1 - z0) - (x1 - x0), (x1 - x0) - (y1 - y0)) + vec3f(1e-6));\n}\n\nstruct Particle {\n  pos: vec3f,\n  age: f32,\n  vel: vec3f,\n  life: f32,\n  size: f32,\n  rot: f32,\n  seed: f32,\n  // Aspect along the direction of travel. 1 or less is a square billboard; a\n  // raindrop is 10 or 20. Zero-initialised, so an effect that never sets it gets\n  // the square it expects.\n  stretch: f32,\n}\n\n\n\nfn bgResolution() -> vec2f { return rzResolution(); }\nfn bgCameraPos() -> vec3f { return rzCameraPos(); }\nfn bgSubjectCount() -> i32 { return rzSubjectCount(); }\n\n/**\n * Where a character IS, in world space \u2014 at the hips, not on the floor.\n *\n * An effect that wants to RESPOND to the cast \u2014 a glow that follows someone,\n * dust kicked up where they are \u2014 needs to know where they are, and the ray and\n * the depth cannot tell it: they describe the pixel, not the scene.\n *\n * The value is model.position + \u30BB\u30F3\u30BF\u30FC + \u5168\u3066\u306E\u89AA. \u30BB\u30F3\u30BF\u30FC sits at hip\n * height on every standard MMD rig, so this is a point in the middle of the\n * body. It is NOT the contact point: a ripple drawn here appears at the waist.\n * Ground effects want the .xz of this and their own floor height, which is what\n * the effects that shipped against it already do.\n *\n * The comment here used to claim it was \"between the feet on the floor\", which\n * is where that habit came from. Left as it is regardless of the name: a\n * published link is immutable, so every shared scene pinning an effect that\n * reads this depends on it meaning exactly what it has always meant.\n *\n * Clamped rather than bounds-checked: an effect looping past the count reads the\n * last subject instead of sampling whatever follows the array, which is a wrong\n * ripple rather than an undefined one.\n *\n * THE INDEX IS THE EFFECT'S OWN, like every other cast accessor \u2014 Dry Ice, Water,\n * Holy Light and Bloody Ash all read this one and all of them should place their\n * fog, their ripple and their shaft under the model the scene aimed them at. The\n * mapping is the identity for an effect aimed at nobody in particular, which is\n * every scene published before one could be aimed.\n */\nfn rzSubjectHip(i: i32) -> vec3f { return viewU[11 + clamp(_rzSubjectSlot(i), 0, 3)].xyz; }\n\nfn bgSubjectPos(i: i32) -> vec3f { return rzSubjectHip(i); }\n\n/** Where in the WORLD the scene drew this pixel \u2014 the depth handed to\n *  foreground() turned into a place. Without it an effect can only think in\n *  distances from the lens, which is no use to anything that belongs somewhere:\n *  fog lying on the ground has to know where the ground is.\n *\n *  depth measures along the VIEW AXIS, not along the ray, so it is divided by\n *  the ray's projection onto camera-forward before being walked out. At the far\n *  plane (nothing drawn) this lands a very long way off, which is what a sky\n *  should do to anything reading it. */\nfn rzWorldPos(ray: vec3f, depth: f32) -> vec3f {\n  let axis = max(dot(normalize(ray), viewU[5].xyz), 1e-4);\n  return rzCameraPos() + normalize(ray) * (depth / axis);\n}\n\nfn bgWorldPos(ray: vec3f, depth: f32) -> vec3f { return rzWorldPos(ray, depth); }\n\n/** What an effect returns for one of its lights. */\nstruct RzLight {\n  pos: vec3f,\n  color: vec3f,\n  intensity: f32,\n  radius: f32,\n}\n\n\n/** Color grading, applied to the tonemapped SCENE (not the background \u2014 see the\n *  call site). The core is ASC CDL, the film-industry interchange standard:\n *\n *      out = (in \u00B7 slope + offset) ^ power        then saturation  (SOP \u2192 SAT)\n *\n *  Using the real standard rather than invented controls means a look authored\n *  here maps onto any grading tool. slope/offset/power are derived on the CPU\n *  from the UI's shadow/midtone/highlight colors (see setColorGrading), so the\n *  per-pixel cost is one mul-add, one pow, one lerp. */\nfn grade(c: vec3f) -> vec3f {\n  var x = pow(max(c * viewU[9].xyz + viewU[7].xyz, vec3f(0.0)), viewU[8].xyz);\n  // Contrast pivots on 0.5 \u2014 display-referred midpoint, since we grade post-Filmic.\n  x = (x - vec3f(0.5)) * viewU[7].w + vec3f(0.5);\n  // Rec.709 luma, matching the ASC SAT node.\n  let luma = dot(x, vec3f(0.2126, 0.7152, 0.0722));\n  return max(mix(vec3f(luma), x, viewU[8].w), vec3f(0.0));\n}\n";
+export declare const EFFECT_SCENE_API = "\n// \u2500\u2500 The effect API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// Named rz*, for the engine. The prefix earns its place twice: user code is\n// concatenated into THIS module, so an unprefixed rzAnchor() would collide with\n// exactly the helper an author would write, and the old bg* prefix stopped being\n// true in 0.41.0 when effects gained a mount over the finished frame.\n//\n// The bg* names below are permanent aliases, not a deprecation with an end date.\n// A published link is immutable, so a scene pinned to a bg* effect has to keep\n// compiling forever. They are one-line and inlined; no new function gets one.\n\n/** Canvas size in pixels \u2014 for aspect correction. */\nfn rzResolution() -> vec2f { return viewU[6].zw; }\n\n/** The camera's world position. */\nfn rzCameraPos() -> vec3f { return viewU[10].xyz; }\n\n/** How many characters the SCENE holds, up to four \u2014 the number the cast api\n *  narrows to this effect's own subjects. See subjectMaskApi. */\nfn _rzCastLive() -> i32 { return i32(viewU[10].w); }\n\n/**\n * A world point as the camera sees it: xy the uv it lands on, z its distance\n * along the VIEW AXIS in metres.\n *\n * The exact inverse of the ray this pass builds per pixel, so it is the cheap way\n * to work with anything anchored in the world. Marching a curve or a trail in 3D\n * costs a distance evaluation per sample per pixel; projecting its points once\n * and measuring in 2D costs a subtraction, which is the difference between a\n * ribbon that runs at 4K and one that does not.\n *\n * z is directly comparable to the depth handed to foreground(), so occlusion is\n * a single test: draw where your z is nearer than the scene's. It is returned\n * SIGNED and unclamped \u2014 behind the camera is negative, and worth rejecting\n * before you use the uv, which is meaningless there.\n */\nfn rzProject(p: vec3f) -> vec3f {\n  let d = p - viewU[10].xyz;\n  let z = dot(d, viewU[5].xyz);\n  // Guard only the divide. z itself is returned as it is, so the caller can see\n  // the sign; clamping it here would put points behind the lens on the horizon.\n  let inv = 1.0 / select(z, 1e-4, z < 1e-4);\n  let ndc = vec2f(dot(d, viewU[3].xyz) * inv / viewU[3].w, dot(d, viewU[4].xyz) * inv / viewU[4].w);\n  return vec3f(ndc * 0.5 + 0.5, z);\n}\n\nfn rzCamPos() -> vec3f { return rzCameraPos(); }\nfn rzCameraRight() -> vec3f { return viewU[3].xyz; }\nfn rzCameraUp() -> vec3f { return viewU[4].xyz; }\nfn rzCameraForward() -> vec3f { return viewU[5].xyz; }\n\n// The cast \u2014 subjects, anchors, trails \u2014 is CAST_API, shared verbatim with the\n// particle and trail modules. It used to be written out here, a second time, and\n// the two copies had drifted: this one had rzAnchor and that one did not.\n\nconst RZ_SUBJECTS: i32 = 4;\nconst RZ_SAMPLES: i32 = 128;\n/** The anchor ADDRESS SPACE \u2014 how many an effect may declare, not how many it\n *  did. RZ_TRAIL_SLOTS is the per-effect number and is not this one; the two\n *  being one number was the old trail bug. */\nconst RZ_MAX_ANCHORS: i32 = 48;\nconst RZ_TRAIL_SAMPLES: i32 = 128;\n\nstruct RzSubject {\n  /** On the FLOOR, under the body \u2014 where a ring or a magic circle belongs. */\n  root: vec3f,\n  /** At the hips, the middle of the body \u2014 where an aura belongs. */\n  center: vec3f,\n  /** Bounding sphere: xyz centre, w radius. Deliberately generous \u2014 cull with it. */\n  bounds: vec4f,\n  /**\n   * How much of this character is still THERE: 1 whole, 0 gone.\n   *\n   * What setModelDissolve last set on them, which the material pass has already\n   * acted on by the time an effect runs \u2014 so an effect drawing what LEAVES a\n   * dissolving body (sparks, ash, a ghost) reads the same number the body was\n   * taken apart with, rather than keeping a clock of its own and hoping the two\n   * agree. 1 on a scene that never dissolves anybody.\n   */\n  dissolve: f32,\n  /**\n   * Where she LOOKS: a unit direction from between the eyes, in world space.\n   * Exact while her eyes are on something (Engine.setEyeTracking); otherwise\n   * the motion's own eye turn undone through the range map \u2014 an eye bone\n   * turns a fraction of the way toward what it looks at, and this gives back\n   * the whole of it. An effect that should go where the look goes \u2014 a beam,\n   * a light \u2014 takes this rather than an eye bone's axis, and it holds in\n   * either mode. Zero, with looking false, only for a model without eyes.\n   */\n  gaze: vec3f,\n  looking: bool,\n  /** False past the end of the cast, and every field is then zero. */\n  valid: bool,\n}\n\nstruct RzAnchor {\n  pos: vec3f,\n  /** World units per second, from the previous frame. Direction for a trail,\n   *  magnitude for anything that should react to how hard someone is moving. */\n  vel: vec3f,\n  /** The bone's forward axis \u2014 which way a foot points, where a head looks. */\n  fwd: vec3f,\n  /** False when this rig has no such bone. Check it: the alternative is drawing\n   *  a hand effect at the world origin on every model that spells it differently. */\n  valid: bool,\n}\n\n/**\n * How many characters THIS EFFECT is on, up to four.\n *\n * Not how many the scene holds. An effect applies to the whole cast unless the\n * scene says otherwise (Engine.setEffectSubjects), and where it says otherwise\n * this counts only the models named \u2014 so an effect aimed at one dancer sees one\n * subject, at index 0, and an author who wrote a loop over the cast gets the\n * targeting for free.\n *\n * Which is the whole design: the FILTER IS IN THE INDEX SPACE, not in the\n * shaders. There is no mask an effect can read, because an effect asking \"am I\n * allowed on this one\" is an effect that can get the answer wrong, and 18 of the\n * shipped built-ins would have had to be rewritten to ask at all.\n */\nfn rzSubjectCount() -> i32 {\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var i = 0; i < live; i++) {\n    if ((mask & (1u << u32(i))) != 0u) { n++; }\n  }\n  return n;\n}\n\n/** This effect's i-th subject \u2192 the scene's slot, or -1 past its own count.\n *  Every accessor below goes through it, which is what keeps one effect's\n *  subject 1 from being another's. */\nfn _rzSubjectSlot(i: i32) -> i32 {\n  if (i < 0) { return -1; }\n  let live = _rzCastLive();\n  let mask = _rzSubjectMask();\n  var n = 0;\n  for (var s = 0; s < live; s++) {\n    if ((mask & (1u << u32(s))) == 0u) { continue; }\n    if (n == i) { return s; }\n    n++;\n  }\n  return -1;\n}\n\n/** Which model this is, stable across a scene \u2014 for per-subject variation. */\nfn rzSubjectId(i: i32) -> u32 {\n  let g = _rzSubjectSlot(i);\n  if (g < 0) { return 0u; }\n  return u32(_rzCast[g * 4 + 1].w);\n}\n\nfn rzSubject(i: i32) -> RzSubject {\n  var s: RzSubject;\n  let g = _rzSubjectSlot(i);\n  s.valid = g >= 0;\n  if (!s.valid) { return s; }\n  let b = g * 4;\n  s.root = _rzCast[b].xyz;\n  s.dissolve = _rzCast[b].w;\n  s.center = _rzCast[b + 1].xyz;\n  s.bounds = _rzCast[b + 2];\n  s.gaze = _rzCast[b + 3].xyz;\n  s.looking = _rzCast[b + 3].w > 0.5;\n  return s;\n}\n\n/**\n * Where a named bone is, this frame.\n *\n * The slot is the author's own: the Nth #anchor in their file, in the order\n * they wrote them. _rzSlot turns that into the scene's address, which is what\n * keeps two effects that both anchor to a wrist from reading each other's.\n */\nfn rzAnchor(subject: i32, slot: i32) -> RzAnchor {\n  var a: RzAnchor;\n  a.valid = false;\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }\n  let b = 16 + (g * 4 + s) * 3;\n  a.valid = _rzCast[b].w > 0.5;\n  a.pos = _rzCast[b].xyz;\n  a.vel = _rzCast[b + 1].xyz;\n  a.fwd = _rzCast[b + 2].xyz;\n  return a;\n}\n\n/**\n * How many samples of a path are recorded \u2014 0 for an anchor that asked for no\n * trail, and for one that has not moved yet.\n *\n * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those\n * are different index spaces: storage is addressed by anchor slot, so an\n * untrailed #anchor followed by a trailed one put the trail at index 1 with a\n * bound of 1 and rzTrail returned zero \u2014 a ribbon that silently did not draw.\n */\nfn rzTrailCount(subject: i32, slot: i32) -> i32 {\n  let g = _rzSlot(slot);\n  let s = _rzSubjectSlot(subject);\n  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }\n  return i32(_rzCast[16 + (g * 4 + s) * 3 + 2].w);\n}\n\n/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */\nfn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {\n  let n = rzTrailCount(subject, slot);\n  if (i < 0 || i >= n) { return vec4f(0.0); }\n  let base = 592 + (_rzSlot(slot) * 4 + _rzSubjectSlot(subject)) * RZ_TRAIL_SAMPLES;\n  return _rzCast[base + i];\n}\n\n\n// The hashes, the noise and rzFalloff \u2014 EFFECT_MATH_API, the same text the\n// particle and trail modules get. The field module used to be missing most of\n// it, so a helper an author wrote for one mount failed to compile in another\n// for no reason visible in the file.\n\nfn rzHash11(x: f32) -> f32 {\n  var p = fract(x * 0.1031);\n  p = p * (p + 33.33);\n  return fract(p * (p + p));\n}\nfn rzHash21(p: vec2f) -> f32 {\n  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);\n  p3 = p3 + dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\n/** Three independent randoms from one seed \u2014 the usual need when spawning. */\nfn rzHash13(x: f32) -> vec3f {\n  return vec3f(rzHash11(x), rzHash11(x + 17.13), rzHash11(x + 41.71));\n}\n/**\n * Compact-support falloff: 1 at the centre, exactly 0 at r, smooth between.\n *\n * It reaches exactly zero rather than merely getting small, because a glow that\n * never quite ends has to be culled somewhere, and culling it wherever it looks\n * close enough is what put a visible hard edge on the first halo effect.\n */\nfn rzFalloff(d: f32, r: f32) -> f32 {\n  let x = clamp(d / max(r, 1e-6), 0.0, 1.0);\n  let f = 1.0 - x;\n  return f * f * f;\n}\nfn rzHash31(p: vec3f) -> f32 {\n  var p3 = fract(p * 0.1031);\n  p3 = p3 + dot(p3, p3.zyx + 31.32);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfn rzValueNoise(p: vec3f) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u = f * f * (3.0 - 2.0 * f);\n  let n000 = rzHash31(i);\n  let n100 = rzHash31(i + vec3f(1.0, 0.0, 0.0));\n  let n010 = rzHash31(i + vec3f(0.0, 1.0, 0.0));\n  let n110 = rzHash31(i + vec3f(1.0, 1.0, 0.0));\n  let n001 = rzHash31(i + vec3f(0.0, 0.0, 1.0));\n  let n101 = rzHash31(i + vec3f(1.0, 0.0, 1.0));\n  let n011 = rzHash31(i + vec3f(0.0, 1.0, 1.0));\n  let n111 = rzHash31(i + vec3f(1.0, 1.0, 1.0));\n  let x00 = mix(n000, n100, u.x);\n  let x10 = mix(n010, n110, u.x);\n  let x01 = mix(n001, n101, u.x);\n  let x11 = mix(n011, n111, u.x);\n  return mix(mix(x00, x10, u.y), mix(x01, x11, u.y), u.z);\n}\n/** Divergence-free flow \u2014 the field a wisp of smoke follows without a solver. */\nfn rzCurlNoise(p: vec3f) -> vec3f {\n  let e = 0.1;\n  let dx = vec3f(e, 0.0, 0.0);\n  let dy = vec3f(0.0, e, 0.0);\n  let dz = vec3f(0.0, 0.0, e);\n  let x0 = rzValueNoise(p - dx); let x1 = rzValueNoise(p + dx);\n  let y0 = rzValueNoise(p - dy); let y1 = rzValueNoise(p + dy);\n  let z0 = rzValueNoise(p - dz); let z1 = rzValueNoise(p + dz);\n  return normalize(vec3f((y1 - y0) - (z1 - z0), (z1 - z0) - (x1 - x0), (x1 - x0) - (y1 - y0)) + vec3f(1e-6));\n}\n\nstruct Particle {\n  pos: vec3f,\n  age: f32,\n  vel: vec3f,\n  life: f32,\n  size: f32,\n  rot: f32,\n  seed: f32,\n  // Aspect along the direction of travel. 1 or less is a square billboard; a\n  // raindrop is 10 or 20. Zero-initialised, so an effect that never sets it gets\n  // the square it expects.\n  stretch: f32,\n}\n\n\n\nfn bgResolution() -> vec2f { return rzResolution(); }\nfn bgCameraPos() -> vec3f { return rzCameraPos(); }\nfn bgSubjectCount() -> i32 { return rzSubjectCount(); }\n\n/**\n * Where a character IS, in world space \u2014 at the hips, not on the floor.\n *\n * An effect that wants to RESPOND to the cast \u2014 a glow that follows someone,\n * dust kicked up where they are \u2014 needs to know where they are, and the ray and\n * the depth cannot tell it: they describe the pixel, not the scene.\n *\n * The value is model.position + \u30BB\u30F3\u30BF\u30FC + \u5168\u3066\u306E\u89AA. \u30BB\u30F3\u30BF\u30FC sits at hip\n * height on every standard MMD rig, so this is a point in the middle of the\n * body. It is NOT the contact point: a ripple drawn here appears at the waist.\n * Ground effects want the .xz of this and their own floor height, which is what\n * the effects that shipped against it already do.\n *\n * The comment here used to claim it was \"between the feet on the floor\", which\n * is where that habit came from. Left as it is regardless of the name: a\n * published link is immutable, so every shared scene pinning an effect that\n * reads this depends on it meaning exactly what it has always meant.\n *\n * Clamped rather than bounds-checked: an effect looping past the count reads the\n * last subject instead of sampling whatever follows the array, which is a wrong\n * ripple rather than an undefined one.\n *\n * THE INDEX IS THE EFFECT'S OWN, like every other cast accessor \u2014 Dry Ice, Water,\n * Holy Light and Bloody Ash all read this one and all of them should place their\n * fog, their ripple and their shaft under the model the scene aimed them at. The\n * mapping is the identity for an effect aimed at nobody in particular, which is\n * every scene published before one could be aimed.\n */\nfn rzSubjectHip(i: i32) -> vec3f { return viewU[11 + clamp(_rzSubjectSlot(i), 0, 3)].xyz; }\n\nfn bgSubjectPos(i: i32) -> vec3f { return rzSubjectHip(i); }\n\n/** Where in the WORLD the scene drew this pixel \u2014 the depth handed to\n *  foreground() turned into a place. Without it an effect can only think in\n *  distances from the lens, which is no use to anything that belongs somewhere:\n *  fog lying on the ground has to know where the ground is.\n *\n *  depth measures along the VIEW AXIS, not along the ray, so it is divided by\n *  the ray's projection onto camera-forward before being walked out. At the far\n *  plane (nothing drawn) this lands a very long way off, which is what a sky\n *  should do to anything reading it. */\nfn rzWorldPos(ray: vec3f, depth: f32) -> vec3f {\n  let axis = max(dot(normalize(ray), viewU[5].xyz), 1e-4);\n  return rzCameraPos() + normalize(ray) * (depth / axis);\n}\n\nfn bgWorldPos(ray: vec3f, depth: f32) -> vec3f { return rzWorldPos(ray, depth); }\n\n/** What an effect returns for one of its lights. */\nstruct RzLight {\n  pos: vec3f,\n  color: vec3f,\n  intensity: f32,\n  radius: f32,\n}\n\n\n/** Color grading, applied to the tonemapped SCENE (not the background \u2014 see the\n *  call site). The core is ASC CDL, the film-industry interchange standard:\n *\n *      out = (in \u00B7 slope + offset) ^ power        then saturation  (SOP \u2192 SAT)\n *\n *  Using the real standard rather than invented controls means a look authored\n *  here maps onto any grading tool. slope/offset/power are derived on the CPU\n *  from the UI's shadow/midtone/highlight colors (see setColorGrading), so the\n *  per-pixel cost is one mul-add, one pow, one lerp. */\nfn grade(c: vec3f) -> vec3f {\n  var x = pow(max(c * viewU[9].xyz + viewU[7].xyz, vec3f(0.0)), viewU[8].xyz);\n  // Contrast pivots on 0.5 \u2014 display-referred midpoint, since we grade post-Filmic.\n  x = (x - vec3f(0.5)) * viewU[7].w + vec3f(0.5);\n  // Rec.709 luma, matching the ASC SAT node.\n  let luma = dot(x, vec3f(0.2126, 0.7152, 0.0722));\n  return max(mix(vec3f(luma), x, viewU[8].w), vec3f(0.0));\n}\n";
 export declare function buildCompositeShader(effect?: CompositeEffectSource | null): string;
 /**
  * The field pass: the user's background/foreground mounts at half resolution,