@jgengine/core 0.18.1 → 0.21.0

package/dist/anim/animGraph.js

@@ -1,3 +1,4 @@
+import { resolveOneShotClip } from "../game/modelAnimation.js";
 const DEFAULT_FADE = 0.2;
 /** Entity blackboard key the shell reads extra graph parameters from: `ctx.scene.entity.blackboard.set(id, ANIM_PARAMS_KEY, { aiming: true })`. */
 export const ANIM_PARAMS_KEY = "anim.params";
@@ -126,7 +127,7 @@ function clipTimeFor(time, duration, loop) {
  *
  * @capability anim-graph data-first animation state machine with blend trees, crossfades, layers, and clip events
  */
-export function createAnimGraphRuntime(initial) {
+export function createAnimGraphRuntime(initial, options = {}) {
     let graph = initial;
     let triggers = new Set();
     let layers = {};
@@ -136,6 +137,14 @@ export function createAnimGraphRuntime(initial) {
             layers[layer.id] = { current: layer.entry, time: 0, transition: null };
     }
     reset();
+    function chooseClip(state, def) {
+        if (def.kind === "clip" && def.variants !== undefined && def.variants.length > 0) {
+            state.selectedClip = resolveOneShotClip({ choice: def.variants }, "choice", options.rng?.() ?? 0) ?? def.clip;
+        }
+        else {
+            delete state.selectedClip;
+        }
+    }
     function pickTransition(layer, state, params, normalized) {
         for (const transition of layer.transitions) {
             if (transition.from !== "*" && transition.from !== state.current)
@@ -162,8 +171,7 @@ export function createAnimGraphRuntime(initial) {
                 continue;
             const at = event.atSec;
             if (loop) {
-                const wrapped = after < before;
-                const hit = wrapped ? at > before || at <= after : at > before && at <= after;
+                const hit = at >= 0 && at <= duration && Math.floor((after - at) / duration) > Math.floor((before - at) / duration);
                 if (hit)
                     out.push({ name: event.name, clip });
             }
@@ -197,6 +205,7 @@ export function createAnimGraphRuntime(initial) {
         advance(dt, params, clips) {
             const output = { clips: [], events: [] };
             const rootDelta = [0, 0, 0];
+            let rootMotion = false;
             for (const layer of graph.layers) {
                 const state = layers[layer.id];
                 if (state === undefined)
@@ -204,16 +213,24 @@ export function createAnimGraphRuntime(initial) {
                 const def = layer.states[state.current];
                 if (def === undefined)
                     continue;
+                if (def.kind === "clip" && def.variants !== undefined && state.selectedClip === undefined)
+                    chooseClip(state, def);
                 const layerWeight = layer.weight ?? 1;
+                if (def.rootMotion === true && layerWeight > 0)
+                    rootMotion = true;
                 const before = state.time;
                 state.time += dt * stateSpeed(def);
-                const weights = stateClipWeights(def, params);
+                const weights = def.kind === "clip" && state.selectedClip !== undefined && def.variants?.includes(state.selectedClip)
+                    ? { [state.selectedClip]: 1 }
+                    : stateClipWeights(def, params);
                 const duration = stateDuration(weights, clips);
                 const loop = stateLoops(def);
                 const normalized = duration > 0 ? (loop ? (state.time % duration) / duration : Math.min(1, state.time / duration)) : 1;
                 for (const clip of Object.keys(weights)) {
+                    if (!(weights[clip] * layerWeight > 0))
+                        continue;
                     const duration = clipDuration(clips[clip]);
-                    collectEvents(output.events, clip, clipTimeFor(before, duration, loop), clipTimeFor(state.time, duration, loop), duration, loop);
+                    collectEvents(output.events, clip, before, state.time, duration, loop);
                     if (def.rootMotion) {
                         const info = clips[clip];
                         if (typeof info !== "number" && info?.rootTrack !== undefined) {
@@ -232,7 +249,13 @@ export function createAnimGraphRuntime(initial) {
                     const times = {};
                     for (const [clip, w] of Object.entries(transition.fromWeights)) {
                         merged[clip] = (merged[clip] ?? 0) + w * (1 - t);
-                        times[clip] = transition.fromTimes[clip] ?? 0;
+                        const playback = transition.fromPlayback?.[clip];
+                        if (w * (1 - t) * layerWeight > 0 && playback?.rootMotion === true)
+                            rootMotion = true;
+                        const time = transition.fromTimes[clip] ?? 0;
+                        const nextTime = playback === undefined ? time : clipTimeFor(time + dt * playback.speed, clipDuration(clips[clip]), playback.loop);
+                        transition.fromTimes[clip] = nextTime;
+                        times[clip] = nextTime;
                     }
                     for (const [clip, w] of Object.entries(weights)) {
                         merged[clip] = (merged[clip] ?? 0) + w * t;
@@ -254,33 +277,326 @@ export function createAnimGraphRuntime(initial) {
                     }
                 }
                 const next = pickTransition(layer, state, params, normalized);
-                if (next !== null && next.to !== state.current) {
+                if (next !== null) {
                     const fromWeights = {};
                     const fromTimes = {};
+                    const fromPlayback = {};
                     for (const entry of output.clips) {
                         if (entry.layer !== layer.id)
                             continue;
                         fromWeights[entry.clip] = (fromWeights[entry.clip] ?? 0) + entry.weight / (layerWeight || 1);
                         fromTimes[entry.clip] = entry.time;
+                        const previous = transition?.fromPlayback?.[entry.clip];
+                        const outgoingRoot = previous?.rootMotion === true && transition !== null &&
+                            transition.duration > 0 && transition.elapsed < transition.duration &&
+                            (transition.fromWeights[entry.clip] ?? 0) > 0;
+                        const playback = weights[entry.clip] === undefined && previous !== undefined
+                            ? previous : { speed: stateSpeed(def), loop };
+                        // Same-clip states share one clock, but an interrupted fade must retain either
+                        // influencing source's in-place policy until that source leaves the pose.
+                        fromPlayback[entry.clip] = { ...playback, ...(def.rootMotion === true || outgoingRoot ? { rootMotion: true } : {}) };
                     }
                     state.current = next.to;
                     state.time = 0;
+                    const target = layer.states[next.to];
+                    if (target !== undefined)
+                        chooseClip(state, target);
                     state.transition = {
                         to: next.to,
                         elapsed: 0,
                         duration: next.duration ?? DEFAULT_FADE,
                         fromWeights,
                         fromTimes,
+                        fromPlayback,
                     };
                 }
-                else if (next !== null && next.to === state.current) {
-                    state.time = 0;
-                }
             }
             triggers.clear();
             if (rootDelta[0] !== 0 || rootDelta[1] !== 0 || rootDelta[2] !== 0)
                 output.rootDelta = rootDelta;
+            if (rootMotion)
+                output.rootMotion = true;
             return output;
         },
     };
 }
+const COMPARES = [">", "<", ">=", "<=", "==", "!="];
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function optionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function parseState(value) {
+    const raw = record(value);
+    if (raw === null)
+        return null;
+    const extra = {
+        ...(optionalNumber(raw.speed) === undefined ? {} : { speed: raw.speed }),
+        ...(typeof raw.loop === "boolean" ? { loop: raw.loop } : {}),
+        ...(typeof raw.rootMotion === "boolean" ? { rootMotion: raw.rootMotion } : {}),
+    };
+    if (raw.kind === "clip" && typeof raw.clip === "string") {
+        const variants = Array.isArray(raw.variants) ? raw.variants.filter((clip) => typeof clip === "string" && clip.length > 0) : undefined;
+        return { kind: "clip", clip: raw.clip, ...(variants === undefined || variants.length === 0 ? {} : { variants }), ...extra };
+    }
+    if (!Array.isArray(raw.points))
+        return null;
+    if (raw.kind === "blend1D" && typeof raw.param === "string") {
+        const points = raw.points.flatMap((point) => {
+            const entry = record(point);
+            return entry !== null && typeof entry.clip === "string" && optionalNumber(entry.at) !== undefined ? [{ at: entry.at, clip: entry.clip }] : [];
+        });
+        return { kind: "blend1D", param: raw.param, points, ...extra };
+    }
+    if (raw.kind === "blend2D" && Array.isArray(raw.params) && raw.params.length === 2 && raw.params.every((param) => typeof param === "string")) {
+        const points = raw.points.flatMap((point) => {
+            const entry = record(point);
+            const at = entry?.at;
+            return entry !== null && typeof entry.clip === "string" && Array.isArray(at) && at.length === 2 && at.every((n) => optionalNumber(n) !== undefined)
+                ? [{ at: [at[0], at[1]], clip: entry.clip }]
+                : [];
+        });
+        return { kind: "blend2D", params: [raw.params[0], raw.params[1]], points, ...extra };
+    }
+    return null;
+}
+function parseTransition(value, states) {
+    const raw = record(value);
+    if (raw === null || typeof raw.from !== "string" || typeof raw.to !== "string")
+        return null;
+    if (states[raw.to] === undefined || (raw.from !== "*" && states[raw.from] === undefined))
+        return null;
+    const when = Array.isArray(raw.when)
+        ? raw.when.flatMap((condition) => {
+            const entry = record(condition);
+            return entry !== null &&
+                typeof entry.param === "string" &&
+                COMPARES.includes(entry.op) &&
+                (typeof entry.value === "number" || typeof entry.value === "boolean")
+                ? [{ param: entry.param, op: entry.op, value: entry.value }]
+                : [];
+        })
+        : undefined;
+    return {
+        from: raw.from,
+        to: raw.to,
+        ...(when === undefined || when.length === 0 ? {} : { when }),
+        ...(typeof raw.trigger === "string" ? { trigger: raw.trigger } : {}),
+        ...(optionalNumber(raw.duration) === undefined ? {} : { duration: Math.max(0, raw.duration) }),
+        ...(optionalNumber(raw.exitTime) === undefined ? {} : { exitTime: raw.exitTime }),
+    };
+}
+/**
+ * Validates untrusted JSON (a saved scene document, a network payload) as an {@link AnimGraph}.
+ * Malformed states, transitions to unknown states, and bad conditions are dropped; a layer whose
+ * entry state is missing is dropped; the result is `undefined` when no layer survives.
+ *
+ * @capability anim-graph load an animation graph from saved JSON without trusting its shape
+ */
+export function parseAnimGraph(value) {
+    const raw = record(value);
+    if (raw === null || !Array.isArray(raw.layers))
+        return undefined;
+    const layers = [];
+    const seen = new Set();
+    for (const candidate of raw.layers) {
+        const layer = record(candidate);
+        if (layer === null || typeof layer.id !== "string" || seen.has(layer.id) || typeof layer.entry !== "string")
+            continue;
+        const rawStates = record(layer.states);
+        if (rawStates === null)
+            continue;
+        const states = {};
+        for (const [name, state] of Object.entries(rawStates)) {
+            const parsed = parseState(state);
+            if (parsed !== null)
+                states[name] = parsed;
+        }
+        if (states[layer.entry] === undefined)
+            continue;
+        const transitions = Array.isArray(layer.transitions)
+            ? layer.transitions.flatMap((transition) => {
+                const parsed = parseTransition(transition, states);
+                return parsed === null ? [] : [parsed];
+            })
+            : [];
+        const mask = Array.isArray(layer.mask) ? layer.mask.filter((prefix) => typeof prefix === "string") : undefined;
+        seen.add(layer.id);
+        layers.push({
+            id: layer.id,
+            entry: layer.entry,
+            states,
+            transitions,
+            ...(mask === undefined ? {} : { mask }),
+            ...(typeof layer.additive === "boolean" ? { additive: layer.additive } : {}),
+            ...(optionalNumber(layer.weight) === undefined ? {} : { weight: Math.min(1, Math.max(0, layer.weight)) }),
+        });
+    }
+    if (layers.length === 0)
+        return undefined;
+    const events = Array.isArray(raw.events)
+        ? raw.events.flatMap((event) => {
+            const entry = record(event);
+            return entry !== null && typeof entry.clip === "string" && typeof entry.name === "string" && optionalNumber(entry.atSec) !== undefined
+                ? [{ clip: entry.clip, atSec: entry.atSec, name: entry.name }]
+                : [];
+        })
+        : [];
+    return { layers, ...(events.length === 0 ? {} : { events }) };
+}
+/**
+ * Validate an authored graph without dropping broken combat states or weakening transition conditions.
+ * Known malformed fields and dangling references reject the whole graph with relative repair locations;
+ * valid data, including authored object/array order, is returned unchanged. Unknown extension fields are
+ * retained. Clip availability belongs to the imported-rig diagnostics. Use {@link parseAnimGraph} when
+ * permissive repair is intentional.
+ * @capability anim-graph validate authored animation graphs with located repair diagnostics without partial fallback
+ */
+export function validateAnimGraph(value) {
+    const diagnostics = [];
+    const issue = (path, message, repair) => { diagnostics.push({ path, message, repair }); };
+    const field = (path, key) => path === "" ? key : /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+    const object = (candidate, path) => {
+        const raw = record(candidate);
+        if (raw === null)
+            issue(path, "Expected an animation graph object.", "Supply an object with the supported fields.");
+        return raw;
+    };
+    const text = (candidate, path, empty = false) => {
+        if (typeof candidate === "string" && (empty || candidate.trim().length > 0))
+            return true;
+        issue(path, "Expected a nonempty string.", "Set an explicit name from this graph or imported rig.");
+        return false;
+    };
+    const number = (candidate, path, min = -Infinity, max = Infinity) => {
+        if (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= min && candidate <= max)
+            return true;
+        issue(path, `Expected a finite number${min === -Infinity && max === Infinity ? "" : max === Infinity ? ` at least ${min}` : ` between ${min} and ${max}`}.`, "Set a finite value in the supported range.");
+        return false;
+    };
+    const boolean = (candidate, path) => {
+        if (typeof candidate !== "boolean")
+            issue(path, "Expected a boolean.", "Set true or false, or omit the optional field.");
+    };
+    const array = (candidate, path) => {
+        if (Array.isArray(candidate))
+            return candidate;
+        issue(path, "Expected an array.", "Supply an array of supported entries.");
+        return null;
+    };
+    const tuple = (candidate, path, numeric) => {
+        const entries = array(candidate, path);
+        if (entries === null)
+            return;
+        if (entries.length !== 2)
+            issue(path, "Expected exactly two entries.", "Supply the two blend axes in authored order.");
+        entries.forEach((entry, index) => numeric ? number(entry, `${path}[${index}]`) : text(entry, `${path}[${index}]`));
+    };
+    const state = (candidate, path) => {
+        const raw = object(candidate, path);
+        if (raw === null)
+            return;
+        if (!["clip", "blend1D", "blend2D"].includes(raw.kind)) {
+            issue(`${path}.kind`, "Unknown animation state kind.", "Choose clip, blend1D or blend2D.");
+            return;
+        }
+        if (raw.speed !== undefined)
+            number(raw.speed, `${path}.speed`);
+        for (const key of ["loop", "rootMotion"])
+            if (raw[key] !== undefined)
+                boolean(raw[key], `${path}.${key}`);
+        const allowed = raw.kind === "clip" ? ["clip", "variants"] : raw.kind === "blend1D" ? ["param", "points"] : ["params", "points"];
+        for (const key of ["clip", "variants", "param", "params", "points"])
+            if (raw[key] !== undefined && !allowed.includes(key)) {
+                issue(`${path}.${key}`, `Field ${key} is not used by a ${raw.kind} state.`, "Remove the field or choose the matching state kind.");
+            }
+        if (raw.kind === "clip") {
+            text(raw.clip, `${path}.clip`);
+            if (raw.variants !== undefined)
+                array(raw.variants, `${path}.variants`)?.forEach((clip, index) => text(clip, `${path}.variants[${index}]`));
+            return;
+        }
+        if (raw.kind === "blend1D")
+            text(raw.param, `${path}.param`);
+        else
+            tuple(raw.params, `${path}.params`, false);
+        array(raw.points, `${path}.points`)?.forEach((candidate, index) => {
+            const pointPath = `${path}.points[${index}]`, point = object(candidate, pointPath);
+            if (point === null)
+                return;
+            text(point.clip, `${pointPath}.clip`);
+            if (raw.kind === "blend1D")
+                number(point.at, `${pointPath}.at`);
+            else
+                tuple(point.at, `${pointPath}.at`, true);
+        });
+    };
+    const raw = object(value, "");
+    if (raw === null)
+        return { graph: undefined, diagnostics };
+    const layers = array(raw.layers, "layers"), seen = new Set();
+    if (layers?.length === 0)
+        issue("layers", "An animation graph needs at least one layer.", "Add a layer with an entry state.");
+    layers?.forEach((candidate, index) => {
+        const path = `layers[${index}]`, layer = object(candidate, path);
+        if (layer === null)
+            return;
+        if (text(layer.id, `${path}.id`)) {
+            if (seen.has(layer.id))
+                issue(`${path}.id`, "Layer id is duplicated.", "Give each layer a distinct id.");
+            seen.add(layer.id);
+        }
+        const validEntry = text(layer.entry, `${path}.entry`), states = object(layer.states, `${path}.states`);
+        if (states !== null) {
+            for (const [name, candidate] of Object.entries(states)) {
+                text(name, field(`${path}.states`, name));
+                state(candidate, field(`${path}.states`, name));
+            }
+            if (validEntry && !Object.hasOwn(states, layer.entry))
+                issue(`${path}.entry`, "Entry state does not exist in this layer.", "Choose a state declared in this layer.");
+        }
+        if (layer.weight !== undefined)
+            number(layer.weight, `${path}.weight`, 0, 1);
+        if (layer.additive !== undefined)
+            boolean(layer.additive, `${path}.additive`);
+        if (layer.mask !== undefined)
+            array(layer.mask, `${path}.mask`)?.forEach((prefix, i) => text(prefix, `${path}.mask[${i}]`, true));
+        array(layer.transitions, `${path}.transitions`)?.forEach((candidate, i) => {
+            const edgePath = `${path}.transitions[${i}]`, edge = object(candidate, edgePath);
+            if (edge === null)
+                return;
+            for (const key of ["from", "to"])
+                if (text(edge[key], `${edgePath}.${key}`) && states !== null && !(key === "from" && edge[key] === "*") && !Object.hasOwn(states, edge[key])) {
+                    issue(`${edgePath}.${key}`, "Transition references an unknown state.", "Choose a state declared in this layer; only from may use *.");
+                }
+            if (edge.trigger !== undefined)
+                text(edge.trigger, `${edgePath}.trigger`);
+            if (edge.duration !== undefined)
+                number(edge.duration, `${edgePath}.duration`, 0);
+            if (edge.exitTime !== undefined)
+                number(edge.exitTime, `${edgePath}.exitTime`);
+            if (edge.when !== undefined)
+                array(edge.when, `${edgePath}.when`)?.forEach((candidate, i) => {
+                    const conditionPath = `${edgePath}.when[${i}]`, condition = object(candidate, conditionPath);
+                    if (condition === null)
+                        return;
+                    text(condition.param, `${conditionPath}.param`);
+                    if (!COMPARES.includes(condition.op))
+                        issue(`${conditionPath}.op`, "Unknown comparison operator.", "Choose >, <, >=, <=, == or !=.");
+                    if (typeof condition.value !== "boolean")
+                        number(condition.value, `${conditionPath}.value`);
+                });
+        });
+    });
+    if (raw.events !== undefined)
+        array(raw.events, "events")?.forEach((candidate, index) => {
+            const path = `events[${index}]`, event = object(candidate, path);
+            if (event === null)
+                return;
+            text(event.clip, `${path}.clip`);
+            text(event.name, `${path}.name`);
+            number(event.atSec, `${path}.atSec`, 0);
+        });
+    return { graph: diagnostics.length === 0 ? value : undefined, diagnostics };
+}

package/dist/anim/boneTexture.d.ts

@@ -0,0 +1,55 @@
+/** A clip to bake: its name and length in seconds. */
+export interface BoneTextureClipInput {
+    name: string;
+    duration: number;
+}
+/** One baked clip's rows in a {@link BoneTextureLayout}. */
+export interface BoneTextureClip {
+    name: string;
+    /** First texture row of the clip. */
+    startFrame: number;
+    /** Rows baked for the clip, first and last pose included. */
+    frameCount: number;
+    duration: number;
+}
+/**
+ * Where every bone matrix of every baked frame lives in a vertex-animation texture: one row per
+ * frame, four RGBA texels (matrix columns) per bone. Plain data, so a baked crowd can be cached,
+ * shipped or checked in a test without a renderer.
+ */
+export interface BoneTextureLayout {
+    boneCount: number;
+    fps: number;
+    width: number;
+    height: number;
+    clips: BoneTextureClip[];
+}
+/** Inputs for {@link planBoneTexture}. */
+export interface BoneTextureInput {
+    boneCount: number;
+    clips: readonly BoneTextureClipInput[];
+    /** Baked samples per second. Default 30. */
+    fps?: number;
+    /** Largest texture side the target GPU accepts. Default 4096. */
+    maxTextureSize?: number;
+}
+/**
+ * Plans a bone-matrix texture for a rig's clips. Throws when the rig or the clip set does not fit
+ * `maxTextureSize`; lower `fps` or bake fewer clips.
+ *
+ * @capability animation bake many clips of a rig into one bone-matrix texture for instanced crowds
+ */
+export declare function planBoneTexture(input: BoneTextureInput): BoneTextureLayout;
+/** Two texture rows around a playback time and the blend between them. */
+export interface BoneTextureSample {
+    rowA: number;
+    rowB: number;
+    t: number;
+}
+/**
+ * Finds the baked rows around `time` in a clip, wrapping when `loop` and holding the last pose
+ * otherwise. This is the CPU mirror of the crowd shader's lookup.
+ *
+ * @capability animation look up the baked frames and blend for a crowd member's playback time
+ */
+export declare function sampleBoneTexture(clip: BoneTextureClip, fps: number, time: number, loop: boolean, out?: BoneTextureSample): BoneTextureSample;

package/dist/anim/boneTexture.js

@@ -0,0 +1,43 @@
+/**
+ * Plans a bone-matrix texture for a rig's clips. Throws when the rig or the clip set does not fit
+ * `maxTextureSize`; lower `fps` or bake fewer clips.
+ *
+ * @capability animation bake many clips of a rig into one bone-matrix texture for instanced crowds
+ */
+export function planBoneTexture(input) {
+    const fps = input.fps ?? 30;
+    const maxSize = input.maxTextureSize ?? 4096;
+    if (!(fps > 0))
+        throw new Error(`planBoneTexture: fps must be positive, got ${fps}`);
+    const width = Math.max(1, input.boneCount) * 4;
+    if (width > maxSize)
+        throw new Error(`planBoneTexture: ${input.boneCount} bones need ${width} texels per row, over the ${maxSize} limit`);
+    const clips = [];
+    let row = 0;
+    for (const clip of input.clips) {
+        const duration = Math.max(0, clip.duration);
+        const frameCount = Math.max(2, Math.ceil(duration * fps) + 1);
+        clips.push({ name: clip.name, startFrame: row, frameCount, duration });
+        row += frameCount;
+    }
+    if (row > maxSize)
+        throw new Error(`planBoneTexture: ${row} frames exceed the ${maxSize}-row limit; lower fps or bake fewer clips`);
+    return { boneCount: input.boneCount, fps, width, height: Math.max(1, row), clips };
+}
+/**
+ * Finds the baked rows around `time` in a clip, wrapping when `loop` and holding the last pose
+ * otherwise. This is the CPU mirror of the crowd shader's lookup.
+ *
+ * @capability animation look up the baked frames and blend for a crowd member's playback time
+ */
+export function sampleBoneTexture(clip, fps, time, loop, out) {
+    const result = out ?? { rowA: 0, rowB: 0, t: 0 };
+    const span = clip.frameCount - 1;
+    const raw = time * fps;
+    const frame = loop ? ((raw % span) + span) % span : Math.min(Math.max(raw, 0), span);
+    const a = Math.floor(frame);
+    result.rowA = clip.startFrame + a;
+    result.rowB = clip.startFrame + Math.min(a + 1, span);
+    result.t = frame - a;
+    return result;
+}

package/dist/anim/footPlacement.d.ts

@@ -0,0 +1,57 @@
+/** One foot's animated ankle height and the ground found under it, both in world units. */
+export interface FootGroundSample {
+    /** Animated ankle (foot bone) height this frame, before any correction. */
+    ankleY: number;
+    /** Ground height under the foot, or `null` when the probe found nothing. */
+    groundY: number | null;
+}
+/** Inputs for {@link placeFeet}. All heights are world units. */
+export interface FootPlacementInput {
+    feet: readonly FootGroundSample[];
+    /** Height of the model origin, which the clips were authored to stand on. */
+    originY: number;
+    /** Ankle height above the sole in the rig's rest pose; the sole never ends below the ground. */
+    ankleHeight: number;
+    /** Largest correction applied to a foot or the pelvis, up or down. */
+    maxAdjust: number;
+    /** A lowest sole this far above its ground reads as airborne. */
+    airborneGap: number;
+}
+/** Result of {@link placeFeet}: where each ankle should go and how far the pelvis drops. */
+export interface FootPlacement {
+    /** Vertical pelvis shift, `<= 0`, so the lowest planted foot can reach its ground. */
+    pelvisOffset: number;
+    /** Target ankle height per foot, or `null` when that foot has no ground or no correction. */
+    ankleTargets: (number | null)[];
+    /** `false` while the feet are clear of the ground, so callers fade the correction out. */
+    grounded: boolean;
+}
+/**
+ * Resolves foot placement for a rig whose clips were authored on flat ground at its origin.
+ * Each foot keeps its animated lift and moves by its ground's height above or below the origin,
+ * the sole is never left under the ground, and the pelvis drops by the deepest reach so both legs
+ * stay within length. Pure and allocation-light; the renderer applies the targets with
+ * {@link solveTwoBone}.
+ *
+ * @capability animation ground rigged feet on slopes and steps without hiding the swing leg
+ */
+export declare function placeFeet(input: FootPlacementInput, out?: FootPlacement): FootPlacement;
+/** A bone as {@link inferLegChains} sees it: its name and its parent's name. */
+export interface RigBone {
+    name: string;
+    parent: string | null;
+}
+/** Thigh → shin → foot bone names for one leg. */
+export interface LegChain {
+    root: string;
+    mid: string;
+    tip: string;
+}
+/**
+ * Finds leg chains on a humanoid rig by bone name: a thigh-like bone (`UpLeg`, `UpperLeg`, `Thigh`)
+ * with its first child and grandchild as shin and foot. Control, IK-target and twist bones are
+ * skipped. Returns chains in rig order; an empty array means the rig has no recognizable legs.
+ *
+ * @capability animation find thigh, shin and foot bones on a humanoid rig for foot IK
+ */
+export declare function inferLegChains(bones: readonly RigBone[]): LegChain[];

package/dist/anim/footPlacement.js

@@ -0,0 +1,67 @@
+function clamp(value, limit) {
+    return Math.max(-limit, Math.min(limit, value));
+}
+/**
+ * Resolves foot placement for a rig whose clips were authored on flat ground at its origin.
+ * Each foot keeps its animated lift and moves by its ground's height above or below the origin,
+ * the sole is never left under the ground, and the pelvis drops by the deepest reach so both legs
+ * stay within length. Pure and allocation-light; the renderer applies the targets with
+ * {@link solveTwoBone}.
+ *
+ * @capability animation ground rigged feet on slopes and steps without hiding the swing leg
+ */
+export function placeFeet(input, out) {
+    const result = out ?? { pelvisOffset: 0, ankleTargets: [], grounded: false };
+    result.ankleTargets.length = input.feet.length;
+    const limit = Math.max(0, input.maxAdjust);
+    let lowestGap = Infinity;
+    let pelvis = 0;
+    for (let i = 0; i < input.feet.length; i += 1) {
+        const foot = input.feet[i];
+        if (foot.groundY === null) {
+            result.ankleTargets[i] = null;
+            continue;
+        }
+        lowestGap = Math.min(lowestGap, foot.ankleY - input.ankleHeight - foot.groundY);
+        const followed = foot.ankleY + clamp(foot.groundY - input.originY, limit);
+        const target = Math.min(foot.ankleY + limit, Math.max(followed, foot.groundY + input.ankleHeight));
+        result.ankleTargets[i] = target;
+        pelvis = Math.min(pelvis, target - foot.ankleY);
+    }
+    result.grounded = lowestGap <= input.airborneGap;
+    result.pelvisOffset = result.grounded ? Math.max(-limit, pelvis) : 0;
+    return result;
+}
+const THIGH = /(upleg|upperleg|thigh|femur)/;
+const HELPER = /(ik|control|ctrl|twist|pole|target|roll)/;
+/**
+ * Finds leg chains on a humanoid rig by bone name: a thigh-like bone (`UpLeg`, `UpperLeg`, `Thigh`)
+ * with its first child and grandchild as shin and foot. Control, IK-target and twist bones are
+ * skipped. Returns chains in rig order; an empty array means the rig has no recognizable legs.
+ *
+ * @capability animation find thigh, shin and foot bones on a humanoid rig for foot IK
+ */
+export function inferLegChains(bones) {
+    const children = new Map();
+    for (const bone of bones) {
+        if (bone.parent === null)
+            continue;
+        const list = children.get(bone.parent);
+        if (list === undefined)
+            children.set(bone.parent, [bone.name]);
+        else
+            list.push(bone.name);
+    }
+    const firstChild = (name) => children.get(name)?.find((child) => !HELPER.test(child.toLowerCase()));
+    const chains = [];
+    for (const bone of bones) {
+        const key = bone.name.toLowerCase().replace(/[^a-z0-9]/g, "");
+        if (!THIGH.test(key) || HELPER.test(key))
+            continue;
+        const mid = firstChild(bone.name);
+        const tip = mid === undefined ? undefined : firstChild(mid);
+        if (mid !== undefined && tip !== undefined)
+            chains.push({ root: bone.name, mid, tip });
+    }
+    return chains;
+}