@jgengine/core 0.26.0 → 0.28.0

package/dist/anim/locomotionGraph.d.ts

@@ -1,16 +1,45 @@
 import type { ModelAnimationConfig } from "../game/playableGame.js";
 import type { AnimGraph } from "./animGraph.js";
-/** Inputs for {@link locomotionGraph}: the idle/walk/run clip names and the one-shot table a rig config already carries. */
+/** Inputs for {@link locomotionGraph}: the locomotion clip names and the one-shot table a rig config already carries. */
 export interface LocomotionGraphInput {
     idle: string;
     walk: string;
     run?: string;
+    /** Clip for moving to the character's left; adds the `strafe` state. */
+    strafeLeft?: string;
+    /** Clip for moving to the character's right; adds the `strafe` state. */
+    strafeRight?: string;
+    /** Clip for moving backwards; adds the `backward` state. */
+    backward?: string;
+    /** Clip for turning on the spot. Omitted, the turn blend uses `walk` as its pivot step. */
+    turn?: string;
     /** Speed (world units/sec) above which the character walks. Default 0.5. */
     walkSpeed?: number;
     /** Speed above which it runs. Default 6. */
     runSpeed?: number;
     /** Crossfade seconds between locomotion states. Default 0.2. */
     fadeSec?: number;
+    /** Lateral share above which the character counts as strafing. Default 0.35. */
+    strafeGate?: number;
+    /** Lateral share at or below which it stops strafing. Default 0.2. */
+    strafeRelease?: number;
+    /** Facing-vs-motion dot below which it counts as moving backwards. Default -0.35. */
+    backwardGate?: number;
+    /** Facing-vs-motion dot at or above which it stops. Default -0.2. */
+    backwardRelease?: number;
+    /** Turn rate (radians/sec) above which the character counts as turning on the spot. Default 1.5. */
+    turnGate?: number;
+    /** Turn rate at which the turn blend reaches its pivot clip. Default 4. */
+    turnFull?: number;
+    /** Speed below which a turn counts as turning on the spot. Default 0.5. */
+    turnSpeed?: number;
+    /**
+     * Mark every locomotion state as a root-motion state, so the rig plays in place and the blended
+     * root travel comes out as `AnimGraphOutput.rootDelta`. The movement owner consumes it with
+     * `takeRootMotion` and resolves it through its controller. Off by default, for rigs whose clips
+     * are authored in place.
+     */
+    rootMotion?: boolean;
     /** One-shot clips keyed by trigger name; `death` holds its last frame instead of returning. */
     oneShots?: Readonly<Record<string, string | readonly string[]>>;
 }
@@ -22,11 +51,37 @@ export declare const LOCOMOTION_GROUNDED_PARAM = "grounded";
 export declare const LOCOMOTION_VERTICAL_SPEED_PARAM = "verticalSpeed";
 /** Physically resolved crouch stance from the shared player motor. */
 export declare const LOCOMOTION_CROUCHED_PARAM = "crouched";
+/**
+ * Signed lateral share of the character's motion: `-1` fully to its left, `+1` fully to its right,
+ * `0` straight ahead or straight back. A custom mover feeds it under `ANIM_PARAMS_KEY`.
+ */
+export declare const LOCOMOTION_DIRECTION_PARAM = "direction";
+/**
+ * Dot of the character's facing with its motion direction: `1` running forward, `-1` running
+ * backwards. A custom mover feeds it under `ANIM_PARAMS_KEY`.
+ */
+export declare const LOCOMOTION_FACING_PARAM = "facing";
+/** Signed yaw rate in radians/sec; a custom mover feeds it under `ANIM_PARAMS_KEY`. */
+export declare const LOCOMOTION_TURN_RATE_PARAM = "turnRate";
 /** Layer id the locomotion graph uses; query `runtime.stateOf(LOCOMOTION_LAYER)`. */
 export declare const LOCOMOTION_LAYER = "base";
+/** State id of the forward idle/walk/run blend. */
+export declare const LOCOMOTION_STATE = "locomotion";
+/** State id of the lateral strafe blend. */
+export declare const LOCOMOTION_STRAFE_STATE = "strafe";
+/** State id of the backwards blend. */
+export declare const LOCOMOTION_BACKWARD_STATE = "backward";
+/** State id of the on-the-spot turn blend. */
+export declare const LOCOMOTION_TURN_STATE = "turn";
 /**
- * The engine's default locomotion as an authored graph: a speed-driven blend between idle, walk, and run, plus a
- * state per one-shot that plays once and returns (or clamps for `death`). What `useModelAnimation` used to hardcode.
+ * The engine's default locomotion as an authored graph: a speed-driven blend between idle, walk and
+ * run, plus a state per one-shot that plays once and returns (or clamps for `death`). What
+ * `useModelAnimation` used to hardcode.
+ *
+ * Supplying `strafeLeft`/`strafeRight` adds a `strafe` blend on the `direction` parameter, and
+ * `backward` and `turn` add their states behind the `facing` and `turnRate` parameters. Each extra
+ * state is joined to the base by a crossfaded transition, so a direction change blends rather than
+ * pops; without them the graph is exactly the speed-only tree it has always been.
  *
  * @capability locomotion-graph build the default idle/walk/run plus one-shot graph from clip names
  */

package/dist/anim/locomotionGraph.js

@@ -6,11 +6,44 @@ export const LOCOMOTION_GROUNDED_PARAM = "grounded";
 export const LOCOMOTION_VERTICAL_SPEED_PARAM = "verticalSpeed";
 /** Physically resolved crouch stance from the shared player motor. */
 export const LOCOMOTION_CROUCHED_PARAM = "crouched";
+/**
+ * Signed lateral share of the character's motion: `-1` fully to its left, `+1` fully to its right,
+ * `0` straight ahead or straight back. A custom mover feeds it under `ANIM_PARAMS_KEY`.
+ */
+export const LOCOMOTION_DIRECTION_PARAM = "direction";
+/**
+ * Dot of the character's facing with its motion direction: `1` running forward, `-1` running
+ * backwards. A custom mover feeds it under `ANIM_PARAMS_KEY`.
+ */
+export const LOCOMOTION_FACING_PARAM = "facing";
+/** Signed yaw rate in radians/sec; a custom mover feeds it under `ANIM_PARAMS_KEY`. */
+export const LOCOMOTION_TURN_RATE_PARAM = "turnRate";
 /** Layer id the locomotion graph uses; query `runtime.stateOf(LOCOMOTION_LAYER)`. */
 export const LOCOMOTION_LAYER = "base";
+/** State id of the forward idle/walk/run blend. */
+export const LOCOMOTION_STATE = "locomotion";
+/** State id of the lateral strafe blend. */
+export const LOCOMOTION_STRAFE_STATE = "strafe";
+/** State id of the backwards blend. */
+export const LOCOMOTION_BACKWARD_STATE = "backward";
+/** State id of the on-the-spot turn blend. */
+export const LOCOMOTION_TURN_STATE = "turn";
+const DEFAULT_STRAFE_GATE = 0.35;
+const DEFAULT_STRAFE_RELEASE = 0.2;
+const DEFAULT_BACKWARD_GATE = -0.35;
+const DEFAULT_BACKWARD_RELEASE = -0.2;
+const DEFAULT_TURN_GATE = 1.5;
+const DEFAULT_TURN_FULL = 4;
+const DEFAULT_TURN_SPEED = 0.5;
 /**
- * The engine's default locomotion as an authored graph: a speed-driven blend between idle, walk, and run, plus a
- * state per one-shot that plays once and returns (or clamps for `death`). What `useModelAnimation` used to hardcode.
+ * The engine's default locomotion as an authored graph: a speed-driven blend between idle, walk and
+ * run, plus a state per one-shot that plays once and returns (or clamps for `death`). What
+ * `useModelAnimation` used to hardcode.
+ *
+ * Supplying `strafeLeft`/`strafeRight` adds a `strafe` blend on the `direction` parameter, and
+ * `backward` and `turn` add their states behind the `facing` and `turnRate` parameters. Each extra
+ * state is joined to the base by a crossfaded transition, so a direction change blends rather than
+ * pops; without them the graph is exactly the speed-only tree it has always been.
  *
  * @capability locomotion-graph build the default idle/walk/run plus one-shot graph from clip names
  */
@@ -18,31 +51,119 @@ export function locomotionGraph(input) {
     const walkSpeed = input.walkSpeed ?? 0.5;
     const runSpeed = input.runSpeed ?? 6;
     const fade = input.fadeSec ?? 0.2;
-    const points = [
-        { at: 0, clip: input.idle },
-        { at: walkSpeed, clip: input.walk },
-        ...(input.run === undefined ? [] : [{ at: runSpeed, clip: input.run }]),
-    ];
+    const rootMotion = input.rootMotion === true ? { rootMotion: true } : {};
     const states = {
-        locomotion: { kind: "blend1D", param: LOCOMOTION_SPEED_PARAM, points },
+        [LOCOMOTION_STATE]: {
+            kind: "blend1D",
+            param: LOCOMOTION_SPEED_PARAM,
+            points: [
+                { at: 0, clip: input.idle },
+                { at: walkSpeed, clip: input.walk },
+                ...(input.run === undefined ? [] : [{ at: runSpeed, clip: input.run }]),
+            ],
+            ...rootMotion,
+        },
+    };
+    const directional = [];
+    const strafes = [input.strafeLeft, input.strafeRight];
+    if (strafes.some((clip) => clip !== undefined)) {
+        const gate = input.strafeGate ?? DEFAULT_STRAFE_GATE;
+        const release = input.strafeRelease ?? DEFAULT_STRAFE_RELEASE;
+        const points = [
+            ...(input.strafeLeft === undefined ? [] : [{ at: -1, clip: input.strafeLeft }]),
+            ...(input.strafeRight === undefined ? [] : [{ at: 1, clip: input.strafeRight }]),
+        ];
+        states[LOCOMOTION_STRAFE_STATE] = { kind: "blend1D", param: LOCOMOTION_DIRECTION_PARAM, points, ...rootMotion };
+        for (const side of [-1, 1]) {
+            directional.push({
+                from: LOCOMOTION_STATE,
+                to: LOCOMOTION_STRAFE_STATE,
+                when: [{ param: LOCOMOTION_DIRECTION_PARAM, op: side < 0 ? "<" : ">", value: side * gate }],
+                duration: fade,
+            });
+        }
+        directional.push({
+            from: LOCOMOTION_STRAFE_STATE,
+            to: LOCOMOTION_STATE,
+            when: [
+                { param: LOCOMOTION_DIRECTION_PARAM, op: ">=", value: -release },
+                { param: LOCOMOTION_DIRECTION_PARAM, op: "<=", value: release },
+            ],
+            duration: fade,
+        });
+    }
+    if (input.backward !== undefined) {
+        const gate = input.backwardGate ?? DEFAULT_BACKWARD_GATE;
+        const release = input.backwardRelease ?? DEFAULT_BACKWARD_RELEASE;
+        states[LOCOMOTION_BACKWARD_STATE] = { kind: "blend1D", param: LOCOMOTION_SPEED_PARAM, points: [{ at: walkSpeed, clip: input.backward }], ...rootMotion };
+        for (const from of [LOCOMOTION_STATE, LOCOMOTION_STRAFE_STATE]) {
+            if (states[from] === undefined)
+                continue;
+            directional.push({
+                from,
+                to: LOCOMOTION_BACKWARD_STATE,
+                when: [
+                    { param: LOCOMOTION_FACING_PARAM, op: "<", value: gate },
+                    { param: LOCOMOTION_SPEED_PARAM, op: ">", value: walkSpeed * 0.5 },
+                ],
+                duration: fade,
+            });
+        }
+        directional.push({
+            from: LOCOMOTION_BACKWARD_STATE,
+            to: LOCOMOTION_STATE,
+            when: [{ param: LOCOMOTION_FACING_PARAM, op: ">=", value: release }],
+            duration: fade,
+        });
+    }
+    const turnGate = input.turnGate ?? DEFAULT_TURN_GATE;
+    const turnFull = input.turnFull ?? DEFAULT_TURN_FULL;
+    const turnSpeed = input.turnSpeed ?? DEFAULT_TURN_SPEED;
+    states[LOCOMOTION_TURN_STATE] = {
+        kind: "blend1D",
+        param: LOCOMOTION_TURN_RATE_PARAM,
+        points: [
+            { at: turnGate, clip: input.idle },
+            { at: turnFull, clip: input.turn ?? input.walk },
+        ],
+        ...rootMotion,
     };
+    for (const from of [LOCOMOTION_STATE, LOCOMOTION_STRAFE_STATE, LOCOMOTION_BACKWARD_STATE]) {
+        if (states[from] === undefined)
+            continue;
+        directional.push({
+            from,
+            to: LOCOMOTION_TURN_STATE,
+            when: [
+                { param: LOCOMOTION_TURN_RATE_PARAM, op: ">", value: turnGate },
+                { param: LOCOMOTION_SPEED_PARAM, op: "<", value: turnSpeed },
+            ],
+            duration: fade,
+        });
+    }
+    directional.push({
+        from: LOCOMOTION_TURN_STATE,
+        to: LOCOMOTION_STATE,
+        when: [{ param: LOCOMOTION_TURN_RATE_PARAM, op: "<=", value: turnGate }],
+        duration: fade,
+    });
     const oneShots = Object.entries(input.oneShots ?? {}).filter(([, spec]) => typeof spec === "string" || spec.length > 0);
+    oneShots.sort(([a], [b]) => Number(b === "death") - Number(a === "death"));
     for (const [name, spec] of oneShots) {
         const clip = typeof spec === "string" ? spec : spec[0];
         states[name] = { kind: "clip", clip, loop: false, ...(typeof spec === "string" || spec.length < 2 ? {} : { variants: [...spec] }) };
     }
-    const transitions = [];
-    oneShots.sort(([a], [b]) => Number(b === "death") - Number(a === "death"));
+    const triggered = [];
     for (const [name] of oneShots) {
         for (const from of Object.keys(states)) {
             if (from !== "death")
-                transitions.push({ from, to: name, trigger: name, duration: 0.1 });
+                triggered.push({ from, to: name, trigger: name, duration: 0.1 });
         }
         if (name !== "death")
-            transitions.push({ from: name, to: "locomotion", exitTime: 1, duration: fade });
+            triggered.push({ from: name, to: LOCOMOTION_STATE, exitTime: 1, duration: fade });
     }
     return {
-        layers: [{ id: LOCOMOTION_LAYER, entry: "locomotion", states, transitions }],
+        layers: [{ id: LOCOMOTION_LAYER, entry: LOCOMOTION_STATE, states, transitions: [...triggered, ...directional] }],
     };
 }
 /**
@@ -60,10 +181,16 @@ export function animGraphFromConfig(config) {
     const states = config.states;
     if (states === undefined || typeof states.idle !== "string" || states.idle.trim().length === 0)
         return undefined;
+    const clip = (value) => typeof value === "string" && value.trim().length > 0 ? value : undefined;
     return locomotionGraph({
         idle: states.idle,
-        walk: typeof states.walk === "string" && states.walk.trim().length > 0 ? states.walk : states.idle,
-        ...(typeof states.run !== "string" || states.run.trim().length === 0 ? {} : { run: states.run }),
+        walk: clip(states.walk) ?? states.idle,
+        ...(clip(states.run) === undefined ? {} : { run: clip(states.run) }),
+        ...(clip(states.strafeLeft) === undefined ? {} : { strafeLeft: clip(states.strafeLeft) }),
+        ...(clip(states.strafeRight) === undefined ? {} : { strafeRight: clip(states.strafeRight) }),
+        ...(clip(states.backward) === undefined ? {} : { backward: clip(states.backward) }),
+        ...(clip(states.turn) === undefined ? {} : { turn: clip(states.turn) }),
+        ...(states.rootMotion === true ? { rootMotion: true } : {}),
         walkSpeed: states.walkSpeed,
         runSpeed: states.runSpeed,
         fadeSec: states.fadeSec,

package/dist/anim/ragdollRig.d.ts

@@ -0,0 +1,53 @@
+import type { RagdollConfig } from "../physics/ragdoll.js";
+import { type SkeletonMap, type SkeletonSlot } from "./skeletonStandard.js";
+/**
+ * One standard slot's world pose, sampled at the moment a character is killed. The orientation is
+ * the reference the ragdoll's aim rotates from, so every bone keeps the roll it died with.
+ */
+export interface RagdollPose {
+    slot: SkeletonSlot;
+    position: readonly [number, number, number];
+    /** World orientation of the bone, as `[x, y, z, w]`. */
+    orientation: readonly [number, number, number, number];
+}
+/** Half-extents and mass of one standard slot's physics body, in the rig's own world units. */
+export interface RagdollBodyShape {
+    halfExtents: readonly [number, number, number];
+    mass: number;
+}
+/**
+ * Humanoid body shapes for the standard slots, sized for a roughly 1.8 m character standing on the
+ * ground. A rig of another scale multiplies them (see {@link RagdollRigOptions.scale}).
+ */
+export declare const HUMANOID_RAGDOLL_BODIES: Readonly<Partial<Record<SkeletonSlot, RagdollBodyShape>>>;
+/** Tuning for {@link ragdollConfigFromPoses}. */
+export interface RagdollRigOptions {
+    /** Overrides {@link HUMANOID_RAGDOLL_BODIES} per slot. A slot absent from both is skipped. */
+    bodies?: Readonly<Partial<Record<SkeletonSlot, RagdollBodyShape>>>;
+    /** Multiplies every half-extent; a rig taller than 1.8 m passes its height over 1.8. Default 1. */
+    scale?: number;
+    /** Also build a body for slots with no shape of their own. Default false. */
+    includeUnshaped?: boolean;
+}
+/**
+ * World orientations for a ragdoll's bones from its bodies' current positions: each bone rotates
+ * from its rest direction-to-child onto the current one, so the aim follows the joints while every
+ * bone keeps the roll it had in the death pose. A bone with no posed child keeps its rest
+ * orientation. The physics bodies carry translation only, so this is what gives the ragdoll a
+ * skeleton instead of a pile of boxes.
+ *
+ * @capability animation orient a ragdoll's bones from its physics bodies' positions
+ */
+export declare function ragdollBoneOrientations(rest: readonly RagdollPose[], positions: Readonly<Partial<Record<SkeletonSlot, readonly [number, number, number]>>>): Partial<Record<SkeletonSlot, [number, number, number, number]>>;
+/**
+ * A jointed ragdoll for a mapped rig from its bones' world poses at the moment of death: one box
+ * body per standard slot that has a shape, sized to the character, and one distance link per slot
+ * that has its parent present, holding the bones' own separation. The bodies start where the
+ * character actually was, so the collapse continues the death pose instead of snapping to a preset.
+ *
+ * `handSlot.l`/`handSlot.r` carry no body: they are prop sockets, not body parts. A slot whose bone
+ * the rig does not have is skipped, and its children link to the nearest present ancestor instead.
+ *
+ * @capability animation build a physics ragdoll from a mapped rig's death pose
+ */
+export declare function ragdollConfigFromPoses(map: SkeletonMap, poses: readonly RagdollPose[], options?: RagdollRigOptions): RagdollConfig;

package/dist/anim/ragdollRig.js

@@ -0,0 +1,132 @@
+import { multiplyQuaternions, quaternionFromUnitVectors } from "./ikSolver.js";
+import { SKELETON_PARENT, SKELETON_SLOTS } from "./skeletonStandard.js";
+/**
+ * Humanoid body shapes for the standard slots, sized for a roughly 1.8 m character standing on the
+ * ground. A rig of another scale multiplies them (see {@link RagdollRigOptions.scale}).
+ */
+export const HUMANOID_RAGDOLL_BODIES = {
+    root: { halfExtents: [0.1, 0.1, 0.08], mass: 4 },
+    hips: { halfExtents: [0.1, 0.09, 0.08], mass: 8 },
+    spine: { halfExtents: [0.1, 0.1, 0.08], mass: 6 },
+    chest: { halfExtents: [0.13, 0.12, 0.09], mass: 10 },
+    head: { halfExtents: [0.09, 0.1, 0.09], mass: 5 },
+    "upperArm.l": { halfExtents: [0.05, 0.13, 0.05], mass: 2 },
+    "upperArm.r": { halfExtents: [0.05, 0.13, 0.05], mass: 2 },
+    "lowerArm.l": { halfExtents: [0.04, 0.12, 0.04], mass: 1.5 },
+    "lowerArm.r": { halfExtents: [0.04, 0.12, 0.04], mass: 1.5 },
+    "hand.l": { halfExtents: [0.04, 0.05, 0.03], mass: 0.5 },
+    "hand.r": { halfExtents: [0.04, 0.05, 0.03], mass: 0.5 },
+    "upperLeg.l": { halfExtents: [0.07, 0.18, 0.07], mass: 4 },
+    "upperLeg.r": { halfExtents: [0.07, 0.18, 0.07], mass: 4 },
+    "lowerLeg.l": { halfExtents: [0.06, 0.17, 0.06], mass: 3 },
+    "lowerLeg.r": { halfExtents: [0.06, 0.17, 0.06], mass: 3 },
+    "foot.l": { halfExtents: [0.06, 0.04, 0.1], mass: 1 },
+    "foot.r": { halfExtents: [0.06, 0.04, 0.1], mass: 1 },
+    "toes.l": { halfExtents: [0.06, 0.03, 0.06], mass: 0.3 },
+    "toes.r": { halfExtents: [0.06, 0.03, 0.06], mass: 0.3 },
+};
+/**
+ * World orientations for a ragdoll's bones from its bodies' current positions: each bone rotates
+ * from its rest direction-to-child onto the current one, so the aim follows the joints while every
+ * bone keeps the roll it had in the death pose. A bone with no posed child keeps its rest
+ * orientation. The physics bodies carry translation only, so this is what gives the ragdoll a
+ * skeleton instead of a pile of boxes.
+ *
+ * @capability animation orient a ragdoll's bones from its physics bodies' positions
+ */
+export function ragdollBoneOrientations(rest, positions) {
+    const restBySlot = new Map(rest.map((pose) => [pose.slot, pose]));
+    const present = new Set(restBySlot.keys());
+    // The nearest posed descendant, walking down through slots the rig or shape table skipped.
+    const childOf = new Map();
+    for (const slot of present) {
+        for (const candidate of SKELETON_SLOTS) {
+            let parent = SKELETON_PARENT[candidate];
+            while (parent !== undefined && !present.has(parent))
+                parent = SKELETON_PARENT[parent];
+            if (parent === slot && !childOf.has(slot)) {
+                childOf.set(slot, candidate);
+                break;
+            }
+        }
+    }
+    const out = {};
+    for (const slot of present) {
+        const pose = restBySlot.get(slot);
+        const current = positions[slot];
+        const child = childOf.get(slot);
+        const childPose = child === undefined ? undefined : restBySlot.get(child);
+        const childCurrent = child === undefined ? undefined : positions[child];
+        if (current === undefined || childPose === undefined || childCurrent === undefined) {
+            out[slot] = [pose.orientation[0], pose.orientation[1], pose.orientation[2], pose.orientation[3]];
+            continue;
+        }
+        const restDirection = [
+            childPose.position[0] - pose.position[0],
+            childPose.position[1] - pose.position[1],
+            childPose.position[2] - pose.position[2],
+        ];
+        const currentDirection = [
+            childCurrent[0] - current[0],
+            childCurrent[1] - current[1],
+            childCurrent[2] - current[2],
+        ];
+        if (Math.hypot(...restDirection) <= 1e-6 || Math.hypot(...currentDirection) <= 1e-6) {
+            out[slot] = [pose.orientation[0], pose.orientation[1], pose.orientation[2], pose.orientation[3]];
+            continue;
+        }
+        const aim = quaternionFromUnitVectors(restDirection, currentDirection);
+        const base = [pose.orientation[0], pose.orientation[1], pose.orientation[2], pose.orientation[3]];
+        const composed = multiplyQuaternions(aim, base);
+        out[slot] = [composed[0], composed[1], composed[2], composed[3]];
+    }
+    return out;
+}
+/**
+ * A jointed ragdoll for a mapped rig from its bones' world poses at the moment of death: one box
+ * body per standard slot that has a shape, sized to the character, and one distance link per slot
+ * that has its parent present, holding the bones' own separation. The bodies start where the
+ * character actually was, so the collapse continues the death pose instead of snapping to a preset.
+ *
+ * `handSlot.l`/`handSlot.r` carry no body: they are prop sockets, not body parts. A slot whose bone
+ * the rig does not have is skipped, and its children link to the nearest present ancestor instead.
+ *
+ * @capability animation build a physics ragdoll from a mapped rig's death pose
+ */
+export function ragdollConfigFromPoses(map, poses, options = {}) {
+    const scale = options.scale ?? 1;
+    const poseBySlot = new Map(poses.map((pose) => [pose.slot, pose.position]));
+    const present = [];
+    const bones = [];
+    for (const slot of SKELETON_SLOTS) {
+        if (map.slots[slot] === undefined)
+            continue;
+        const position = poseBySlot.get(slot);
+        if (position === undefined)
+            continue;
+        const shape = options.bodies?.[slot] ?? HUMANOID_RAGDOLL_BODIES[slot];
+        if (shape === undefined && options.includeUnshaped !== true)
+            continue;
+        const halfExtents = shape?.halfExtents ?? [0.1, 0.1, 0.1];
+        bones.push({
+            name: slot,
+            position: [position[0], position[1], position[2]],
+            halfExtents: [halfExtents[0] * scale, halfExtents[1] * scale, halfExtents[2] * scale],
+            mass: shape?.mass ?? 1,
+        });
+        present.push(slot);
+    }
+    const included = new Set(present);
+    const links = [];
+    for (const slot of present) {
+        let parent = SKELETON_PARENT[slot];
+        // Walk up past slots this rig or this shape table does not cover, so a legless rig still links
+        // its head to the chest rather than dropping the bone out of the joint chain.
+        while (parent !== undefined && !included.has(parent))
+            parent = SKELETON_PARENT[parent];
+        if (parent === undefined)
+            continue;
+        links.push({ a: parent, b: slot, kind: "distance" });
+    }
+    return { bones, links };
+}

package/dist/anim/skeletonStandard.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The engine's one humanoid skeleton standard, and the path any other CC0 rig takes onto it.
+ *
+ * The standard is the **KayKit character rig**: one armature shared by every rigged character in
+ * `kaykit-adventurers` (Barbarian, Knight, Mage, Rogue, Rogue_Hooded) and `kaykit-skeletons`
+ * (Skeleton_Mage/Minion/Rogue/Warrior). Because they share it, all nine characters play the same
+ * clip set and one authored graph, foot-IK rig, attachment slot or ragdoll layout serves all of
+ * them. There is no second standard to keep in sync.
+ *
+ * A rig on a different scheme (Quaternius aliens, Mixamo exports) is not rewritten: its bones are
+ * *mapped* slot by slot onto the standard's names, and what it does not have is reported rather
+ * than guessed. A rig missing every leg slot can still be driven on its spine and head; a rig
+ * missing a slot never silently borrows a neighbour's bone.
+ */
+/**
+ * One canonical bone on the standard. Names are the authored names in the KayKit armature; the
+ * loaded runtime name drops `.` (see {@link runtimeBoneName}), so `upperleg.l` is `upperlegl` in
+ * the scene graph and both spellings resolve through `resolveRigNode`.
+ */
+export type SkeletonSlot = "root" | "hips" | "spine" | "chest" | "head" | "upperArm.l" | "upperArm.r" | "lowerArm.l" | "lowerArm.r" | "hand.l" | "hand.r" | "handSlot.l" | "handSlot.r" | "upperLeg.l" | "upperLeg.r" | "lowerLeg.l" | "lowerLeg.r" | "foot.l" | "foot.r" | "toes.l" | "toes.r";
+/** Every standard slot, in parent-before-child order. */
+export declare const SKELETON_SLOTS: readonly SkeletonSlot[];
+/** The parent slot of each slot that has one; `root` has none. */
+export declare const SKELETON_PARENT: Readonly<Partial<Record<SkeletonSlot, SkeletonSlot>>>;
+/** A named skeleton standard: its id and the authored bone name for each slot it defines. */
+export interface SkeletonStandard {
+    id: string;
+    label: string;
+    slots: Readonly<Partial<Record<SkeletonSlot, string>>>;
+}
+/**
+ * The one humanoid skeleton standard. Bone names are the authored KayKit names; the loaded
+ * hierarchy spells them without `.` and `resolveRigNode` accepts either.
+ *
+ * @capability skeleton-standard the shared humanoid bone standard every rigged character maps onto
+ */
+export declare const SKELETON_STANDARD: SkeletonStandard;
+/**
+ * A source naming scheme and the bone names on it that fill each standard slot. A slot lists every
+ * accepted spelling; matching is case- and punctuation-insensitive, so `mixamorigLeftUpLeg` and
+ * `LeftUpLeg` are the same candidate.
+ */
+export interface RigScheme {
+    id: string;
+    label: string;
+    /** Where the scheme comes from, for credits and diagnostics. */
+    source: string;
+    slots: Readonly<Partial<Record<SkeletonSlot, readonly string[]>>>;
+}
+/**
+ * The standard itself, as a scheme: a KayKit rig already is the standard, so its own names are the
+ * candidates. Both authored (`upperleg.l`) and runtime (`upperlegl`) spellings are accepted.
+ *
+ * @capability skeleton-standard map a rig on the standard scheme onto the standard's slots
+ */
+export declare const KAYKIT_SCHEME: RigScheme;
+/**
+ * Mixamo exports (`mixamorig*` names, or the same names without the prefix). Mixamo has a neck and
+ * a shoulder per side, which the standard folds into `chest` and `upperArm`; its toe is
+ * `ToeBase`, which is the standard's `toes`. Mixamo's topmost bone is `Hips`, so `root` and `hips`
+ * both resolve to it — a rig on this scheme has no bone above the pelvis.
+ */
+export declare const MIXAMO_SCHEME: RigScheme;
+/**
+ * Quaternius sci-fi aliens: a `Root` plus a `Spine_1..Spine_6` chain, a `Neck` and a `Head`. The
+ * pack ships no arms and no legs, so those slots stay empty and the alien can only be driven on
+ * its spine and head. That is the honest mapping: the pack's own clip set is `Alien_Idle` alone.
+ */
+export declare const QUATERNIUS_ALIEN_SCHEME: RigScheme;
+/** Every scheme the engine ships a mapping for, keyed by {@link RigScheme.id}. */
+export declare const RIG_SCHEMES: Readonly<Record<string, RigScheme>>;
+/**
+ * The runtime name GLTFLoader gives an authored bone name: three's `PropertyBinding.sanitizeNodeName`
+ * strips `[ ] . : /`, so the authored `upperleg.l` loads as `upperlegl`.
+ *
+ * @capability skeleton-standard convert an authored bone name to its loaded runtime name
+ */
+export declare function runtimeBoneName(authored: string): string;
+/** The result of mapping a rig's bones onto {@link SKELETON_STANDARD}. */
+export interface SkeletonMap {
+    /** Scheme the map was built from. */
+    scheme: string;
+    /** Standard slot → the bone name on this rig that fills it. */
+    slots: Partial<Record<SkeletonSlot, string>>;
+    /** Slots the standard defines that this rig has no bone for. */
+    missing: SkeletonSlot[];
+    /** Bones on the rig that fill no standard slot (helpers, props, IK targets). */
+    unmapped: string[];
+}
+/**
+ * Maps a rig's bone names onto {@link SKELETON_STANDARD} through one {@link RigScheme}. Each slot
+ * takes the first candidate that resolves; a candidate list is tried in order, so a scheme can name
+ * a preferred bone and fall back. Bones that fill no slot come back in `unmapped`, and slots the rig
+ * cannot fill in `missing` — the caller decides whether a partial map is usable.
+ *
+ * @capability skeleton-standard map any CC0 rig's bones onto the shared humanoid slots
+ */
+export declare function mapRigToStandard(bones: readonly string[], scheme?: RigScheme | string): SkeletonMap;
+/** A standard slot and the rest-pose length of the bone chain that reaches it. */
+export interface SlotLength {
+    slot: SkeletonSlot;
+    /** Distance from the slot's bone to its parent bone, in the rig's own units. */
+    length: number;
+}
+/**
+ * Per-slot length ratios that stretch a source rig's bone chain onto the standard's proportions, so
+ * a retargeted clip moves both rigs the same distance rather than the same angle. Slots with no
+ * counterpart on either side are omitted; a source length of zero is skipped instead of dividing.
+ *
+ * @capability skeleton-standard scale a retargeted clip to the target rig's bone proportions
+ */
+export declare function retargetBoneScales(source: readonly SlotLength[], target: readonly SlotLength[]): Partial<Record<SkeletonSlot, number>>;
+/**
+ * Bone-name prefixes for a set of standard slots, for an {@link AnimLayer.mask}. A slot on one side
+ * contributes its side-less prefix (`upperLeg.l` → `upperleg`), which matches both sides' tracks; an
+ * unsided slot contributes its own runtime name. Masking by slot means a rig mapped onto the
+ * standard is masked without hand-typing its bone names.
+ *
+ * @capability skeleton-standard build a layer mask from the standard's own slots
+ */
+export declare function standardBoneMask(slots: readonly SkeletonSlot[]): string[];
+/** Standard slots an upper-body action layer drives: spine, chest, head and both arms. */
+export declare const UPPER_BODY_SLOTS: readonly SkeletonSlot[];
+/** Standard slots a lower-body layer drives: hips, both legs and both feet. */
+export declare const LOWER_BODY_SLOTS: readonly SkeletonSlot[];
+/** Layer mask for an upper-body action layer (aim, reload, hit reaction) on a standard rig. */
+export declare const UPPER_BODY_MASK: readonly string[];
+/** Layer mask for a lower-body layer on a standard rig. */
+export declare const LOWER_BODY_MASK: readonly string[];
+/**
+ * Renames a clip's tracks from a rig's own bone names onto the standard's, so one authored clip
+ * plays on a mapped rig. The emitted node is the **runtime** bone name (see {@link runtimeBoneName}),
+ * which is what both the loaded scene graph and the loaded clips spell. A track whose node fills no
+ * slot is dropped (`null` in the result) rather than left pointing at a bone the rig does not have;
+ * a track whose property is not one of the four three writes is dropped too, since renaming it
+ * would not make it resolvable.
+ *
+ * @capability skeleton-standard rename an animation clip's tracks onto a mapped rig
+ */
+export declare function retargetTracks(tracks: readonly string[], map: SkeletonMap): (string | null)[];