reze-engine 0.51.0 → 0.53.0

package/src/index.ts

@@ -26,7 +26,8 @@ export {
 export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload"
 export { parseMidi } from "./midi-loader"
 // Radiance .hdr, for HDRI worlds — the host fetches the file and hands the
-// parsed image to setBackdropEquirect.
+// parsed image to setWorldEquirect. Not setBackdropEquirect: that one is the
+// 360 picture you SEE, and an HDRI is what LIGHTS the scene.
 export { parseHDR, type HdrImage } from "./hdr"
 // Lyrics timing (.lrc) — the host parses the file and hands the lines to setLyrics.
 export { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, parseLRC, type LyricLine, type LyricRect } from "./shaders/lyrics-api"
@@ -34,6 +35,10 @@ export { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, parseLRC, type LyricLine, type Ly
 // wants to draw a track, or scrub one, should read the same curve the engine
 // plays rather than reimplementing it a second time.
 export { sampleParamTrack, type ParamKey, type ParamValue } from "./param-track"
+// The strip an effect is scheduled by, and the pure evaluator behind it —
+// exported so a caller can draw a lane against the same numbers the engine
+// renders from, rather than a second copy of the ramp maths.
+export { effectState, type EffectWindow, type EffectState } from "./effect-schedule"
 export {
   compileGraph,
   validateGraph,
@@ -70,6 +75,17 @@ export { STOCKINGS_GRAPH } from "./graph/presets/stockings"
 export { EYE_GRAPH } from "./graph/presets/eye"
 export { FACE_GRAPH } from "./graph/presets/face"
 export { UNLIT_GRAPH } from "./graph/presets/unlit"
+// What an effect declares, and the source with those lines blanked. Exported
+// because a host builds parameter controls from the declarations and needs the
+// same answer the engine got — two parsers is how they disagree.
+export {
+  parseDirectives,
+  stripDirectives,
+  DIRECTIVE_LINE,
+  DIRECTIVE_NOTE,
+  type EffectDirectives,
+  type EffectParamDecl,
+} from "./shaders/directives"
 export {
   Model,
   MATERIAL_MORPH_MULTIPLY,

package/src/shaders/anchor-table.ts

@@ -91,7 +91,7 @@ export function buildAnchorTable(requests: AnchorRequest[][], max: number): Anch
  * TRAILED anchor, so its instance index counts 0,1,2… over trailed anchors only
  * — while the cast buffer is addressed by DECLARATION slot. Those coincide
  * exactly when every anchor is trailed, which is true of all 14 library effects
- * and is why this stayed latent: declare `@anchor 頭` then `@anchor 左手首 trail`
+ * and is why this stayed latent: declare `#anchor 頭` then `#anchor 左手首 trail`
  * and ribbon 0 asked for the trail of 頭, which has none, so the ribbon silently
  * did not draw.
  *
@@ -127,7 +127,7 @@ ${cases}
  * folds away.
  */
 export function anchorAliasWgsl(alias: number[]): string {
-  // NO @anchor AT ALL. Every slot is unmapped, and rzAnchor() must report
+  // NO #anchor AT ALL. Every slot is unmapped, and rzAnchor() must report
   // .valid false for all of them.
   //
   // This used to fall through to the identity branch below — `[].every()` is
@@ -139,7 +139,7 @@ export function anchorAliasWgsl(alias: number[]): string {
   // reading.
   if (alias.length === 0) {
     return `
-/** No @anchor in this effect: every slot is unmapped, so rzAnchor() is invalid
+/** No #anchor in this effect: every slot is unmapped, so rzAnchor() is invalid
  *  rather than reading whichever bone another effect declared first. */
 fn _rzSlot(local: i32) -> i32 { return -1; }
 `

package/src/shaders/cast-api.ts

@@ -92,7 +92,7 @@ fn rzSubject(i: i32) -> RzSubject {
 /**
  * Where a named bone is, this frame.
  *
- * The slot is the author's own: the Nth @anchor in their file, in the order
+ * The slot is the author's own: the Nth #anchor in their file, in the order
  * they wrote them. _rzSlot turns that into the scene's address, which is what
  * keeps two effects that both anchor to a wrist from reading each other's.
  */
@@ -115,7 +115,7 @@ fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
  *
  * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those
  * are different index spaces: storage is addressed by anchor slot, so an
- * untrailed @anchor followed by a trailed one put the trail at index 1 with a
+ * untrailed #anchor followed by a trailed one put the trail at index 1 with a
  * bound of 1 and rzTrail returned zero — a ribbon that silently did not draw.
  */
 fn rzTrailCount(subject: i32, slot: i32) -> i32 {

package/src/shaders/directives.ts

@@ -0,0 +1,289 @@
+// What an effect DECLARES about itself — parsed once, in one place.
+//
+// An effect file is WGSL plus a handful of lines that configure how the engine
+// mounts it: which resolution it draws at, how it blends, which bones it
+// follows, what knobs it exposes. Those lines are not comments. They decide
+// whether the file gets what it asks for, and the failure they used to have was
+// the worst kind available.
+//
+// WHY `#` AND NOT `// @`. The old spelling put directives inside comments,
+// which meant two things. Authors read them as comments and wrote notes on the
+// same line — every parser was anchored to end-of-line, so the note silently
+// unmade the directive, and three shipped effects ran at half the resolution
+// their own first line said they needed while a fourth quietly stopped being
+// additive. Nothing failed and nothing was reported, because nothing had been
+// declared to fail. And it could not be fixed by being strict: a comment
+// beginning with `@` is a legitimate thing to write, so an unrecognised one can
+// only ever be a warning.
+//
+// WGSL has no `#` syntax of its own. A line starting with `#` is therefore
+// unambiguously ours, an unknown one is an ERROR rather than a guess, and the
+// sigil is the one every shader author already reads as "directive" from
+// `#pragma`. The cost usually quoted for this — that the file stops being valid
+// WGSL — is not a cost we pay: an effect calls rzSubject, rzTrail and reads
+// `params`, none of which exist until the engine splices them in, so these
+// files have never compiled anywhere else.
+//
+// STRIPPED BY BLANKING, not by deleting: the compiler sees an empty line where
+// each directive was, so every diagnostic's line number still points at the
+// line the author is looking at.
+
+/** A knob an effect exposes, for a host to build a control from. */
+export type EffectParamDecl = {
+  name: string
+  kind: "float" | "color" | "vec3"
+  /** Numbers for float/vec3; `#rrggbb` for a colour, which the host converts. */
+  value: number | [number, number, number] | string
+  /** float only, and only when the author gave a range. */
+  min?: number
+  max?: number
+}
+
+export type EffectDirectives = {
+  /** Bones this effect follows, in declaration order — slot 0 is the first. */
+  anchors: { bone: string; trail: boolean }[]
+  params: EffectParamDecl[]
+  /** Field layer: 0 full, 1 half. Full unless `#halfres` says otherwise. */
+  fieldLayer: 0 | 1
+  /** The field layer composites additively rather than over. */
+  additiveLayer: boolean
+  /** Particle blend, which is a different axis from the field layer's. */
+  particleBlend: "alpha" | "additive"
+  particles: number
+  lights: number
+  grid: number
+  bloom: boolean
+  /** This effect takes the cast apart — the host reads the timing. */
+  dissolve: boolean
+  /**
+   * How long ONE firing of this effect lasts, in seconds. 0 = undeclared.
+   *
+   * An effect is one of two things, and only its author knows which. A HIT has
+   * an arc — a circle flares, peaks and is gone — and its length is a fact
+   * about it, the way a video clip's length is a fact about the file. An
+   * AMBIENT effect (stars, fog, rain) has no length at all; it is a condition
+   * the scene is in.
+   *
+   * Declaring it is what lets a host place the effect instead of making someone
+   * construct it: dropping a hit on the timeline gives a strip already the
+   * right size, and an effect that declares nothing spans the scene. Every
+   * timeline works this way — a clip arrives at its own duration.
+   */
+  duration: number
+}
+
+/** Every directive, with how many words follow it. `rest` means free-form. */
+const SPEC = {
+  anchor: "rest",
+  param: "rest",
+  halfres: 0,
+  layer: 1,
+  blend: 1,
+  particles: 1,
+  lights: 1,
+  grid: 1,
+  bloom: 0,
+  dissolve: 0,
+  duration: 1,
+} as const
+
+/** A line that declares something, and what it declares. Exported because an
+ *  editor highlights by the same rule the parser reads by — a highlighter with
+ *  its own idea of what counts is one that paints a line as configuration that
+ *  the engine then ignores. */
+export const DIRECTIVE_LINE = /^[ \t]*#([a-zA-Z]+)[ \t]*(.*)$/
+const LINE = DIRECTIVE_LINE
+
+/**
+ * Split a directive's arguments from a trailing note.
+ *
+ * `#anchor 左手首 trail — her sword hand` is one line doing two jobs, and
+ * refusing it is what made the old spelling dangerous: the note is the natural
+ * thing to write, so it has to be the accepted thing to write.
+ */
+export const DIRECTIVE_NOTE = /(?:^|\s)(?:—|--|\/\/|#)\s/
+
+function argsOf(rest: string): string[] {
+  // `^` as well as `\s`: the tag's own trailing space is eaten by LINE, so a
+  // note can begin at the very first character — which is what
+  // `#halfres — glyph edges` looks like by the time it reaches here.
+  const note = rest.search(DIRECTIVE_NOTE)
+  return (note >= 0 ? rest.slice(0, note) : rest).trim().split(/\s+/).filter(Boolean)
+}
+
+/** A number, or null. Empty is NULL, not zero: `Number("")` is 0, so a missing
+ *  default silently became a real one — an author who wrote `#param float D`
+ *  and meant to finish the line got a knob quietly pinned at zero. */
+const num = (s: string | undefined): number | null => {
+  if (!s || !s.trim()) return null
+  const v = Number(s)
+  return Number.isFinite(v) ? v : null
+}
+
+export type DirectiveResult = { directives: EffectDirectives; errors: string[] }
+
+/** Read every declaration in a source. Errors name the line, one-based. */
+export function parseDirectives(wgsl: string): DirectiveResult {
+  const d: EffectDirectives = {
+    anchors: [],
+    params: [],
+    // FULL unless asked otherwise — the default is what an author gets for
+    // saying nothing, so it has to be the answer that cannot silently ruin an
+    // effect. `#halfres` is a claim about being cheap, which is a claim only
+    // the author can make.
+    fieldLayer: 0,
+    additiveLayer: false,
+    particleBlend: "alpha",
+    particles: 0,
+    lights: 0,
+    grid: 0,
+    bloom: false,
+    dissolve: false,
+    duration: 0,
+  }
+  const errors: string[] = []
+  const lines = wgsl.split("\n")
+
+  lines.forEach((line, i) => {
+    const m = LINE.exec(line)
+    if (!m) return
+    const at = `line ${i + 1}`
+    const tag = m[1].toLowerCase()
+    if (!(tag in SPEC)) {
+      errors.push(`${at}: #${m[1]} is not a directive. Known: ${Object.keys(SPEC).map((k) => `#${k}`).join(", ")}`)
+      return
+    }
+    const args = argsOf(m[2])
+    const want = SPEC[tag as keyof typeof SPEC]
+    if (want !== "rest" && args.length !== want) {
+      errors.push(`${at}: #${tag} takes ${want} argument${want === 1 ? "" : "s"}, got ${args.length}`)
+      return
+    }
+
+    switch (tag) {
+      case "anchor": {
+        if (args.length < 1 || args.length > 2 || (args[1] && args[1] !== "trail")) {
+          errors.push(`${at}: #anchor takes a bone name and optionally the word "trail"`)
+          return
+        }
+        d.anchors.push({ bone: args[0], trail: args[1] === "trail" })
+        return
+      }
+      case "param": {
+        const [kind, name, ...rest] = args
+        if (!name || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+          errors.push(`${at}: #param needs a WGSL identifier for a name`)
+          return
+        }
+        if (kind === "color") {
+          if (!/^#[0-9a-fA-F]{6}$/.test(rest[0] ?? "")) {
+            errors.push(`${at}: #param color ${name} needs a default like #3b82f6`)
+            return
+          }
+          d.params.push({ name, kind: "color", value: rest[0] })
+          return
+        }
+        if (kind === "vec3") {
+          const v = rest.slice(0, 3).map(num)
+          if (v.length !== 3 || v.some((x) => x === null)) {
+            errors.push(`${at}: #param vec3 ${name} needs three numbers`)
+            return
+          }
+          d.params.push({ name, kind: "vec3", value: v as [number, number, number] })
+          return
+        }
+        if (kind === "float") {
+          const v = num(rest[0])
+          if (v === null) {
+            errors.push(`${at}: #param float ${name} needs a default`)
+            return
+          }
+          const lo = num(rest[1])
+          const hi = num(rest[2])
+          // A range is optional and all-or-nothing: half of one is a slider
+          // with an end nobody chose.
+          if ((rest[1] !== undefined) !== (rest[2] !== undefined) || (rest[1] !== undefined && (lo === null || hi === null))) {
+            errors.push(`${at}: #param float ${name} takes both a min and a max, or neither`)
+            return
+          }
+          d.params.push({ name, kind: "float", value: v, ...(lo !== null && hi !== null ? { min: lo, max: hi } : {}) })
+          return
+        }
+        errors.push(`${at}: #param kind must be float, color or vec3`)
+        return
+      }
+      case "halfres":
+        d.fieldLayer = 1
+        return
+      case "layer":
+        if (args[0] !== "additive") {
+          errors.push(`${at}: #layer takes "additive" — over is the default`)
+          return
+        }
+        d.additiveLayer = true
+        return
+      case "blend":
+        if (args[0] !== "additive") {
+          errors.push(`${at}: #blend takes "additive" — alpha is the default`)
+          return
+        }
+        d.particleBlend = "additive"
+        return
+      case "bloom":
+        d.bloom = true
+        return
+      case "dissolve":
+        d.dissolve = true
+        return
+      case "duration": {
+        // SECONDS, like every other time a directive states (see #dissolve).
+        // The document above works in frames and converts once; an author
+        // writing a shader is thinking about how long a flare takes, not about
+        // MMD's frame rate.
+        const n = num(args[0])
+        if (n === null || n <= 0) {
+          errors.push(`${at}: #duration takes a length in seconds`)
+          return
+        }
+        d.duration = n
+        return
+      }
+      default: {
+        // The three that take a count.
+        const n = num(args[0])
+        if (n === null || n < 0) {
+          errors.push(`${at}: #${tag} takes a number`)
+          return
+        }
+        if (tag === "particles") d.particles = n
+        else if (tag === "lights") d.lights = n
+        else if (tag === "grid") d.grid = n
+        return
+      }
+    }
+  })
+
+  // Duplicates are an author editing one line and forgetting another; last-wins
+  // is a coin toss they never see resolved.
+  const names = new Set<string>()
+  for (const p of d.params) {
+    if (names.has(p.name)) errors.push(`#param ${p.name} is declared twice`)
+    names.add(p.name)
+  }
+
+  return { directives: d, errors }
+}
+
+/**
+ * The source as the compiler should see it: every directive line blanked.
+ *
+ * Blanked rather than removed so line numbers survive — a diagnostic points at
+ * the line the author is looking at, which is the whole reason the engine
+ * rebases them in the first place.
+ */
+export function stripDirectives(wgsl: string): string {
+  return wgsl
+    .split("\n")
+    .map((line) => (LINE.test(line) ? "" : line))
+    .join("\n")
+}

package/src/shaders/lights.ts

@@ -45,21 +45,6 @@ export const MAX_LIGHTS = 16
 /** Floats in the whole buffer. */
 export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
 
-/**
- * `// @lights 3` — how many lights this effect emits.
- *
- * Declared, like every other mount: what the file says is what gets allocated,
- * so an effect that emits none costs no slots and nobody pays for a cap they
- * did not ask for. Clamped rather than rejected, the same choice `@particles`
- * makes — an author asking for a hundred gets the most the engine will give and
- * a scene that still runs.
- */
-export function parseLightCount(wgsl: string, max: number): number {
-  const m = /^\s*\/\/\s*@lights\s+(\d+)\s*$/m.exec(wgsl)
-  if (!m) return 0
-  return Math.max(1, Math.min(max, parseInt(m[1], 10)))
-}
-
 /**
  * The RzLight struct, declared in EVERY module a user's source is spliced into.
  *
@@ -144,8 +129,8 @@ 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, _) — see buildLightEmitShader on why the base is
-// here and not in the text.
+// (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;
 // 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
@@ -195,12 +180,19 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
   let finite = l.pos.x == l.pos.x && l.pos.y == l.pos.y && l.pos.z == l.pos.z &&
     l.radius == l.radius && l.intensity == l.intensity &&
     l.color.x == l.color.x && l.color.y == l.color.y && l.color.z == l.color.z;
-  let c = select(vec3f(0.0), max(l.color * l.intensity, vec3f(0.0)), finite);
+  // 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;
   _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);
-  _rzLightsOut[b + 3u] = select(0.0, max(l.radius, 0.0), finite);
+  // Radius goes to zero when the effect is OFF, and is left alone at every
+  // 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);
   // 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/composite.ts

@@ -58,13 +58,13 @@ import { gridReadApi } from "./grid"
 /**
  * The bones an effect asked for, in declaration order — the slots rzAnchor reads.
  *
- *     // @anchor 左手首 trail
- *     // @anchor 頭
+ *     #anchor 左手首 trail
+ *     #anchor 頭
  *
  * A declaration in the source, like the mounts: what a file names is what gets
  * resolved and uploaded, so naming none costs nothing and nobody pays for a
  * rig's other five hundred bones. Anchored to the start of a line so that
- * writing the word @anchor in ordinary prose does not silently add a slot —
+ * writing the word #anchor in ordinary prose does not silently add a slot —
  * which would shift every slot after it.
  *
  * `trail` additionally keeps that bone's recent PATH, for rzTrail. Opt-in
@@ -75,7 +75,7 @@ import { gridReadApi } from "./grid"
  * not have simply reports invalid.
  */
 export function parseEffectAnchors(wgsl: string, max: number): { bone: string; trail: boolean }[] {
-  return [...wgsl.matchAll(/^[ \t]*\/\/[ \t]*@anchor[ \t]+(\S+)([ \t]+trail)?[ \t]*$/gm)]
+  return [...wgsl.matchAll(/^[ \t]*\/\/[ \t]*#anchor[ \t]+(\S+)([ \t]+trail)?[ \t]*$/gm)]
     .map((m) => ({ bone: m[1], trail: m[2] !== undefined }))
     .slice(0, max)
 }
@@ -93,7 +93,7 @@ type CompositeEffectSource = {
   hasBackground: boolean
   /** Defines `fn foreground(...)` — mount over the finished frame. */
   hasForeground: boolean
-  /** Grid resolution when the effect declared `// @grid`, else 0. */
+  /** Grid resolution when the effect declared `#grid`, else 0. */
   gridSize: number
   /** Whether the scene pass carries the id attachment, so the field module can
    *  bind it. False emits accessors that answer 0 rather than nothing at all. */
@@ -728,7 +728,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;
+@group(0) @binding(22) var<uniform> _rzFieldClock: vec4f;   // (time, weight, _, _)
 
 @vertex fn fieldVs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
   let x = f32((vi & 1u) << 2u) - 1.0;
@@ -752,6 +752,13 @@ struct FieldOut {
   out.fg = vec4f(0.0);
   ${bgLine}
   ${fgLine}
+  // WEIGHT, applied where the author cannot decline it.
+  //
+  // Alpha only: both field blends multiply the fragment's colour by src-alpha,
+  // so this is the fade for the alpha-over layer and the additive one alike.
+  // Scaling colour as well would fade as the square.
+  out.bg.a *= _rzFieldClock.y;
+  out.fg.a *= _rzFieldClock.y;
   return out;
 }
 `

package/src/shaders/passes/grid.ts

@@ -40,15 +40,6 @@ export const GRID_MAX = 1024
 /** rgba16float, ping-ponged. Two of these is the whole memory cost. */
 export const SIM_FORMAT: GPUTextureFormat = "rgba16float"
 
-/** `// @grid 256` — the grid's resolution, in texels per side. */
-export function parseGridSize(wgsl: string, max: number): number {
-  const m = /^\s*\/\/\s*@grid\s+(\d+)\s*$/m.exec(wgsl)
-  if (!m) return 0
-  // Clamped rather than rejected, as the particle count is: an author asking for
-  // 4096 gets the most the engine will give and a scene that still runs.
-  return Math.max(8, Math.min(max, parseInt(m[1], 10)))
-}
-
 /** Whether this effect drives a grid at all. */
 export function gridEntryPoint(wgsl: string): boolean {
   return /\bfn\s+gridStep\s*\(/.test(wgsl)

package/src/shaders/passes/particles.ts

@@ -102,6 +102,11 @@ struct ParticleU {
   dt: f32,
   count: u32,
   frame: u32,
+  /** The effect's evaluated influence, applied at the one output site below. */
+  weight: f32,
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,
 }
 `
 
@@ -134,26 +139,6 @@ fn rzProject(p: vec3f) -> vec3f {
 fn rzCamPos() -> vec3f { return cam.camPos; }
 `
 
-/** `// @particles 4096` — how many live at once. */
-export function parseParticleCount(wgsl: string, max: number): number {
-  const m = /^\s*\/\/\s*@particles\s+(\d+)\s*$/m.exec(wgsl)
-  if (!m) return 0
-  // Clamped rather than rejected: an author asking for a million gets the most
-  // the engine will give and a scene that still runs, which is a better failure
-  // than a compile error naming a number they had no way to know.
-  return Math.max(1, Math.min(max, parseInt(m[1], 10)))
-}
-
-/** `// @bloom` — opt in to the bloom pyramid. Sparks want it; rain does not. */
-export function parseParticleBloom(wgsl: string): boolean {
-  return /^\s*\/\/\s*@bloom\s*$/m.test(wgsl)
-}
-
-/** `// @blend additive` — default is straight alpha. */
-export function parseParticleBlend(wgsl: string): ParticleBlend {
-  return /^\s*\/\/\s*@blend\s+additive\s*$/m.test(wgsl) ? "additive" : "alpha"
-}
-
 /** Does the source define the particle contract? All three are required together. */
 export function particleEntryPoints(wgsl: string): { init: boolean; step: boolean; shade: boolean } {
   return {
@@ -316,7 +301,16 @@ ${sceneIdFieldWgsl()}}
 @fragment
 fn fs(in: VSOut) -> FSOut {
   let p = particles[in.id];
-  let c = particleShade(p, in.uv);
+  // WEIGHT IS APPLIED HERE, on the author's result, before anything reads it.
+  //
+  // Alpha alone, and that is not a shortcut: this fragment is premultiplied
+  // two lines down, so scaling alpha scales the colour with it — and where the
+  // target blends additively the premultiply is what carries the fade. One
+  // multiply is the correct fade for both particle targets.
+  var c = particleShade(p, in.uv);
+  c.a *= pu.weight;
+  // Weight 0 therefore discards every fragment, so an effect faded out costs
+  // nothing past the vertex stage even on the frame the draw is still issued.
   if (c.a <= 0.0) { discard; }
   var out: FSOut;
   // PREMULTIPLIED: the scene's colour target blends with srcFactor \"one\", so a

package/src/shaders/passes/scene-contract.ts

@@ -86,7 +86,7 @@ type SceneRenderClass =
   | "outline"
   /** Particles and ribbons in their default, non-additive mode. */
   | "particle"
-  /** Particles declaring `// @blend additive` — LIGHT rather than matter, so
+  /** Particles declaring `#blend additive` — LIGHT rather than matter, so
    *  colour sums and alpha is left alone: a glow must not claim coverage it
    *  never occluded. The aux target sums with it, which is what lets an
    *  additive effect reach the bloom gate at all. */

package/src/shaders/passes/trails.ts

@@ -132,7 +132,8 @@ struct TrailU {
   // model is added or removed, and recompiling every trail shader for that
   // would be absurd.
   subjects: f32,
-  _pad1: f32,
+  /** The effect's evaluated influence, applied at the one output site below. */
+  weight: f32,
   _pad2: f32,
 }
 @group(0) @binding(0) var<storage, read> _rzCast: array<vec4f>;
@@ -402,15 +403,19 @@ fn fs(in: VSOut) -> TrailFSOut {
   // hardware does it, correctly and for free, and the reversed-Z trap that
   // needed its own regression test goes with it.
   let c = trailShade(in.uv.x, in.uv.y, in.age, in.weight, i32(in.slot));
-  if (c.a <= 0.0) { discard; }
+  // THE EFFECT'S weight, not the ribbon's — in.weight above is the strand's
+  // own taper and belongs to the author. This one is the scheduler's, and it
+  // scales alpha because the target below multiplies colour by src-alpha.
+  let a = c.a * tu.weight;
+  if (a <= 0.0) { discard; }
   var o: TrailFSOut;
   // STRAIGHT colour into an ADDITIVE target, which reverses the old MAX rule
   // deliberately: max existed so parallel strands could not double into bright
   // dashes on a layer composited after tone mapping. In HDR before bloom,
   // overlapping light SHOULD sum — that is what neon does — and the tone
   // mapper is what keeps the sum from clipping.
-  o.color = vec4f(c.rgb, c.a);
-  o.aux = vec4f(${src.bloom ? "1.0" : "0.0"}, 1.0, 0.0, c.a);
+  o.color = vec4f(c.rgb, a);
+  o.aux = vec4f(${src.bloom ? "1.0" : "0.0"}, 1.0, 0.0, a);
 ${sceneIdPadWgsl("o")}  return o;
 }
 `