reze-engine 0.56.14 → 0.57.1

package/dist/engine.js

@@ -626,6 +626,28 @@ function paramValue(p, given) {
         return { x: p.value[0], y: p.value[1], z: p.value[2] };
     return typeof p.value === "number" ? p.value : 0;
 }
+/**
+ * Which models an effect is on, as it is kept: names, deduplicated, or null for
+ * the whole cast.
+ *
+ * AN EMPTY LIST IS THE WHOLE CAST, not nobody. An effect on nobody is a dark
+ * effect with no sign of why, and there are already two ways to say that on
+ * purpose — influence 0 and a schedule with no window here. A host that filters
+ * a target list down to nothing (every named model deleted, say) gets the
+ * default back instead of a scene with a mystery in it.
+ */
+function normalizeSubjects(list) {
+    if (!list || list.length === 0)
+        return null;
+    const seen = [...new Set(list.filter((n) => typeof n === "string" && n.length > 0))];
+    return seen.length === 0 ? null : seen;
+}
+/** One target set as a comparable string — `*` is the whole cast. Sorted, so two
+ *  effects naming the same models in a different order share one distance field
+ *  rather than paying for the same flood twice. */
+function castSubjectKey(subjects) {
+    return subjects ? [...subjects].sort().join("\u0000") : "*";
+}
 const EFFECT_PARAMS_BINDING = 7;
 const EFFECT_PARAMS_BINDING_GRID = 9;
 /**
@@ -809,8 +831,27 @@ export class Engine {
         this.castSeedViews = [null, null];
         this.castCoverageTexture = null;
         this.castCoverageView = null;
-        this.castDistTexture = null;
-        this.castDistView = null;
+        /**
+         * One field per distinct set of models — the seeds, the flood and the resolve
+         * run once for each.
+         *
+         * WHY IT CANNOT BE FILTERED AFTERWARDS. The field answers "how far is the
+         * nearest cast pixel", and that is a function of every pixel around this one.
+         * Ask it about a smaller cast and the answer is a different number, not a
+         * subset of the same one — the nearest pixel of the model you left out was the
+         * answer, and the true distance to the one you kept is unknown. An effect on
+         * one dancer would have its aura bitten out wherever the other one passed
+         * nearer. So a target set is a field.
+         *
+         * The PING-PONG IS SHARED, and that is most of the memory: the seeds and the
+         * coverage are scratch within one variant's chain, so the variants take turns
+         * in them and only the resolved r16float distance is per set. What a second set
+         * costs is the FLOOD — log2(resolution) full-res passes — which is the honest
+         * price of the second answer and the reason nothing here tries to be clever
+         * about it. A scene where every silhouette effect is aimed at the same models,
+         * which is nearly all of them, builds exactly one.
+         */
+        this.castDistanceVariants = [];
         /** 1x1 holding half-float 65504, bound whenever the pass is not running: an
          *  effect keyed on distance then finds the cast unreachably far and draws
          *  nothing, rather than the accessor being a name that does not exist. */
@@ -819,10 +860,12 @@ export class Engine {
         this.castSeedPipeline = null;
         this.castStepPipeline = null;
         this.castResolvePipeline = null;
-        this.castSeedBindGroup = null;
         this.castStepBindGroups = [];
-        this.castResolveBindGroup = null;
         this.castStepStrideBuffers = [];
+        /** Which of the two seed textures the last flood pass wrote — the one every
+         *  variant's resolve reads. Parity of the pass count, recorded where the
+         *  passes are counted. */
+        this.castResolveReadsSeed = 0;
         /** The visible props' object ids for the seed pass, count in slot 0. Grown in
          *  powers of two; see writeCastSeedProps. */
         this.castSeedPropBuffer = null;
@@ -1010,7 +1053,6 @@ export class Engine {
          */
         this.worldEquirectTexture = null;
         this.worldEquirectView = null;
-        this.worldStrength = 1;
         /** A three-colour sky's irradiance SH, when the world is a gradient rather
          *  than a picture. An HDRI outranks it — see writeWorld. */
         this.worldGradientSH = null;
@@ -1031,6 +1073,9 @@ export class Engine {
         /** Subjects the cast actually holds, set while it is filled. The ribbons size
          *  their instance count by this rather than by the four-subject cap. */
         this.castSubjectCount = 0;
+        /** Model name → cast slot, rebuilt as the cast is written. What turns "this
+         *  effect is on 今汐" into a bit the shaders can read. */
+        this.castSlotOf = new Map();
         this.effects = [];
         /** Just the header, for rewriting the total without touching a record. */
         this.lightHeader = new Float32Array(LIGHT_HEADER);
@@ -1659,13 +1704,15 @@ export class Engine {
         // exposure and view transform as the scene — a sun rolls off like a sun).
         // The camera basis at u[12..23] is refreshed per frame.
         // In modes 2 and 3 the colour slot is dead, so mode 3 carries the world
-        // STRENGTH in u[8] — Blender's world-strength dial, default 1.
+        // STRENGTH in u[8] — Blender's world-strength dial, the SAME number that
+        // scales the irradiance. A sky you can see at full brightness while it
+        // lights at two thirds is two skies.
         const bg = this.backgroundColor;
         // THE BACKDROP WINS WHAT YOU SEE; the world lights regardless. With only a
         // world installed it is also the sky, which is what an HDRI alone has
         // always done.
         const showingWorld = this.backdropEquirectView === null && this.worldEquirectView !== null;
-        u[8] = showingWorld ? this.worldStrength : (bg?.x ?? 0);
+        u[8] = showingWorld ? this.world.strength : (bg?.x ?? 0);
         u[9] = bg?.y ?? 0;
         u[10] = bg?.z ?? 0;
         // Base-layer mode only. A user effect is a separate LAYER over whichever
@@ -2519,19 +2566,15 @@ export class Engine {
         for (const t of this.castSeedTextures)
             t?.destroy();
         this.castCoverageTexture?.destroy();
-        this.castDistTexture?.destroy();
         for (const b of this.castStepStrideBuffers)
             b.destroy();
+        this.releaseCastDistanceVariants();
         this.castSeedTextures = [null, null];
         this.castSeedViews = [null, null];
         this.castCoverageTexture = null;
         this.castCoverageView = null;
-        this.castDistTexture = null;
-        this.castDistView = null;
         this.castStepStrideBuffers = [];
         this.castStepBindGroups = [];
-        this.castSeedBindGroup = null;
-        this.castResolveBindGroup = null;
         if (!this.device || !this.castDistanceWanted || this.fieldFullW === 0)
             return;
         if (!this.castSeedPipeline || !this.castStepPipeline || !this.castResolvePipeline)
@@ -2554,20 +2597,12 @@ export class Engine {
             usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
         });
         this.castCoverageView = this.castCoverageTexture.createView();
-        this.castDistTexture = this.device.createTexture({
-            label: "cast distance",
-            size: [w, h],
-            format: CAST_DIST_FORMAT,
-            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
-        });
-        this.castDistView = this.castDistTexture.createView();
         // The flood starts at half the longest side and halves to one. That is what
         // makes it exact everywhere rather than out to some radius: every seed gets
         // the chance to reach every texel it is nearest to.
         const strides = [];
         for (let k = 1 << Math.ceil(Math.log2(Math.max(w, h))); k >= 1; k >>= 1)
             strides.push(k);
-        this.createCastSeedBindGroup();
         strides.forEach((stride, i) => {
             const buf = this.device.createBuffer({
                 label: `cast distance stride ${stride}`,
@@ -2587,18 +2622,38 @@ export class Engine {
                 ],
             }));
         });
-        this.castResolveBindGroup = this.device.createBindGroup({
-            label: "cast distance resolve",
-            layout: this.castResolvePipeline.getBindGroupLayout(0),
-            entries: [
-                { binding: 0, resource: this.castSeedViews[strides.length % 2] },
-                { binding: 1, resource: this.castCoverageView },
-            ],
-        });
+        // WHICH seed texture the resolve reads: the one the last flood pass wrote,
+        // and that is the parity of the pass count. Shared by every variant, since
+        // they take turns in the same pair.
+        this.castResolveReadsSeed = strides.length % 2;
+        this.buildCastDistanceVariants(w, h);
+    }
+    /** Every variant's own resources, gone. The shared scratch is not touched:
+     *  a target set changing does not resize the frame. */
+    releaseCastDistanceVariants() {
+        for (const v of this.castDistanceVariants) {
+            v.texture.destroy();
+            v.uniform.destroy();
+        }
+        this.castDistanceVariants = [];
     }
-    /** The seed pass's inputs: the id attachment, the cast, and the prop ids. */
-    createCastSeedBindGroup() {
+    /**
+     * One field per distinct target set among the effects that read one, and each
+     * effect pointed at its own.
+     *
+     * Built from the effect list rather than accumulated, so a removed effect takes
+     * its flood with it and the untargeted default is not kept alive by nobody.
+     */
+    buildCastDistanceVariants(w, h) {
         const device = this.device;
+        // The seed pass reads the id attachment, so there is nothing to build before
+        // the scene has one. Effects then read the 1x1 "unreachably far" fallback,
+        // which is what an effect keyed on distance already sees while no flood is
+        // running — and the next createFieldTargets builds the real thing.
+        if (!this.idView || !this.castCoverageView) {
+            this.releaseCastDistanceVariants();
+            return;
+        }
         if (!this.castSeedPropBuffer) {
             this.castSeedPropBuffer = device.createBuffer({
                 label: "cast distance prop seeds",
@@ -2607,15 +2662,83 @@ export class Engine {
             });
             device.queue.writeBuffer(this.castSeedPropBuffer, 0, this.castSeedPropData);
         }
-        this.castSeedBindGroup = device.createBindGroup({
-            label: "cast distance seed",
-            layout: this.castSeedPipeline.getBindGroupLayout(0),
-            entries: [
-                { binding: 0, resource: this.idView },
-                { binding: 1, resource: { buffer: this.castBuffer } },
-                { binding: 2, resource: { buffer: this.castSeedPropBuffer } },
-            ],
-        });
+        this.releaseCastDistanceVariants();
+        for (const e of this.effects) {
+            if (!e.readsCastDistance)
+                continue;
+            const key = castSubjectKey(e.subjects);
+            const at = this.castDistanceVariants.findIndex((v) => castSubjectKey(v.subjects) === key);
+            if (at >= 0) {
+                e.distVariant = at;
+                continue;
+            }
+            e.distVariant = this.castDistanceVariants.length;
+            const data = new Float32Array([0xf, 0, 0, 0]);
+            const uniform = device.createBuffer({
+                label: `cast distance seeds (${key})`,
+                size: data.byteLength,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(uniform, 0, data.buffer);
+            const texture = device.createTexture({
+                label: `cast distance (${key})`,
+                size: [w, h],
+                format: CAST_DIST_FORMAT,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+            });
+            this.castDistanceVariants.push({
+                subjects: e.subjects,
+                // 0xf is what the buffer above was written with; the first frame's
+                // updateSubjectMasks narrows it to the live cast.
+                mask: 0xf,
+                uniform,
+                data,
+                seedBind: device.createBindGroup({
+                    label: `cast distance seed (${key})`,
+                    layout: this.castSeedPipeline.getBindGroupLayout(0),
+                    entries: [
+                        { binding: 0, resource: this.idView },
+                        { binding: 1, resource: { buffer: this.castBuffer } },
+                        { binding: 2, resource: { buffer: this.castSeedPropBuffer } },
+                        { binding: 3, resource: { buffer: uniform } },
+                    ],
+                }),
+                texture,
+                view: texture.createView(),
+                resolveBind: device.createBindGroup({
+                    label: `cast distance resolve (${key})`,
+                    layout: this.castResolvePipeline.getBindGroupLayout(0),
+                    entries: [
+                        { binding: 0, resource: this.castSeedViews[this.castResolveReadsSeed] },
+                        { binding: 1, resource: this.castCoverageView },
+                    ],
+                }),
+            });
+        }
+    }
+    /**
+     * The target sets changed — an effect was aimed somewhere else.
+     *
+     * Rebuilds the variants and the field bind groups that name their textures.
+     * Nothing recompiles: which field an effect reads is a binding, not a constant
+     * in its module.
+     */
+    syncCastDistanceVariants() {
+        if (!this.device || !this.castDistanceWanted || this.fieldFullW === 0)
+            return;
+        const before = this.castDistanceVariants.map((v) => castSubjectKey(v.subjects)).join("|");
+        const want = [...new Set(this.effects.filter((e) => e.readsCastDistance).map((e) => castSubjectKey(e.subjects)))].join("|");
+        if (before === want)
+            return;
+        const w = Math.max(1, Math.ceil(this.fieldFullW / CAST_FIELD_DIV));
+        const h = Math.max(1, Math.ceil(this.fieldFullH / CAST_FIELD_DIV));
+        this.buildCastDistanceVariants(w, h);
+        this.rebuildFieldBindGroup();
+    }
+    /** The field this effect reads, or the 1x1 "unreachably far" fallback while no
+     *  flood is running. */
+    castDistViewFor(owner) {
+        return this.castDistanceVariants[owner.distVariant]?.view ?? this.castDistFallbackView;
     }
     /**
      * Which props seed the field this frame: every visible one.
@@ -2636,7 +2759,10 @@ export class Engine {
             this.castSeedPropData = data;
             this.castSeedPropBuffer?.destroy();
             this.castSeedPropBuffer = null;
-            this.createCastSeedBindGroup();
+            // Every variant's seed group names that buffer, so they are all rebuilt —
+            // at the size the frame is now, which is where the shared scratch is.
+            this.buildCastDistanceVariants(Math.max(1, Math.ceil(this.fieldFullW / CAST_FIELD_DIV)), Math.max(1, Math.ceil(this.fieldFullH / CAST_FIELD_DIV)));
+            this.rebuildFieldBindGroup();
             changed = true;
         }
         data[0] = n;
@@ -2659,38 +2785,44 @@ export class Engine {
      * whole point of paying for it in passes rather than in per-pixel search.
      */
     encodeCastDistance(encoder) {
-        if (!this.castDistanceWanted || !this.castSeedBindGroup || !this.castResolveBindGroup)
+        if (!this.castDistanceWanted || this.castDistanceVariants.length === 0)
             return;
         this.writeCastSeedProps();
-        const seed = encoder.beginRenderPass({
-            label: "cast distance (seed)",
-            colorAttachments: [
-                { view: this.castSeedViews[0], loadOp: "clear", clearValue: { r: -1, g: -1, b: 0, a: 0 }, storeOp: "store" },
-                { view: this.castCoverageView, loadOp: "clear", clearValue: { r: 0, g: 0, b: 0, a: 0 }, storeOp: "store" },
-            ],
-        });
-        seed.setPipeline(this.castSeedPipeline);
-        seed.setBindGroup(0, this.castSeedBindGroup);
-        seed.draw(3);
-        seed.end();
-        this.castStepBindGroups.forEach((group, i) => {
-            const pass = encoder.beginRenderPass({
-                label: "cast distance (flood)",
-                colorAttachments: [{ view: this.castSeedViews[(i + 1) % 2], loadOp: "clear", clearValue: { r: -1, g: -1, b: 0, a: 0 }, storeOp: "store" }],
+        // One chain per target set, in turn through the shared seed pair. Serial and
+        // not overlapped on purpose: the second chain overwrites the first's scratch,
+        // and the only thing that has to survive is the resolved distance, which is
+        // each variant's own texture.
+        for (const v of this.castDistanceVariants) {
+            const seed = encoder.beginRenderPass({
+                label: "cast distance (seed)",
+                colorAttachments: [
+                    { view: this.castSeedViews[0], loadOp: "clear", clearValue: { r: -1, g: -1, b: 0, a: 0 }, storeOp: "store" },
+                    { view: this.castCoverageView, loadOp: "clear", clearValue: { r: 0, g: 0, b: 0, a: 0 }, storeOp: "store" },
+                ],
             });
-            pass.setPipeline(this.castStepPipeline);
-            pass.setBindGroup(0, group);
-            pass.draw(3);
-            pass.end();
-        });
-        const resolve = encoder.beginRenderPass({
-            label: "cast distance (resolve)",
-            colorAttachments: [{ view: this.castDistView, loadOp: "clear", clearValue: { r: 0, g: 0, b: 0, a: 0 }, storeOp: "store" }],
-        });
-        resolve.setPipeline(this.castResolvePipeline);
-        resolve.setBindGroup(0, this.castResolveBindGroup);
-        resolve.draw(3);
-        resolve.end();
+            seed.setPipeline(this.castSeedPipeline);
+            seed.setBindGroup(0, v.seedBind);
+            seed.draw(3);
+            seed.end();
+            this.castStepBindGroups.forEach((group, i) => {
+                const pass = encoder.beginRenderPass({
+                    label: "cast distance (flood)",
+                    colorAttachments: [{ view: this.castSeedViews[(i + 1) % 2], loadOp: "clear", clearValue: { r: -1, g: -1, b: 0, a: 0 }, storeOp: "store" }],
+                });
+                pass.setPipeline(this.castStepPipeline);
+                pass.setBindGroup(0, group);
+                pass.draw(3);
+                pass.end();
+            });
+            const resolve = encoder.beginRenderPass({
+                label: "cast distance (resolve)",
+                colorAttachments: [{ view: v.view, loadOp: "clear", clearValue: { r: 0, g: 0, b: 0, a: 0 }, storeOp: "store" }],
+            });
+            resolve.setPipeline(this.castResolvePipeline);
+            resolve.setBindGroup(0, v.resolveBind);
+            resolve.draw(3);
+            resolve.end();
+        }
     }
     createFieldTargets() {
         if (!this.device || this.fieldFullW === 0)
@@ -2803,7 +2935,7 @@ export class Engine {
                 ...(this.idView ? [{ binding: 23, resource: this.idView }] : []),
                 { binding: 17, resource: grid },
                 { binding: 18, resource: this.simSampler },
-                { binding: 26, resource: this.castDistView ?? this.castDistFallbackView },
+                { binding: 26, resource: this.castDistViewFor(owner) },
                 { binding: 27, resource: this.hdrResolveTexture.createView() },
                 { binding: 28, resource: this.simSampler },
                 // The other effects' layers, for rzSceneFrame — see the loop below.
@@ -2927,7 +3059,7 @@ export class Engine {
      * `strength` is Blender's world-strength dial and is folded into the
      * coefficients, so what lights her is what you see.
      */
-    setWorldEquirect(source, options) {
+    setWorldEquirect(source) {
         // RETIRED, NOT DESTROYED. A frame already encoded against the old sky can
         // still be in flight — the bind groups that name it are rebuilt below, but
         // the command buffer holding the previous ones is submitted at the end of
@@ -2938,7 +3070,6 @@ export class Engine {
             this.retiredSkies.push(this.worldEquirectTexture);
         this.worldEquirectTexture = null;
         this.worldEquirectView = null;
-        this.worldStrength = Math.max(options?.strength ?? 1, 0);
         const hadSH = this.worldSH !== null;
         this.worldSH = null;
         if (source && this.device) {
@@ -2993,11 +3124,13 @@ export class Engine {
             // The sky lights the scene, not only backs it. The sun keeps the toon
             // ramp — this is the ambient term, exactly where the flat world colour
             // used to sit.
+            // RAW irradiance. The World strength dial is applied where every other
+            // reading of it is, in writeWorld — folding it in here made the sky's
+            // brightness a function of WHEN it was installed: the dial moved
+            // afterwards rescaled the write and not the projection, and an install
+            // that landed mid-session carried a different strength from the same
+            // document reopened.
             this.worldSH = projectIrradianceSH({ ...source, data: source.data }, 4);
-            if (this.worldStrength !== 1) {
-                for (let i = 0; i < this.worldSH.length; i++)
-                    this.worldSH[i] *= this.worldStrength;
-            }
         }
         if (this.worldSH || hadSH)
             this.writeWorld();
@@ -3119,7 +3252,7 @@ export class Engine {
     alias) {
         const noMounts = { background: false, foreground: false };
         if (!this.device)
-            return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts, params: [], duration: 0 };
+            return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts, params: [], duration: 0, readsCast: false };
         // WHAT THE FILE DECLARES, read once. Everything below takes it from `d`
         // rather than running a regex of its own — eight parsers over one file was
         // eight chances to disagree about what it said, and they did.
@@ -3130,7 +3263,7 @@ export class Engine {
         // typo was indistinguishable from prose and could only ever be warned about.
         const parsed = parseDirectives(authored);
         if (parsed.errors.length)
-            return { ok: false, diagnostics: parsed.errors, mounts: noMounts, params: [], duration: 0 };
+            return { ok: false, diagnostics: parsed.errors, mounts: noMounts, params: [], duration: 0, readsCast: false };
         const d = parsed.directives;
         // The compiler sees the file with its directive lines BLANKED, so every
         // diagnostic below still names the line the author is looking at.
@@ -3153,7 +3286,7 @@ export class Engine {
             return { ok: false, diagnostics: [
                     `a ribbon effect needs both fn trailWidth(u: f32, age: f32) -> f32 and ` +
                         `fn trailShade(u: f32, v: f32, age: f32, weight: f32, slot: i32) -> vec4f`,
-                ], mounts: noMounts, params: [], duration: 0 };
+                ], mounts: noMounts, params: [], duration: 0, readsCast: false };
         }
         if (wantsParticles && !(pe.init && pe.step && pe.shade)) {
             const missing = [
@@ -3161,7 +3294,7 @@ export class Engine {
                 pe.step ? null : "fn particleStep(p: Particle, dt: f32) -> Particle",
                 pe.shade ? null : "fn particleShade(p: Particle, uv: vec2f) -> vec4f",
             ].filter(Boolean);
-            return { ok: false, diagnostics: [`a particle effect also needs ${missing.join(" and ")}`], mounts: noMounts, params: [], duration: 0 };
+            return { ok: false, diagnostics: [`a particle effect also needs ${missing.join(" and ")}`], mounts: noMounts, params: [], duration: 0, readsCast: false };
         }
         // One file, one kind — for now.
         //
@@ -3179,7 +3312,7 @@ export class Engine {
             return { ok: false, diagnostics: [
                     "an effect declares field mounts (background/foreground) or particles, not both — " +
                         "split them into two effects",
-                ], mounts: noMounts, params: [], duration: 0 };
+                ], mounts: noMounts, params: [], duration: 0, readsCast: false };
         }
         // lightEmit counts as a mount on its own: a pure lighting rig draws nothing
         // and is still an effect — it is how a scene gets stage lights without also
@@ -3195,7 +3328,7 @@ export class Engine {
                         "the ribbon pair (trailWidth/trailShade), " +
                         "fn lightEmit(i: u32) -> RzLight with #lights <n>, " +
                         "or #mirror",
-                ], mounts: noMounts, params: [], duration: 0 };
+                ], mounts: noMounts, params: [], duration: 0, readsCast: false };
         }
         const mounts = { background: hasBackground, foreground: hasForeground };
         // ── Directives only some mounts honour ──
@@ -3247,7 +3380,7 @@ export class Engine {
         let cursor = 0;
         for (const p of d.params) {
             if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(p.name)) {
-                return { ok: false, diagnostics: [`invalid param name "${p.name}" (must be a WGSL identifier)`], mounts, params: d.params, duration: d.duration };
+                return { ok: false, diagnostics: [`invalid param name "${p.name}" (must be a WGSL identifier)`], mounts, params: d.params, duration: d.duration, readsCast: false };
             }
             // KIND comes from the declaration, never from the runtime type of the
             // value: a caller handing a number to a colour must not silently turn a
@@ -3303,7 +3436,7 @@ export class Engine {
         const module = this.device.createShaderModule({ label: "composite shader (effect)", code: source });
         const scopeErr = await this.device.popErrorScope();
         if (scopeErr)
-            return { ok: false, diagnostics: [scopeErr.message], mounts, params: d.params, duration: d.duration };
+            return { ok: false, diagnostics: [scopeErr.message], mounts, params: d.params, duration: d.duration, readsCast: false };
         // Declared like every other mount property: by what the source says, not by
         // a setting somewhere else that an author cannot see from the file.
         const layerBlend = d.additiveLayer
@@ -3323,7 +3456,7 @@ export class Engine {
             if (diagnostics.length === 0 && fieldScopeErr)
                 diagnostics.push(fieldScopeErr.message);
             if (diagnostics.length > 0)
-                return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration };
+                return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration, readsCast: false };
             try {
                 fieldPipeline = await this.device.createRenderPipelineAsync({
                     label: "field layer pipeline",
@@ -3355,7 +3488,7 @@ export class Engine {
                 });
             }
             catch (e) {
-                return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts, params: d.params, duration: d.duration };
+                return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts, params: d.params, duration: d.duration, readsCast: false };
             }
         }
         let identity;
@@ -3379,7 +3512,7 @@ export class Engine {
             ]);
         }
         catch (e) {
-            return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts, params: d.params, duration: d.duration };
+            return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts, params: d.params, duration: d.duration, readsCast: false };
         }
         // Built BEFORE the swap: a particle stage that fails to compile has to leave
         // the previously installed effect running, exactly as a bad composite does.
@@ -3430,7 +3563,7 @@ export class Engine {
             grid?.textures[1].destroy();
             grid?.uniform.destroy();
             trails?.uniform.destroy();
-            return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration };
+            return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration, readsCast: false };
         };
         if (wantsParticles) {
             const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor);
@@ -3503,6 +3636,19 @@ export class Engine {
             // attachment would be stored exactly as often as before.
             readsIds: /\brz(?:ObjectAt|MaterialAt)\s*\(/.test(wgsl),
             readsCastDistance: castDistanceUsed(wgsl),
+            // Every route to the cast, in one test, and the author's own source for
+            // the reason readsIds gives. `#anchor` counts: a file declaring one asks
+            // the engine to record a bone for it, whether or not the accessor is
+            // spelled out in a line this matches.
+            readsCast: /\brz(?:Subject|SubjectCount|SubjectId|Anchor|Trail|TrailCount|CastDistance)\s*\(/.test(wgsl) ||
+                anchors.length > 0,
+            // Aimed at nobody in particular — the whole cast, which is what every
+            // effect did before it could be aimed. A host narrows it afterwards, the
+            // way it sets influence and a schedule.
+            subjects: null,
+            subjectMask: 0xf,
+            subjectCount: 0,
+            distVariant: 0,
             anchors,
             // The effect's own clock starts now. Per effect so that one installed
             // later still gets a frame where rzGridFrame() is 0 and can seed.
@@ -3581,7 +3727,7 @@ export class Engine {
         if (!this.device) {
             if (!list || list.length === 0)
                 return [];
-            return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts, params: [], duration: 0 }];
+            return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts, params: [], duration: 0, readsCast: false }];
         }
         const requested = list ?? [];
         if (requested.length === 0) {
@@ -3622,6 +3768,7 @@ export class Engine {
                 results.push(built);
                 continue;
             }
+            built.instance.subjects = normalizeSubjects(requested[i].subjects);
             instances.push(built.instance);
             results.push({
                 ok: true,
@@ -3631,6 +3778,9 @@ export class Engine {
                 // but will never fire. Same channel as the dropped-anchor note below.
                 diagnostics: built.warnings,
                 mounts: { background: built.instance.hasBackground, foreground: built.instance.hasForeground },
+                // Whether aiming this one at particular models means anything. Read off
+                // the instance the engine just built, not off a second parse.
+                readsCast: built.instance.readsCast,
             });
         }
         // An anchor the cap refused is worth saying out loud on the effect that
@@ -3663,6 +3813,12 @@ export class Engine {
             // The field bind groups name the distance texture, and it has just been
             // created or destroyed — they are rebuilt below with the new list anyway.
         }
+        else {
+            // The answer did not change, but WHO the fields are built from may have:
+            // this list's effects are aimed wherever the install said, and the old
+            // list's variants belong to effects that are gone.
+            this.syncCastDistanceVariants();
+        }
         // The new list's emitters need their slots before the next frame reads them.
         this.allocateLightSlots();
         // A rig the cap refused is worth saying out loud on the effect that asked
@@ -3720,10 +3876,10 @@ export class Engine {
         const noMounts = { background: false, foreground: false };
         if (wgsl === null) {
             await this.setEffects(null);
-            return { ok: true, diagnostics: [], mounts: noMounts, params: [], duration: 0 };
+            return { ok: true, diagnostics: [], mounts: noMounts, params: [], duration: 0, readsCast: false };
         }
         const [result] = await this.setEffects([{ wgsl, params }]);
-        return result ?? { ok: false, diagnostics: ["effect failed to install"], mounts: noMounts, params: [], duration: 0 };
+        return result ?? { ok: false, diagnostics: ["effect failed to install"], mounts: noMounts, params: [], duration: 0, readsCast: false };
     }
     async buildParticles(
     /** Already stripped of directives — see compileEffect. */
@@ -3780,7 +3936,7 @@ export class Engine {
         });
         const uniform = this.device.createBuffer({
             label: "particle uniforms",
-            // Two vec4-sized rows: (time, dt, count, frame) and (weight, _, _, _).
+            // Two vec4-sized rows: (time, dt, count, frame) and (weight, subjects, _, _).
             // The first was exactly full, and weight has to live in the same buffer
             // as the clock or a frame could draw one without the other.
             size: 32,
@@ -3928,7 +4084,10 @@ export class Engine {
         const diagnostics = info.messages.filter((m) => m.type === "error").map((m) => `${m.lineNum}:${m.linePos} ${m.message}`);
         if (diagnostics.length)
             return { ok: false, diagnostics };
-        const data = new Float32Array(4);
+        // Two vec4s: (time, base slot, count, weight) and the subject mask — an
+        // emitter reads the cast through the same accessors its drawing half does,
+        // so it needs the same answer about who this effect is on.
+        const data = new Float32Array(8);
         const uniform = this.device.createBuffer({
             label: "light emit uniform",
             size: data.byteLength,
@@ -4020,6 +4179,9 @@ export class Engine {
             // per effect now, so every mount in one file agrees by construction.
             l.data[0] = this.sceneClock - e.epochScene;
             l.data[3] = e.weight;
+            // Which characters this rig is on — the second vec4. A lamp that follows a
+            // hand follows the hand of the model the effect is aimed at.
+            l.data[4] = e.subjectMask;
             this.device.queue.writeBuffer(l.uniform, 0, l.data.buffer);
             const cp = encoder.beginComputePass({ label: "light emit" });
             cp.setPipeline(l.pipeline);
@@ -4049,6 +4211,9 @@ export class Engine {
             // state it left rather than the one it would have reached, so fading one
             // back in would rewind it.
             p.data[4] = e.weight;
+            // Which characters this pool spawns off — rzSubjectCount() in particleInit
+            // counts these, not the cast.
+            p.data[5] = e.subjectMask;
             // Clamped: a backgrounded tab returns with a delta of whole seconds, and an
             // unclamped step flings every particle out of the scene in one frame.
             // A scheduled effect steps by the transport instead, clamped the same way
@@ -4267,11 +4432,16 @@ export class Engine {
             // The shader decodes [ribbon][subject][segment] with the same number out
             // of its uniform, so the two cannot drift: change one without the other
             // and ribbons land on the wrong subject rather than merely costing more.
-            const live = Math.max(1, this.castSubjectCount);
+            // THIS EFFECT'S subjects, not the scene's: a ribbon aimed at one dancer
+            // draws one ribbon. The shader decodes [ribbon][subject][segment] out of
+            // the same number, and the subject it decodes is the effect's own index —
+            // which is exactly what rzTrail takes.
+            const live = Math.max(1, e.subjectCount);
             if (view === "camera") {
                 t.data[0] = this.sceneClock - e.epochScene;
                 t.data[1] = live;
                 t.data[2] = e.weight;
+                t.data[3] = e.subjectMask;
                 this.device.queue.writeBuffer(t.uniform, 0, t.data.buffer);
             }
             pass.setPipeline(t.pipeline);
@@ -4310,6 +4480,10 @@ export class Engine {
                 continue;
             this.fieldClockScratch[0] = this.sceneClock - e.epochScene;
             this.fieldClockScratch[1] = e.weight;
+            // Which characters this effect is on. In the clock block because that is
+            // the one uniform a field mount already has per effect, and both are the
+            // same kind of thing: what is true of THIS effect this frame.
+            this.fieldClockScratch[2] = e.subjectMask;
             this.device.queue.writeBuffer(e.fieldClock, 0, this.fieldClockScratch.buffer);
         }
         // ONE PASS PER RESOLUTION, N draws each, in document order — a pair is
@@ -4507,7 +4681,9 @@ export class Engine {
         const read = [textures[0].createView(), textures[1].createView()];
         const uniform = this.device.createBuffer({
             label: "grid uniforms",
-            size: 16,
+            // Two vec4s: (time, dt, size, frame) and the subject mask, which WGSL pads
+            // out to the second one whether or not anything else joins it.
+            size: 32,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
         this.device.pushErrorScope("validation");
@@ -4536,7 +4712,7 @@ export class Engine {
                     layout,
                     binds: [bindFor(0), bindFor(1)],
                     uniform,
-                    data: new Float32Array(4),
+                    data: new Float32Array(8),
                     parity: 0,
                     frame: 0,
                     params: params.buffer,
@@ -4595,6 +4771,7 @@ export class Engine {
             grid.data[1] = scheduled ? e.simStep : Math.min(0.1, Math.max(0, deltaTime));
             grid.data[2] = grid.size;
             grid.data[3] = grid.frame++;
+            grid.data[4] = e.subjectMask;
             this.device.queue.writeBuffer(grid.uniform, 0, grid.data.buffer);
             const cp = encoder.beginComputePass({ label: "grid" });
             cp.setPipeline(grid.pipeline);
@@ -4669,6 +4846,45 @@ export class Engine {
     getEffectInfluence(index) {
         return this.effects[index]?.influence ?? 0;
     }
+    /**
+     * WHICH MODELS one effect is on, by name. Null is the whole cast, which is
+     * what an effect starts as and what every effect did before this existed.
+     *
+     * The filter lands in the INDEX SPACE the shaders read, not in the shaders: the
+     * effect's rzSubjectCount() counts only the models named, and rzSubject(0),
+     * rzAnchor(0, …) and rzTrail(0, …) are the first of them. So a file written
+     * against the whole cast — every shipped built-in — is aimed by this without a
+     * line changing, and one that hardcodes subject 0 follows the model it is aimed
+     * at rather than whoever happened to load first.
+     *
+     * Names, because a cast SLOT is not a property of a model: the cast is every
+     * visible character in load order, so hiding one moves everybody after them up
+     * a slot. They resolve in the loop that assigns the slots, once a frame.
+     *
+     * A name the cast does not hold is simply not in the mask — a model still
+     * loading, or one since removed. It is not an error and not a warning: the
+     * cast changes under a scene all the time, and a target is a claim about the
+     * scene rather than about this frame of it.
+     *
+     * Aiming an effect that reads no cast at all (rain, a glitch, a tone curve)
+     * does nothing, and that is why the install reports `readsCast` — so a host
+     * can decline to offer the control rather than offer one that does nothing.
+     */
+    setEffectSubjects(index, models) {
+        const fx = this.effects[index];
+        if (!fx)
+            return;
+        fx.subjects = normalizeSubjects(models);
+        // The distance field is built per distinct target set, so changing one may
+        // add or drop a whole flood — and the field bind groups name the texture it
+        // resolves into.
+        if (fx.readsCastDistance)
+            this.syncCastDistanceVariants();
+    }
+    /** What one effect is aimed at, or null for the whole cast. */
+    getEffectSubjects(index) {
+        return this.effects[index]?.subjects ?? null;
+    }
     /**
      * Schedule one instance: when it is alive, and how it enters and leaves.
      *
@@ -8569,6 +8785,54 @@ export class Engine {
     getModel(name) {
         return this.modelInstances.get(name)?.model ?? null;
     }
+    /**
+     * What the engine is actually about to draw, per model.
+     *
+     * Every model the engine holds, not every model the host thinks it holds —
+     * which is the point. A scene that comes up brighter after an upload than the
+     * same document does after a reload differs somewhere between the two, and
+     * the candidates are all countable: a model left behind by a replace draws its
+     * transparent surfaces a second time, and a group that compiled but claimed
+     * nothing leaves its materials on the default graph. Both are invisible from
+     * the host, which sees its own lists rather than the engine's.
+     *
+     * `grouped` counts draw calls bound to a style group; `ungrouped` is the rest,
+     * on the default graph.
+     */
+    /**
+     * What the composite is about to put behind the scene, and at what level.
+     *
+     * `mode` is the base layer: 0 transparent, 1 a flat colour, 2 an LDR 360
+     * picture, 3 the HDR world as scene-linear radiance. `level` is what mode 3
+     * is multiplied by. The whole frame's brightness turns on these two, and
+     * neither is visible from a host reading its own document — a scene that came
+     * up brighter after an upload than after a reload of the same document is one
+     * of the cases they answer.
+     */
+    getBackgroundState() {
+        const showingWorld = this.backdropEquirectView === null && this.worldEquirectView !== null;
+        return {
+            mode: this.backdropEquirectView ? 2 : showingWorld ? 3 : this.backgroundColor ? 1 : 0,
+            level: this.world.strength,
+            backdrop: this.backdropEquirectView !== null,
+            world: this.worldEquirectView !== null,
+        };
+    }
+    getDrawStats() {
+        const out = [];
+        for (const [name, inst] of this.modelInstances) {
+            const shaded = inst.drawCalls.filter((d) => d.baseBindGroupEntries);
+            out.push({
+                model: name,
+                materials: shaded.length,
+                opaque: shaded.filter((d) => d.type === "opaque").length,
+                transparent: shaded.filter((d) => d.type === "transparent").length,
+                grouped: shaded.filter((d) => d.groupId !== null).length,
+                ungrouped: shaded.filter((d) => d.groupId === null).length,
+            });
+        }
+        return out;
+    }
     /**
      * Hang a model from a bone of another — MMD's 外部親 (outside parent).
      *
@@ -9432,13 +9696,16 @@ export class Engine {
         install.uniformBuffer.destroy();
         for (const tex of install.images ?? [])
             tex?.destroy();
+        for (const set of Object.values(install.imagesByMaterial ?? {}))
+            for (const tex of set)
+                tex?.destroy();
     }
     /** Upload a group's image maps. Sources are decoded images the host already
      *  holds; the engine never fetches, matching how models and motions arrive. */
-    uploadGroupImages(group) {
-        if (!group.images?.length)
+    uploadGroupImages(group, slots = group.images) {
+        if (!slots?.length)
             return undefined;
-        return group.images.slice(0, 4).map((entry) => {
+        return slots.slice(0, 4).map((entry) => {
             if (!entry)
                 return null;
             const wrapped = "source" in entry;
@@ -13267,15 +13534,22 @@ export class Engine {
         return true;
     }
     /** The model at one cast slot — the subject rzSubject(index) reads. */
-    castSubjectName(index) {
+    castSubjectName(index, subjects = null) {
         let n = 0;
+        let local = 0;
         let found = null;
         this.forEachInstance((inst) => {
             if (found !== null || n >= MAX_EFFECT_SUBJECTS || inst.isStage || inst.isPlane || inst.isProp || !inst.model.visible)
                 return;
-            if (n === index)
-                found = inst.name;
             n++;
+            // The effect's OWN index, which is what its shaders count in: an effect
+            // aimed at the third dancer finds her at 0, so a #dissolve on it takes HER
+            // apart rather than whoever stands at the head of the cast.
+            if (subjects && !subjects.includes(inst.name))
+                return;
+            if (local === index)
+                found = inst.name;
+            local++;
         });
         return found;
     }
@@ -13297,9 +13571,10 @@ export class Engine {
      *
      * Two things ask for one. A cycle set on a model (setModelDissolveCycle) runs
      * on the scene clock and repeats, as it always has. An effect declaring
-     * `#dissolve` takes subject 0 apart on ITS OWN terms: scheduled, the cycle on
-     * each clip's clock with her whole between clips; unscheduled, the same
-     * repeating cycle as before. Where both ask, the more dissolved wins — two
+     * `#dissolve` takes ITS OWN subject 0 apart on its own terms — the first model
+     * it is aimed at, the head of the cast when it is aimed at nobody in
+     * particular: scheduled, the cycle on each clip's clock with her whole between
+     * clips; unscheduled, the same repeating cycle as before. Where both ask, the more dissolved wins — two
      * answers about one body, and half a body is not one of them.
      */
     evaluateDissolves() {
@@ -13312,7 +13587,7 @@ export class Engine {
             if (!fx.dissolve)
                 continue;
             const cycle = dissolveCycleOf(this.dissolveTimingsOf(fx, fx.dissolve));
-            const subject = this.castSubjectName(0);
+            const subject = this.castSubjectName(0, fx.subjects);
             if (!cycle || !subject)
                 continue;
             if (fx.window && fx.window.length > 0) {
@@ -13348,7 +13623,19 @@ export class Engine {
     async compileAndInstallGroup(inst, group, opts) {
         const renderClass = group.renderClass ?? "auto";
         const alphaMode = group.alphaMode ?? "opaque";
-        const signature = JSON.stringify({ g: group.graph, rc: renderClass, am: alphaMode, o: opts?.previewNode ?? null });
+        // THE MAPS ARE PART OF THE SIGNATURE, because a matching one skips the
+        // upload below and keeps whatever the install already holds. A group can
+        // arrive twice — once as the model lands and again once its sidecar has
+        // decoded — and without this the second apply refreshed the definition and
+        // silently kept the empty slots from the first.
+        const signature = JSON.stringify({
+            g: group.graph,
+            rc: renderClass,
+            am: alphaMode,
+            o: opts?.previewNode ?? null,
+            im: group.images?.length ?? 0,
+            ibm: Object.keys(group.imagesByMaterial ?? {}).sort(),
+        });
         const existing = inst.styleGroups.get(group.id);
         if (existing && existing.signature === signature) {
             existing.group = group; // refresh def (label/materials) without recompiling
@@ -13418,6 +13705,9 @@ export class Engine {
             mirrorPipeline,
             uniformBuffer,
             images: this.uploadGroupImages(group),
+            imagesByMaterial: group.imagesByMaterial
+                ? Object.fromEntries(Object.entries(group.imagesByMaterial).map(([name, slots]) => [name, this.uploadGroupImages(group, slots) ?? []]))
+                : undefined,
             slotMap: result.slotMap,
             signature,
         });
@@ -13488,10 +13778,13 @@ export class Engine {
                     : dc.baseType;
             if (dc.type !== type)
                 dc.type = type;
-            if (dc.groupId === groupId)
+            // Rebind when the INSTALL changed, not merely when the id did.
+            const bound = install ?? null;
+            if (dc.groupId === groupId && dc.boundInstall === bound)
                 continue;
             dc.groupId = groupId;
-            dc.bindGroup = this.createMaterialBindGroup(`material: ${dc.materialName}`, dc.baseBindGroupEntries, install ? install.uniformBuffer : this.zeroStyleBuffer, install?.images);
+            dc.boundInstall = bound;
+            dc.bindGroup = this.createMaterialBindGroup(`material: ${dc.materialName}`, dc.baseBindGroupEntries, install ? install.uniformBuffer : this.zeroStyleBuffer, install?.imagesByMaterial?.[dc.materialName] ?? install?.images);
         }
         this.sortDrawCalls(inst);
     }
@@ -14007,10 +14300,17 @@ export class Engine {
             // spawned its motes off a body nobody could see, and the silhouette field
             // seeded on one. The cast is who is ON STAGE.
             let n = 0;
+            this.castSlotOf.clear();
             this.forEachInstance((inst) => {
                 if (n >= MAX_EFFECT_SUBJECTS || inst.isStage || inst.isPlane || inst.isProp || !inst.model.visible)
                     return;
                 const m = inst.model;
+                // WHO IS IN WHICH SLOT, recorded here because here is where it is
+                // decided. An effect is aimed by model name, and a name only becomes a
+                // bit in a mask once this loop has said where that model sits — a slot
+                // is a position in the cast, not a property of a model, and a hidden
+                // model moves everybody after it up one.
+                this.castSlotOf.set(inst.name, n);
                 // The model transform is only where the model was PLACED. A motion moves
                 // the character by animating bones, so an effect anchored to the
                 // transform never follows anyone anywhere — it sits at the spawn point
@@ -14042,6 +14342,8 @@ export class Engine {
             // drawTrails. Recorded rather than recomputed: this loop is the one place
             // that knows how many subjects the cast actually ended up holding.
             this.castSubjectCount = n;
+            // Each effect's own view of that cast, before any mount reads it.
+            this.updateSubjectMasks();
             this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u);
             // Only what an effect declared, and only while one is installed. A scene
             // with no effect writes nothing here at all.
@@ -14061,6 +14363,63 @@ export class Engine {
             }
         }
     }
+    /**
+     * Every effect's own view of the cast, once a frame, right after the slots are
+     * assigned and before any mount reads them.
+     *
+     * The mask is what the shaders see: CAST_API counts its bits for
+     * rzSubjectCount() and walks them for rzSubject(i), so an effect aimed at the
+     * third dancer alone finds her at index 0. `subjectCount` is the same number on
+     * the CPU, for the one thing that needs it there — the ribbons' instance count,
+     * which must agree with what the trail shader decodes or a ribbon lands on the
+     * wrong body.
+     *
+     * Recomputed rather than cached against a version: it is four models, a map
+     * lookup each, and the alternative is a cache that has to be invalidated from
+     * every place a model can be added, removed, hidden or renamed.
+     */
+    updateSubjectMasks() {
+        const live = this.castSubjectCount;
+        const all = live === 0 ? 0 : (1 << live) - 1;
+        for (const e of this.effects) {
+            let mask = 0xf;
+            if (e.subjects) {
+                mask = 0;
+                for (const name of e.subjects) {
+                    const slot = this.castSlotOf.get(name);
+                    if (slot !== undefined)
+                        mask |= 1 << slot;
+                }
+            }
+            e.subjectMask = mask;
+            let n = 0;
+            for (let i = 0; i < live; i++)
+                if (mask & (1 << i))
+                    n++;
+            e.subjectCount = n;
+        }
+        // The floods, one per distinct target set. Their masks are written here for
+        // the same reason the effects' are: the slots have just been decided.
+        for (const v of this.castDistanceVariants) {
+            let mask = 0xf;
+            if (v.subjects) {
+                mask = 0;
+                for (const name of v.subjects) {
+                    const slot = this.castSlotOf.get(name);
+                    if (slot !== undefined)
+                        mask |= 1 << slot;
+                }
+            }
+            // Bounded by the live cast, so a mask naming a slot nobody occupies cannot
+            // seed off a stale entry in the buffer.
+            const want = mask & all;
+            if (v.mask === want)
+                continue;
+            v.mask = want;
+            v.data[0] = want;
+            this.device.queue.writeBuffer(v.uniform, 0, v.data.buffer);
+        }
+    }
     /**
      * One character's slice of the effect API's view of the cast.
      *