@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/anim/root-motion.js

@@ -0,0 +1,224 @@
+/**
+ * Root motion: split the root node's travel out of a clip so the character animates in place
+ * while the game moves its transform by the extracted motion, without guessing at speeds.
+ *
+ * `extractRootMotion` returns two clips sharing keyframe times: `clip` (in place: the root keeps
+ * its first-frame translation and yaw) and `motion` (the root's translation relative to the
+ * first frame and its yaw about +Y relative to the first frame). At every keyframe
+ * `motion + clip` (translation) and `motion · clip` (rotation) equal the original root transform.
+ * `applyRootMotionDelta` samples `motion` at two times and gives the game a position delta in the
+ * root's own heading frame plus a yaw delta, handling the loop wrap. Yaw is about +Y (Y up).
+ */
+import { sampleChannel } from './clip.js';
+import { quatMultiply, quatNormalize } from './quat.js';
+function copyChannel(ch) {
+    return {
+        node: ch.node,
+        path: ch.path,
+        interpolation: ch.interpolation,
+        times: new Float32Array(ch.times),
+        values: new Float32Array(ch.values),
+    };
+}
+const q = new Float32Array(4);
+const twist = new Float32Array(4);
+const twist0 = new Float32Array(4);
+const conj0 = new Float32Array(4);
+const rem = new Float32Array(4);
+/** Yaw (rotation about +Y) part of `src[o..o+4)` into `out`, by swing-twist decomposition. */
+function yawOf(out, src, o) {
+    out[0] = 0;
+    out[1] = src[o + 1];
+    out[2] = 0;
+    out[3] = src[o + 3];
+    quatNormalize(out, 0);
+}
+/** Flip `dst` so it sits on the same hemisphere as the key before it (no slerp flips). */
+function hemisphere(dst, o) {
+    if (o < 4)
+        return;
+    const dot = dst[o] * dst[o - 4] +
+        dst[o + 1] * dst[o - 3] +
+        dst[o + 2] * dst[o - 2] +
+        dst[o + 3] * dst[o - 1];
+    if (dot < 0)
+        for (let i = 0; i < 4; i++)
+            dst[o + i] = -dst[o + i];
+}
+/**
+ * Split `clip` into an in-place clip and a motion clip for `rootNode`. Channels are copied, never
+ * aliased; the two clips share keyframe times with the input. Translation keeps `CUBICSPLINE`
+ * tangents (the in-place side's extracted components get zero tangents); a `CUBICSPLINE`
+ * rotation channel on the root comes back as two `LINEAR` channels over its key values. Clips
+ * with no root channel yield an empty `motion`. Allocates; call at load time.
+ */
+export function extractRootMotion(clip, rootNode, opts) {
+    const planar = opts?.planar ?? false;
+    const stay = [];
+    const move = [];
+    for (const ch of clip.channels) {
+        if (ch.node !== rootNode || ch.path === 'scale' || ch.path === 'weights') {
+            stay.push(copyChannel(ch));
+            continue;
+        }
+        if (ch.path === 'translation') {
+            const cubic = ch.interpolation === 'CUBICSPLINE';
+            const stride = cubic ? 9 : 3;
+            const valueOff = cubic ? 3 : 0;
+            const n = ch.times.length;
+            const s = new Float32Array(ch.values.length);
+            const m = new Float32Array(ch.values.length);
+            const src = ch.values;
+            for (let k = 0; k < n; k++) {
+                const base = k * stride;
+                for (let part = 0; part < (cubic ? 3 : 1); part++) {
+                    const isValue = cubic ? part === 1 : true;
+                    for (let comp = 0; comp < 3; comp++) {
+                        const idx = base + part * 3 + comp;
+                        const extract = !planar || comp !== 1;
+                        const first = isValue ? src[valueOff + comp] : 0;
+                        if (extract) {
+                            m[idx] = src[idx] - first;
+                            s[idx] = first;
+                        }
+                        else {
+                            m[idx] = 0;
+                            s[idx] = src[idx];
+                        }
+                    }
+                }
+            }
+            stay.push({ ...copyChannel(ch), values: s });
+            move.push({ ...copyChannel(ch), values: m });
+            continue;
+        }
+        // Rotation.
+        if (planar) {
+            stay.push(copyChannel(ch));
+            continue;
+        }
+        const cubic = ch.interpolation === 'CUBICSPLINE';
+        const n = ch.times.length;
+        const s = new Float32Array(n * 4);
+        const m = new Float32Array(n * 4);
+        const src = ch.values;
+        if (n > 0)
+            yawOf(twist0, src, cubic ? 4 : 0);
+        conj0[0] = -twist0[0];
+        conj0[1] = -twist0[1];
+        conj0[2] = -twist0[2];
+        conj0[3] = twist0[3];
+        for (let k = 0; k < n; k++) {
+            const vo = cubic ? k * 12 + 4 : k * 4;
+            for (let i = 0; i < 4; i++)
+                q[i] = src[vo + i];
+            yawOf(twist, q, 0);
+            // q = twist · rem  →  rem = conj(twist) · q.
+            rem[0] = -twist[0];
+            rem[1] = -twist[1];
+            rem[2] = -twist[2];
+            rem[3] = twist[3];
+            quatMultiply(rem, 0, rem, 0, q, 0);
+            // motion = twist · conj(twist0); stay = twist0 · rem; motion · stay = twist · rem = q.
+            quatMultiply(m, k * 4, twist, 0, conj0, 0);
+            quatMultiply(s, k * 4, twist0, 0, rem, 0);
+            quatNormalize(m, k * 4);
+            quatNormalize(s, k * 4);
+            hemisphere(m, k * 4);
+            hemisphere(s, k * 4);
+        }
+        const interpolation = cubic ? 'LINEAR' : ch.interpolation;
+        const times = new Float32Array(ch.times);
+        stay.push({ node: ch.node, path: 'rotation', interpolation, times, values: s });
+        move.push({
+            node: ch.node,
+            path: 'rotation',
+            interpolation,
+            times: new Float32Array(times),
+            values: m,
+        });
+    }
+    const inPlace = { name: clip.name, duration: clip.duration, channels: stay };
+    if (clip.events)
+        inPlace.events = clip.events.map((e) => ({ ...e }));
+    return {
+        clip: inPlace,
+        motion: { name: `${clip.name}.motion`, duration: clip.duration, channels: move },
+    };
+}
+const p0 = new Float32Array(3);
+const p1 = new Float32Array(3);
+const r0 = new Float32Array(4);
+const r1 = new Float32Array(4);
+const seg = new Float32Array(4);
+/** Yaw angle (radians, about +Y) of a rotation channel at `t`, 0 without a channel. */
+function yawAt(ch, t, out) {
+    if (!ch)
+        return 0;
+    sampleChannel(ch, t, out, 0);
+    return 2 * Math.atan2(out[1], out[3]);
+}
+function wrapAngle(a) {
+    let r = a % (2 * Math.PI);
+    if (r > Math.PI)
+        r -= 2 * Math.PI;
+    else if (r <= -Math.PI)
+        r += 2 * Math.PI;
+    return r;
+}
+/** One forward segment `t0 → t1` into `out`: the position delta in the heading frame at `t0`, yaw delta. */
+function segment(tr, rot, t0, t1, out) {
+    if (tr) {
+        sampleChannel(tr, t0, p0, 0);
+        sampleChannel(tr, t1, p1, 0);
+    }
+    else {
+        p0.fill(0);
+        p1.fill(0);
+    }
+    const y0 = yawAt(rot, t0, r0);
+    const y1 = yawAt(rot, t1, r1);
+    const dx = p1[0] - p0[0];
+    const dy = p1[1] - p0[1];
+    const dz = p1[2] - p0[2];
+    // Undo the heading at t0: rotate by -y0 about +Y.
+    const c = Math.cos(-y0);
+    const s = Math.sin(-y0);
+    out[0] = dx * c + dz * s;
+    out[1] = dy;
+    out[2] = -dx * s + dz * c;
+    out[3] = wrapAngle(y1 - y0);
+}
+/**
+ * The root's motion between `t0` and `t1` of a `motion` clip, into `outDelta` (4 floats):
+ * `[dx, dy, dz]` is the position delta expressed in the root's heading frame at `t0` (the motion
+ * clip's yaw there, zero at the first key: rotate the delta by the character's own heading, then
+ * add it to the position) and `[3]` is the yaw delta in radians about +Y (add it to the
+ * heading). When `t1 < t0` the clip has looped: the
+ * delta runs `t0 → duration` then `0 → t1`. Returns `outDelta`. No allocation.
+ */
+export function applyRootMotionDelta(motionClip, t0, t1, outDelta) {
+    let tr = null;
+    let rot = null;
+    for (const ch of motionClip.channels) {
+        if (ch.path === 'translation' && !tr)
+            tr = ch;
+        else if (ch.path === 'rotation' && !rot)
+            rot = ch;
+    }
+    if (t1 >= t0) {
+        segment(tr, rot, t0, t1, outDelta);
+        return outDelta;
+    }
+    segment(tr, rot, t0, motionClip.duration, outDelta);
+    segment(tr, rot, 0, t1, seg);
+    // The second segment is in the heading frame at 0; bring it into the frame at t0 by the yaw
+    // the first segment turned.
+    const c = Math.cos(outDelta[3]);
+    const s = Math.sin(outDelta[3]);
+    outDelta[0] = outDelta[0] + seg[0] * c + seg[2] * s;
+    outDelta[1] = outDelta[1] + seg[1];
+    outDelta[2] = outDelta[2] - seg[0] * s + seg[2] * c;
+    outDelta[3] = wrapAngle(outDelta[3] + seg[3]);
+    return outDelta;
+}

package/dist/anim/skin-pose.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `skinPose`: one call per frame from an animated pose to a skin palette slot (ws/assets-4).
+ * It runs the steps a skinned character repeats every frame: advance the clips (`update(dt)`,
+ * when a source and a `dt` are given), resolve the pose into node world matrices
+ * (`poseToWorld`), multiply each joint by its inverse bind matrix (`skinMatrices`) and write
+ * the result straight into the palette's staging (`palette.write(slot)`). The world matrices
+ * live in a scratch array cached per skeleton and are returned, for sockets and IK. Nothing
+ * allocates after the first call for a skeleton.
+ */
+import type { SkinPalette } from '../render/skin.js';
+import { type Pose, type Skeleton } from './pose.js';
+/**
+ * What `skinPose` reads a pose from: an object that owns a pose and advances it, such as an
+ * `AnimationMixer`. An `AnimGraph` drives a mixer; pass that mixer (after `graph.update`) or
+ * its `pose`.
+ */
+export interface SkinPoseSource {
+    readonly pose: Pose;
+    update(dt: number): void;
+}
+/**
+ * The part of a `SkinPalette` that `skinPose` uses: a slot's staging block to fill in place.
+ * When the target also has a `jointCount` (a `SkinPalette` does), `skinPose` checks it first.
+ */
+export type SkinPoseTarget = Pick<SkinPalette, 'write'>;
+/**
+ * Pose one skinned instance into `palette` slot `slot` and return the node world matrices
+ * (3×4 row-major, `WORLD_NODE_FLOATS` per node). `source` is a `Pose`, used as it is, or a
+ * `SkinPoseSource` (an `AnimationMixer`): with `dt` given, `source.update(dt)` runs first;
+ * without it the source's current pose is used, so a game that updated a graph, or edited the
+ * pose with IK, passes no `dt`. The result equals `update(dt)` → `poseToWorld` →
+ * `skinMatrices(skeleton, world, palette.write(slot))` bit for bit. Throws when the
+ * skeleton has more joints than the palette's slot holds (ws/render-11; a `SkinPalette` is
+ * checked by `jointCount` before the source advances). The returned array is shared per skeleton and rewritten by the next call for the same skeleton: read it (sockets,
+ * `attachTransform`) before posing another instance of that skeleton, or pass your own
+ * `world`. Call `palette.flush()` once per frame after posing every slot. Allocates only the
+ * scratch array on the first call for a skeleton without `world`.
+ */
+export declare function skinPose(skeleton: Skeleton, source: Pose | SkinPoseSource, palette: SkinPoseTarget, slot?: number, dt?: number, world?: Float32Array): Float32Array;

package/dist/anim/skin-pose.js

@@ -0,0 +1,53 @@
+import { jointCount, poseToWorld, skinMatrices, WORLD_NODE_FLOATS, } from './pose.js';
+const worldCache = new WeakMap();
+/**
+ * Pose one skinned instance into `palette` slot `slot` and return the node world matrices
+ * (3×4 row-major, `WORLD_NODE_FLOATS` per node). `source` is a `Pose`, used as it is, or a
+ * `SkinPoseSource` (an `AnimationMixer`): with `dt` given, `source.update(dt)` runs first;
+ * without it the source's current pose is used, so a game that updated a graph, or edited the
+ * pose with IK, passes no `dt`. The result equals `update(dt)` → `poseToWorld` →
+ * `skinMatrices(skeleton, world, palette.write(slot))` bit for bit. Throws when the
+ * skeleton has more joints than the palette's slot holds (ws/render-11; a `SkinPalette` is
+ * checked by `jointCount` before the source advances). The returned array is shared per skeleton and rewritten by the next call for the same skeleton: read it (sockets,
+ * `attachTransform`) before posing another instance of that skeleton, or pass your own
+ * `world`. Call `palette.flush()` once per frame after posing every slot. Allocates only the
+ * scratch array on the first call for a skeleton without `world`.
+ */
+export function skinPose(skeleton, source, palette, slot = 0, dt, world) {
+    const joints = jointCount(skeleton);
+    const has = palette.jointCount;
+    if (has !== undefined && has < joints)
+        throw tooSmall(joints, has, slot);
+    let pose;
+    if (source instanceof Float32Array) {
+        pose = source;
+    }
+    else {
+        if (dt !== undefined)
+            source.update(dt);
+        pose = source.pose;
+    }
+    const out = world ?? worldFor(skeleton);
+    poseToWorld(skeleton, pose, out);
+    const block = palette.write(slot);
+    // A target without `jointCount`: its block's length says how many joints it holds.
+    // One 3×4 matrix (`WORLD_NODE_FLOATS`) per joint, as `skinMatrices` writes them.
+    if (block.length < joints * WORLD_NODE_FLOATS) {
+        throw tooSmall(joints, Math.floor(block.length / WORLD_NODE_FLOATS), slot);
+    }
+    skinMatrices(skeleton, out, block);
+    return out;
+}
+function tooSmall(joints, has, slot) {
+    return new Error(`skinPose: the skeleton has ${joints} joints but the palette holds ${has} per slot ` +
+        `(slot ${slot}); make the SkinPalette with joints: ${joints} or more`);
+}
+function worldFor(skeleton) {
+    const floats = skeleton.parents.length * WORLD_NODE_FLOATS;
+    let w = worldCache.get(skeleton);
+    if (!w || w.length !== floats) {
+        w = new Float32Array(floats);
+        worldCache.set(skeleton, w);
+    }
+    return w;
+}

package/dist/anim/socket.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Attachment sockets: a joint plus a fixed local offset. Each frame a socket yields the world 3×4
+ * of whatever rides it (a second mesh, a particle emitter, a `Transform`), so cosmetics follow an
+ * animated skeleton with no code in the game beyond "attach here".
+ *
+ * `socketWorld = instanceWorld · world[joint] · offset`, all 3×4 row-major (`render/transform.ts`
+ * layout); nothing here allocates after `createSocket`. The only tie to `render/` is the
+ * `Transform` type `attachTransform` writes into, imported as a type.
+ */
+import type { Transform } from '../render/transform.js';
+import { type Skeleton } from './pose.js';
+/** A joint (node index into the world array `poseToWorld` writes) and a 3×4 offset in joint space. */
+export interface Socket {
+    joint: number;
+    /** 12 floats, 3×4 row-major: `T · R · S` of `SocketLocal`. */
+    offset: Float32Array;
+}
+/** The offset of a socket in joint space; every part defaults to the identity. */
+export interface SocketLocal {
+    /** `[x, y, z]` along the joint's axes. */
+    position?: ArrayLike<number>;
+    /** Unit quaternion `[x, y, z, w]`. */
+    rotation?: ArrayLike<number>;
+    /** `[x, y, z]`, or one number for all three. */
+    scale?: ArrayLike<number> | number;
+}
+/**
+ * Build a socket on `joint` (a node index, or a name resolved through `Skeleton.names`) with the
+ * local offset `local`. Throws when the index is out of range, when a name is given without
+ * `names`, or when no node carries that name. Allocates (setup).
+ */
+export declare function createSocket(skeleton: Skeleton, joint: number | string, local?: SocketLocal): Socket;
+/**
+ * `out = instanceWorld · worldPose[joint] · offset`: the socket's world 3×4 for the node world
+ * matrices `worldPose` (`poseToWorld` output) and the skeleton instance's own world matrix
+ * (`null` when the pose is already in world space, or the attached transform has the instance as
+ * its parent). Writes 12 floats at `out[0..12)` and returns `out`; `out` may not alias
+ * `worldPose`. No allocation.
+ */
+export declare function socketWorld(socket: Socket, worldPose: Float32Array, instanceWorld: Float32Array | null, out: Float32Array): Float32Array;
+/**
+ * Write `socketWorld(...)` into `transform` (`Transform.setMatrix`), so the attached mesh draws
+ * through `frame.mesh(mesh, material, transform)` like any other. The transform should have no
+ * parent, or the skeleton instance's transform as its parent with `instanceWorld` `null`. No
+ * allocation.
+ */
+export declare function attachTransform(socket: Socket, worldPose: Float32Array, instanceWorld: Float32Array | null, transform: Transform): void;

package/dist/anim/socket.js

@@ -0,0 +1,84 @@
+import { multiplyAffine, POSE_NODE_FLOATS, WORLD_NODE_FLOATS, writeNodeMatrix, } from './pose.js';
+/**
+ * Build a socket on `joint` (a node index, or a name resolved through `Skeleton.names`) with the
+ * local offset `local`. Throws when the index is out of range, when a name is given without
+ * `names`, or when no node carries that name. Allocates (setup).
+ */
+export function createSocket(skeleton, joint, local) {
+    const n = skeleton.parents.length;
+    let index;
+    if (typeof joint === 'string') {
+        const names = skeleton.names;
+        if (!names)
+            throw new Error(`createSocket: joint '${joint}' by name, but the skeleton has no names`);
+        index = names.indexOf(joint);
+        if (index < 0)
+            throw new Error(`createSocket: no node named '${joint}'`);
+    }
+    else {
+        index = joint;
+    }
+    if (!Number.isInteger(index) || index < 0 || index >= n) {
+        throw new Error(`createSocket: joint ${index} is not a node (${n} nodes)`);
+    }
+    const node = new Float32Array(POSE_NODE_FLOATS);
+    node[6] = 1;
+    node[7] = node[8] = node[9] = 1;
+    if (local) {
+        const p = local.position;
+        if (p) {
+            node[0] = p[0];
+            node[1] = p[1];
+            node[2] = p[2];
+        }
+        const r = local.rotation;
+        if (r) {
+            const len = Math.hypot(r[0], r[1], r[2], r[3]) || 1;
+            node[3] = r[0] / len;
+            node[4] = r[1] / len;
+            node[5] = r[2] / len;
+            node[6] = r[3] / len;
+        }
+        const s = local.scale;
+        if (typeof s === 'number') {
+            node[7] = node[8] = node[9] = s;
+        }
+        else if (s) {
+            node[7] = s[0];
+            node[8] = s[1];
+            node[9] = s[2];
+        }
+    }
+    const offset = new Float32Array(WORLD_NODE_FLOATS);
+    writeNodeMatrix(offset, 0, node, 0);
+    return { joint: index, offset };
+}
+const scratch = new Float32Array(WORLD_NODE_FLOATS);
+/**
+ * `out = instanceWorld · worldPose[joint] · offset`: the socket's world 3×4 for the node world
+ * matrices `worldPose` (`poseToWorld` output) and the skeleton instance's own world matrix
+ * (`null` when the pose is already in world space, or the attached transform has the instance as
+ * its parent). Writes 12 floats at `out[0..12)` and returns `out`; `out` may not alias
+ * `worldPose`. No allocation.
+ */
+export function socketWorld(socket, worldPose, instanceWorld, out) {
+    const jo = socket.joint * WORLD_NODE_FLOATS;
+    if (instanceWorld) {
+        multiplyAffine(scratch, 0, worldPose, jo, socket.offset, 0);
+        multiplyAffine(out, 0, instanceWorld, 0, scratch, 0);
+    }
+    else {
+        multiplyAffine(out, 0, worldPose, jo, socket.offset, 0);
+    }
+    return out;
+}
+const attached = new Float32Array(WORLD_NODE_FLOATS);
+/**
+ * Write `socketWorld(...)` into `transform` (`Transform.setMatrix`), so the attached mesh draws
+ * through `frame.mesh(mesh, material, transform)` like any other. The transform should have no
+ * parent, or the skeleton instance's transform as its parent with `instanceWorld` `null`. No
+ * allocation.
+ */
+export function attachTransform(socket, worldPose, instanceWorld, transform) {
+    transform.setMatrix(socketWorld(socket, worldPose, instanceWorld, attached));
+}

package/dist/anim/spring-chain.d.ts

@@ -0,0 +1,73 @@
+import { type Pose, type Skeleton } from './pose.js';
+/** A sphere in instance space. */
+export interface SpringSphere {
+    center: ArrayLike<number>;
+    radius: number;
+}
+/** A capsule in instance space: the segment `a`–`b` swept by `radius`. */
+export interface SpringCapsule {
+    a: ArrayLike<number>;
+    b: ArrayLike<number>;
+    radius: number;
+}
+export type SpringCollider = SpringSphere | SpringCapsule;
+export interface SpringChainDesc {
+    /** The first joint of the chain; it is pinned to the animation and only turns. */
+    root: number;
+    /** The last joint: the chain is every node on the path from `root` down to `tip`. */
+    tip?: number;
+    /** Or the joints in order, parent before child, as an alternative to `tip`. */
+    joints?: ArrayLike<number>;
+    /** Spring toward the sampled position, per second². Default 80. */
+    stiffness?: number;
+    /** Velocity decay per second. Default 6. */
+    damping?: number;
+    /** Instance-space gravity, units per second². Default `[0, -9.8, 0]`. */
+    gravity?: ArrayLike<number>;
+    /** 0..1: the fraction of the sampled pose's own motion the joints inherit. Default 0. */
+    drag?: number;
+    /** Joint radius for collisions. Default 0. */
+    radius?: number;
+    /** Largest angle (radians) a bone may swing away from its sampled direction. Default π. */
+    limitAngle?: number;
+    /** Colliders, read every frame (mutate them in place to move them). */
+    collide?: SpringCollider[];
+    /** Largest sub-step; a frame is split into equal steps no longer than this. Default 1/120. */
+    maxDt?: number;
+    /** A root jump beyond this (instance units) in one frame shifts the chain with no velocity. Default 1. */
+    teleportDistance?: number;
+}
+/** A spring chain with its state, from `createSpringChain`. */
+export interface SpringChain {
+    readonly joints: Int16Array;
+    stiffness: number;
+    damping: number;
+    readonly gravity: Float32Array;
+    drag: number;
+    radius: number;
+    limitAngle: number;
+    collide: SpringCollider[];
+    maxDt: number;
+    teleportDistance: number;
+    /** Simulated joint positions in instance space, 3 per joint, after the last update. */
+    readonly positions: Float32Array;
+    /** The sampled joint positions in instance space, 3 per joint, from the last update. */
+    readonly animated: Float32Array;
+    /** Forget the state: the next update starts the chain at the sampled pose with no velocity. */
+    reset(): void;
+    /** @internal */
+    readonly prev: Float32Array;
+    /** @internal */
+    readonly animPrev: Float32Array;
+    /** @internal */
+    readonly lengths: Float32Array;
+    /** @internal */
+    started: boolean;
+}
+/** Validate and allocate; call once. */
+export declare function createSpringChain(skeleton: Skeleton, desc: SpringChainDesc): SpringChain;
+/**
+ * Step the chain by `dt` (split into sub-steps of at most `maxDt`) and rewrite the chain's
+ * rotations in `pose`. Call after sampling and `poseToWorld`, before skinning. No allocation.
+ */
+export declare function updateSpringChain(pose: Pose, skeleton: Skeleton, worldPose: Float32Array, chain: SpringChain, instanceWorld: Float32Array | null, dt: number): void;