@jgengine/core 0.18.0 → 0.19.0

package/dist/anim/animGraph.js

@@ -0,0 +1,414 @@
+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";
+function compare(actual, op, value) {
+    const a = actual === undefined ? 0 : Number(actual);
+    const b = Number(value);
+    switch (op) {
+        case ">":
+            return a > b;
+        case "<":
+            return a < b;
+        case ">=":
+            return a >= b;
+        case "<=":
+            return a <= b;
+        case "==":
+            return a === b;
+        case "!=":
+            return a !== b;
+    }
+}
+/** Static clip weights of a state at `params`, before any crossfade. */
+export function stateClipWeights(state, params) {
+    const out = {};
+    if (state.kind === "clip") {
+        out[state.clip] = 1;
+        return out;
+    }
+    if (state.kind === "blend1D") {
+        const points = [...state.points].sort((x, y) => x.at - y.at);
+        if (points.length === 0)
+            return out;
+        const value = Number(params[state.param] ?? 0);
+        if (value <= points[0].at) {
+            out[points[0].clip] = 1;
+            return out;
+        }
+        const last = points[points.length - 1];
+        if (value >= last.at) {
+            out[last.clip] = 1;
+            return out;
+        }
+        for (let i = 0; i + 1 < points.length; i += 1) {
+            const lo = points[i];
+            const hi = points[i + 1];
+            if (value >= lo.at && value <= hi.at) {
+                const t = hi.at === lo.at ? 0 : (value - lo.at) / (hi.at - lo.at);
+                out[lo.clip] = (out[lo.clip] ?? 0) + (1 - t);
+                out[hi.clip] = (out[hi.clip] ?? 0) + t;
+                return out;
+            }
+        }
+        return out;
+    }
+    const x = Number(params[state.params[0]] ?? 0);
+    const y = Number(params[state.params[1]] ?? 0);
+    let total = 0;
+    const raw = [];
+    for (const point of state.points) {
+        const dx = point.at[0] - x;
+        const dy = point.at[1] - y;
+        const d2 = dx * dx + dy * dy;
+        if (d2 < 1e-9) {
+            out[point.clip] = 1;
+            return out;
+        }
+        const w = 1 / d2;
+        raw.push({ clip: point.clip, w });
+        total += w;
+    }
+    for (const entry of raw)
+        out[entry.clip] = (out[entry.clip] ?? 0) + entry.w / total;
+    return out;
+}
+function stateSpeed(state) {
+    return state.speed ?? 1;
+}
+function stateLoops(state) {
+    return state.loop !== false;
+}
+/** Longest clip in a state at these weights; the state's timeline length for exit times and events. */
+function stateDuration(weights, clips) {
+    let duration = 0;
+    for (const clip of Object.keys(weights))
+        duration = Math.max(duration, clipDuration(clips[clip]));
+    return duration;
+}
+function clipDuration(info) {
+    return typeof info === "number" ? info : info?.duration ?? 0;
+}
+function rootPosition(track, time, duration, loop) {
+    const count = Math.min(track.times.length, Math.floor(track.values.length / 3));
+    if (count === 0)
+        return [0, 0, 0];
+    const first = track.times[0] ?? 0;
+    const last = track.times[count - 1] ?? first;
+    const cycle = loop && duration > 0 ? Math.floor(time / duration) : 0;
+    const local = loop && duration > 0 ? ((time % duration) + duration) % duration : Math.min(Math.max(time, first), last);
+    let i = 0;
+    while (i + 1 < count && (track.times[i + 1] ?? 0) <= local)
+        i += 1;
+    const next = Math.min(i + 1, count - 1);
+    const span = (track.times[next] ?? 0) - (track.times[i] ?? 0);
+    const t = next === i || span <= 0 ? 0 : (local - (track.times[i] ?? 0)) / span;
+    const out = [0, 0, 0];
+    for (let axis = 0; axis < 3; axis += 1) {
+        const a = track.values[i * 3 + axis] ?? 0;
+        const b = track.values[next * 3 + axis] ?? a;
+        const cycleOffset = loop && duration > 0 ? ((track.values[(count - 1) * 3 + axis] ?? 0) - (track.values[axis] ?? 0)) * cycle : 0;
+        out[axis] = a + (b - a) * t + cycleOffset;
+    }
+    return out;
+}
+function clipTimeFor(time, duration, loop) {
+    if (!(duration > 0))
+        return 0;
+    if (loop)
+        return time % duration;
+    return Math.min(time, duration);
+}
+/**
+ * Headless animation state machine and blend evaluator. It owns every clip's playback time and weight, so the
+ * renderer only seeks and weights actions on a mixer, and headless hosts, replays, and tests advance the same
+ * graph without three.js. Transitions are data (parameter comparisons and consumed triggers), layers can be
+ * masked or additive, and events fire by clip time, including across loop wraps.
+ *
+ * @capability anim-graph data-first animation state machine with blend trees, crossfades, layers, and clip events
+ */
+export function createAnimGraphRuntime(initial) {
+    let graph = initial;
+    let triggers = new Set();
+    let layers = {};
+    function reset() {
+        layers = {};
+        for (const layer of graph.layers)
+            layers[layer.id] = { current: layer.entry, time: 0, transition: null };
+    }
+    reset();
+    function pickTransition(layer, state, params, normalized) {
+        for (const transition of layer.transitions) {
+            if (transition.from !== "*" && transition.from !== state.current)
+                continue;
+            if (transition.to === state.current && transition.from === "*")
+                continue;
+            if (transition.trigger !== undefined && !triggers.has(transition.trigger))
+                continue;
+            if (transition.exitTime !== undefined && normalized < transition.exitTime)
+                continue;
+            if (transition.when !== undefined && !transition.when.every((c) => compare(params[c.param], c.op, c.value)))
+                continue;
+            if (transition.trigger !== undefined)
+                triggers.delete(transition.trigger);
+            return transition;
+        }
+        return null;
+    }
+    function collectEvents(out, clip, before, after, duration, loop) {
+        if (graph.events === undefined || !(duration > 0))
+            return;
+        for (const event of graph.events) {
+            if (event.clip !== clip)
+                continue;
+            const at = event.atSec;
+            if (loop) {
+                const wrapped = after < before;
+                const hit = wrapped ? at > before || at <= after : at > before && at <= after;
+                if (hit)
+                    out.push({ name: event.name, clip });
+            }
+            else if (at > before && at <= after) {
+                out.push({ name: event.name, clip });
+            }
+        }
+    }
+    return {
+        graph: () => graph,
+        retune(next) {
+            graph = next;
+            const previous = layers;
+            reset();
+            for (const [id, state] of Object.entries(previous)) {
+                const layer = graph.layers.find((l) => l.id === id);
+                if (layer !== undefined && layer.states[state.current] !== undefined)
+                    layers[id] = state;
+            }
+        },
+        state: () => ({ layers, triggers: [...triggers] }),
+        snapshot: () => ({ layers: structuredClone(layers), triggers: [...triggers] }),
+        restore(next) {
+            layers = structuredClone(next.layers);
+            triggers = new Set(next.triggers);
+        },
+        trigger(name) {
+            triggers.add(name);
+        },
+        stateOf: (layerId) => layers[layerId]?.current ?? null,
+        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)
+                    continue;
+                const def = layer.states[state.current];
+                if (def === undefined)
+                    continue;
+                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 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)) {
+                    const duration = clipDuration(clips[clip]);
+                    collectEvents(output.events, clip, clipTimeFor(before, duration, loop), clipTimeFor(state.time, duration, loop), duration, loop);
+                    if (def.rootMotion) {
+                        const info = clips[clip];
+                        if (typeof info !== "number" && info?.rootTrack !== undefined) {
+                            const from = rootPosition(info.rootTrack, before, duration, loop);
+                            const to = rootPosition(info.rootTrack, state.time, duration, loop);
+                            for (let axis = 0; axis < 3; axis += 1)
+                                rootDelta[axis] += (to[axis] - from[axis]) * weights[clip] * layerWeight;
+                        }
+                    }
+                }
+                const transition = state.transition;
+                if (transition !== null) {
+                    transition.elapsed += dt;
+                    const t = transition.duration > 0 ? Math.min(1, transition.elapsed / transition.duration) : 1;
+                    const merged = {};
+                    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;
+                    }
+                    for (const [clip, w] of Object.entries(weights)) {
+                        merged[clip] = (merged[clip] ?? 0) + w * t;
+                        times[clip] = clipTimeFor(state.time, clipDuration(clips[clip]), loop);
+                    }
+                    for (const [clip, w] of Object.entries(merged)) {
+                        if (w <= 0)
+                            continue;
+                        output.clips.push({ clip, weight: w * layerWeight, time: times[clip] ?? 0, layer: layer.id });
+                    }
+                    if (t >= 1)
+                        state.transition = null;
+                }
+                else {
+                    for (const [clip, w] of Object.entries(weights)) {
+                        if (w <= 0)
+                            continue;
+                        output.clips.push({ clip, weight: w * layerWeight, time: clipTimeFor(state.time, clipDuration(clips[clip]), loop), layer: layer.id });
+                    }
+                }
+                const next = pickTransition(layer, state, params, normalized);
+                if (next !== null && next.to !== state.current) {
+                    const fromWeights = {};
+                    const fromTimes = {};
+                    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;
+                    }
+                    state.current = next.to;
+                    state.time = 0;
+                    state.transition = {
+                        to: next.to,
+                        elapsed: 0,
+                        duration: next.duration ?? DEFAULT_FADE,
+                        fromWeights,
+                        fromTimes,
+                    };
+                }
+                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")
+        return { kind: "clip", clip: raw.clip, ...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 }) };
+}

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;
+}