reze-engine 0.41.3 → 0.42.0

package/dist/model.js

@@ -151,6 +151,8 @@ export class Model {
         this.blendGenCounter = 0;
         this.assetReader = null;
         this.assetBasePath = "";
+        /** 軸制限 bones and their normalised axes — see applyFixedAxes. */
+        this.fixedAxisBones = [];
         // When true, update() skips applyPoseFromClip, so whatever was last written to
         // localRotations / localTranslations persists across frames. Used by gizmo drag
         // and other direct-manipulation flows to prevent the currently-shown clip from
@@ -201,6 +203,19 @@ export class Model {
             localTranslations[i] = Vec3.zeros();
             worldMatrices[i] = Mat4.identity();
         }
+        // 軸制限 bones, gathered once and normalised. A standard rig has four —
+        // the two arm twists and the two wrist twists — so this is a four-element
+        // walk per pose rather than a branch on every bone.
+        this.fixedAxisBones = [];
+        for (let i = 0; i < boneCount; i++) {
+            const a = this.skeleton.bones[i].fixedAxis;
+            if (!a)
+                continue;
+            const len = Math.hypot(a[0], a[1], a[2]);
+            if (len < 1e-8)
+                continue;
+            this.fixedAxisBones.push({ index: i, x: a[0] / len, y: a[1] / len, z: a[2] / len });
+        }
         this.runtimeSkeleton = {
             localRotations,
             localTranslations,
@@ -372,19 +387,42 @@ export class Model {
      * Stages are the reason this exists: a door or a lift is rigged as a bone
      * morph and there is no VMD anywhere that drives it.
      */
+    /**
+     * Take the last frame's bone-morph offsets back off, before any pose source
+     * runs.
+     *
+     * This cannot live at the top of applyBoneMorphs, which is where it used to
+     * be. A pose source writes only the bones its clip keys, and it writes them
+     * from the clip — so restoring afterwards overwrote the freshly animated pose
+     * with a snapshot taken a frame earlier, and the re-snapshot immediately
+     * below then saved that same stale value again. The result was not a drift or
+     * a lag: every bone any bone morph touched stayed pinned to the first frame
+     * the model was posed at, permanently, and at ANY weight — the restore ran
+     * over the touched set before the weight test, so a morph sitting at 0 froze
+     * its bones just as hard as one at 1.
+     *
+     * It reads as "the arms don't animate" because arms are what these morphs
+     * touch: character models routinely ship T-Pose / A-Pose / ShouderBlend /
+     * ElbowBlend adjusters on 腕 and ひじ, and nothing else in the rig is a
+     * comparably popular bone-morph target.
+     */
+    undoBoneMorphs() {
+        if (!this.boneMorphApplied)
+            return;
+        for (let i = 0; i < this.boneMorphBones.length; i++) {
+            const b = this.boneMorphBones[i];
+            this.runtimeSkeleton.localRotations[b].set(this.boneMorphRestoreR[i]);
+            this.runtimeSkeleton.localTranslations[b].set(this.boneMorphRestoreT[i]);
+        }
+        this.boneMorphApplied = false;
+    }
     applyBoneMorphs() {
         if (this.boneMorphPlan.length === 0)
             return;
-        // Undo the previous application first. With a clip running this is a no-op
-        // in effect — the pose source already overwrote these bones — but a stage
-        // has no clip, so without it the same offset would be re-added every frame.
-        if (this.boneMorphApplied) {
-            for (let i = 0; i < this.boneMorphBones.length; i++) {
-                const b = this.boneMorphBones[i];
-                this.runtimeSkeleton.localRotations[b].set(this.boneMorphRestoreR[i]);
-                this.runtimeSkeleton.localTranslations[b].set(this.boneMorphRestoreT[i]);
-            }
-        }
+        // Snapshot the pose as the sources left it, so undoBoneMorphs can hand these
+        // bones back unmorphed at the top of the next frame. The two halves are a
+        // pair: without the undo a stage — which has no clip to rewrite its bones —
+        // would compound the same offset every frame.
         for (let i = 0; i < this.boneMorphBones.length; i++) {
             const b = this.boneMorphBones[i];
             this.boneMorphRestoreR[i].set(this.runtimeSkeleton.localRotations[b]);
@@ -598,6 +636,24 @@ export class Model {
             return null;
         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) {
+        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() {
         return this.skinning;
     }
@@ -1513,6 +1569,38 @@ export class Model {
                     (frameB.frame > frameA.frame ? (clampedFrame - frameA.frame) / (frameB.frame - frameA.frame) : 0)
             : frameA.weight;
     }
+    /**
+     * Hold 軸制限 bones to their own axis.
+     *
+     * A twist bone (腕捩 / 手捩) exists to rotate about the length of the limb and
+     * nothing else, and PMX says so by giving it a fixed axis. A VMD still keys it
+     * with a full quaternion, so without the constraint the bone bends as well as
+     * twists — and because the elbow is parented to 腕捩 and 腕捩1..3 inherit a
+     * fraction of it, that error is carried into the whole forearm and multiplied
+     * three ways down the arm. It is the most visible thing on the model.
+     *
+     * Projecting the quaternion's vector part onto the axis and renormalising is
+     * what keeps the twist and drops everything else; the same operation MMD and
+     * every faithful runtime performs.
+     *
+     * Applied to the STORED local rotation rather than inside a matrix path,
+     * because the append children read that array directly: constrain it once and
+     * the bone, its inheritors and a hand-posed gizmo all agree.
+     */
+    applyFixedAxes() {
+        for (const a of this.fixedAxisBones) {
+            const q = this.runtimeSkeleton.localRotations[a.index];
+            const dot = q.x * a.x + q.y * a.y + q.z * a.z;
+            const x = a.x * dot;
+            const y = a.y * dot;
+            const z = a.z * dot;
+            const len = Math.sqrt(x * x + y * y + z * z + q.w * q.w);
+            if (len > 1e-8) {
+                const inv = 1 / len;
+                q.setXYZW(x * inv, y * inv, z * inv, q.w * inv);
+            }
+        }
+    }
     applyPoseFromClip(clip, frame) {
         if (!clip)
             return;
@@ -1532,6 +1620,7 @@ export class Model {
             this.runtimeSkeleton.localRotations[boneIdx].set(_animSlerp);
             this.runtimeSkeleton.localTranslations[boneIdx].set(localTranslation);
         }
+        this.applyFixedAxes();
         for (const [morphName, keyFrames] of clip.morphTracks.entries()) {
             const weight = this.sampleMorphTrack(morphName, keyFrames, frame, this.morphTrackIndices);
             if (Number.isNaN(weight))
@@ -1680,6 +1769,7 @@ export class Model {
             this.runtimeSkeleton.localRotations[i].set(_blendQ);
             this.runtimeSkeleton.localTranslations[i].set(localTranslation);
         }
+        this.applyFixedAxes();
         const morphCount = morphAcc.length;
         for (let i = 0; i < morphCount; i++) {
             if (morphGen[i] !== gen)
@@ -1835,6 +1925,11 @@ export class Model {
         const evWatch = this.clipEvents.size > 0 ? this.animationState.getCurrentAnimation() : null;
         const evPrevFrame = evWatch !== null ? this.animationState.getCurrentFrame() : 0;
         this.animationState.update(deltaTime);
+        // Hand the pose sources their bones unmorphed. A bone morph is an offset on
+        // top of the pose, so last frame's offset has to come off before this
+        // frame's pose goes on — taking it off afterwards is what froze every
+        // morph-touched bone at its first posed frame.
+        this.undoBoneMorphs();
         if (!this.clipApplySuspended) {
             if (this.oneShot !== null) {
                 this.applyOneShot(deltaTime);
@@ -1956,7 +2051,9 @@ export class Model {
         let addLocalTx = 0, addLocalTy = 0, addLocalTz = 0;
         // Handle append transformations (same logic as computeWorldMatrices)
         const appendParentIdx = b.appendParentIndex;
-        const hasAppend = b.appendRotate &&
+        // `|| appendMove`: a move-only append (no rotation) was skipped altogether,
+        // because the guard demanded appendRotate before either branch could run.
+        const hasAppend = (b.appendRotate || b.appendMove) &&
             appendParentIdx !== undefined &&
             appendParentIdx >= 0 &&
             appendParentIdx < bones.length;
@@ -1982,12 +2079,15 @@ export class Model {
                     scratchQuat[0].setXYZW(ax, ay, az, aw);
                     scratchQuat[2].setIdentity();
                     Quat.slerpInto(scratchQuat[2], scratchQuat[0], absRatio, scratchQuat[1]);
-                    // finalRot = slerpResult * finalRot (rotation composition as quat mul)
+                    // MMD composes the append on the RIGHT: own animated rotation first, then
+                    // the inherited one (saba's `r = r * appendRotate`). We had it on the
+                    // left, which is a different rotation whenever a bone carries BOTH its
+                    // own key and an append — the twist bones, if a motion keys them.
                     const sx = scratchQuat[1].x, sy = scratchQuat[1].y, sz = scratchQuat[1].z, sw = scratchQuat[1].w;
-                    const nx = sw * fx + sx * fw + sy * fz - sz * fy;
-                    const ny = sw * fy - sx * fz + sy * fw + sz * fx;
-                    const nz = sw * fz + sx * fy - sy * fx + sz * fw;
-                    const nw = sw * fw - sx * fx - sy * fy - sz * fz;
+                    const nx = fw * sx + fx * sw + fy * sz - fz * sy;
+                    const ny = fw * sy - fx * sz + fy * sw + fz * sx;
+                    const nz = fw * sz + fx * sy - fy * sx + fz * sw;
+                    const nw = fw * sw - fx * sx - fy * sy - fz * sz;
                     fx = nx;
                     fy = ny;
                     fz = nz;
@@ -2036,7 +2136,7 @@ export class Model {
             let fx = boneRot.x, fy = boneRot.y, fz = boneRot.z, fw = boneRot.w;
             let addLocalTx = 0, addLocalTy = 0, addLocalTz = 0;
             const appendParentIdx = b.appendParentIndex;
-            const hasAppend = b.appendRotate && appendParentIdx !== undefined && appendParentIdx >= 0 && appendParentIdx < boneCount;
+            const hasAppend = (b.appendRotate || b.appendMove) && appendParentIdx !== undefined && appendParentIdx >= 0 && appendParentIdx < boneCount;
             if (hasAppend) {
                 const ratio = b.appendRatio === undefined ? 1 : Math.max(-1, Math.min(1, b.appendRatio));
                 const hasRatio = Math.abs(ratio) > 1e-6;
@@ -2054,12 +2154,15 @@ export class Model {
                         scratchQuat[0].setXYZW(ax, ay, az, aw);
                         scratchQuat[2].setIdentity();
                         Quat.slerpInto(scratchQuat[2], scratchQuat[0], absRatio, scratchQuat[1]);
-                        // finalRot = slerpResult * finalRot (quat mul)
+                        // MMD composes the append on the RIGHT: own animated rotation first, then
+                        // the inherited one (saba's `r = r * appendRotate`). We had it on the
+                        // left, which is a different rotation whenever a bone carries BOTH its
+                        // own key and an append — the twist bones, if a motion keys them.
                         const sx = scratchQuat[1].x, sy = scratchQuat[1].y, sz = scratchQuat[1].z, sw = scratchQuat[1].w;
-                        const nx = sw * fx + sx * fw + sy * fz - sz * fy;
-                        const ny = sw * fy - sx * fz + sy * fw + sz * fx;
-                        const nz = sw * fz + sx * fy - sy * fx + sz * fw;
-                        const nw = sw * fw - sx * fx - sy * fy - sz * fz;
+                        const nx = fw * sx + fx * sw + fy * sz - fz * sy;
+                        const ny = fw * sy - fx * sz + fy * sw + fz * sx;
+                        const nz = fw * sz + fx * sy - fy * sx + fz * sw;
+                        const nw = fw * sw - fx * sx - fy * sy - fz * sz;
                         fx = nx;
                         fy = ny;
                         fz = nz;

package/dist/pmx-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pmx-loader.d.ts","sourceRoot":"","sources":["../src/pmx-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAcN,MAAM,SAAS,CAAA;AAGhB,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEzE,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,kBAAkB,CAAI;IAC9B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAY;IAC/B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAe;IAE/B,OAAO;IAQP,OAAO,CAAC,IAAI;WAMC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAI9C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK;WAIpC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAKxF,OAAO,CAAC,KAAK;IAiBb,OAAO,CAAC,WAAW;IAwDnB,OAAO,CAAC,aAAa;IA+FrB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,cAAc;IAqEtB,OAAO,CAAC,UAAU;IAsKlB,OAAO,CAAC,WAAW;IAgMnB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,gBAAgB;IA+FxB,OAAO,CAAC,WAAW;IAmGnB,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,OAAO;IAkJf,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,OAAO;IAwBf,OAAO,CAAC,QAAQ;CAIjB"}
+{"version":3,"file":"pmx-loader.d.ts","sourceRoot":"","sources":["../src/pmx-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAcN,MAAM,SAAS,CAAA;AAGhB,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEzE,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,kBAAkB,CAAI;IAC9B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAY;IAC/B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAe;IAE/B,OAAO;IAQP,OAAO,CAAC,IAAI;WAMC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAI9C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK;WAIpC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAKxF,OAAO,CAAC,KAAK;IAiBb,OAAO,CAAC,WAAW;IAwDnB,OAAO,CAAC,aAAa;IA+FrB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,cAAc;IAqEtB,OAAO,CAAC,UAAU;IA2KlB,OAAO,CAAC,WAAW;IAgMnB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,gBAAgB;IA+FxB,OAAO,CAAC,WAAW;IAmGnB,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,OAAO;IAkJf,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,OAAO;IAwBf,OAAO,CAAC,QAAQ;CAIjB"}

package/dist/pmx-loader.js

@@ -302,7 +302,7 @@ export class PmxLoader {
                 const y = this.getFloat32();
                 const z = this.getFloat32();
                 const parentIndex = this.getNonVertexIndex(this.boneIndexSize);
-                this.getInt32(); // transform order (skip)
+                const deformLayer = this.getInt32(); // 変形階層
                 const flags = this.getUint16();
                 // Tail: bone index or offset vector3
                 if ((flags & FLAG_TAIL_IS_BONE) !== 0) {
@@ -325,11 +325,10 @@ export class PmxLoader {
                     appendRotate = (flags & FLAG_APPEND_ROTATE) !== 0;
                     appendMove = (flags & FLAG_APPEND_MOVE) !== 0;
                 }
-                // Axis limit
+                // Axis limit (軸制限)
+                let fixedAxis = undefined;
                 if ((flags & FLAG_AXIS_LIMIT) !== 0) {
-                    this.getFloat32();
-                    this.getFloat32();
-                    this.getFloat32();
+                    fixedAxis = [this.getFloat32(), this.getFloat32(), this.getFloat32()];
                 }
                 // Local axis (two vectors x and z)
                 if ((flags & FLAG_LOCAL_AXIS) !== 0) {
@@ -392,6 +391,8 @@ export class PmxLoader {
                     appendRatio,
                     appendRotate,
                     appendMove,
+                    fixedAxis,
+                    deformLayer,
                     ikTargetIndex,
                     ikIteration,
                     ikLimitAngle,
@@ -411,6 +412,8 @@ export class PmxLoader {
                     appendRatio: a.appendRatio,
                     appendRotate: a.appendRotate,
                     appendMove: a.appendMove,
+                    fixedAxis: a.fixedAxis,
+                    deformLayer: a.deformLayer,
                     ikTargetIndex: a.ikTargetIndex,
                     ikIteration: a.ikIteration,
                     ikLimitAngle: a.ikLimitAngle,

package/dist/shaders/passes/composite.d.ts

@@ -14,7 +14,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
@@ -23,6 +31,43 @@
  *  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 declare function parseEffectAnchors(wgsl: string, max: number): {
+    bone: string;
+    trail: boolean;
+}[];
+/**
+ * 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 declare const EFFECT_SUBJECTS = 4;
+export declare const EFFECT_ANCHORS = 8;
+export declare const EFFECT_TRAIL_SAMPLES = 128;
+/** vec4 slot where the trails begin — after the subjects and the anchors. */
+export declare const EFFECT_TRAIL_BASE: number;
 export type CompositeEffectSource = {
     /** The user's WGSL verbatim: helpers plus whichever entry points it defines. */
     wgsl: string;

package/dist/shaders/passes/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;+BAwB+B;AAC/B,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;CACvB,CAAA;AA4XD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAclF;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,eAAO,MAAM,cAAc,IAAI,CAAA;AAC/B,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,QAA6D,CAAA;AAE3F,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;CACvB,CAAA;AA2hBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAclF;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}

package/dist/shaders/passes/composite.js

@@ -12,6 +12,77 @@
 //
 // Both composite in display space, so neither affects lighting, bloom, or
 // tonemapping, and both are captured by offline export like any background.
+/** What user effect WGSL may define, documented once. A file declares its own
+ *  mounts by which of these it defines — defining both is how one file is one
+ *  weather system (dark sky behind, rain in front):
+ *
+ *    fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+ *    fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f
+ *
+ *  - `ray`   — normalized world-space view direction of this pixel (left-handed,
+ *              +Z forward; identical to what the 360 skybox samples by).
+ *  - `uv`    — 0..1 across the canvas, origin bottom-left (shadertoy-style).
+ *  - `time`  — seconds since the effect was applied.
+ *  - `depth` — FOREGROUND ONLY. Camera-space distance in metres of whatever the
+ *              scene drew at this pixel, the far plane where it drew nothing.
+ *              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.
+ *  - `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
+ *  LAYERS, so alpha is what decides how much they replace: a background effect
+ *  at alpha 1 covers the base (solid color / 360 equirect / transparent) and at
+ *  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, max) {
+    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;
 const COMPOSITE_HEAD = /* wgsl */ `
 // Pipeline-override constant: the engine creates two composite pipelines, one
 // with APPLY_GAMMA=false (gamma=1 fast path) and one with APPLY_GAMMA=true.
@@ -70,6 +141,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;
@@ -165,29 +243,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); }
+
+/**
+ * A world point as the camera sees it: xy the uv it lands on, z its distance
+ * along the VIEW AXIS in metres.
+ *
+ * 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};
 
 /**
- * Where a character is standing, in world space.
+ * 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.
  *
- * 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 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
@@ -198,11 +426,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:
  *