reze-engine 0.55.4 → 0.55.7

package/src/engine.ts

@@ -1271,6 +1271,26 @@ function vertexMorphReach(model: Model): number {
 const TEXTURE_EXTENSION_GUESSES = [".png", ".jpg", ".jpeg", ".bmp", ".tga", ".dds", ".spa", ".sph"]
 
 /** One effect's GPU particle pool. Per effect: each declares its own count. */
+/**
+ * The binding number an effect's params take in each pass.
+ *
+ * 7 in the composite, the particle stages and the ribbon pass, which all stop
+ * below it. The GRID reaches 8 on its own, so it takes the next one up rather
+ * than everything else moving to accommodate one mount.
+ */
+const EFFECT_PARAMS_BINDING = 7
+const EFFECT_PARAMS_BINDING_GRID = 9
+
+/** How a mount receives the effect's declared dials: a generator for the struct
+ *  at the binding that mount has free, and the buffer behind it. Null buffer
+ *  means the effect declared none, and then neither the decl nor the binding is
+ *  emitted — WGSL has no empty struct, and a bound buffer nothing reads is a
+ *  layout mismatch. */
+type EffectParamsBinding = {
+  wgsl: (binding: number) => string
+  buffer: GPUBuffer | null
+}
+
 interface EffectParticles {
   count: number
   buffer: GPUBuffer
@@ -1313,6 +1333,9 @@ interface EffectGrid {
   data: Float32Array
   parity: number
   frame: number
+  /** The effect's declared dials, or null. Held HERE as well as on the instance
+   *  because the rebind path rebuilds this bind group from the grid alone. */
+  params: GPUBuffer | null
 }
 
 /**
@@ -1470,6 +1493,9 @@ interface EffectInstance {
     /** How many slots it asked for. Its base is assigned by the engine and can
      *  move, which is why it travels in the uniform rather than the shader. */
     count: number
+    /** The effect's declared parameters, or null when it declares none. Kept
+     *  for the same reason `layout` is: `bind` is rebuilt on a buffer swap. */
+    params: GPUBuffer | null
   } | null
   /** The field mount's pipeline and its two parity bind groups, or null when the
    *  effect declares neither background nor foreground. */
@@ -3253,7 +3279,13 @@ export class Engine {
    * fail where it was written, it fails at the next submit.
    */
   private gridBindGroup(
-    g: { layout: GPUBindGroupLayout; uniform: GPUBuffer; read: [GPUTextureView, GPUTextureView]; textures: [GPUTexture, GPUTexture] },
+    g: {
+      layout: GPUBindGroupLayout
+      uniform: GPUBuffer
+      read: [GPUTextureView, GPUTextureView]
+      textures: [GPUTexture, GPUTexture]
+      params: GPUBuffer | null
+    },
     i: number,
   ): GPUBindGroup {
     return this.device.createBindGroup({
@@ -3268,6 +3300,9 @@ export class Engine {
         { binding: 6, resource: { buffer: this.compositeUniformBuffer } },
         { binding: 7, resource: { buffer: this.midiBuffer } },
         { binding: 8, resource: { buffer: this.lyricsBuffer } },
+        // The grid is the one pass whose own bindings reach 8, so its params sit
+        // above them rather than everything else shifting for one mount.
+        ...(g.params ? [{ binding: EFFECT_PARAMS_BINDING_GRID, resource: { buffer: g.params } }] : []),
       ],
     })
   }
@@ -3304,7 +3339,7 @@ export class Engine {
         e.particles.mirrorRenderBind = b.mirrorRenderBind
       }
       if (e.grid) e.grid.binds = [this.gridBindGroup(e.grid, 0), this.gridBindGroup(e.grid, 1)]
-      if (e.lights) e.lights.bind = this.lightEmitBindGroup(e.lights.layout, e.lights.uniform)
+      if (e.lights) e.lights.bind = this.lightEmitBindGroup(e.lights.layout, e.lights.uniform, e.lights.params)
     }
   }
 
@@ -3610,9 +3645,19 @@ export class Engine {
         paramsData[slot.offset + 2] = value.z
       }
     }
-    const paramsDecl = entries.length
-      ? `struct EffectParams {\n${fields.join("\n")}\n}\n@group(0) @binding(7) var<uniform> params: EffectParams;\n`
-      : ""
+    /**
+     * The params block, at whatever binding the pass asking has free.
+     *
+     * A single hardcoded slot cannot serve every mount — the grid's layout
+     * already reaches binding 8 — so the struct is generated per pass and each
+     * one states the number it can spare. Empty when nothing is declared: WGSL
+     * has no empty struct, and a binding nothing reads is a layout mismatch.
+     */
+    const paramsWgsl = (binding: number) =>
+      entries.length
+        ? `struct EffectParams {\n${fields.join("\n")}\n}\n@group(0) @binding(${binding}) var<uniform> params: EffectParams;\n`
+        : ""
+    const paramsDecl = paramsWgsl(EFFECT_PARAMS_BINDING)
 
     // ── Compile with validation captured, not thrown at the console. Line
     // numbers in diagnostics are rebased to the USER's source.
@@ -3720,7 +3765,32 @@ export class Engine {
     let grid: EffectGrid | null = null
     let trails: EffectTrails | null = null
 
+    // PARAMS ARE NOT A FIELD-MOUNT FEATURE, and used to be one by accident.
+    //
+    // `paramsDecl` was spliced into the composite alone, so `#param` worked for
+    // background/foreground and produced "unresolved value 'params'" for every
+    // particle, grid and ribbon effect — which is most of the ones anyone wants
+    // a dial on. Rain's fall speed is the whole example.
+    //
+    // The buffer is created HERE rather than beside the instance it ends up on,
+    // because the mount builders below need to bind it and they run first. That
+    // makes `abandon` its owner: a mount that fails to compile must not leak it.
+    let paramsBuffer: GPUBuffer | null = null
+    if (entries.length) {
+      paramsBuffer = this.device.createBuffer({
+        label: "effect params",
+        size: paramsData.byteLength,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      })
+      this.device.queue.writeBuffer(paramsBuffer, 0, paramsData)
+    }
+    /** What every mount splices and binds: a generator for the struct decl at
+     *  the binding that mount has free, and the buffer behind it. The buffer is
+     *  null when nothing is declared, and then no binding is added at all. */
+    const paramsFor: EffectParamsBinding = { wgsl: paramsWgsl, buffer: paramsBuffer }
+
     const abandon = (diagnostics: string[]): EffectResult => {
+      paramsBuffer?.destroy()
       particles?.buffer.destroy()
       particles?.uniform.destroy()
       grid?.textures[0].destroy()
@@ -3730,12 +3800,12 @@ export class Engine {
       return { ok: false, diagnostics, mounts, params: d.params, duration: d.duration }
     }
     if (wantsParticles) {
-      const built = await this.buildParticles(wgsl, d, anchors, alias)
+      const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor)
       if (!built.ok) return abandon(built.diagnostics)
       particles = built.state
     }
     if (gridEntryPoint(wgsl)) {
-      const built = await this.buildSim(wgsl, d, anchors, alias)
+      const built = await this.buildSim(wgsl, d, anchors, alias, paramsFor)
       if (!built.ok) return abandon(built.diagnostics)
       grid = built.state
     }
@@ -3744,9 +3814,9 @@ export class Engine {
       // bone recorded without one would read zeroes and paint a line to the origin.
       const trailSlots = anchors.filter((a) => a.trail).length
       if (trailSlots === 0) {
-        return { ok: false, diagnostics: ["a ribbon effect needs at least one #anchor <bone> trail"], mounts, params: d.params, duration: d.duration }
+        return abandon(["a ribbon effect needs at least one #anchor <bone> trail"])
       }
-      const built = await this.buildTrails(wgsl, d, anchors, alias)
+      const built = await this.buildTrails(wgsl, d, anchors, alias, paramsFor)
       if (!built.ok) return abandon(built.diagnostics)
       trails = built.state
     }
@@ -3769,7 +3839,7 @@ export class Engine {
       ])
     }
     if (declaredLights > 0) {
-      const built = await this.buildLightEmit(wgsl, declaredLights, alias, anchors)
+      const built = await this.buildLightEmit(wgsl, declaredLights, alias, anchors, paramsFor)
       if (!built.ok) return abandon(built.diagnostics)
       lights = built.state
     }
@@ -3783,15 +3853,6 @@ export class Engine {
         })
       : null
 
-    let paramsBuffer: GPUBuffer | null = null
-    if (entries.length) {
-      paramsBuffer = this.device.createBuffer({
-        label: "effect params",
-        size: paramsData.byteLength,
-        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-      })
-      this.device.queue.writeBuffer(paramsBuffer, 0, paramsData)
-    }
     const instance: EffectInstance = {
         wgsl,
         paramDecls: d.params,
@@ -4041,11 +4102,14 @@ export class Engine {
      *  engine: the builders run BEFORE the swap, so this.anchorTable still
      *  describes the effect that is still on screen. */
     alias: number[],
+    /** The effect's declared dials. Spliced into both stages and bound at 7,
+     *  the same binding the composite gives them. */
+    params: EffectParamsBinding,
   ): Promise<{ ok: true; state: EffectParticles } | { ok: false; diagnostics: string[] }> {
     // No pragma means "some": an author who wrote the trio clearly wants
     // particles, and failing over a missing comment would be pedantry.
     const count = Math.min(d.particles || 1024, Engine.MAX_PARTICLES)
-    const src = { wgsl, count, blend: d.particleBlend, bloom: d.bloom }
+    const src = { wgsl, count, blend: d.particleBlend, bloom: d.bloom, paramsDecl: params.wgsl(EFFECT_PARAMS_BINDING) }
     // Sparks want to spawn where a trail is, so the particle stages see the same
     // cast buffer the trail draw reads.
     const cast = {
@@ -4110,6 +4174,9 @@ export class Engine {
           // rule and a background read the same instant.
           { binding: 5, visibility, buffer: { type: "read-only-storage" } },
           { binding: 6, visibility, buffer: { type: "read-only-storage" } },
+          // Only when the effect declared any: WGSL has no empty struct, so a
+          // param-less effect must not carry the decl OR the binding.
+          ...(params.buffer ? [{ binding: 7, visibility, buffer: { type: "uniform" as const } }] : []),
         ],
       })
     const bindFor = (layout: GPUBindGroupLayout, camera: GPUBuffer) =>
@@ -4123,6 +4190,7 @@ export class Engine {
           { binding: 4, resource: { buffer: this.audioBuffer } },
           { binding: 5, resource: { buffer: this.midiBuffer } },
           { binding: 6, resource: { buffer: this.lyricsBuffer } },
+          ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
         ],
       })
 
@@ -4212,6 +4280,7 @@ export class Engine {
     count: number,
     alias: number[],
     anchors: { bone: string; trail: boolean }[],
+    params: EffectParamsBinding,
   ): Promise<{ ok: true; state: NonNullable<EffectInstance["lights"]> } | { ok: false; diagnostics: string[] }> {
     const layout = this.device.createBindGroupLayout({
       label: "light emit layout",
@@ -4223,13 +4292,21 @@ export class Engine {
         { binding: 4, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
         { binding: 5, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
         { binding: 6, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+        ...(params.buffer
+          ? [{ binding: EFFECT_PARAMS_BINDING, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" as const } }]
+          : []),
       ],
     })
     const module = this.device.createShaderModule({
       label: "light emit",
       // The same scene API and the same per-effect anchor alias its drawing
       // half gets, so a lamp reads the cast exactly as the beam that paints it.
-      code: buildLightEmitShader(wgsl, EFFECT_SCENE_API + anchorAliasWgsl(alias), { trailCount: anchors.filter((a) => a.trail).length }),
+      code: buildLightEmitShader(
+        wgsl,
+        EFFECT_SCENE_API + anchorAliasWgsl(alias),
+        { trailCount: anchors.filter((a) => a.trail).length },
+        params.wgsl(EFFECT_PARAMS_BINDING),
+      ),
     })
     const info = await module.getCompilationInfo()
     const diagnostics = info.messages.filter((m) => m.type === "error").map((m) => `${m.lineNum}:${m.linePos} ${m.message}`)
@@ -4251,15 +4328,15 @@ export class Engine {
       uniform.destroy()
       return { ok: false, diagnostics: [scoped.message] }
     }
-    const bind = this.lightEmitBindGroup(layout, uniform)
+    const bind = this.lightEmitBindGroup(layout, uniform, params.buffer)
     // The layout travels with the state so the emitter can be rebound when a
     // shared buffer under it is replaced — see rebindSharedBuffers.
-    return { ok: true, state: { pipeline, bind, layout, uniform, data, count } }
+    return { ok: true, state: { pipeline, bind, layout, uniform, data, count, params: params.buffer } }
   }
 
   /** The light emitter's bind group. One author, for the reason gridBindGroup
    *  gives: it is built once and rebuilt on every shared-buffer swap. */
-  private lightEmitBindGroup(layout: GPUBindGroupLayout, uniform: GPUBuffer): GPUBindGroup {
+  private lightEmitBindGroup(layout: GPUBindGroupLayout, uniform: GPUBuffer, params: GPUBuffer | null): GPUBindGroup {
     return this.device.createBindGroup({
       label: "light emit bind",
       layout,
@@ -4271,6 +4348,7 @@ export class Engine {
         { binding: 4, resource: { buffer: this.audioBuffer } },
         { binding: 5, resource: { buffer: this.midiBuffer } },
         { binding: 6, resource: { buffer: this.lyricsBuffer } },
+        ...(params ? [{ binding: EFFECT_PARAMS_BINDING, resource: { buffer: params } }] : []),
       ],
     })
   }
@@ -4380,6 +4458,8 @@ export class Engine {
      *  engine: the builders run BEFORE the swap, so this.anchorTable still
      *  describes the effect that is still on screen. */
     alias: number[],
+    /** The effect's declared dials, spliced and bound at 7 as everywhere else. */
+    params: EffectParamsBinding,
   ): Promise<{ ok: true; state: EffectTrails } | { ok: false; diagnostics: string[] }> {
     // `slots` here is how many RIBBONS to draw — one per trailed anchor — which
     // is a different number from the anchor ADDRESS SPACE the accessors index
@@ -4390,7 +4470,7 @@ export class Engine {
     // nothing before: ribbon i was read as anchor slot i.
     const ribbonSlots = anchors.map((a, i) => (a.trail ? i : -1)).filter((i) => i >= 0)
     const slots = ribbonSlots.length
-    const src = { wgsl, slots, ribbonSlots, blend: d.particleBlend, bloom: d.bloom }
+    const src = { wgsl, slots, ribbonSlots, blend: d.particleBlend, bloom: d.bloom, paramsDecl: params.wgsl(EFFECT_PARAMS_BINDING) }
     const code = buildTrailShader(src, {
       subjects: MAX_EFFECT_SUBJECTS,
       samples: TRAIL_SAMPLES,
@@ -4434,6 +4514,9 @@ export class Engine {
         { binding: 5, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "read-only-storage" } },
         // The lyrics, for rzLyric*.
         { binding: 6, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "read-only-storage" } },
+        ...(params.buffer
+          ? [{ binding: 7, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" as const } }]
+          : []),
       ],
     })
     // TWO targets, the scene pass's own: HDR colour and the aux (bloom mask,
@@ -4486,6 +4569,7 @@ export class Engine {
               { binding: 4, resource: { buffer: this.audioBuffer } },
               { binding: 5, resource: { buffer: this.midiBuffer } },
               { binding: 6, resource: { buffer: this.lyricsBuffer } },
+              ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
             ],
           }),
           mirrorBind: this.device.createBindGroup({
@@ -4497,6 +4581,7 @@ export class Engine {
               { binding: 4, resource: { buffer: this.audioBuffer } },
               { binding: 5, resource: { buffer: this.midiBuffer } },
               { binding: 6, resource: { buffer: this.lyricsBuffer } },
+              ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
             ],
           }),
         },
@@ -4694,6 +4779,8 @@ export class Engine {
      *  engine: the builders run BEFORE the swap, so this.anchorTable still
      *  describes the effect that is still on screen. */
     alias: number[],
+    /** The effect's declared dials, spliced and bound above the grid's own. */
+    params: EffectParamsBinding,
   ): Promise<{ ok: true; state: EffectGrid } | { ok: false; diagnostics: string[] }> {
     const size = Math.min(d.grid || 256, GRID_MAX)
     const cast = {
@@ -4705,7 +4792,7 @@ export class Engine {
       trailCount: anchors.filter((x) => x.trail).length,
       alias,
     }
-    const code = buildSimShader(wgsl, size, cast)
+    const code = buildSimShader(wgsl, size, cast, params.wgsl(EFFECT_PARAMS_BINDING_GRID))
     const offset = code.slice(0, code.indexOf(wgsl)).split("\n").length - 1
     this.device.pushErrorScope("validation")
     const module = this.device.createShaderModule({ label: "grid step", code })
@@ -4733,6 +4820,9 @@ export class Engine {
         { binding: 6, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
         { binding: 7, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
         { binding: 8, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+        ...(params.buffer
+          ? [{ binding: EFFECT_PARAMS_BINDING_GRID, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" as const } }]
+          : []),
       ],
     })
 
@@ -4766,7 +4856,7 @@ export class Engine {
         return { ok: false, diagnostics: [scoped.message] }
       }
       // One per parity: binds[i] READS textures[i] and WRITES the other.
-      const bindFor = (i: number) => this.gridBindGroup({ layout, uniform, read, textures }, i)
+      const bindFor = (i: number) => this.gridBindGroup({ layout, uniform, read, textures, params: params.buffer }, i)
       return {
         ok: true,
         state: {
@@ -4780,6 +4870,7 @@ export class Engine {
           data: new Float32Array(4),
           parity: 0,
           frame: 0,
+          params: params.buffer,
         },
       }
     } catch (e) {
@@ -7604,17 +7695,23 @@ export class Engine {
   /** Bind camera orbit center to a model's bone (Souls-style follow cam). Pass null to unbind. */
   setCameraTarget(model: Model | null, boneName: string, offset?: Vec3): void
   setCameraTarget(modelOrVec: Model | Vec3 | null, boneName?: string, offset?: Vec3): void {
+    // panLocked tracks the BINDING, on every path that changes it — a target
+    // set to a fixed point is pannable again, and forgetting it here is how the
+    // pan stays dead after the follow was turned off. See Camera.panLocked.
     if (modelOrVec === null) {
+      this.camera.panLocked = false
       this.cameraTargetModel = null
       return
     }
     if ("x" in modelOrVec && "y" in modelOrVec && "z" in modelOrVec) {
+      this.camera.panLocked = false
       this.cameraTargetModel = null
       this.camera.target.x = modelOrVec.x
       this.camera.target.y = modelOrVec.y
       this.camera.target.z = modelOrVec.z
       return
     }
+    this.camera.panLocked = true
     this.cameraTargetModel = modelOrVec
     this.cameraTargetBoneName = boneName ?? ""
     this.cameraTargetOffset.x = offset?.x ?? 0
@@ -7624,6 +7721,9 @@ export class Engine {
 
   /** Souls-style follow cam: orbit center tracks a model bone each frame. Shorthand for setCameraTarget(model, boneName, offset). */
   setCameraFollow(model: Model | null, boneName?: string, offset?: Vec3, smoothing?: number): void {
+    // Panning sets the very thing the follow overwrites each frame, so it is
+    // refused for as long as the shot is riding a bone. See Camera.panLocked.
+    this.camera.panLocked = model !== null
     if (model === null) {
       this.cameraTargetModel = null
       return
@@ -9397,6 +9497,59 @@ export class Engine {
     else inst.hiddenMaterials.add(materialName)
   }
 
+  /**
+   * Push a colour/shading edit straight into a material's own uniform buffer —
+   * the same block createMaterialUniformBuffer wrote at load, offset for
+   * offset. A single write per call, on the fields that actually moved, so
+   * dragging one slider does not touch the other eleven.
+   *
+   * UNGROUPED materials only. A grouped material renders through its style
+   * group's own compiled graph (setupPipelines' neutral/DEFAULT_GRAPH path is
+   * what reads this buffer, and a grouped material never runs it) — the call
+   * still writes the bytes, they are simply never sampled, which would look
+   * like the edit silently failing. Callers check groupsByModel first and this
+   * quietly no-ops rather than assume that check was made, since a document
+   * edit landing to the WRONG channel (the group's own colour input) would be
+   * a worse failure than one that does nothing.
+   *
+   * Structural fields — anything that changes which draw bucket a material is
+   * in, or which texture it binds — are NOT here: alpha crossing the 1.0
+   * opaque/transparent line, edge on/off, a texture swap, all need the draw
+   * list or the bind group rebuilt, not a uniform write. Those get their own
+   * call when something needs them.
+   */
+  setMaterialUniforms(
+    modelName: string,
+    materialName: string,
+    patch: {
+      diffuse?: readonly [number, number, number, number]
+      specular?: readonly [number, number, number]
+      specularPower?: number
+      ambient?: readonly [number, number, number]
+    },
+  ): boolean {
+    const inst = this.modelInstances.get(modelName)
+    if (!inst) return false
+    const materials = inst.model.getMaterials()
+    const index = materials.findIndex((m) => m.name === materialName)
+    if (index < 0) return false
+    const buffer = inst.materialUniformBuffers[index]
+    if (!buffer) return false
+    if (patch.diffuse) {
+      this.device.queue.writeBuffer(buffer, 0, new Float32Array(patch.diffuse))
+    }
+    if (patch.ambient) {
+      this.device.queue.writeBuffer(buffer, 16, new Float32Array(patch.ambient))
+    }
+    if (patch.specularPower !== undefined) {
+      this.device.queue.writeBuffer(buffer, 28, new Float32Array([patch.specularPower]))
+    }
+    if (patch.specular) {
+      this.device.queue.writeBuffer(buffer, 32, new Float32Array(patch.specular))
+    }
+    return true
+  }
+
   isMaterialVisible(modelName: string, materialName: string): boolean {
     const inst = this.modelInstances.get(modelName)
     return inst ? !inst.hiddenMaterials.has(materialName) : false

package/src/index.ts

@@ -184,3 +184,17 @@ export {
   type RGBA,
   type Vec3Tuple,
 } from "./overlay"
+
+/**
+ * The WGSL an effect's own source is compiled against — the hashes, the noise,
+ * the falloff, and the Particle struct the particle trio is written in terms of.
+ *
+ * Exported because reze-design renders LIBRARY PREVIEWS by hosting an effect's
+ * source itself, and a preview that reimplements this drifts from the renderer
+ * it is previewing. `rzHash13` meaning one thing on a card and another in the
+ * scene is worse than no card at all — and a preview missing them entirely just
+ * fails to compile, which is a blank card with nothing said anywhere.
+ *
+ * Pure strings, no GPU: importing them costs a host nothing.
+ */
+export { EFFECT_MATH_API, PARTICLE_STRUCT_WGSL } from "./shaders/passes/hosted-api"

package/src/shaders/lights.ts

@@ -127,6 +127,7 @@ export function buildLightEmitShader(
   wgsl: string,
   sceneApi: string,
   cast: { trailCount: number },
+  paramsDecl = "",
 ): string {
   return /* wgsl */ `
 // read_write HERE and read-only in the material shaders. Different passes, so
@@ -164,6 +165,10 @@ ${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()}
+// 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.
+${paramsDecl}
 ${wgsl}
 
 @compute @workgroup_size(64)

package/src/shaders/passes/grid.ts

@@ -107,9 +107,12 @@ struct SimU {
  * from", and that place is almost never a texel centre. Point-sampling it is
  * what turns smoke into a staircase.
  */
-export function buildSimShader(wgsl: string, size: number, cast: CastLayout): string {
+export function buildSimShader(wgsl: string, size: number, cast: CastLayout, paramsDecl = ""): string {
   return (
     SIM_UNIFORMS +
+    // The effect's declared dials, ahead of everything that reads them. Empty
+    // when it declared none.
+    paramsDecl +
     /* wgsl */ `
 @group(0) @binding(0) var<uniform> su: SimU;
 @group(0) @binding(1) var _rzGridPrevTex: texture_2d<f32>;

package/src/shaders/passes/particles.ts

@@ -83,6 +83,10 @@ type ParticleSource = {
   blend: ParticleBlend
   /** Feed the bloom pyramid. Off by default — rain should not glow. */
   bloom: boolean
+  /** The effect's `#param` block, or empty. Spliced into BOTH stages: a spawn
+   *  rule reads the same dial the shading does, and rain's fall speed is used
+   *  in the compute half. */
+  paramsDecl: string
 }
 
 /** Bytes per particle. Explicitly padded — see the struct below. */
@@ -165,6 +169,7 @@ export function buildParticleComputeShader(src: ParticleSource, cast: CastLayout
     CAMERA_STRUCT +
     PARTICLE_UNIFORMS +
     `
+${src.paramsDecl}
 @group(0) @binding(0) var<storage, read_write> particles: array<Particle>;
 @group(0) @binding(1) var<uniform> pu: ParticleU;
 @group(0) @binding(2) var<uniform> cam: CameraU;
@@ -227,6 +232,7 @@ override ADDITIVE: bool = ${src.blend === "additive" ? "true" : "false"};\n` +
     CAMERA_STRUCT +
     PARTICLE_UNIFORMS +
     `
+${src.paramsDecl}
 @group(0) @binding(0) var<storage, read> particles: array<Particle>;
 @group(0) @binding(1) var<uniform> pu: ParticleU;
 @group(0) @binding(2) var<uniform> cam: CameraU;

package/src/shaders/passes/trails.ts

@@ -33,6 +33,8 @@ type TrailSource = {
   /** For each ribbon, the LOCAL anchor slot it belongs to. Identity when every
    *  anchor is trailed; otherwise it skips the untrailed ones. */
   ribbonSlots: number[]
+  /** The effect's `#param` block, or empty. */
+  paramsDecl: string
   /** Additive, like most glowing ribbons, or straight alpha. */
   blend: "alpha" | "additive"
   bloom: boolean
@@ -138,6 +140,7 @@ struct TrailU {
   weight: f32,
   _pad2: f32,
 }
+${src.paramsDecl}
 @group(0) @binding(0) var<storage, read> _rzCast: array<vec4f>;
 @group(0) @binding(1) var<uniform> tu: TrailU;
 @group(0) @binding(2) var<uniform> cam: CameraU;