reze-engine 0.41.4 → 0.42.0

package/src/engine.ts

@@ -34,7 +34,14 @@ import {
   BLOOM_UPSAMPLE_SHADER_WGSL,
 } from "./shaders/passes/bloom"
 import { AGX_LUT_GZ, AGX_LUT_SIZE } from "./shaders/agx-lut"
-import { buildCompositeShader } from "./shaders/passes/composite"
+import {
+  buildCompositeShader,
+  parseEffectAnchors,
+  EFFECT_ANCHORS,
+  EFFECT_SUBJECTS,
+  EFFECT_TRAIL_BASE,
+  EFFECT_TRAIL_SAMPLES,
+} from "./shaders/passes/composite"
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick"
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap"
 import { compileGraph, type CompileOptions, type StyleSlot } from "./graph/compile"
@@ -234,14 +241,43 @@ export type WorldOptions = {
 
 /** A model's scene placement — root offset baked into skinning + visibility. Serializable
  *  into a scene descriptor via getModelTransform. */
-/** How many character positions an effect can read (viewU[11..14]). */
-const MAX_EFFECT_SUBJECTS = 4
+/** How many character positions an effect can read (viewU[11..14]). Defined
+ *  beside the shader that reads them — the layout arithmetic has to agree. */
+const MAX_EFFECT_SUBJECTS = EFFECT_SUBJECTS
 /** Where a character IS, for an effect that follows them. センター carries a
  *  motion's root movement — walking, jumping — where the model transform only
  *  carries where the model was placed; 全ての親 is the fallback for a model that
  *  animates the true root instead. */
 const SUBJECT_BONES = ["センター", "全ての親"]
 
+/** How many bones one effect may name. Eight is already a lot for one file, and
+ *  this is a MINIMUM: raising it breaks nothing, because effects read through
+ *  rzAnchor() rather than indexing the buffer. Lowering it would. */
+const MAX_EFFECT_ANCHORS = EFFECT_ANCHORS
+
+/** Only for the bounding sphere's height. */
+const HEAD_BONE = "頭"
+
+/** Path samples kept per trailed anchor. ~2.1s at the sampling rate below, which
+ *  is a long ribbon — a dancer's arm draws most of a circle in that time.
+ *
+ *  A MINIMUM, like every cap here, and raising it is why that matters: effects
+ *  read through rzTrail and loop to rzTrailCount, so this went 64 → 128 without
+ *  touching a single published effect. Lowering it is the direction that breaks. */
+const TRAIL_SAMPLES = EFFECT_TRAIL_SAMPLES
+/** Sampled on the SCENE clock at a fixed rate, so a path is identical in the
+ *  editor, in an export and in a re-export, and its spacing does not change with
+ *  the display's refresh. */
+const TRAIL_HZ = 60
+const TRAIL_DT = 1 / TRAIL_HZ
+
+/** vec4 slots: four subjects × 3, then anchors × four subjects × 3, then the
+ *  trails — slot-major, four subjects each, TRAIL_SAMPLES apiece. */
+const CAST_SUBJECT_VEC4S = MAX_EFFECT_SUBJECTS * 3
+const CAST_ANCHOR_VEC4S = MAX_EFFECT_ANCHORS * MAX_EFFECT_SUBJECTS * 3
+const CAST_TRAIL_BASE = EFFECT_TRAIL_BASE
+const CAST_VEC4S = CAST_TRAIL_BASE + MAX_EFFECT_ANCHORS * MAX_EFFECT_SUBJECTS * TRAIL_SAMPLES
+
 export type ModelTransform = {
   position: Vec3
   rotation: Quat
@@ -840,7 +876,29 @@ export class Engine {
     /** Mounted over the finished frame — and the reason the scene pass has to
      *  STORE its depth, which it otherwise discards into tile memory. */
     hasForeground: boolean
+    /** Bones the source asked for, in declaration order — rzAnchor's slots. Only
+     *  these are resolved and uploaded, so a file that names none costs nothing. */
+    anchors: { bone: string; trail: boolean }[]
   } | null = null
+  /** The cast, as the effect API sees it. Written per frame while an effect is
+   *  installed, and only up to what that effect actually declared. */
+  private castBuffer!: GPUBuffer
+  private castData!: Float32Array<ArrayBuffer>
+  /** Last frame's anchor world positions, for velocity. Keyed model id → slot. */
+  private anchorPrev = new Map<string, Float32Array>()
+  private castLastMs = 0
+  /** Recent path per trailed anchor, keyed "model\0slot". Newest first, so the
+   *  shader's index 0 is now — written by unshifting rather than by tracking a
+   *  head, because 64 is short and the alternative is an index the GPU side
+   *  would also have to know about. */
+  private anchorTrail = new Map<string, { pos: number[]; t: number[] }>()
+  /** Scene seconds, advanced by the frame delta — NOT wall time, so an offline
+   *  export samples the same path the editor showed. */
+  private sceneClock = 0
+  private trailAccum = 0
+  /** Trail samples owed this frame, computed once so every trail on every
+   *  character samples in lockstep and their paths stay comparable. */
+  private trailDue = 0
   private agxLutTexture: GPUTexture | null = null
   private agxFallbackTexture!: GPUTexture
   /** Bound at composite binding 7 when no effect (or a param-less one) is set. */
@@ -1191,6 +1249,7 @@ export class Engine {
 
   private rebuildCompositeBindGroup(): void {
     if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView || !this.depthReadView) return
+    if (!this.castBuffer) return
     this.compositeBindGroup = this.device.createBindGroup({
       label: "composite bind group",
       layout: this.compositeBindGroupLayout,
@@ -1206,6 +1265,7 @@ export class Engine {
         { binding: 8, resource: this.depthReadView },
         { binding: 9, resource: { buffer: this.dofUniformBuffer } },
         { binding: 10, resource: (this.agxLutTexture ?? this.agxFallbackTexture).createView({ dimension: "3d" }) },
+        { binding: 11, resource: { buffer: this.castBuffer } },
       ],
     })
   }
@@ -1337,6 +1397,14 @@ export class Engine {
     }
     const mounts = { background: hasBackground, foreground: hasForeground }
 
+    // ── Which bones did the author ask for? Same idea as the mounts above: a
+    // declaration in the source, not a setting somewhere else. Only what is
+    // named here gets resolved and uploaded, so naming none costs nothing and
+    // naming eight costs eight — rather than every rig's 500 bones costing
+    // everybody. Past the cap the extras are dropped rather than silently
+    // shifting every slot after them.
+    const anchors = parseEffectAnchors(wgsl, MAX_EFFECT_ANCHORS)
+
     // ── Params: codegen a WGSL struct and mirror its uniform layout on the CPU.
     // Fields are emitted in declaration order; offsets follow WGSL's natural
     // uniform rules (f32 align 4, vec3f align 16 size 12), computed identically
@@ -1418,7 +1486,13 @@ export class Engine {
       })
       this.device.queue.writeBuffer(paramsBuffer, 0, paramsData)
     }
-    this.effect = { wgsl, paramLayout: layout, paramsBuffer, paramsData, hasBackground, hasForeground }
+    this.effect = { wgsl, paramLayout: layout, paramsBuffer, paramsData, hasBackground, hasForeground, anchors }
+    // Velocities and paths restart from rest rather than continuing from
+    // whatever the last effect's slot 0 happened to be — the slots mean
+    // something different now, and a trail would otherwise draw a line from the
+    // old bone to the new one across the whole scene.
+    this.anchorPrev.clear()
+    this.anchorTrail.clear()
     this.compositePipelineIdentity = identity
     this.compositePipelineGamma = gamma
     this.effectEpochMs = performance.now()
@@ -2457,6 +2531,15 @@ export class Engine {
       size: 16,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
+    // Allocated at full size once rather than grown: it is ~7KB, the bind group
+    // would otherwise be rebuilt whenever an effect declared a different number
+    // of bones, and only the declared prefix is ever written.
+    this.castData = new Float32Array(CAST_VEC4S * 4)
+    this.castBuffer = this.device.createBuffer({
+      label: "effect cast data",
+      size: this.castData.byteLength,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    })
     this.compositeBindGroupLayout = this.device.createBindGroupLayout({
       label: "composite bind group layout",
       entries: [
@@ -2486,6 +2569,9 @@ export class Engine {
         // AgX's 57³ cube. Decompressed and uploaded off the critical path, so a
         // 1×1×1 stand-in keeps the bind group valid until it arrives.
         { binding: 10, visibility: GPUShaderStage.FRAGMENT, texture: { viewDimension: "3d" } },
+        // The cast, for rzSubject/rzAnchor. Always bound so the base shader's
+        // layout matches; the base shader simply never reads it.
+        { binding: 11, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "read-only-storage" } },
       ],
     })
     this.fallbackEquirectTexture = this.device.createTexture({
@@ -5393,6 +5479,13 @@ export class Engine {
   }
 
   private renderWithDelta(deltaTime: number) {
+    // The scene clock, and the only clock a trail may sample on: renderFrame()
+    // drives offline export with an exact per-frame delta, so a path recorded
+    // against this is reproducible where one recorded against wall time is not.
+    this.sceneClock += deltaTime
+    this.trailAccum += deltaTime
+    this.trailDue = Math.floor(this.trailAccum / TRAIL_DT)
+    this.trailAccum -= this.trailDue * TRAIL_DT
     const tFrame = performance.now()
     this.frameAnimMsRaw = 0
     this.framePhysicsMsRaw = 0
@@ -6218,11 +6311,172 @@ export class Engine {
         u[44 + n * 4] = px
         u[45 + n * 4] = py
         u[46 + n * 4] = pz
+        this.writeCastEntry(inst, n, px, py, pz)
         n++
       })
       u[43] = n
       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.
+      if (this.effect) {
+        // Up to the last trailed slot, not the whole buffer: an effect with no
+        // trails never uploads the 32KB it would otherwise pay for every frame.
+        let lastTrail = -1
+        for (let i = 0; i < this.effect.anchors.length; i++) if (this.effect.anchors[i].trail) lastTrail = i
+        const used =
+          lastTrail >= 0
+            ? CAST_TRAIL_BASE + (lastTrail * MAX_EFFECT_SUBJECTS + MAX_EFFECT_SUBJECTS) * TRAIL_SAMPLES
+            : CAST_SUBJECT_VEC4S + this.effect.anchors.length * MAX_EFFECT_SUBJECTS * 3
+        this.device.queue.writeBuffer(this.castBuffer, 0, this.castData, 0, used * 4)
+        this.castLastMs = performance.now()
+      }
+    }
+  }
+
+  /**
+   * One character's slice of the effect API's view of the cast.
+   *
+   * `px/py/pz` is the hip point the caller just composed — passed in rather than
+   * recomputed, since it is the same two bone lookups.
+   *
+   * Bone positions are model-space, so each is scaled, rotated and translated by
+   * the model transform exactly as the hip point above was. Getting that wrong
+   * does not look wrong on a model standing at the origin, which is precisely
+   * how it would ship.
+   */
+  private writeCastEntry(inst: ModelInstance, n: number, px: number, py: number, pz: number): void {
+    const effect = this.effect
+    if (!effect) return
+    const m = inst.model
+    const cd = this.castData
+    const toWorld = (v: Vec3): Vec3 => {
+      v.setXYZ(v.x * m.scale, v.y * m.scale, v.z * m.scale)
+      Quat.rotateVecInto(m.rotation, v, v)
+      v.setXYZ(v.x + m.position.x, v.y + m.position.y, v.z + m.position.z)
+      return v
+    }
+
+    // The floor under this character: where the model was PLACED.
+    //
+    // A foot bone was the obvious answer and the wrong one. 足ＩＫ sits at the
+    // ANKLE, not on the sole — an ankle above the ground even standing still,
+    // and further still in heels — so a floor derived from it lands a hand's
+    // width up the leg, which is exactly where the first version of Footfalls
+    // drew its marks. A PMX's origin is between the feet on the floor by
+    // convention, and placing a character on a stage moves that origin with
+    // them, so the placement already answers "what is the ground here".
+    //
+    // Deliberately NOT the animated height: a jump lifts the character, not the
+    // floor, and a floor that follows a jump is not a floor.
+    const floorY = m.position.y
+    // Generous on purpose: this is for culling, and a sphere that is too small
+    // clips the effect it was meant to bound. Height is hip-to-head doubled;
+    // arm span is about height on a human, so half of it is the radius, and the
+    // rest is margin for a motion that reaches.
+    const head = m.getBoneWorldPosition(HEAD_BONE)
+    const height = head ? Math.max(0.01, toWorld(head).y - floorY) : Math.max(0.01, (py - floorY) * 2)
+    const b = n * 12
+    cd[b] = px
+    cd[b + 1] = floorY
+    cd[b + 2] = pz
+    cd[b + 3] = 1
+    cd[b + 4] = px
+    cd[b + 5] = py
+    cd[b + 6] = pz
+    cd[b + 8] = px
+    cd[b + 9] = floorY + height * 0.5
+    cd[b + 10] = pz
+    cd[b + 11] = height * 0.75
+
+    // Declared bones. Velocity is per model AND per slot, so two characters
+    // wearing the same effect never inherit each other's motion.
+    const anchors = effect.anchors
+    if (anchors.length === 0) return
+    let prev = this.anchorPrev.get(inst.name)
+    const dtMs = Math.max(1, performance.now() - this.castLastMs)
+    const invDt = 1000 / dtMs
+    if (!prev || prev.length !== anchors.length * 3) {
+      prev = new Float32Array(anchors.length * 3).fill(NaN)
+      this.anchorPrev.set(inst.name, prev)
+    }
+    for (let s = 0; s < anchors.length; s++) {
+      const a = CAST_SUBJECT_VEC4S * 4 + (s * MAX_EFFECT_SUBJECTS + n) * 12
+      const pos = m.getBoneWorldPosition(anchors[s].bone)
+      if (!pos) {
+        cd[a + 3] = 0
+        continue
+      }
+      toWorld(pos)
+      const p = s * 3
+      // NaN on the first frame a slot exists — a velocity out of nothing would
+      // be a spike, and a trail or a spark reading it would fire on load.
+      const vx = Number.isNaN(prev[p]) ? 0 : (pos.x - prev[p]) * invDt
+      const vy = Number.isNaN(prev[p]) ? 0 : (pos.y - prev[p + 1]) * invDt
+      const vz = Number.isNaN(prev[p]) ? 0 : (pos.z - prev[p + 2]) * invDt
+      prev[p] = pos.x
+      prev[p + 1] = pos.y
+      prev[p + 2] = pos.z
+      cd[a] = pos.x
+      cd[a + 1] = pos.y
+      cd[a + 2] = pos.z
+      cd[a + 3] = 1
+      cd[a + 4] = vx
+      cd[a + 5] = vy
+      cd[a + 6] = vz
+      if (anchors[s].trail) this.writeTrail(inst.name, s, n, pos, cd, a)
+      const fwd = m.getBoneWorldForward(anchors[s].bone)
+      if (fwd) {
+        Quat.rotateVecInto(m.rotation, fwd, fwd)
+        cd[a + 8] = fwd.x
+        cd[a + 9] = fwd.y
+        cd[a + 10] = fwd.z
+      }
+    }
+  }
+
+  /**
+   * One trailed anchor's recent path, sampled on the scene clock and written
+   * newest-first.
+   *
+   * Newest-first is what lets a ribbon be drawn by walking the index upward and
+   * fading on age, and it means the shader never needs to know where the ring's
+   * head is. Sixty-four entries is short enough that unshifting beats the
+   * bookkeeping an actual ring buffer would push onto the GPU side too.
+   *
+   * Sampling is gated on TRAIL_DT of SCENE time, so a 120Hz display and a 30fps
+   * export record the same path at the same spacing. A frame that covers several
+   * intervals emits several samples rather than one, or a fast hand would tear.
+   */
+  private writeTrail(model: string, slot: number, n: number, pos: Vec3, cd: Float32Array, anchorBase: number): void {
+    const key = `${model}\u0000${slot}`
+    let ring = this.anchorTrail.get(key)
+    if (!ring) {
+      ring = { pos: [], t: [] }
+      this.anchorTrail.set(key, ring)
+    }
+    if (this.trailDue > 0 || ring.pos.length === 0) {
+      const steps = Math.min(this.trailDue, 4)
+      for (let k = 0; k < Math.max(1, steps); k++) {
+        ring.pos.unshift(pos.x, pos.y, pos.z)
+        ring.t.unshift(this.sceneClock)
+        if (ring.t.length > TRAIL_SAMPLES) {
+          ring.t.length = TRAIL_SAMPLES
+          ring.pos.length = TRAIL_SAMPLES * 3
+        }
+      }
     }
+    const count = ring.t.length
+    // Age rather than a timestamp: the shader would otherwise need the scene
+    // clock too, and there is only one place that has to know what time it is.
+    const base = (CAST_TRAIL_BASE + (slot * MAX_EFFECT_SUBJECTS + n) * TRAIL_SAMPLES) * 4
+    for (let i = 0; i < count; i++) {
+      cd[base + i * 4] = ring.pos[i * 3]
+      cd[base + i * 4 + 1] = ring.pos[i * 3 + 1]
+      cd[base + i * 4 + 2] = ring.pos[i * 3 + 2]
+      cd[base + i * 4 + 3] = this.sceneClock - ring.t[i]
+    }
+    // The count rides in the anchor's spare lane, so rzTrailCount is one read.
+    cd[anchorBase + 11] = count
   }
 
   private updateSkinMatrices() {

package/src/model.ts

@@ -968,6 +968,23 @@ export class Model {
     return this.runtimeSkeleton.worldMatrices[idx].getPosition()
   }
 
+  /**
+   * A bone's forward axis, normalised — which way a foot points, where a head
+   * looks. Model space, like getBoneWorldPosition: the caller composes the model
+   * transform on top if it wants world space.
+   *
+   * Column 2 of the world matrix. Null for a name this rig does not have, which
+   * is the ordinary case across rigs that spell bones differently.
+   */
+  getBoneWorldForward(boneName: string): Vec3 | null {
+    const idx = this.runtimeSkeleton.nameIndex[boneName]
+    if (idx === undefined || idx < 0) return null
+    const m = this.runtimeSkeleton.worldMatrices[idx].values
+    const len = Math.hypot(m[8], m[9], m[10])
+    if (len < 1e-8) return null
+    return new Vec3(m[8] / len, m[9] / len, m[10] / len)
+  }
+
   getSkinning(): Skinning {
     return this.skinning
   }

package/src/shaders/passes/composite.ts

@@ -29,7 +29,15 @@
  *              Compare a particle's own distance against it and the model
  *              occludes it; fog needs no comparison at all, its alpha simply IS
  *              a function of distance.
- *  - `bgResolution()` — canvas size in pixels, for aspect correction.
+ *  - `rzResolution()` — canvas size in pixels, for aspect correction.
+ *  - `rzCameraPos()`, `rzWorldPos(ray, depth)` — the lens, and the place a pixel
+ *              was drawn.
+ *  - `rzSubjectCount()`, `rzSubjectHip(i)` — the cast, at HIP height (see the
+ *              function; it is not the floor, and reading it as the floor is a
+ *              mistake this API's own comment used to invite).
+ *  - `rzProject(p)` — a world point as uv + view-axis distance; the cheap way to
+ *              anchor anything, and `z` compares directly against `depth`.
+ *  - the bg* spellings of all of the above still resolve, permanently.
  *  - declared params arrive as `params.<name>` (f32 or vec3f), shared by both.
  *
  *  Return display-space sRGB + alpha, 0..1. Both mounts are alpha-composited
@@ -38,6 +46,46 @@
  *  0 lets it through, which is how a starfield is stars over the user's color;
  *  a foreground at alpha 1 covers the frame. No mode flag anywhere — the alpha
  *  channel already says it. */
+/**
+ * The bones an effect asked for, in declaration order — the slots rzAnchor reads.
+ *
+ *     // @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 —
+ * which would shift every slot after it.
+ *
+ * `trail` additionally keeps that bone's recent PATH, for rzTrail. Opt-in
+ * because a path is two orders of magnitude more data than a point, and most
+ * anchors want a point.
+ *
+ * Names are passed through verbatim: any bone the rig has works, and one it does
+ * 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)]
+    .map((m) => ({ bone: m[1], trail: m[2] !== undefined }))
+    .slice(0, max)
+}
+
+/**
+ * The caps the cast buffer is built to, shared by the shader below and by the
+ * engine that fills it. Interpolated into the WGSL rather than written twice:
+ * the layout arithmetic on both sides has to agree exactly, and two literals
+ * that must match are two literals that eventually will not.
+ *
+ * All three are MINIMUMS. Raising one breaks nothing, because effects read
+ * through accessors and loop to the count functions; lowering one does.
+ */
+export const EFFECT_SUBJECTS = 4
+export const EFFECT_ANCHORS = 8
+export const EFFECT_TRAIL_SAMPLES = 128
+/** vec4 slot where the trails begin — after the subjects and the anchors. */
+export const EFFECT_TRAIL_BASE = EFFECT_SUBJECTS * 3 + EFFECT_ANCHORS * EFFECT_SUBJECTS * 3
+
 export type CompositeEffectSource = {
   /** The user's WGSL verbatim: helpers plus whichever entry points it defines. */
   wgsl: string
@@ -107,6 +155,13 @@ override APPLY_GAMMA: bool = true;
 // Blender's AgX, as the 57³ lookup it ships as rather than a reconstruction of
 // it. Sampled in the log-encoded E-Gamut space the cube expects — see agxTransform.
 @group(0) @binding(10) var agxLut: texture_3d<f32>;
+// The cast, as data. Read through rzSubject/rzAnchor below — the LAYOUT IS NOT
+// STABLE and never will be, because it depends on what each effect declared.
+// Reading it directly is the one thing that would freeze it forever.
+//
+// vec4 slots: [0 .. 11] four subjects, three each (root+valid, hip, bounds);
+// then MAX_ANCHORS × four subjects, three each (pos+valid, vel, fwd).
+@group(0) @binding(11) var<storage, read> _rzCast: array<vec4f>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
@@ -202,29 +257,179 @@ fn viewTransform(c: vec3f) -> vec3f {
   return vec3f(filmic(c.r), filmic(c.g), filmic(c.b));
 }
 
-/** Canvas size in pixels — for user effects (aspect correction). */
-fn bgResolution() -> vec2f { return viewU[6].zw; }
+// ── The effect API ────────────────────────────────────────────────────────────
+//
+// Named rz*, for the engine. The prefix earns its place twice: user code is
+// concatenated into THIS module, so an unprefixed rzAnchor() would collide with
+// exactly the helper an author would write, and the old bg* prefix stopped being
+// true in 0.41.0 when effects gained a mount over the finished frame.
+//
+// The bg* names below are permanent aliases, not a deprecation with an end date.
+// A published link is immutable, so a scene pinned to a bg* effect has to keep
+// compiling forever. They are one-line and inlined; no new function gets one.
+
+/** Canvas size in pixels — for aspect correction. */
+fn rzResolution() -> vec2f { return viewU[6].zw; }
 
 /** The camera's world position. */
-fn bgCameraPos() -> vec3f { return viewU[10].xyz; }
+fn rzCameraPos() -> vec3f { return viewU[10].xyz; }
 
 /** How many characters are in the scene, up to four. */
-fn bgSubjectCount() -> i32 { return i32(viewU[10].w); }
+fn rzSubjectCount() -> i32 { return i32(viewU[10].w); }
 
 /**
- * Where a character is standing, in world space.
+ * A world point as the camera sees it: xy the uv it lands on, z its distance
+ * along the VIEW AXIS in metres.
  *
- * An effect that wants to RESPOND to the cast — ripples under the feet, a glow
- * that follows someone, dust kicked up where they are — needs to know where
- * they are, and the ray and the depth cannot tell it: they describe the pixel,
- * not the scene. This is the model's root, which for a PMX is between the feet
- * on the floor, so it is already the contact point a ripple wants.
+ * The exact inverse of the ray this pass builds per pixel, so it is the cheap way
+ * to work with anything anchored in the world. Marching a curve or a trail in 3D
+ * costs a distance evaluation per sample per pixel; projecting its points once
+ * and measuring in 2D costs a subtraction, which is the difference between a
+ * ribbon that runs at 4K and one that does not.
+ *
+ * z is directly comparable to the depth handed to foreground(), so occlusion is
+ * a single test: draw where your z is nearer than the scene's. It is returned
+ * SIGNED and unclamped — behind the camera is negative, and worth rejecting
+ * before you use the uv, which is meaningless there.
+ */
+fn rzProject(p: vec3f) -> vec3f {
+  let d = p - viewU[10].xyz;
+  let z = dot(d, viewU[5].xyz);
+  // Guard only the divide. z itself is returned as it is, so the caller can see
+  // the sign; clamping it here would put points behind the lens on the horizon.
+  let inv = 1.0 / select(z, 1e-4, z < 1e-4);
+  let ndc = vec2f(dot(d, viewU[3].xyz) * inv / viewU[3].w, dot(d, viewU[4].xyz) * inv / viewU[4].w);
+  return vec3f(ndc * 0.5 + 0.5, z);
+}
+
+/** A character, as much of one as a shader needs. */
+struct RzSubject {
+  /** On the FLOOR, under the body — where a ring or a magic circle belongs. */
+  root: vec3f,
+  /** At the hips, the middle of the body — where an aura belongs. */
+  center: vec3f,
+  /** Bounding sphere: xyz centre, w radius. Deliberately generous — cull with it. */
+  bounds: vec4f,
+  /** False past the end of the cast, and every field is then zero. */
+  valid: bool,
+}
+
+/** One bone an effect asked for, by name, at the top of its own source. */
+struct RzAnchor {
+  pos: vec3f,
+  /** World units per second, from the previous frame. Direction for a trail,
+   *  magnitude for anything that should react to how hard someone is moving. */
+  vel: vec3f,
+  /** The bone's forward axis — which way a foot points, where a head looks. */
+  fwd: vec3f,
+  /** False when this rig has no such bone. Check it: the alternative is drawing
+   *  a hand effect at the world origin on every model that spells it differently. */
+  valid: bool,
+}
+
+const RZ_MAX_ANCHORS: i32 = ${EFFECT_ANCHORS};
+
+/**
+ * Character i. Loop to rzSubjectCount(), never to a constant — the caps here are
+ * MINIMUMS and are free to grow, which is only true while nobody hardcodes them.
+ */
+fn rzSubject(i: i32) -> RzSubject {
+  var s: RzSubject;
+  s.valid = i >= 0 && i < rzSubjectCount();
+  if (!s.valid) { return s; }
+  let b = i * 3;
+  s.root = _rzCast[b].xyz;
+  s.center = _rzCast[b + 1].xyz;
+  s.bounds = _rzCast[b + 2];
+  return s;
+}
+
+/**
+ * The slot-th bone this effect declared, on character subject.
+ *
+ * Slots are the order of the declarations at the top of your source:
+ *
+ *     // @anchor 左手首
+ *     // @anchor 頭
+ *
+ * gives you slot 0 and slot 1. Any bone name the model has works; valid is
+ * false when it does not have it, which is the normal case across rigs that
+ * spell things differently.
+ */
+fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
+  var a: RzAnchor;
+  a.valid = false;
+  if (subject < 0 || subject >= rzSubjectCount() || slot < 0 || slot >= RZ_MAX_ANCHORS) { return a; }
+  let b = ${EFFECT_SUBJECTS * 3} + (slot * ${EFFECT_SUBJECTS} + subject) * 3;
+  a.valid = _rzCast[b].w > 0.5;
+  a.pos = _rzCast[b].xyz;
+  a.vel = _rzCast[b + 1].xyz;
+  a.fwd = _rzCast[b + 2].xyz;
+  return a;
+}
+
+const RZ_TRAIL_SAMPLES: i32 = ${EFFECT_TRAIL_SAMPLES};
+
+/**
+ * How many path samples this anchor has. Zero unless it was declared with
+ * trail, and it climbs from zero as the trail fills after the effect loads.
+ *
+ * Loop to THIS, never to RZ_TRAIL_SAMPLES: the cap is a minimum and is free to
+ * grow, which stays true only while nobody hardcodes it.
+ */
+fn rzTrailCount(subject: i32, slot: i32) -> i32 {
+  if (subject < 0 || subject >= rzSubjectCount() || slot < 0 || slot >= RZ_MAX_ANCHORS) { return 0; }
+  return i32(_rzCast[${EFFECT_SUBJECTS * 3} + (slot * ${EFFECT_SUBJECTS} + subject) * 3 + 2].w);
+}
+
+/**
+ * Sample i of an anchor's path: xyz where it was, w how many seconds ago.
+ *
+ * i = 0 is NOW and they run backwards in time, so a ribbon is drawn by walking i
+ * upward and fading on .w. Sampled at a fixed rate on the SCENE clock, not the
+ * display's — so the path is identical in the editor, in an export, and in a
+ * re-export, and its spacing does not change with framerate.
+ *
+ * This is what a hand trail wants instead of position and velocity. One position
+ * and one velocity is a straight segment that jitters, because a velocity is a
+ * difference between two frames; a path is what actually happened.
+ */
+fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
+  let n = rzTrailCount(subject, slot);
+  if (i < 0 || i >= n) { return vec4f(0.0); }
+  let base = ${EFFECT_TRAIL_BASE} + (slot * ${EFFECT_SUBJECTS} + subject) * RZ_TRAIL_SAMPLES;
+  return _rzCast[base + i];
+}
+
+fn bgResolution() -> vec2f { return rzResolution(); }
+fn bgCameraPos() -> vec3f { return rzCameraPos(); }
+fn bgSubjectCount() -> i32 { return rzSubjectCount(); }
+
+/**
+ * Where a character IS, in world space — at the hips, not on the floor.
+ *
+ * An effect that wants to RESPOND to the cast — a glow that follows someone,
+ * dust kicked up where they are — needs to know where they are, and the ray and
+ * the depth cannot tell it: they describe the pixel, not the scene.
+ *
+ * The value is model.position + センター + 全ての親. センター sits at hip
+ * height on every standard MMD rig, so this is a point in the middle of the
+ * body. It is NOT the contact point: a ripple drawn here appears at the waist.
+ * Ground effects want the .xz of this and their own floor height, which is what
+ * the effects that shipped against it already do.
+ *
+ * The comment here used to claim it was "between the feet on the floor", which
+ * is where that habit came from. Left as it is regardless of the name: a
+ * published link is immutable, so every shared scene pinning an effect that
+ * reads this depends on it meaning exactly what it has always meant.
  *
  * Clamped rather than bounds-checked: an effect looping past the count reads the
  * last subject instead of sampling whatever follows the array, which is a wrong
  * ripple rather than an undefined one.
  */
-fn bgSubjectPos(i: i32) -> vec3f { return viewU[11 + clamp(i, 0, 3)].xyz; }
+fn rzSubjectHip(i: i32) -> vec3f { return viewU[11 + clamp(i, 0, 3)].xyz; }
+
+fn bgSubjectPos(i: i32) -> vec3f { return rzSubjectHip(i); }
 
 /** Where in the WORLD the scene drew this pixel — the depth handed to
  *  foreground() turned into a place. Without it an effect can only think in
@@ -235,11 +440,13 @@ fn bgSubjectPos(i: i32) -> vec3f { return viewU[11 + clamp(i, 0, 3)].xyz; }
  *  the ray's projection onto camera-forward before being walked out. At the far
  *  plane (nothing drawn) this lands a very long way off, which is what a sky
  *  should do to anything reading it. */
-fn bgWorldPos(ray: vec3f, depth: f32) -> vec3f {
+fn rzWorldPos(ray: vec3f, depth: f32) -> vec3f {
   let axis = max(dot(normalize(ray), viewU[5].xyz), 1e-4);
-  return bgCameraPos() + normalize(ray) * (depth / axis);
+  return rzCameraPos() + normalize(ray) * (depth / axis);
 }
 
+fn bgWorldPos(ray: vec3f, depth: f32) -> vec3f { return rzWorldPos(ray, depth); }
+
 /** Color grading, applied to the tonemapped SCENE (not the background — see the
  *  call site). The core is ASC CDL, the film-industry interchange standard:
  *