@woosh/meep-engine 3.52.0 → 3.53.0

package/src/shade/renderer/animation/POSE_ACCUMULATOR_LAYOUT.d.ts

@@ -11,22 +11,27 @@
  * Per-axis dirty bits live in a single dirty u32 (atomicOr to set,
  * atomicLoad in resolve, atomicStore(0) to clear).
  *
- * Layout in u32 indices (slot stride = 16 u32s = 64 bytes — one u32 of
- * tail padding gives the slot a power-of-two stride so addressing is a
+ * Layout in u32 indices (slot stride = 32 u32s = 128 bytes — 11 u32s of
+ * tail padding give the slot a power-of-two stride so addressing is a
  * shift, not a multiply):
  *
- *   [0..3]   translation.xyz       (3 atomic<u32>, f32 bitcast)
- *   [3..7]   rotation.xyzw         (4 atomic<u32>, f32 bitcast)
- *   [7..10]  scale.xyz             (3 atomic<u32>, f32 bitcast)
+ *   [0..3]   translation.xyz       (3 atomic<u32>, f32 bitcast, weighted delta from rest)
+ *   [3..7]   rotation.xyzw         (4 atomic<u32>, f32 bitcast, weighted delta from rest)
+ *   [7..10]  scale.xyz             (3 atomic<u32>, f32 bitcast, weighted delta from rest)
  *   [10]     dirty_mask            (atomic<u32>, see flag bits below)
  *   [11..15] rest_rotation.xyzw    (4 atomic<u32>, f32 bitcast)
- *   [15]     padding
+ *   [15..18] rest_translation.xyz  (3 atomic<u32>, f32 bitcast)
+ *   [18..21] rest_scale.xyz        (3 atomic<u32>, f32 bitcast)
+ *   [21..32] padding
  *
- * `rest_rotation` is not a sum. Every rotation contribution stores its
- * target's rest rotation there, whatever its weight, and the resolve
- * writes it to the row when the rotation sum has length zero. It is not
- * drained: a row is only rotation-dirty in a frame some contribution
- * stored it afresh.
+ * `rest_rotation`, `rest_translation`, and `rest_scale` are not sums.
+ * Every contribution stores its target's rest value there, whatever its
+ * weight, and the resolve adds the accumulated delta to the rest value:
+ *   V_final = V_rest + sum(w_i * (V_i - V_rest))
+ * Because every clip accumulates a delta from rest, normal blending
+ * (weights summing to 1), fade-to-rest (single clip with weight < 1),
+ * and additive layering (any number of extra clips on top of a base pose)
+ * all use the exact same equation with zero runtime mode flags.
  *
  * `dirty_mask` bit layout:
  *   bits 0–2: translation x/y/z written this frame
@@ -42,7 +47,7 @@
  */
 /**
  * u32-stride per pose-accumulator slot. Picked to be a power of two so
- * `row << 4` works as the slot offset. 15 u32s are used, 1 is padding.
+ * `row << 5` works as the slot offset. 21 u32s are used, 11 are padding.
  * @type {number}
  */
 export const POSE_ACCUMULATOR_STRIDE: number;
@@ -59,6 +64,8 @@ export const POSE_ACCUMULATOR_OFFSET_ROTATION: 3;
 export const POSE_ACCUMULATOR_OFFSET_SCALE: 7;
 export const POSE_ACCUMULATOR_OFFSET_DIRTY: 10;
 export const POSE_ACCUMULATOR_OFFSET_REST_ROTATION: 11;
+export const POSE_ACCUMULATOR_OFFSET_REST_TRANSLATION: 15;
+export const POSE_ACCUMULATOR_OFFSET_REST_SCALE: 18;
 /**
  * Dirty-mask bit layout. Per-axis for T/S, single bit for R.
  */

package/src/shade/renderer/animation/POSE_ACCUMULATOR_LAYOUT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"POSE_ACCUMULATOR_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/POSE_ACCUMULATOR_LAYOUT.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;GAIG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;GAKG;AACH,0CAFU,MAAM,CAEuD;AAEvE,gDAAgD;AAChD,oDAAqD;AACrD,iDAAkD;AAClD,8CAA+C;AAC/C,+CAAgD;AAChD,uDAAwD;AAExD;;GAEG;AACH,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC;AACpC,kCAAmC;AACnC,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC"}
+{"version":3,"file":"POSE_ACCUMULATOR_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/POSE_ACCUMULATOR_LAYOUT.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;;GAIG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;GAKG;AACH,0CAFU,MAAM,CAEuD;AAEvE,gDAAgD;AAChD,oDAAqD;AACrD,iDAAkD;AAClD,8CAA+C;AAC/C,+CAAgD;AAChD,uDAAwD;AACxD,0DAA2D;AAC3D,oDAAqD;AAErD;;GAEG;AACH,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC;AACpC,kCAAmC;AACnC,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC"}

package/src/shade/renderer/animation/POSE_ACCUMULATOR_LAYOUT.js

@@ -11,22 +11,27 @@
  * Per-axis dirty bits live in a single dirty u32 (atomicOr to set,
  * atomicLoad in resolve, atomicStore(0) to clear).
  *
- * Layout in u32 indices (slot stride = 16 u32s = 64 bytes — one u32 of
- * tail padding gives the slot a power-of-two stride so addressing is a
+ * Layout in u32 indices (slot stride = 32 u32s = 128 bytes — 11 u32s of
+ * tail padding give the slot a power-of-two stride so addressing is a
  * shift, not a multiply):
  *
- *   [0..3]   translation.xyz       (3 atomic<u32>, f32 bitcast)
- *   [3..7]   rotation.xyzw         (4 atomic<u32>, f32 bitcast)
- *   [7..10]  scale.xyz             (3 atomic<u32>, f32 bitcast)
+ *   [0..3]   translation.xyz       (3 atomic<u32>, f32 bitcast, weighted delta from rest)
+ *   [3..7]   rotation.xyzw         (4 atomic<u32>, f32 bitcast, weighted delta from rest)
+ *   [7..10]  scale.xyz             (3 atomic<u32>, f32 bitcast, weighted delta from rest)
  *   [10]     dirty_mask            (atomic<u32>, see flag bits below)
  *   [11..15] rest_rotation.xyzw    (4 atomic<u32>, f32 bitcast)
- *   [15]     padding
+ *   [15..18] rest_translation.xyz  (3 atomic<u32>, f32 bitcast)
+ *   [18..21] rest_scale.xyz        (3 atomic<u32>, f32 bitcast)
+ *   [21..32] padding
  *
- * `rest_rotation` is not a sum. Every rotation contribution stores its
- * target's rest rotation there, whatever its weight, and the resolve
- * writes it to the row when the rotation sum has length zero. It is not
- * drained: a row is only rotation-dirty in a frame some contribution
- * stored it afresh.
+ * `rest_rotation`, `rest_translation`, and `rest_scale` are not sums.
+ * Every contribution stores its target's rest value there, whatever its
+ * weight, and the resolve adds the accumulated delta to the rest value:
+ *   V_final = V_rest + sum(w_i * (V_i - V_rest))
+ * Because every clip accumulates a delta from rest, normal blending
+ * (weights summing to 1), fade-to-rest (single clip with weight < 1),
+ * and additive layering (any number of extra clips on top of a base pose)
+ * all use the exact same equation with zero runtime mode flags.
  *
  * `dirty_mask` bit layout:
  *   bits 0–2: translation x/y/z written this frame
@@ -43,10 +48,10 @@
 
 /**
  * u32-stride per pose-accumulator slot. Picked to be a power of two so
- * `row << 4` works as the slot offset. 15 u32s are used, 1 is padding.
+ * `row << 5` works as the slot offset. 21 u32s are used, 11 are padding.
  * @type {number}
  */
-export const POSE_ACCUMULATOR_STRIDE = 16;
+export const POSE_ACCUMULATOR_STRIDE = 32;
 
 /**
  * Byte size of one slot. Convenience for buffer-size math; the GPU
@@ -62,6 +67,8 @@ export const POSE_ACCUMULATOR_OFFSET_ROTATION = 3;
 export const POSE_ACCUMULATOR_OFFSET_SCALE = 7;
 export const POSE_ACCUMULATOR_OFFSET_DIRTY = 10;
 export const POSE_ACCUMULATOR_OFFSET_REST_ROTATION = 11;
+export const POSE_ACCUMULATOR_OFFSET_REST_TRANSLATION = 15;
+export const POSE_ACCUMULATOR_OFFSET_REST_SCALE = 18;
 
 /**
  * Dirty-mask bit layout. Per-axis for T/S, single bit for R.

package/src/shade/renderer/animation/ShadeAnimationClip.d.ts

@@ -1,9 +1,3 @@
-/**
- * @typedef {import("../../../engine/ecs/transform/Transform64.js").Transform64} Transform64
- */
-/**
- * @typedef {import("./ShadeAnimationChannel.js").ShadeAnimationChannel} ShadeAnimationChannel
- */
 /**
  * A bundle of {@link ShadeAnimationChannel}s sharing one playback
  * clock — the GPU-driven equivalent of an animation "clip". Each
@@ -32,6 +26,39 @@ export class ShadeAnimationClip {
         name?: string;
         channels: ShadeAnimationChannel[];
     }): ShadeAnimationClip;
+    /**
+     * Build a rest-anchored additive clip by extracting the motion delta of `source_clip`
+     * relative to `reference_clip` sampled at `reference_time`, rebased onto each target's
+     * rest pose (`rest_of`).
+     *
+     * Because the runtime pose pipeline accumulates rest-anchored deltas
+     * (`V_final = V_rest + sum(w_i * (V_i(t) - V_rest))`), rebasing `source_clip` so that
+     * its delta from `V_rest` equals its authored delta from `V_ref` requires zero runtime
+     * flags or shader branches:
+     *  - Translation: `T_rebased(t) = T_rest + (T_src(t) - T_ref)`
+     *  - Scale:       `S_rebased(t) = S_rest + (S_src(t) - S_ref)`
+     *  - Rotation:    `R_rebased(t) = (R_rest * R_ref^-1) * R_src(t)`, sign-canonicalised
+     *                 against `R_rest` via {@link quat3_canonicalize_sign_run}
+     *
+     * Any per-axis curve or rotation channel whose delta from `V_ref` is constant zero across
+     * the clip is automatically stripped. This means an upper-body gesture exported as a
+     * full-body clip where the lower body stands still at the reference frame automatically
+     * drops all lower-body bindings without needing a bone mask.
+     *
+     * @param {ShadeAnimationClip} source_clip
+     * @param {object} [options]
+     * @param {ShadeAnimationClip} [options.reference_clip=source_clip] clip to sample the reference pose from
+     * @param {number} [options.reference_time] time within `reference_clip` (defaults to `reference_clip.start_time`)
+     * @param {function(number): (Transform64|undefined)} [options.rest_of] target node rest transform lookup
+     * @param {string} [options.name] optional name for the resulting clip
+     * @returns {ShadeAnimationClip}
+     */
+    static from_additive(source_clip: ShadeAnimationClip, { reference_clip, reference_time, rest_of, name, }?: {
+        reference_clip?: ShadeAnimationClip;
+        reference_time?: number;
+        rest_of?: (arg0: number) => (Transform64 | undefined);
+        name?: string;
+    }): ShadeAnimationClip;
     /**
      * Human-readable name. Optional; empty by default.
      *
@@ -134,6 +161,6 @@ export class ShadeAnimationClip {
      */
     readonly isShadeAnimationClip: boolean;
 }
-export type Transform64 = import("../../../engine/ecs/transform/Transform64.js").Transform64;
-export type ShadeAnimationChannel = import("./ShadeAnimationChannel.js").ShadeAnimationChannel;
+import { ShadeAnimationChannel } from "./ShadeAnimationChannel.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 //# sourceMappingURL=ShadeAnimationClip.d.ts.map

package/src/shade/renderer/animation/ShadeAnimationClip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeAnimationClip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ShadeAnimationClip.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA+DI;;;OAGG;IACH,gCAHW;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,qBAAqB,EAAE,CAAA;KAAE,GAClD,kBAAkB,CAU9B;IAzED;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,UAFU,qBAAqB,EAAE,CAEnB;IAEd;;;;;OAKG;IACH,yBAWC;IAED;;;;;OAKG;IACH,uBAWC;IAED;;OAEG;IACH,uBAEC;IAgBD;;;;;;;;;;;;;;OAcG;IACH,YAFW,kBAAkB,QAY5B;IAED;;;;;OAKG;IACH,SAFa,kBAAkB,CAM9B;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAHW,MAAM,uBACG,MAAM,KAAG,WAAW,QAYvC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAHoB,MAAM,KAAG,CAAC,WAAW,GAAC,SAAS,CAAC,QAcnD;IAGL;;;OAGG;IACH,+BAFU,OAAO,CAEgC;CANhD;0BA7MY,OAAO,8CAA8C,EAAE,WAAW;oCAIlE,OAAO,4BAA4B,EAAE,qBAAqB"}
+{"version":3,"file":"ShadeAnimationClip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ShadeAnimationClip.js"],"names":[],"mappings":"AA6TA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA+DI;;;OAGG;IACH,gCAHW;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,qBAAqB,EAAE,CAAA;KAAE,GAClD,kBAAkB,CAU9B;IAyGD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,kCARW,kBAAkB;QAEW,cAAc,GAA3C,kBAAkB;QACD,cAAc,GAA/B,MAAM;QAC8C,OAAO,UAAlD,MAAM,KAAG,CAAC,WAAW,GAAC,SAAS,CAAC;QACxB,IAAI,GAArB,MAAM;QACJ,kBAAkB,CAiG9B;IA5SD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,UAFU,qBAAqB,EAAE,CAEnB;IAEd;;;;;OAKG;IACH,yBAWC;IAED;;;;;OAKG;IACH,uBAWC;IAED;;OAEG;IACH,uBAEC;IAgBD;;;;;;;;;;;;;;OAcG;IACH,YAFW,kBAAkB,QAY5B;IAED;;;;;OAKG;IACH,SAFa,kBAAkB,CAM9B;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAHW,MAAM,uBACG,MAAM,KAAG,WAAW,QAYvC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAHoB,MAAM,KAAG,CAAC,WAAW,GAAC,SAAS,CAAC,QAcnD;IA+HL;;;OAGG;IACH,+BAFU,OAAO,CAEgC;CANhD;sCAxnBqC,4BAA4B;4BAFtC,8CAA8C"}

package/src/shade/renderer/animation/ShadeAnimationClip.js

@@ -1,12 +1,319 @@
 import { assert } from "../../../core/assert.js";
+import { quat3_canonicalize_sign_run } from "../../../core/geom/3d/quaternion/quat3_canonicalize_sign_run.js";
+import { AnimationCurve } from "../../../engine/animation/curve/AnimationCurve.js";
+import { animation_curve_optimize } from "../../../engine/animation/curve/animation_curve_optimize.js";
+import { Keyframe } from "../../../engine/animation/curve/Keyframe.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Node3DProperty } from "../object_property/Node3DProperty.js";
+import { ShadeAnimationChannel } from "./ShadeAnimationChannel.js";
+
+const ADDITIVE_EPSILON = 1e-5;
+const DEFAULT_REST = new Transform64();
 
 /**
- * @typedef {import("../../../engine/ecs/transform/Transform64.js").Transform64} Transform64
+ * @param {AnimationCurve} curve
+ * @param {number} expected_value
+ * @returns {boolean}
+ */
+function is_curve_constant_at(curve, expected_value) {
+    const keys = curve.keys;
+    for (let i = 0; i < keys.length; i++) {
+        const k = keys[i];
+        if (Math.abs(k.value - expected_value) > ADDITIVE_EPSILON) return false;
+        if (Math.abs(k.inTangent) > ADDITIVE_EPSILON) return false;
+        if (Math.abs(k.outTangent) > ADDITIVE_EPSILON) return false;
+    }
+    return true;
+}
+
+/**
+ * Clone a scalar curve and shift every keyframe's value by `offset`.
+ * Returns `undefined` when the resulting curve is constant at `rest_value`.
+ *
+ * @param {AnimationCurve|undefined} curve
+ * @param {number} offset
+ * @param {number} rest_value
+ * @returns {AnimationCurve|undefined}
  */
+function rebase_scalar_curve(curve, offset, rest_value) {
+    if (curve === undefined) {
+        return undefined;
+    }
+
+    const rebased = curve.clone();
+    if (offset !== 0) {
+        const keys = rebased.keys;
+        for (let i = 0; i < keys.length; i++) {
+            keys[i].value += offset;
+        }
+    }
+
+    if (is_curve_constant_at(rebased, rest_value)) {
+        return undefined;
+    }
+
+    animation_curve_optimize(rebased);
+    return rebased;
+}
+
+/**
+ * Collect sorted unique keyframe timestamps across a rotation channel's curves,
+ * and check whether all four curves are present with identical timestamps.
+ *
+ * @param {import("./ShadeAnimationChannel.js").ChannelCurves} curves
+ * @returns {{ aligned: boolean, times: number[] }}
+ */
+function collect_rotation_times(curves) {
+    const present = [];
+    if (curves.x !== undefined) present.push(curves.x);
+    if (curves.y !== undefined) present.push(curves.y);
+    if (curves.z !== undefined) present.push(curves.z);
+    if (curves.w !== undefined) present.push(curves.w);
+
+    if (present.length === 0) {
+        return { aligned: true, times: [] };
+    }
+
+    const first_keys = present[0].keys;
+    const n = first_keys.length;
+    let aligned = true;
+    for (let c = 1; c < present.length; c++) {
+        if (present[c].keys.length !== n) {
+            aligned = false;
+            break;
+        }
+    }
+
+    if (aligned) {
+        const times = new Array(n);
+        for (let i = 0; i < n; i++) {
+            const t = first_keys[i].time;
+            for (let c = 1; c < present.length; c++) {
+                if (present[c].keys[i].time !== t) {
+                    aligned = false;
+                    break;
+                }
+            }
+            if (!aligned) break;
+            times[i] = t;
+        }
+        if (aligned) {
+            return { aligned: true, times };
+        }
+    }
+
+    const time_set = new Set();
+    for (let c = 0; c < present.length; c++) {
+        const keys = present[c].keys;
+        for (let i = 0; i < keys.length; i++) {
+            time_set.add(keys[i].time);
+        }
+    }
+
+    const times = Array.from(time_set);
+    times.sort((a, b) => a - b);
+    return { aligned: false, times };
+}
 
 /**
- * @typedef {import("./ShadeAnimationChannel.js").ShadeAnimationChannel} ShadeAnimationChannel
+ * Hamilton product `q * v` written into `out` at `offset`.
+ *
+ * @param {Float64Array} out
+ * @param {number} offset
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ * @param {number} vw
  */
+function quat_mul_into(out, offset, qx, qy, qz, qw, vx, vy, vz, vw) {
+    out[offset + 0] = qw * vx + qx * vw + qy * vz - qz * vy;
+    out[offset + 1] = qw * vy - qx * vz + qy * vw + qz * vx;
+    out[offset + 2] = qw * vz + qx * vy - qy * vx + qz * vw;
+    out[offset + 3] = qw * vw - qx * vx - qy * vy - qz * vz;
+}
+
+/**
+ * Rebase a rotation channel from its reference orientation `ref_pose` onto `rest`.
+ * Returns `undefined` when the rebased rotation is constant at `rest`.
+ *
+ * @param {ShadeAnimationChannel} channel
+ * @param {Transform64} ref_pose
+ * @param {Transform64} rest
+ * @returns {ShadeAnimationChannel|undefined}
+ */
+function rebase_rotation_channel(channel, ref_pose, rest) {
+    const curves = channel.curves;
+    const { aligned, times } = collect_rotation_times(curves);
+    const key_count = times.length;
+    if (key_count === 0) {
+        return undefined;
+    }
+
+    const rest_rx = rest.rotation_x;
+    const rest_ry = rest.rotation_y;
+    const rest_rz = rest.rotation_z;
+    const rest_rw = rest.rotation_w;
+
+    const ref_rx = ref_pose.rotation_x;
+    const ref_ry = ref_pose.rotation_y;
+    const ref_rz = ref_pose.rotation_z;
+    const ref_rw = ref_pose.rotation_w;
+
+    // Q_shift = R_rest * (R_ref)^-1, where (R_ref)^-1 = (-ref_rx, -ref_ry, -ref_rz, ref_rw).
+    // Left-multiplying R_src(t) = R_ref * delta_R(t) by Q_shift yields R_rest * delta_R(t).
+    let sx = rest_rw * (-ref_rx) + rest_rx * ref_rw + rest_ry * (-ref_rz) - rest_rz * (-ref_ry);
+    let sy = rest_rw * (-ref_ry) - rest_rx * (-ref_rz) + rest_ry * ref_rw + rest_rz * (-ref_rx);
+    let sz = rest_rw * (-ref_rz) + rest_rx * (-ref_ry) - rest_ry * (-ref_rx) + rest_rz * ref_rw;
+    let sw = rest_rw * ref_rw - rest_rx * (-ref_rx) - rest_ry * (-ref_ry) - rest_rz * (-ref_rz);
+    const s_len = Math.hypot(sx, sy, sz, sw);
+    if (s_len > 0) {
+        sx /= s_len;
+        sy /= s_len;
+        sz /= s_len;
+        sw /= s_len;
+    } else {
+        sx = 0;
+        sy = 0;
+        sz = 0;
+        sw = 1;
+    }
+
+    // Each keyframe block holds 12 floats: [inTangent(4), value(4), outTangent(4)].
+    const blocks = new Float64Array(key_count * 12);
+
+    if (aligned) {
+        const kx = curves.x !== undefined ? curves.x.keys : undefined;
+        const ky = curves.y !== undefined ? curves.y.keys : undefined;
+        const kz = curves.z !== undefined ? curves.z.keys : undefined;
+        const kw = curves.w !== undefined ? curves.w.keys : undefined;
+
+        for (let k = 0; k < key_count; k++) {
+            const base = k * 12;
+            const ix = kx !== undefined ? kx[k].inTangent : 0;
+            const iy = ky !== undefined ? ky[k].inTangent : 0;
+            const iz = kz !== undefined ? kz[k].inTangent : 0;
+            const iw = kw !== undefined ? kw[k].inTangent : 0;
+
+            const vx = kx !== undefined ? kx[k].value : 0;
+            const vy = ky !== undefined ? ky[k].value : 0;
+            const vz = kz !== undefined ? kz[k].value : 0;
+            const vw = kw !== undefined ? kw[k].value : 1;
+
+            const ox = kx !== undefined ? kx[k].outTangent : 0;
+            const oy = ky !== undefined ? ky[k].outTangent : 0;
+            const oz = kz !== undefined ? kz[k].outTangent : 0;
+            const ow = kw !== undefined ? kw[k].outTangent : 0;
+
+            quat_mul_into(blocks, base + 0, sx, sy, sz, sw, ix, iy, iz, iw);
+            quat_mul_into(blocks, base + 4, sx, sy, sz, sw, vx, vy, vz, vw);
+            quat_mul_into(blocks, base + 8, sx, sy, sz, sw, ox, oy, oz, ow);
+
+            const v_len = Math.hypot(blocks[base + 4], blocks[base + 5], blocks[base + 6], blocks[base + 7]);
+            if (v_len > 0 && Math.abs(v_len - 1) > 1e-6) {
+                const inv = 1 / v_len;
+                for (let j = 0; j < 12; j++) {
+                    blocks[base + j] *= inv;
+                }
+            }
+        }
+    } else {
+        const cx = curves.x;
+        const cy = curves.y;
+        const cz = curves.z;
+        const cw = curves.w;
+
+        for (let k = 0; k < key_count; k++) {
+            const t = times[k];
+            const base = k * 12;
+            const vx = cx !== undefined ? cx.evaluate(t) : 0;
+            const vy = cy !== undefined ? cy.evaluate(t) : 0;
+            const vz = cz !== undefined ? cz.evaluate(t) : 0;
+            const vw = cw !== undefined ? cw.evaluate(t) : 1;
+
+            quat_mul_into(blocks, base + 4, sx, sy, sz, sw, vx, vy, vz, vw);
+            const v_len = Math.hypot(blocks[base + 4], blocks[base + 5], blocks[base + 6], blocks[base + 7]);
+            if (v_len > 0) {
+                const inv = 1 / v_len;
+                blocks[base + 4] *= inv;
+                blocks[base + 5] *= inv;
+                blocks[base + 6] *= inv;
+                blocks[base + 7] *= inv;
+            }
+        }
+    }
+
+    quat3_canonicalize_sign_run(blocks, key_count, 12, 4, {
+        x: rest_rx,
+        y: rest_ry,
+        z: rest_rz,
+        w: rest_rw,
+    });
+
+    let is_constant_rest = true;
+    for (let k = 0; k < key_count; k++) {
+        const base = k * 12;
+        if (
+            Math.abs(blocks[base + 4] - rest_rx) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 5] - rest_ry) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 6] - rest_rz) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 7] - rest_rw) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 0]) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 1]) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 2]) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 3]) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 8]) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 9]) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 10]) > ADDITIVE_EPSILON ||
+            Math.abs(blocks[base + 11]) > ADDITIVE_EPSILON
+        ) {
+            is_constant_rest = false;
+            break;
+        }
+    }
+
+    if (is_constant_rest) {
+        return undefined;
+    }
+
+    const keys_x = new Array(key_count);
+    const keys_y = new Array(key_count);
+    const keys_z = new Array(key_count);
+    const keys_w = new Array(key_count);
+
+    for (let k = 0; k < key_count; k++) {
+        const t = times[k];
+        const base = k * 12;
+        keys_x[k] = Keyframe.from(t, blocks[base + 4], blocks[base + 0], blocks[base + 8]);
+        keys_y[k] = Keyframe.from(t, blocks[base + 5], blocks[base + 1], blocks[base + 9]);
+        keys_z[k] = Keyframe.from(t, blocks[base + 6], blocks[base + 2], blocks[base + 10]);
+        keys_w[k] = Keyframe.from(t, blocks[base + 7], blocks[base + 3], blocks[base + 11]);
+    }
+
+    const rx_curve = AnimationCurve.from(keys_x);
+    const ry_curve = AnimationCurve.from(keys_y);
+    const rz_curve = AnimationCurve.from(keys_z);
+    const rw_curve = AnimationCurve.from(keys_w);
+
+    animation_curve_optimize(rx_curve);
+    animation_curve_optimize(ry_curve);
+    animation_curve_optimize(rz_curve);
+    animation_curve_optimize(rw_curve);
+
+    return ShadeAnimationChannel.from({
+        target: channel.target,
+        property: Node3DProperty.Rotation,
+        curves: {
+            x: rx_curve,
+            y: ry_curve,
+            z: rz_curve,
+            w: rw_curve,
+        },
+    });
+}
 
 /**
  * A bundle of {@link ShadeAnimationChannel}s sharing one playback
@@ -206,6 +513,130 @@ export class ShadeAnimationClip {
         }
         this.channels = kept;
     }
+
+    /**
+     * Build a rest-anchored additive clip by extracting the motion delta of `source_clip`
+     * relative to `reference_clip` sampled at `reference_time`, rebased onto each target's
+     * rest pose (`rest_of`).
+     *
+     * Because the runtime pose pipeline accumulates rest-anchored deltas
+     * (`V_final = V_rest + sum(w_i * (V_i(t) - V_rest))`), rebasing `source_clip` so that
+     * its delta from `V_rest` equals its authored delta from `V_ref` requires zero runtime
+     * flags or shader branches:
+     *  - Translation: `T_rebased(t) = T_rest + (T_src(t) - T_ref)`
+     *  - Scale:       `S_rebased(t) = S_rest + (S_src(t) - S_ref)`
+     *  - Rotation:    `R_rebased(t) = (R_rest * R_ref^-1) * R_src(t)`, sign-canonicalised
+     *                 against `R_rest` via {@link quat3_canonicalize_sign_run}
+     *
+     * Any per-axis curve or rotation channel whose delta from `V_ref` is constant zero across
+     * the clip is automatically stripped. This means an upper-body gesture exported as a
+     * full-body clip where the lower body stands still at the reference frame automatically
+     * drops all lower-body bindings without needing a bone mask.
+     *
+     * @param {ShadeAnimationClip} source_clip
+     * @param {object} [options]
+     * @param {ShadeAnimationClip} [options.reference_clip=source_clip] clip to sample the reference pose from
+     * @param {number} [options.reference_time] time within `reference_clip` (defaults to `reference_clip.start_time`)
+     * @param {function(number): (Transform64|undefined)} [options.rest_of] target node rest transform lookup
+     * @param {string} [options.name] optional name for the resulting clip
+     * @returns {ShadeAnimationClip}
+     */
+    static from_additive(
+        source_clip,
+        {
+            reference_clip = source_clip,
+            reference_time,
+            rest_of,
+            name,
+        } = {}
+    ) {
+        assert.defined(source_clip, 'source_clip');
+        assert.equal(source_clip.isShadeAnimationClip, true, 'source_clip.isShadeAnimationClip !== true');
+        assert.defined(reference_clip, 'reference_clip');
+        assert.equal(reference_clip.isShadeAnimationClip, true, 'reference_clip.isShadeAnimationClip !== true');
+
+        const ref_time = reference_time !== undefined ? reference_time : reference_clip.start_time;
+
+        /** @type {Map<number, { rest: Transform64, ref: Transform64 }>} */
+        const poses_by_target = new Map();
+
+        const src_channels = source_clip.channels;
+        for (let i = 0; i < src_channels.length; i++) {
+            const target = src_channels[i].target;
+            if (!poses_by_target.has(target)) {
+                const rest = (rest_of !== undefined ? rest_of(target) : undefined) ?? DEFAULT_REST;
+                const ref = new Transform64();
+                ref.copy(rest);
+                poses_by_target.set(target, { rest, ref });
+            }
+        }
+
+        const ref_channels = reference_clip.channels;
+        for (let i = 0; i < ref_channels.length; i++) {
+            const ref_ch = ref_channels[i];
+            const entry = poses_by_target.get(ref_ch.target);
+            if (entry !== undefined) {
+                ref_ch.apply(ref_time, entry.ref);
+            }
+        }
+
+        const out_channels = [];
+
+        for (let i = 0; i < src_channels.length; i++) {
+            const ch = src_channels[i];
+            const { rest, ref } = poses_by_target.get(ch.target);
+
+            switch (ch.property) {
+                case Node3DProperty.Translation: {
+                    const curves = ch.curves;
+                    const x = rebase_scalar_curve(curves.x, rest.translation_x - ref.translation_x, rest.translation_x);
+                    const y = rebase_scalar_curve(curves.y, rest.translation_y - ref.translation_y, rest.translation_y);
+                    const z = rebase_scalar_curve(curves.z, rest.translation_z - ref.translation_z, rest.translation_z);
+
+                    if (x !== undefined || y !== undefined || z !== undefined) {
+                        out_channels.push(ShadeAnimationChannel.from({
+                            target: ch.target,
+                            property: Node3DProperty.Translation,
+                            curves: { x, y, z },
+                        }));
+                    }
+                    break;
+                }
+
+                case Node3DProperty.Scale: {
+                    const curves = ch.curves;
+                    const x = rebase_scalar_curve(curves.x, rest.scale_x - ref.scale_x, rest.scale_x);
+                    const y = rebase_scalar_curve(curves.y, rest.scale_y - ref.scale_y, rest.scale_y);
+                    const z = rebase_scalar_curve(curves.z, rest.scale_z - ref.scale_z, rest.scale_z);
+
+                    if (x !== undefined || y !== undefined || z !== undefined) {
+                        out_channels.push(ShadeAnimationChannel.from({
+                            target: ch.target,
+                            property: Node3DProperty.Scale,
+                            curves: { x, y, z },
+                        }));
+                    }
+                    break;
+                }
+
+                case Node3DProperty.Rotation: {
+                    const rebased_rot = rebase_rotation_channel(ch, ref, rest);
+                    if (rebased_rot !== undefined) {
+                        out_channels.push(rebased_rot);
+                    }
+                    break;
+                }
+
+                default:
+                    break;
+            }
+        }
+
+        const result = new ShadeAnimationClip();
+        result.name = name !== undefined ? name : `${source_clip.name}_additive`;
+        result.channels = out_channels;
+        return result;
+    }
 }
 
 /**

package/src/shade/renderer/animation/chunk_pose_accumulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_pose_accumulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_pose_accumulator.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,SAAS,CAwGgB;0BAzIT,iCAAiC"}
+{"version":3,"file":"chunk_pose_accumulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_pose_accumulator.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,SAAS,CA8GgB;0BAjJT,iCAAiC"}