reze-engine 0.56.14 → 0.57.1

package/src/graph/registry.ts

@@ -217,6 +217,38 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
   // PMX material's diffuse color (the authored base tint). Multiply the diffuse texture
   // by this for the MMD-correct base — untextured materials carry their color here, so a
   // texture-only base would render them white.
+  // WHAT THE SURFACE IS MADE OF, when whoever wrote the model said so.
+  //
+  // PMX carries a specular colour its own renderer barely uses, and a stage
+  // converted out of a game engine packs its material's (metal, roughness,
+  // occlusion) there — the same triple that game's property map holds, averaged
+  // per material. One shared look can then read it and a whole stage keeps ONE
+  // pipeline, where a look per material was what cost a garden its frame rate.
+  //
+  // A hand-authored PMX leaves it at whatever its exporter wrote, so a graph
+  // that reads this is choosing to trust the model. Nothing else does.
+  // How opaque the PMX said this material is, before its texture's alpha is
+  // multiplied in. A graph that computes its own opacity still wants it: glass
+  // is see-through by the amount its author chose and a mirror at a grazing
+  // angle, and without this every pane in a stage gets the same transparency
+  // whatever its material says.
+  material_alpha: {
+    inputs: {},
+    outputs: { value: "float" },
+    contextOutputs: { value: "material.alpha" },
+  },
+
+  material_specular: {
+    inputs: {},
+    outputs: { color: "color" },
+    contextOutputs: { color: "material.specular" },
+  },
+  material_shininess: {
+    inputs: {},
+    outputs: { value: "float" },
+    contextOutputs: { value: "material.shininess" },
+  },
+
   material_diffuse: {
     inputs: {},
     outputs: { color: "color" },

package/src/graph/style-group.ts

@@ -36,6 +36,20 @@ export type StyleGroup = {
    * no-op rather than a failure.
    */
   images?: (GroupImage | GroupImageSource | null)[]
+  /**
+   * The same slots, but PER MATERIAL — for a group whose members each bring
+   * their own maps.
+   *
+   * `images` belongs to the LOOK and is right when a look carries its own ramp
+   * or detail map. A converted stage is the other case: twenty-seven props, one
+   * shading model, and a different normal map on every one of them. Keyed here,
+   * they share a pipeline and differ only in what the bind group points at —
+   * the alternative is a group per material, which is a pipeline per material,
+   * which is what cost a garden stage its frame rate.
+   *
+   * A material with no entry falls back to `images`, and then to 1×1 white.
+   */
+  imagesByMaterial?: Record<string, (GroupImage | GroupImageSource | null)[]>
 }
 
 export type GroupImageSource = ImageBitmap | HTMLImageElement | HTMLCanvasElement

package/src/shaders/cast-api.ts

@@ -15,17 +15,22 @@
 // that did not exist. Baking them makes this a constant string, which is what
 // lets both families share it without either one deciding the shape.
 //
-// WHAT A HOST MUST SUPPLY. Three names, and deliberately only three:
+// WHAT A HOST MUST SUPPLY. Four names, and deliberately only four:
 //
-//   _rzCast          the buffer, at whatever binding the module puts it on
-//   _rzSlot(i)       the effect's local slot → the scene's, from its alias
-//   rzSubjectCount() how many subjects are live
+//   _rzCast           the buffer, at whatever binding the module puts it on
+//   _rzSlot(i)        the effect's local slot → the scene's, from its alias
+//   _rzCastLive()     how many subjects the SCENE holds
+//   _rzSubjectMask()  which of them THIS EFFECT applies to, one bit per slot
 //
-// The last is a host's because the two families genuinely disagree on it: the
+// The third is a host's because the two families genuinely disagree on it: the
 // field module reads a count the engine wrote into the view uniform, and the
 // particle module scans the buffer, because it has no view uniform to read.
 // They agree in value. Unifying them would be a behaviour change to every
 // shipped effect for no gain, so the seam stays and is named here instead.
+//
+// The fourth is a host's because every mount carries it in a uniform of its own
+// — the field clock's z, the particle and trail pads, the grid's and the light
+// emitter's blocks — and each of those is written once a frame by the engine.
 
 import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES, EFFECT_SUBJECT_VEC4S } from "./cast-layout"
 
@@ -82,17 +87,59 @@ struct RzAnchor {
   valid: bool,
 }
 
+/**
+ * How many characters THIS EFFECT is on, up to four.
+ *
+ * Not how many the scene holds. An effect applies to the whole cast unless the
+ * scene says otherwise (Engine.setEffectSubjects), and where it says otherwise
+ * this counts only the models named — so an effect aimed at one dancer sees one
+ * subject, at index 0, and an author who wrote a loop over the cast gets the
+ * targeting for free.
+ *
+ * Which is the whole design: the FILTER IS IN THE INDEX SPACE, not in the
+ * shaders. There is no mask an effect can read, because an effect asking "am I
+ * allowed on this one" is an effect that can get the answer wrong, and 18 of the
+ * shipped built-ins would have had to be rewritten to ask at all.
+ */
+fn rzSubjectCount() -> i32 {
+  let live = _rzCastLive();
+  let mask = _rzSubjectMask();
+  var n = 0;
+  for (var i = 0; i < live; i++) {
+    if ((mask & (1u << u32(i))) != 0u) { n++; }
+  }
+  return n;
+}
+
+/** This effect's i-th subject → the scene's slot, or -1 past its own count.
+ *  Every accessor below goes through it, which is what keeps one effect's
+ *  subject 1 from being another's. */
+fn _rzSubjectSlot(i: i32) -> i32 {
+  if (i < 0) { return -1; }
+  let live = _rzCastLive();
+  let mask = _rzSubjectMask();
+  var n = 0;
+  for (var s = 0; s < live; s++) {
+    if ((mask & (1u << u32(s))) == 0u) { continue; }
+    if (n == i) { return s; }
+    n++;
+  }
+  return -1;
+}
+
 /** Which model this is, stable across a scene — for per-subject variation. */
 fn rzSubjectId(i: i32) -> u32 {
-  if (i < 0 || i >= rzSubjectCount()) { return 0u; }
-  return u32(_rzCast[i * ${EFFECT_SUBJECT_VEC4S} + 1].w);
+  let g = _rzSubjectSlot(i);
+  if (g < 0) { return 0u; }
+  return u32(_rzCast[g * ${EFFECT_SUBJECT_VEC4S} + 1].w);
 }
 
 fn rzSubject(i: i32) -> RzSubject {
   var s: RzSubject;
-  s.valid = i >= 0 && i < rzSubjectCount();
+  let g = _rzSubjectSlot(i);
+  s.valid = g >= 0;
   if (!s.valid) { return s; }
-  let b = i * ${EFFECT_SUBJECT_VEC4S};
+  let b = g * ${EFFECT_SUBJECT_VEC4S};
   s.root = _rzCast[b].xyz;
   s.dissolve = _rzCast[b].w;
   s.center = _rzCast[b + 1].xyz;
@@ -113,8 +160,9 @@ fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
   var a: RzAnchor;
   a.valid = false;
   let g = _rzSlot(slot);
-  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }
-  let b = ${EFFECT_SUBJECTS * EFFECT_SUBJECT_VEC4S} + (g * ${EFFECT_SUBJECTS} + subject) * 3;
+  let s = _rzSubjectSlot(subject);
+  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }
+  let b = ${EFFECT_SUBJECTS * EFFECT_SUBJECT_VEC4S} + (g * ${EFFECT_SUBJECTS} + s) * 3;
   a.valid = _rzCast[b].w > 0.5;
   a.pos = _rzCast[b].xyz;
   a.vel = _rzCast[b + 1].xyz;
@@ -133,15 +181,35 @@ fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
  */
 fn rzTrailCount(subject: i32, slot: i32) -> i32 {
   let g = _rzSlot(slot);
-  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }
-  return i32(_rzCast[${EFFECT_SUBJECTS * EFFECT_SUBJECT_VEC4S} + (g * ${EFFECT_SUBJECTS} + subject) * 3 + 2].w);
+  let s = _rzSubjectSlot(subject);
+  if (s < 0 || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }
+  return i32(_rzCast[${EFFECT_SUBJECTS * EFFECT_SUBJECT_VEC4S} + (g * ${EFFECT_SUBJECTS} + s) * 3 + 2].w);
 }
 
 /** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */
 fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
   let n = rzTrailCount(subject, slot);
   if (i < 0 || i >= n) { return vec4f(0.0); }
-  let base = ${EFFECT_TRAIL_BASE} + (_rzSlot(slot) * ${EFFECT_SUBJECTS} + subject) * RZ_TRAIL_SAMPLES;
+  let base = ${EFFECT_TRAIL_BASE} + (_rzSlot(slot) * ${EFFECT_SUBJECTS} + _rzSubjectSlot(subject)) * RZ_TRAIL_SAMPLES;
   return _rzCast[base + i];
 }
 `
+
+/**
+ * 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
+ * uniform already has it from EFFECT_SCENE_API).
+ *
+ * One bit per cast slot. An EXPRESSION rather than a value: it resolves per
+ * draw, out of a uniform the engine writes once a frame, so a module that baked
+ * it would stop following a target being changed or a model being hidden.
+ */
+export const subjectMaskApi = (mask: string): string => /* wgsl */ `
+fn _rzSubjectMask() -> u32 { return ${mask}; }
+`
+
+/** Every subject the scene has. For a mount that is not an effect — the
+ *  composite's own module, where nothing user-written lands and the accessors
+ *  exist only so the shared API compiles — and the value the engine writes for
+ *  an effect the scene has not aimed at anybody in particular. */
+export const CAST_MASK_ALL = "0xfu"

package/src/shaders/lights.ts

@@ -1,4 +1,5 @@
 import { SCENE_TAP_STUB } from "./scene-tap"
+import { subjectMaskApi } from "./cast-api"
 // Positional lights, as data — the sibling of the cast, audio and score
 // interfaces, and shaped like them: one shared buffer, read through accessors,
 // never touched directly.
@@ -149,15 +150,18 @@ export function buildLightEmitShader(
 // read_write HERE and read-only in the material shaders. Different passes, so
 // the two never coexist: this compute runs before the scene pass that reads it.
 @group(0) @binding(0) var<storage, read_write> _rzLightsOut: array<f32>;
-// (time, base slot, count, weight) — see buildLightEmitShader on why the base
-// is here and not in the text.
-@group(0) @binding(1) var<uniform> _rzLightU: vec4f;
+// [0] (time, base slot, count, weight) — see buildLightEmitShader on why the
+// base is here and not in the text — and [1].x the subject mask, which is the
+// only thing the second vec4 is for: an emitter reads the cast through the same
+// accessors its drawing half does, so a rig aimed at one dancer must see one.
+@group(0) @binding(1) var<uniform> _rzLightU: array<vec4f, 2>;
 // The camera block and the cast — the two buffers the scene API reads. Same
 // contents the field and grid modules bind, so an effect's lightEmit sees the
 // scene exactly as its drawing half does.
 @group(0) @binding(2) var<uniform> viewU: array<vec4<f32>, 15>;
 @group(0) @binding(3) var<storage, read> _rzCast: array<vec4f>;
 ${sceneApi}
+${subjectMaskApi("u32(_rzLightU[1].x)")}
 ${SCENE_TAP_STUB}
 // Audio and score at 4 and 5, the same bindings the particle and trail modules
 // put them on. A lamp that pulses on the beat or lights on a note is the whole
@@ -171,7 +175,7 @@ ${lyricsApi(0, 6)}
 // grows a lamp at its tip compiles its ribbon code in this module too. The math
 // helpers and the Particle struct are NOT repeated — they arrive with the scene
 // API above, and a second copy is a redefinition error in engine code.
-${clockApi("_rzLightU.x", "0.0")}
+${clockApi("_rzLightU[0].x", "0.0")}
 // Canvas height — the same number the drawing modules read out of their camera
 // struct, both written from canvas.height, so this name means ONE value in
 // every module. Verified against the writers, not assumed: cameraMatrixData[35]
@@ -192,12 +196,12 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
   let i = gid.x;
   // The dispatch is sized to the count, but a workgroup is 64 wide and the
   // count rarely is — the tail must not write into the next effect's slots.
-  if (i >= u32(_rzLightU.z)) { return; }
+  if (i >= u32(_rzLightU[0].z)) { return; }
   // Time is a PARAMETER, not an rzTime() call: this same source compiles
   // inside the field, particle, trail and grid modules, and those already
   // define rzTime differently or not at all. A parameter needs nothing from
   // the module it lands in, which is why the field mounts take theirs too.
-  let l = lightEmit(i, _rzLightU.x);
+  let l = lightEmit(i, _rzLightU[0].x);
   // SANITIZED at the one write site, because lightEmit is HOSTED USER CODE and
   // this buffer feeds every fragment of every material: one NaN position would
   // poison the whole frame, and WGSL leaves max(NaN, 0) indeterminate, so it
@@ -211,8 +215,8 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
   // Weight rides along with the sanitisation, which is already the one place
   // this buffer is written: a lamp at half weight is half as bright, and one
   // at zero never reaches here because the dispatch is skipped.
-  let c = select(vec3f(0.0), max(l.color * l.intensity, vec3f(0.0)), finite) * _rzLightU.w;
-  let b = ${LIGHT_HEADER}u + (u32(_rzLightU.y) + i) * ${LIGHT_STRIDE}u;
+  let c = select(vec3f(0.0), max(l.color * l.intensity, vec3f(0.0)), finite) * _rzLightU[0].w;
+  let b = ${LIGHT_HEADER}u + (u32(_rzLightU[0].y) + i) * ${LIGHT_STRIDE}u;
   _rzLightsOut[b] = select(0.0, l.pos.x, finite);
   _rzLightsOut[b + 1u] = select(0.0, l.pos.y, finite);
   _rzLightsOut[b + 2u] = select(0.0, l.pos.z, finite);
@@ -220,7 +224,7 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
   // weight above it. Scaling it with the fade would shrink a dimming lamp's
   // reach, which is a different thing than dimming it; zeroing it at nothing
   // is what lets a material's distance cull drop the slot entirely.
-  _rzLightsOut[b + 3u] = select(0.0, max(l.radius, 0.0), finite && _rzLightU.w > 0.0);
+  _rzLightsOut[b + 3u] = select(0.0, max(l.radius, 0.0), finite && _rzLightU[0].w > 0.0);
   // Colour carries intensity, exactly as the CPU writer stores it — one product,
   // one place, so the two producers cannot disagree about what a slot means.
   _rzLightsOut[b + 4u] = c.x;

package/src/shaders/passes/cast-distance.ts

@@ -86,6 +86,14 @@ fn vs(@builtin(vertex_index) i: u32) -> VSOut {
  * 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.
+ *
+ * WHICH SUBJECTS SEED IS A MASK, because an effect can be aimed at some of the
+ * cast and this field is how a screen-space look knows where anybody is. The
+ * distance to a model left out of the mask is not "large", it is a different
+ * question — so a field is built per distinct target set rather than filtered
+ * afterwards. The props are not masked: a prop belongs to whoever is holding it,
+ * and the engine does not know who that is. It seeds either way, which is the
+ * side that keeps a border whole.
  */
 export function buildCastSeedShader(samples: number): string {
   return (
@@ -99,6 +107,8 @@ const RZ_ID_SAMPLES: i32 = ${samples};
 /** 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>;
+/** (subject mask, _, _, _) — which cast slots this field is built from. */
+@group(0) @binding(3) var<uniform> _rzSeedU: vec4f;
 
 // 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
@@ -114,9 +124,11 @@ 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. */
+/** Does this object seed the field: a MASKED subject, or a prop. */
 fn rzSeeds(o: u32, subjects: i32) -> bool {
+  let mask = u32(_rzSeedU.x);
   for (var i = 0; i < subjects; i++) {
+    if ((mask & (1u << u32(i))) == 0u) { continue; }
     if (o == rzSubjectId(i)) { return true; }
   }
   let props = min(_rzSeedProps[0], arrayLength(&_rzSeedProps) - 1u);

package/src/shaders/passes/composite.ts

@@ -1,7 +1,7 @@
 import { RZ_LIGHT_STRUCT_WGSL } from "../lights"
 import { sceneTapApi } from "../scene-tap"
 import { anchorAliasWgsl } from "../anchor-table"
-import { CAST_API } from "../cast-api"
+import { CAST_API, CAST_MASK_ALL, subjectMaskApi } from "../cast-api"
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
 import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "../cast-layout"
 import { audioApi } from "../audio-api"
@@ -337,8 +337,9 @@ fn rzResolution() -> vec2f { return viewU[6].zw; }
 /** The camera's world position. */
 fn rzCameraPos() -> vec3f { return viewU[10].xyz; }
 
-/** How many characters are in the scene, up to four. */
-fn rzSubjectCount() -> i32 { return i32(viewU[10].w); }
+/** How many characters the SCENE holds, up to four — the number the cast api
+ *  narrows to this effect's own subjects. See subjectMaskApi. */
+fn _rzCastLive() -> i32 { return i32(viewU[10].w); }
 
 /**
  * A world point as the camera sees it: xy the uv it lands on, z its distance
@@ -407,8 +408,14 @@ fn bgSubjectCount() -> i32 { return rzSubjectCount(); }
  * Clamped rather than bounds-checked: an effect looping past the count reads the
  * last subject instead of sampling whatever follows the array, which is a wrong
  * ripple rather than an undefined one.
+ *
+ * THE INDEX IS THE EFFECT'S OWN, like every other cast accessor — Dry Ice, Water,
+ * Holy Light and Bloody Ash all read this one and all of them should place their
+ * fog, their ripple and their shaft under the model the scene aimed them at. The
+ * mapping is the identity for an effect aimed at nobody in particular, which is
+ * every scene published before one could be aimed.
  */
-fn rzSubjectHip(i: i32) -> vec3f { return viewU[11 + clamp(i, 0, 3)].xyz; }
+fn rzSubjectHip(i: i32) -> vec3f { return viewU[11 + clamp(_rzSubjectSlot(i), 0, 3)].xyz; }
 
 fn bgSubjectPos(i: i32) -> vec3f { return rzSubjectHip(i); }
 
@@ -659,7 +666,13 @@ export function buildCompositeShader(effect?: CompositeEffectSource | null): str
   // The composite is STATIC either way now: the user's code compiles in the
   // field module alone, and the composite only decides whether to sample it.
   return COMPOSITE_HEAD +
-    EFFECT_SCENE_API + anchorAliasWgsl(effect?.alias ?? []) + audioApi(0, 13) + midiApi(0, 19) + lyricsApi(0, 24) + body
+    EFFECT_SCENE_API +
+    subjectMaskApi(CAST_MASK_ALL) +
+    anchorAliasWgsl(effect?.alias ?? []) +
+    audioApi(0, 13) +
+    midiApi(0, 19) +
+    lyricsApi(0, 24) +
+    body
 }
 
 /**
@@ -691,6 +704,9 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
   return (
     COMPOSITE_HEAD +
     EFFECT_SCENE_API +
+    // Which characters this effect is on, out of its own clock block — see the
+    // declaration of _rzFieldClock below for why that buffer is per effect.
+    subjectMaskApi("u32(_rzFieldClock.z)") +
     anchorAliasWgsl(effect.alias ?? []) +
     audioApi(0, 13) +
     midiApi(0, 19) +
@@ -727,7 +743,7 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
  * whose lightEmit read its own epoch disagreed with its own background()
  * about what time it was. One buffer per effect, one answer.
  */
-@group(0) @binding(22) var<uniform> _rzFieldClock: vec4f;   // (time, weight, _, _)
+@group(0) @binding(22) var<uniform> _rzFieldClock: vec4f;   // (time, weight, subject mask, _)
 
 /** A filter's own straight-alpha output over the premultiplied layers it read
  *  (the layer blend state, restated) and the additive form of the same. */

package/src/shaders/passes/grid.ts

@@ -3,6 +3,7 @@ import { lyricsApi } from "../lyrics-api"
 import { anchorAliasWgsl } from "../anchor-table"
 import { midiApi } from "../midi-api"
 import { EFFECT_SCENE_API } from "./composite"
+import { subjectMaskApi } from "../cast-api"
 import { SCENE_TAP_STUB } from "../scene-tap"
 import { type CastLayout } from "./particles"
 import { clockApi, trailSlotsApi, viewportApi } from "./hosted-api"
@@ -91,6 +92,11 @@ struct SimU {
   dt: f32,
   size: f32,
   frame: f32,
+  /** Which cast slots this effect is on, one bit each — see subjectMaskApi. */
+  mask: f32,
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,
 }
 `
 
@@ -140,6 +146,9 @@ fn rzGridPrev(uv: vec2f) -> vec4f {
 }
 ` +
     EFFECT_SCENE_API +
+    // Which characters this kernel is on. A wake follows the feet it was aimed
+    // at, and a grid the whole cast walks through is the default.
+    subjectMaskApi("u32(su.mask)") +
     SCENE_TAP_STUB +
     // The alias _rzSlot, which the scene API's accessors route through. Every
     // module embedding EFFECT_SCENE_API must splice this; the sim module was

package/src/shaders/passes/particles.ts

@@ -4,7 +4,7 @@ import { audioApi } from "../audio-api"
 import { lyricsApi } from "../lyrics-api"
 import { anchorAliasWgsl } from "../anchor-table"
 import { midiApi } from "../midi-api"
-import { CAST_API } from "../cast-api"
+import { CAST_API, subjectMaskApi } from "../cast-api"
 import { EFFECT_SUBJECT_VEC4S } from "../cast-layout"
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
 import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract"
@@ -54,12 +54,12 @@ export type CastLayout = {
  *  a kernel that displaces fog has to know where the dancer's feet are. */
 function castApi(cast: CastLayout): string {
   return (
-    // rzSubjectCount FIRST, because CAST_API is written against it and this
-    // module has no view uniform to read the engine's count out of. Scanning
-    // for a subject whose bounding sphere has a radius is the same answer by a
+    // _rzCastLive FIRST, because CAST_API is written against it and this module
+    // has no view uniform to read the engine's count out of. Scanning for a
+    // subject whose bounding sphere has a radius is the same answer by a
     // different route — the seam is named at the top of cast-api.ts.
     `
-fn rzSubjectCount() -> i32 {
+fn _rzCastLive() -> i32 {
   var n = 0;
   for (var i = 0; i < RZ_SUBJECTS; i++) {
     if (_rzCast[i * ${EFFECT_SUBJECT_VEC4S} + 2].w > 0.0) { n = i + 1; }
@@ -67,6 +67,7 @@ fn rzSubjectCount() -> i32 {
   return n;
 }
 ` +
+    subjectMaskApi("u32(pu.subjects)") +
     CAST_API +
     trailSlotsApi(cast.trailCount) +
     anchorAliasWgsl(cast.alias)
@@ -111,7 +112,8 @@ struct ParticleU {
   frame: u32,
   /** The effect's evaluated influence, applied at the one output site below. */
   weight: f32,
-  _pad0: f32,
+  /** Which cast slots this effect is on, one bit each — see subjectMaskApi. */
+  subjects: f32,
   _pad1: f32,
   _pad2: f32,
 }

package/src/shaders/passes/trails.ts

@@ -4,7 +4,7 @@ import { audioApi } from "../audio-api"
 import { lyricsApi } from "../lyrics-api"
 import { anchorAliasWgsl, ribbonSlotWgsl } from "../anchor-table"
 import { midiApi } from "../midi-api"
-import { CAST_API } from "../cast-api"
+import { CAST_API, subjectMaskApi } from "../cast-api"
 import { EFFECT_SUBJECT_VEC4S } from "../cast-layout"
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
 import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract"
@@ -94,6 +94,7 @@ export function buildTrailShader(
   },
 ): string {
   return (
+    subjectMaskApi("u32(tu.mask)") +
     CAST_API +
     trailSlotsApi(src.slots) +
     EFFECT_MATH_API +
@@ -129,17 +130,21 @@ struct CameraU {
 }
 struct TrailU {
   time: f32,
-  // How many subjects the cast ACTUALLY holds this frame, not the four the
-  // layout has room for. The instance count is sized by this on the CPU and
-  // decoded by it here, and the two must use the same number or the flattened
-  // [ribbon][subject][segment] index lands on the wrong ribbon. It is a uniform
-  // rather than the RZ_SUBJECTS constant precisely because it changes when a
-  // model is added or removed, and recompiling every trail shader for that
-  // would be absurd.
+  // How many subjects THIS EFFECT ribbons this frame, not the four the layout
+  // has room for and not the whole cast. The instance count is sized by this on
+  // the CPU and decoded by it here, and the two must use the same number or the
+  // flattened [ribbon][subject][segment] index lands on the wrong ribbon. It is
+  // a uniform rather than the RZ_SUBJECTS constant precisely because it changes
+  // when a model is added, removed, hidden or taken off this effect's list, and
+  // recompiling every trail shader for that would be absurd.
+  //
+  // The subject it decodes is the effect's OWN index, which is what rzTrail
+  // takes — so a ribbon aimed at one dancer draws one ribbon, on her.
   subjects: f32,
   /** The effect's evaluated influence, applied at the one output site below. */
   weight: f32,
-  _pad2: f32,
+  /** Which cast slots this effect is on, one bit each — see subjectMaskApi. */
+  mask: f32,
 }
 ${src.paramsDecl}
 @group(0) @binding(0) var<storage, read> _rzCast: array<vec4f>;
@@ -163,7 +168,7 @@ fn rzProject(p: vec3f) -> vec3f {
   return vec3f(clip.xy / w * 0.5 + 0.5, clip.w);
 }
 fn rzCamPos() -> vec3f { return cam.camPos; }
-fn rzSubjectCount() -> i32 {
+fn _rzCastLive() -> i32 {
   var n = 0;
   for (var i = 0; i < RZ_SUBJECTS; i++) {
     if (_rzCast[i * ${EFFECT_SUBJECT_VEC4S} + 2].w > 0.0) { n = i + 1; }