@aura3d/engine 3.0.0 → 4.0.0

package/dist/animation/SpringBones.js

@@ -22,91 +22,268 @@ export function createSpringChain(options) {
     const gravity = options.gravity ?? [0, -9.81, 0];
     const colliders = options.colliders ?? [];
     const substeps = Math.max(1, Math.floor(options.substeps ?? 2));
+    const relativeDamping = Math.max(0, options.relativeDamping ?? 0);
     const name = options.name ?? "spring-chain";
     // Rest offset of each particle relative to its parent, in the root's initial frame.
-    const restOffsets = options.bones.map((bone, i) => i === 0 ? [0, 0, 0] : sub(bone, options.bones[i - 1]));
-    const restLengths = restOffsets.map((o) => len(o));
-    const positions = options.bones.map((b) => [...b]);
-    const velocities = options.bones.map(() => [0, 0, 0]);
+    const restOffsets = new Float32Array(options.bones.length * 3);
+    for (let i = 0; i < options.bones.length; i += 1) {
+        const bone = options.bones[i];
+        restOffsets[i * 3] = i === 0 ? 0 : bone[0] - options.bones[i - 1][0];
+        restOffsets[i * 3 + 1] = i === 0 ? 0 : bone[1] - options.bones[i - 1][1];
+        restOffsets[i * 3 + 2] = i === 0 ? 0 : bone[2] - options.bones[i - 1][2];
+    }
+    const restLengths = new Float32Array(options.bones.length);
+    for (let i = 0; i < options.bones.length; i += 1) {
+        restLengths[i] = Math.hypot(restOffsets[i * 3], restOffsets[i * 3 + 1], restOffsets[i * 3 + 2]);
+    }
+    // §13 — flat particle state so `step` performs scalar math with no per-call
+    // allocation (the Vec3-of-arrays version measured ~5× over the spring
+    // micro-budget).
+    const count = options.bones.length;
+    const positions = new Float32Array(count * 3);
+    const velocities = new Float32Array(count * 3);
+    for (let i = 0; i < count; i += 1) {
+        const bone = options.bones[i];
+        positions[i * 3] = bone[0];
+        positions[i * 3 + 1] = bone[1];
+        positions[i * 3 + 2] = bone[2];
+    }
     let contacts = 0;
-    function rotatedRestOffset(i, rotation) {
-        return rotation ? rotateVec3(restOffsets[i], rotation) : restOffsets[i];
+    const anchorSpace = options.space === "anchor";
+    // Anchor rotation at the previous step (anchor space only).
+    const prevAnchorRot = new Float64Array([0, 0, 0, 1]);
+    /**
+     * Anchor space: carry every simulated particle and its velocity rigidly
+     * with the root's motion since the last step (translation + delta
+     * rotation about the root), before the spring/gravity update.
+     */
+    function transportWithAnchor(root) {
+        const q = root.rotation;
+        let dx = 0, dy = 0, dz = 0, dw = 1;
+        {
+            const qx = q?.[0] ?? 0, qy = q?.[1] ?? 0, qz = q?.[2] ?? 0, qw = q?.[3] ?? 1;
+            // dq = q * conj(prev)
+            const bx = -prevAnchorRot[0], by = -prevAnchorRot[1], bz = -prevAnchorRot[2], bw = prevAnchorRot[3];
+            dx = qx * bw + qw * bx + qy * bz - qz * by;
+            dy = qy * bw + qw * by + qz * bx - qx * bz;
+            dz = qz * bw + qw * bz + qx * by - qy * bx;
+            dw = qw * bw - qx * bx - qy * by - qz * bz;
+        }
+        const ox = positions[0], oy = positions[1], oz = positions[2];
+        const rx = root.position[0], ry = root.position[1], rz = root.position[2];
+        for (let i = 1; i < count; i += 1) {
+            const ci = i * 3;
+            // Scalar quaternion rotation keeps the hot transport path allocation-free.
+            const px = positions[ci] - ox, py = positions[ci + 1] - oy, pz = positions[ci + 2] - oz;
+            const tx = 2 * (dy * pz - dz * py), ty = 2 * (dz * px - dx * pz), tz = 2 * (dx * py - dy * px);
+            positions[ci] = rx + px + dw * tx + dy * tz - dz * ty;
+            positions[ci + 1] = ry + py + dw * ty + dz * tx - dx * tz;
+            positions[ci + 2] = rz + pz + dw * tz + dx * ty - dy * tx;
+            const vx = velocities[ci], vy = velocities[ci + 1], vz = velocities[ci + 2];
+            const ux = 2 * (dy * vz - dz * vy), uy = 2 * (dz * vx - dx * vz), uz = 2 * (dx * vy - dy * vx);
+            velocities[ci] = vx + dw * ux + dy * uz - dz * uy;
+            velocities[ci + 1] = vy + dw * uy + dz * ux - dx * uz;
+            velocities[ci + 2] = vz + dw * uz + dx * uy - dy * ux;
+        }
+        prevAnchorRot[0] = q?.[0] ?? 0;
+        prevAnchorRot[1] = q?.[1] ?? 0;
+        prevAnchorRot[2] = q?.[2] ?? 0;
+        prevAnchorRot[3] = q?.[3] ?? 1;
     }
     function step(dt, root) {
         contacts = 0;
-        // Root particle is kinematic.
-        positions[0] = [...root.position];
-        velocities[0] = [0, 0, 0];
-        for (let i = 1; i < positions.length; i += 1) {
-            const parent = positions[i - 1];
-            const rest = add(parent, rotatedRestOffset(i, root.rotation));
-            const p = positions[i];
-            const v = velocities[i];
+        const q = root.rotation;
+        const offs = root.offsets;
+        if (anchorSpace)
+            transportWithAnchor(root);
+        // Root particle is kinematic (zero velocity: in anchor space it is the
+        // frame origin; in model space this is the legacy behaviour).
+        velocities[0] = 0;
+        velocities[1] = 0;
+        velocities[2] = 0;
+        positions[0] = root.position[0];
+        positions[1] = root.position[1];
+        positions[2] = root.position[2];
+        for (let i = 1; i < count; i += 1) {
+            const pi = (i - 1) * 3;
+            const ci = i * 3;
+            // Rest target = parent position + rest offset: the animated offset
+            // when supplied, else the bind offset rotated into the root frame.
+            let ox, oy, oz;
+            if (offs !== undefined) {
+                ox = offs[ci];
+                oy = offs[ci + 1];
+                oz = offs[ci + 2];
+            }
+            else {
+                ox = restOffsets[ci];
+                oy = restOffsets[ci + 1];
+                oz = restOffsets[ci + 2];
+                if (q !== undefined) {
+                    const ix = q[3] * ox + q[1] * oz - q[2] * oy;
+                    const iy = q[3] * oy + q[2] * ox - q[0] * oz;
+                    const iz = q[3] * oz + q[0] * oy - q[1] * ox;
+                    const iw = -q[0] * ox - q[1] * oy - q[2] * oz;
+                    ox = ix * q[3] + iw * -q[0] + iy * -q[2] - iz * -q[1];
+                    oy = iy * q[3] + iw * -q[1] + iz * -q[0] - ix * -q[2];
+                    oz = iz * q[3] + iw * -q[2] + ix * -q[1] - iy * -q[0];
+                }
+            }
+            const restLength = offs !== undefined ? Math.hypot(ox, oy, oz) : restLengths[i];
+            const rx = positions[pi] + ox;
+            const ry = positions[pi + 1] + oy;
+            const rz = positions[pi + 2] + oz;
+            const px = positions[ci], py = positions[ci + 1], pz = positions[ci + 2];
+            const vx = velocities[ci], vy = velocities[ci + 1], vz = velocities[ci + 2];
             // a = stiffness*(rest - p) + gravity - damping*v  (semi-implicit: update v, then p)
-            const ax = stiffness * (rest[0] - p[0]) + gravity[0] - damping * v[0];
-            const ay = stiffness * (rest[1] - p[1]) + gravity[1] - damping * v[1];
-            const az = stiffness * (rest[2] - p[2]) + gravity[2] - damping * v[2];
-            const nv = [v[0] + ax * dt, v[1] + ay * dt, v[2] + az * dt];
-            let np = [p[0] + nv[0] * dt, p[1] + nv[1] * dt, p[2] + nv[2] * dt];
+            const ax = stiffness * (rx - px) + gravity[0] - damping * vx;
+            const ay = stiffness * (ry - py) + gravity[1] - damping * vy;
+            const az = stiffness * (rz - pz) + gravity[2] - damping * vz;
+            let nvx = vx + ax * dt;
+            let nvy = vy + ay * dt;
+            let nvz = vz + az * dt;
+            let npx = px + nvx * dt;
+            let npy = py + nvy * dt;
+            let npz = pz + nvz * dt;
             // Distance constraint: keep the bone length to the parent.
-            np = enforceLength(parent, np, restLengths[i]);
-            // Collider push-out.
+            {
+                const dx = npx - positions[pi], dy = npy - positions[pi + 1], dz = npz - positions[pi + 2];
+                const l = Math.hypot(dx, dy, dz);
+                if (l <= 1e-8) {
+                    npx = positions[pi];
+                    npy = positions[pi + 1] + restLength;
+                    npz = positions[pi + 2];
+                }
+                else {
+                    const s = restLength / l;
+                    npx = positions[pi] + dx * s;
+                    npy = positions[pi + 1] + dy * s;
+                    npz = positions[pi + 2] + dz * s;
+                }
+            }
+            // Collider push-out (scalar form of pushOut/closestPointOnSegment).
             for (const collider of colliders) {
-                const resolved = pushOut(np, collider);
-                if (resolved) {
-                    np = resolved.position;
-                    // Remove the inward velocity component so it doesn't tunnel back in.
-                    const dot = nv[0] * resolved.normal[0] + nv[1] * resolved.normal[1] + nv[2] * resolved.normal[2];
-                    if (dot < 0) {
-                        nv[0] -= dot * resolved.normal[0];
-                        nv[1] -= dot * resolved.normal[1];
-                        nv[2] -= dot * resolved.normal[2];
-                    }
-                    contacts += 1;
+                let cx = collider.center[0], cy = collider.center[1], cz = collider.center[2];
+                if (collider.kind === "capsule" && collider.tail) {
+                    const abx = collider.tail[0] - cx, aby = collider.tail[1] - cy, abz = collider.tail[2] - cz;
+                    const t = clamp(((npx - cx) * abx + (npy - cy) * aby + (npz - cz) * abz) / Math.max(1e-8, abx * abx + aby * aby + abz * abz), 0, 1);
+                    cx += abx * t;
+                    cy += aby * t;
+                    cz += abz * t;
                 }
+                const dx = npx - cx, dy = npy - cy, dz = npz - cz;
+                const l = Math.hypot(dx, dy, dz);
+                if (l >= collider.radius)
+                    continue;
+                const inx = l <= 1e-8 ? 0 : dx / l;
+                const iny = l <= 1e-8 ? 1 : dy / l;
+                const inz = l <= 1e-8 ? 0 : dz / l;
+                npx = cx + inx * collider.radius;
+                npy = cy + iny * collider.radius;
+                npz = cz + inz * collider.radius;
+                // Remove the inward velocity component so it doesn't tunnel back in.
+                const d = nvx * inx + nvy * iny + nvz * inz;
+                if (d < 0) {
+                    nvx -= d * inx;
+                    nvy -= d * iny;
+                    nvz -= d * inz;
+                }
+                contacts += 1;
             }
             // Recompute velocity from the constrained position so energy bookkeeping stays consistent.
-            velocities[i] = [(np[0] - p[0]) / dt, (np[1] - p[1]) / dt, (np[2] - p[2]) / dt];
-            positions[i] = np;
+            let evx = (npx - px) / dt;
+            let evy = (npy - py) / dt;
+            let evz = (npz - pz) / dt;
+            if (relativeDamping > 0) {
+                const keep = Math.exp(-relativeDamping * dt);
+                const pvx = velocities[pi], pvy = velocities[pi + 1], pvz = velocities[pi + 2];
+                evx = pvx + (evx - pvx) * keep;
+                evy = pvy + (evy - pvy) * keep;
+                evz = pvz + (evz - pvz) * keep;
+            }
+            velocities[ci] = evx;
+            velocities[ci + 1] = evy;
+            velocities[ci + 2] = evz;
+            positions[ci] = npx;
+            positions[ci + 1] = npy;
+            positions[ci + 2] = npz;
         }
     }
     return {
         integrate(dt, rootTransform) {
             if (!Number.isFinite(dt) || dt <= 0)
                 throw new Error("Spring chain dt must be finite and positive.");
+            if (rootTransform.offsets !== undefined && rootTransform.offsets.length !== count * 3)
+                throw new Error("Spring chain offsets must contain 3 floats per particle.");
             const sub = dt / substeps;
             for (let s = 0; s < substeps; s += 1)
                 step(sub, rootTransform);
         },
         positions() {
-            return positions.map((p) => [...p]);
+            const out = new Array(count);
+            for (let i = 0; i < count; i += 1) {
+                out[i] = [positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2]];
+            }
+            return out;
+        },
+        positionsFlat(out) {
+            out.set(positions.subarray(0, count * 3));
+            return out;
         },
         telemetry() {
-            const tip = positions[positions.length - 1];
-            const root = positions[0];
+            const ti = (count - 1) * 3;
             let ke = 0;
-            for (const v of velocities)
-                ke += 0.5 * (v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+            for (let i = 0; i < count * 3; i += 1)
+                ke += 0.5 * velocities[i] * velocities[i];
             return {
                 name,
-                boneCount: positions.length,
+                boneCount: count,
                 stiffness,
                 damping,
-                rootPosition: [...root],
-                tipPosition: [...tip],
-                maxDisplacement: dist(root, tip),
+                rootPosition: [positions[0], positions[1], positions[2]],
+                tipPosition: [positions[ti], positions[ti + 1], positions[ti + 2]],
+                maxDisplacement: Math.hypot(positions[ti] - positions[0], positions[ti + 1] - positions[1], positions[ti + 2] - positions[2]),
                 collisionContacts: contacts,
                 kineticEnergy: ke
             };
         },
         reset(rootTransform) {
             const rootPos = rootTransform?.position ?? options.bones[0];
-            const rotation = rootTransform?.rotation;
-            positions[0] = [...rootPos];
-            velocities[0] = [0, 0, 0];
-            for (let i = 1; i < positions.length; i += 1) {
-                positions[i] = add(positions[i - 1], rotatedRestOffset(i, rotation));
-                velocities[i] = [0, 0, 0];
+            const q = rootTransform?.rotation;
+            const offs = rootTransform?.offsets;
+            if (offs !== undefined && offs.length !== count * 3)
+                throw new Error("Spring chain offsets must contain 3 floats per particle.");
+            prevAnchorRot[0] = q?.[0] ?? 0;
+            prevAnchorRot[1] = q?.[1] ?? 0;
+            prevAnchorRot[2] = q?.[2] ?? 0;
+            prevAnchorRot[3] = q?.[3] ?? 1;
+            contacts = 0;
+            positions[0] = rootPos[0];
+            positions[1] = rootPos[1];
+            positions[2] = rootPos[2];
+            velocities.fill(0);
+            for (let i = 1; i < count; i += 1) {
+                const pi = (i - 1) * 3;
+                const ci = i * 3;
+                if (offs !== undefined) {
+                    positions[ci] = positions[pi] + offs[ci];
+                    positions[ci + 1] = positions[pi + 1] + offs[ci + 1];
+                    positions[ci + 2] = positions[pi + 2] + offs[ci + 2];
+                    continue;
+                }
+                let ox = restOffsets[ci], oy = restOffsets[ci + 1], oz = restOffsets[ci + 2];
+                if (q !== undefined) {
+                    const ix = q[3] * ox + q[1] * oz - q[2] * oy;
+                    const iy = q[3] * oy + q[2] * ox - q[0] * oz;
+                    const iz = q[3] * oz + q[0] * oy - q[1] * ox;
+                    const iw = -q[0] * ox - q[1] * oy - q[2] * oz;
+                    ox = ix * q[3] + iw * -q[0] + iy * -q[2] - iz * -q[1];
+                    oy = iy * q[3] + iw * -q[1] + iz * -q[0] - ix * -q[2];
+                    oz = iz * q[3] + iw * -q[2] + ix * -q[1] - iy * -q[0];
+                }
+                positions[ci] = positions[pi] + ox;
+                positions[ci + 1] = positions[pi + 1] + oy;
+                positions[ci + 2] = positions[pi + 2] + oz;
             }
         }
     };
@@ -193,4 +370,371 @@ function rotateVec3(v, q) {
         iz * w + iw * -z + ix * -y - iy * -x
     ];
 }
+function springFkFrame(pose, skeleton, joint) {
+    const rot = [pose.rotations[joint * 4], pose.rotations[joint * 4 + 1], pose.rotations[joint * 4 + 2], pose.rotations[joint * 4 + 3]];
+    const scl = [pose.scales[joint * 3], pose.scales[joint * 3 + 1], pose.scales[joint * 3 + 2]];
+    const pos = [pose.positions[joint * 3], pose.positions[joint * 3 + 1], pose.positions[joint * 3 + 2]];
+    const parent = skeleton.parentIndices[joint] ?? -1;
+    if (parent < 0 || parent >= skeleton.boneCount || parent === joint) {
+        return { position: pos, rotation: rot, scale: scl };
+    }
+    const pf = springFkFrame(pose, skeleton, parent);
+    const scaled = [pos[0] * pf.scale[0], pos[1] * pf.scale[1], pos[2] * pf.scale[2]];
+    const rotated = rotateVec3(scaled, pf.rotation);
+    return {
+        position: [pf.position[0] + rotated[0], pf.position[1] + rotated[1], pf.position[2] + rotated[2]],
+        rotation: multiplyQuat(pf.rotation, rot),
+        scale: [pf.scale[0] * scl[0], pf.scale[1] * scl[1], pf.scale[2] * scl[2]]
+    };
+}
+function multiplyQuat(a, b) {
+    const [ax, ay, az, aw] = a;
+    const [bx, by, bz, bw] = b;
+    return [
+        ax * bw + aw * bx + ay * bz - az * by,
+        ay * bw + aw * by + az * bx - ax * bz,
+        az * bw + aw * bz + ax * by - ay * bx,
+        aw * bw - ax * bx - ay * by - az * bz
+    ];
+}
+function conjugateQuat(q) {
+    return [-q[0], -q[1], -q[2], q[3]];
+}
+function quatFromUnitVectors(from, to) {
+    const d = Math.max(-1, Math.min(1, from[0] * to[0] + from[1] * to[1] + from[2] * to[2]));
+    if (d > 1 - 1e-9)
+        return [0, 0, 0, 1];
+    if (d < -1 + 1e-9) {
+        const axis = Math.abs(from[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0];
+        const c = [
+            from[1] * axis[2] - from[2] * axis[1],
+            from[2] * axis[0] - from[0] * axis[2],
+            from[0] * axis[1] - from[1] * axis[0]
+        ];
+        const l = Math.hypot(c[0], c[1], c[2]) || 1;
+        return [c[0] / l, c[1] / l, c[2] / l, 0];
+    }
+    const c = [
+        from[1] * to[2] - from[2] * to[1],
+        from[2] * to[0] - from[0] * to[2],
+        from[0] * to[1] - from[1] * to[0]
+    ];
+    const w = Math.sqrt((1 + d) / 2);
+    const s = 1 / (2 * w);
+    return [c[0] * s, c[1] * s, c[2] * s, w];
+}
+function normalizeVec3(v) {
+    const l = len(v);
+    return l <= 1e-9 ? [0, 1, 0] : [v[0] / l, v[1] / l, v[2] / l];
+}
+/**
+ * T4.1 (PRD-06 §7.1) — bind a {@link SpringChain} to a skeleton bone chain.
+ * `boneNames` lists the chain root first (the kinematic anchor, driven by
+ * animation) followed by the simulated bones. Unknown names throw — a
+ * misspelled chain is louder than a silently dead spring.
+ *
+ * Per `step`, the kinematic root frame is read from the pose, the fixed-step
+ * accumulator integrates at `substepHz`, and each bone with a simulated child
+ * gets a local rotation aiming its rest child-direction at the simulated
+ * segment direction. Positions stay FK-driven: the sim only bends the chain.
+ */
+export function bindSpringChainToSkeleton(chain, skeleton, boneNames, options) {
+    if (boneNames.length < 2) {
+        throw new Error("SpringBones: a bound chain needs a root plus at least one simulated bone.");
+    }
+    const indices = boneNames.map((name) => {
+        const slots = skeleton.jointIndicesByName.get(name);
+        if (slots === undefined || slots.length === 0) {
+            throw new Error(`SpringBones: unknown bone "${name}".`);
+        }
+        return slots[0];
+    });
+    const substepHz = Math.max(1, options?.substepHz ?? 60);
+    const maxSubsteps = Math.max(1, Math.floor(options?.maxSubsteps ?? 8));
+    const h = 1 / substepHz;
+    let accumulator = 0;
+    let initialized = false;
+    // §13 — flat FK-frame scratch: `springFkFrame` re-walked the ancestor chain
+    // and allocated per call (~allocs × depth × bones per step, ~5× over the
+    // spring micro-budget). Now frames resolve once per step into flat arrays,
+    // memoized by generation mark, and the aim write is pure scalar math.
+    const fPos = new Float32Array(skeleton.boneCount * 3);
+    const fRot = new Float32Array(skeleton.boneCount * 4);
+    const fScl = new Float32Array(skeleton.boneCount * 3);
+    const fMark = new Uint32Array(skeleton.boneCount);
+    const simPos = new Float32Array(indices.length * 3);
+    const rootPosArr = [0, 0, 0];
+    const rootRotArr = [0, 0, 0, 1];
+    // Animated rest targets (this frame and the last integrated frame) and the
+    // per-substep interpolated copies handed to the chain.
+    const curOffsets = new Float32Array(indices.length * 3);
+    const prevOffsets = new Float32Array(indices.length * 3);
+    const subOffsets = new Float32Array(indices.length * 3);
+    const prevRoot = new Float32Array(3);
+    const subRoot = [0, 0, 0];
+    // Aim write bookkeeping (see `restoreUnauthoredAims`).
+    const aimRot = new Float32Array(indices.length * 4);
+    const authoredRot = new Float32Array(indices.length * 4);
+    const aimWritten = new Uint8Array(indices.length);
+    let fGen = 0;
+    /** World-frame of `joint` in `pose`, computed once per generation into the flat scratch. */
+    function frameOf(pose, joint) {
+        if (fMark[joint] === fGen)
+            return;
+        const lp = joint * 3;
+        const lr = joint * 4;
+        const lpx = pose.positions[lp], lpy = pose.positions[lp + 1], lpz = pose.positions[lp + 2];
+        const lrx = pose.rotations[lr], lry = pose.rotations[lr + 1], lrz = pose.rotations[lr + 2], lrw = pose.rotations[lr + 3];
+        const lsx = pose.scales[lp], lsy = pose.scales[lp + 1], lsz = pose.scales[lp + 2];
+        const parent = skeleton.parentIndices[joint] ?? -1;
+        if (parent < 0 || parent >= skeleton.boneCount || parent === joint) {
+            fPos[lp] = lpx;
+            fPos[lp + 1] = lpy;
+            fPos[lp + 2] = lpz;
+            fRot[lr] = lrx;
+            fRot[lr + 1] = lry;
+            fRot[lr + 2] = lrz;
+            fRot[lr + 3] = lrw;
+            fScl[lp] = lsx;
+            fScl[lp + 1] = lsy;
+            fScl[lp + 2] = lsz;
+            fMark[joint] = fGen;
+            return;
+        }
+        frameOf(pose, parent);
+        const pp = parent * 3;
+        const pr = parent * 4;
+        const qx = fRot[pr], qy = fRot[pr + 1], qz = fRot[pr + 2], qw = fRot[pr + 3];
+        // pos = parentPos + rotate(parentRot, localPos * parentScale)
+        const sx = lpx * fScl[pp], sy = lpy * fScl[pp + 1], sz = lpz * fScl[pp + 2];
+        const ix = qw * sx + qy * sz - qz * sy;
+        const iy = qw * sy + qz * sx - qx * sz;
+        const iz = qw * sz + qx * sy - qy * sx;
+        const iw = -qx * sx - qy * sy - qz * sz;
+        fPos[lp] = fPos[pp] + (ix * qw + iw * -qx + iy * -qz - iz * -qy);
+        fPos[lp + 1] = fPos[pp + 1] + (iy * qw + iw * -qy + iz * -qx - ix * -qz);
+        fPos[lp + 2] = fPos[pp + 2] + (iz * qw + iw * -qz + ix * -qy - iy * -qx);
+        // rot = parentRot * localRot
+        fRot[lr] = qx * lrw + qw * lrx + qy * lrz - qz * lry;
+        fRot[lr + 1] = qy * lrw + qw * lry + qz * lrx - qx * lrz;
+        fRot[lr + 2] = qz * lrw + qw * lrz + qx * lry - qy * lrx;
+        fRot[lr + 3] = qw * lrw - qx * lrx - qy * lry - qz * lrz;
+        fScl[lp] = fScl[pp] * lsx;
+        fScl[lp + 1] = fScl[pp + 1] * lsy;
+        fScl[lp + 2] = fScl[pp + 2] * lsz;
+        fMark[joint] = fGen;
+    }
+    // Rest child-direction per bone expressed in its own frame. Derived from the
+    // bind-time (rest) pose so the aim write preserves the authored chain shape
+    // and only bends it toward the simulated segment.
+    const restFrames = indices.map((joint) => springFkFrame(skeleton.restPose, skeleton, joint));
+    const childDirLocal = indices.map((joint, i) => {
+        if (i + 1 >= indices.length)
+            return [0, 0, 0];
+        const restDir = normalizeVec3([
+            restFrames[i + 1].position[0] - restFrames[i].position[0],
+            restFrames[i + 1].position[1] - restFrames[i].position[1],
+            restFrames[i + 1].position[2] - restFrames[i].position[2]
+        ]);
+        return normalizeVec3(rotateVec3(restDir, conjugateQuat(restFrames[i].rotation)));
+    });
+    function initialize(pose) {
+        fGen += 1;
+        restoreUnauthoredAims(pose);
+        readAnimatedTargets(pose);
+        chain.reset({ position: rootPosArr, rotation: rootRotArr, offsets: curOffsets });
+        prevRoot.set(rootPosArr);
+        prevOffsets.set(curOffsets);
+        aimWritten.fill(0);
+        accumulator = 0;
+        initialized = true;
+    }
+    /**
+     * The aim write below edits `pose.rotations` in place. A host that mixes a
+     * fresh pose every frame overwrites it; one that re-steps the same buffer
+     * would otherwise feed the aimed rotation back in as the "animated" target
+     * (the spring would chase itself). An aimed joint whose rotation is still
+     * bit-identical to the value written is restored to the authored rotation.
+     */
+    function restoreUnauthoredAims(pose) {
+        for (let i = 1; i + 1 < indices.length; i += 1) {
+            if (aimWritten[i] === 0)
+                continue;
+            const jr = indices[i] * 4;
+            const ar = i * 4;
+            if (pose.rotations[jr] === aimRot[ar] && pose.rotations[jr + 1] === aimRot[ar + 1] &&
+                pose.rotations[jr + 2] === aimRot[ar + 2] && pose.rotations[jr + 3] === aimRot[ar + 3]) {
+                pose.rotations[jr] = authoredRot[ar];
+                pose.rotations[jr + 1] = authoredRot[ar + 1];
+                pose.rotations[jr + 2] = authoredRot[ar + 2];
+                pose.rotations[jr + 3] = authoredRot[ar + 3];
+            }
+        }
+    }
+    /**
+     * Animated (pre-aim) chain frame: root world position/rotation and each
+     * particle's FK offset from its parent. These are the spring's rest
+     * targets, so the chain settles onto the *animated* pose — a clip that
+     * re-poses the chain (a crouch, a landing) moves the target with it instead
+     * of leaving the particles springing toward bind-pose offsets.
+     */
+    function readAnimatedTargets(pose) {
+        for (let i = 0; i < indices.length; i += 1)
+            frameOf(pose, indices[i]);
+        const ri = indices[0];
+        rootPosArr[0] = fPos[ri * 3];
+        rootPosArr[1] = fPos[ri * 3 + 1];
+        rootPosArr[2] = fPos[ri * 3 + 2];
+        rootRotArr[0] = fRot[ri * 4];
+        rootRotArr[1] = fRot[ri * 4 + 1];
+        rootRotArr[2] = fRot[ri * 4 + 2];
+        rootRotArr[3] = fRot[ri * 4 + 3];
+        for (let i = 1; i < indices.length; i += 1) {
+            const a = indices[i - 1] * 3;
+            const b = indices[i] * 3;
+            curOffsets[i * 3] = fPos[b] - fPos[a];
+            curOffsets[i * 3 + 1] = fPos[b + 1] - fPos[a + 1];
+            curOffsets[i * 3 + 2] = fPos[b + 2] - fPos[a + 2];
+        }
+    }
+    function step(pose, dt) {
+        if (!Number.isFinite(dt) || dt < 0) {
+            throw new Error("SpringBones: step dt must be finite and non-negative.");
+        }
+        if (!initialized)
+            initialize(pose);
+        fGen += 1;
+        restoreUnauthoredAims(pose);
+        accumulator = Math.min(accumulator + dt, 0.25);
+        const substeps = Math.min(Math.floor(accumulator / h), maxSubsteps);
+        if (substeps > 0) {
+            readAnimatedTargets(pose);
+            // The animated pose only advances once per host frame; spread that
+            // motion across this call's substeps (linear in position/offset)
+            // instead of teleporting the anchor on the first substep. A teleport
+            // makes the length constraint convert a whole frame's anchor travel
+            // into one substep's velocity — ~substeps× the real anchor speed —
+            // which flings the chain on every fast anchor move (the landing).
+            for (let k = 0; k < substeps; k += 1) {
+                const u = (k + 1) / substeps;
+                subRoot[0] = prevRoot[0] + (rootPosArr[0] - prevRoot[0]) * u;
+                subRoot[1] = prevRoot[1] + (rootPosArr[1] - prevRoot[1]) * u;
+                subRoot[2] = prevRoot[2] + (rootPosArr[2] - prevRoot[2]) * u;
+                for (let c = 3; c < subOffsets.length; c += 1) {
+                    subOffsets[c] = prevOffsets[c] + (curOffsets[c] - prevOffsets[c]) * u;
+                }
+                chain.integrate(h, { position: subRoot, rotation: rootRotArr, offsets: subOffsets });
+            }
+            prevRoot.set(rootPosArr);
+            prevOffsets.set(curOffsets);
+            accumulator -= substeps * h;
+        }
+        chain.positionsFlat(simPos);
+        // Animated-target FK frames predate the aim writes. Recompute the parent
+        // chain lazily as each newly aimed rotation becomes a descendant's parent.
+        fGen += 1;
+        // Aim bones[1..n-2]: each simulated bone that has a simulated child. The
+        // chain root stays purely kinematic — writing its rotation would feed the
+        // aim back into the next frame's root frame and the rest target would
+        // chase itself; the tip has no child to aim at.
+        for (let i = 1; i + 1 < indices.length; i += 1) {
+            const joint = indices[i];
+            const si = i * 3;
+            const sdx = simPos[si + 3] - simPos[si];
+            const sdy = simPos[si + 4] - simPos[si + 1];
+            const sdz = simPos[si + 5] - simPos[si + 2];
+            const sl = Math.hypot(sdx, sdy, sdz);
+            if (sl <= 1e-9)
+                continue;
+            const ndx = sdx / sl, ndy = sdy / sl, ndz = sdz / sl;
+            const parent = skeleton.parentIndices[joint] ?? -1;
+            let prx = 0, pry = 0, prz = 0, prw = 1;
+            if (parent >= 0 && parent < skeleton.boneCount) {
+                frameOf(pose, parent);
+                const pr = parent * 4;
+                prx = fRot[pr];
+                pry = fRot[pr + 1];
+                prz = fRot[pr + 2];
+                prw = fRot[pr + 3];
+            }
+            const jr = joint * 4;
+            const lrx = pose.rotations[jr], lry = pose.rotations[jr + 1], lrz = pose.rotations[jr + 2], lrw = pose.rotations[jr + 3];
+            // worldRot = parentRot * localRot
+            const wx = prx * lrw + prw * lrx + pry * lrz - prz * lry;
+            const wy = pry * lrw + prw * lry + prz * lrx - prx * lrz;
+            const wz = prz * lrw + prw * lrz + prx * lry - pry * lrx;
+            const ww = prw * lrw - prx * lrx - pry * lry - prz * lrz;
+            // currentDir = normalize(rotate(childDirLocal[i], worldRot))
+            const cv = childDirLocal[i];
+            const cix = ww * cv[0] + wy * cv[2] - wz * cv[1];
+            const ciy = ww * cv[1] + wz * cv[0] - wx * cv[2];
+            const ciz = ww * cv[2] + wx * cv[1] - wy * cv[0];
+            const ciw = -wx * cv[0] - wy * cv[1] - wz * cv[2];
+            let cdx = cix * ww + ciw * -wx + ciy * -wz - ciz * -wy;
+            let cdy = ciy * ww + ciw * -wy + ciz * -wx - cix * -wz;
+            let cdz = ciz * ww + ciw * -wz + cix * -wy - ciy * -wx;
+            const cl = Math.hypot(cdx, cdy, cdz);
+            if (cl <= 1e-9) {
+                cdx = 0;
+                cdy = 1;
+                cdz = 0;
+            }
+            else {
+                cdx /= cl;
+                cdy /= cl;
+                cdz /= cl;
+            }
+            // aim = quatFromUnitVectors(currentDir, simDir)
+            let ax = 0, ay = 0, az = 0, aw = 1;
+            const d = Math.max(-1, Math.min(1, cdx * ndx + cdy * ndy + cdz * ndz));
+            if (d > 1 - 1e-9) {
+                // aim stays identity
+            }
+            else if (d < -1 + 1e-9) {
+                const ux = Math.abs(cdx) < 0.9 ? 1 : 0;
+                const uy = Math.abs(cdx) < 0.9 ? 0 : 1;
+                let cxx = cdy * 0 - cdz * uy;
+                let cyy = cdz * ux - cdx * 0;
+                let czz = cdx * uy - cdy * ux;
+                const ul = Math.hypot(cxx, cyy, czz) || 1;
+                ax = cxx / ul;
+                ay = cyy / ul;
+                az = czz / ul;
+                aw = 0;
+            }
+            else {
+                const cx = cdy * ndz - cdz * ndy;
+                const cy = cdz * ndx - cdx * ndz;
+                const cz = cdx * ndy - cdy * ndx;
+                const hw = Math.sqrt((1 + d) / 2);
+                const s = 1 / (2 * hw);
+                ax = cx * s;
+                ay = cy * s;
+                az = cz * s;
+                aw = hw;
+            }
+            // newLocal = conjugate(parentRot) * (aim * worldRot)
+            const m1x = ax * ww + aw * wx + ay * wz - az * wy;
+            const m1y = ay * ww + aw * wy + az * wx - ax * wz;
+            const m1z = az * ww + aw * wz + ax * wy - ay * wx;
+            const m1w = aw * ww - ax * wx - ay * wy - az * wz;
+            pose.rotations[jr] = -prx * m1w + prw * m1x - pry * m1z + prz * m1y;
+            pose.rotations[jr + 1] = -pry * m1w + prw * m1y - prz * m1x + prx * m1z;
+            pose.rotations[jr + 2] = -prz * m1w + prw * m1z - prx * m1y + pry * m1x;
+            pose.rotations[jr + 3] = prw * m1w + prx * m1x + pry * m1y + prz * m1z;
+            const ar = i * 4;
+            authoredRot[ar] = lrx;
+            authoredRot[ar + 1] = lry;
+            authoredRot[ar + 2] = lrz;
+            authoredRot[ar + 3] = lrw;
+            aimRot[ar] = pose.rotations[jr];
+            aimRot[ar + 1] = pose.rotations[jr + 1];
+            aimRot[ar + 2] = pose.rotations[jr + 2];
+            aimRot[ar + 3] = pose.rotations[jr + 3];
+            aimWritten[i] = 1;
+            fMark[joint] = 0;
+        }
+    }
+    return { initialize, step };
+}
 //# sourceMappingURL=SpringBones.js.map