@jgengine/shell 0.18.1 → 0.21.0

package/dist/render/useFootIk.js

@@ -1,89 +1,281 @@
 import { useFrame, useThree } from "@react-three/fiber";
-import { useRef } from "react";
+import { useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { inferLegChains, placeFeet } from "@jgengine/core/anim/footPlacement";
 import { lookAt, solveTwoBone } from "@jgengine/core/anim/ikSolver";
-function tuple(value) {
-    return [value.x, value.y, value.z];
+import { resolveRigNode } from "./rigNode.js";
+const DEFAULT_MAX_ADJUST = 0.4;
+const UP = new THREE.Vector3(0, 1, 0);
+const scratch = {
+    root: new THREE.Vector3(),
+    mid: new THREE.Vector3(),
+    tip: new THREE.Vector3(),
+    a: new THREE.Vector3(),
+    b: new THREE.Vector3(),
+    q: new THREE.Quaternion(),
+    q2: new THREE.Quaternion(),
+    parent: new THREE.Quaternion(),
+    m: new THREE.Matrix4(),
+};
+const solved = { mid: [0, 0, 0], tip: [0, 0, 0] };
+function bindPosition(skeleton, bone, out) {
+    const index = skeleton.bones.indexOf(bone);
+    if (index < 0)
+        return null;
+    return out.setFromMatrixPosition(scratch.m.copy(skeleton.boneInverses[index]).invert());
 }
-function worldQuaternion(bone) {
-    const result = new THREE.Quaternion();
-    bone.getWorldQuaternion(result);
-    return result;
+function restAnkleRatio(scene, leg) {
+    let soleY = Infinity;
+    let ratio = 0;
+    const root = new THREE.Vector3();
+    const mid = new THREE.Vector3();
+    const tip = new THREE.Vector3();
+    scene.traverse((object) => {
+        const mesh = object;
+        if (mesh.isSkinnedMesh !== true || !(leg.tip instanceof THREE.Bone) || !(leg.mid instanceof THREE.Bone) || !(leg.root instanceof THREE.Bone))
+            return;
+        if (bindPosition(mesh.skeleton, leg.tip, tip) === null || bindPosition(mesh.skeleton, leg.mid, mid) === null || bindPosition(mesh.skeleton, leg.root, root) === null)
+            return;
+        if (mesh.geometry.boundingBox === null)
+            mesh.geometry.computeBoundingBox();
+        const box = mesh.geometry.boundingBox.clone().applyMatrix4(mesh.bindMatrix);
+        soleY = Math.min(soleY, box.min.y);
+        const length = root.distanceTo(mid) + mid.distanceTo(tip);
+        if (length > 1e-6)
+            ratio = Math.max(0, tip.y - soleY) / length;
+    });
+    return ratio;
+}
+function isAncestor(ancestor, child) {
+    for (let parent = child.parent; parent !== null; parent = parent.parent) {
+        if (parent === ancestor)
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolves foot-IK bones on a loaded rig: explicit chains, or legs found by bone name for `"auto"`
+ * and configs without `feet`. Returns `null` when no leg resolves.
+ */
+export function resolveFootIkRig(scene, config) {
+    const options = config === "auto" ? {} : config;
+    const named = new Map();
+    scene.traverse((object) => {
+        if (object.name.length === 0)
+            return;
+        const matches = named.get(object.name);
+        if (matches === undefined)
+            named.set(object.name, [object]);
+        else
+            matches.push(object);
+    });
+    const available = [...named.keys()].filter((name) => named.get(name).some((object) => object.isBone === true)).slice(0, 12).join(", ");
+    const warn = (message) => console.warn(`[jgengine foot IK] ${message}${available.length > 0 ? ` Available bones include: ${available}.` : ""}`);
+    const resolve = (name, role) => {
+        const matches = named.get(name);
+        if (matches?.length === 1)
+            return matches[0];
+        if (matches === undefined) {
+            const imported = resolveRigNode(scene, name);
+            if (imported.node !== undefined)
+                return imported.node;
+            warn(`${role} "${name}" ${imported.diagnostic.code === "ambiguous-node" ? "matches multiple original imported names; use a unique runtime name or repair duplicate imported names" : "was not found by runtime or original imported name; check the loaded rig names"}.`);
+            return null;
+        }
+        warn(`${role} "${name}" matches multiple objects; use a unique rig name.`);
+        return null;
+    };
+    let chains = options.feet;
+    if (chains === undefined) {
+        const bones = [];
+        scene.traverse((object) => {
+            if (object.isBone === true)
+                bones.push({ name: object.name, parent: object.parent?.isBone === true ? object.parent.name : null });
+        });
+        chains = inferLegChains(bones);
+        if (chains.length === 0 && options.lookAt === undefined)
+            warn("No thigh → shin → foot chain was recognized. Configure feet with the rig's bone names, or disable IK for this model.");
+    }
+    const legs = [];
+    const used = new Set();
+    for (const chain of chains) {
+        const root = resolve(chain.root, "Foot-chain root");
+        const mid = resolve(chain.mid, "Foot-chain middle");
+        const tip = resolve(chain.tip, "Foot-chain tip");
+        if (root === null || mid === null || tip === null)
+            continue;
+        if (!isAncestor(root, mid) || !isAncestor(mid, tip)) {
+            warn(`Skipped chain "${chain.root}" → "${chain.mid}" → "${chain.tip}": each joint must descend from the previous joint.`);
+            continue;
+        }
+        if ([root, mid, tip].some((bone) => used.has(bone))) {
+            warn(`Skipped chain "${chain.root}" → "${chain.mid}" → "${chain.tip}": a joint is already corrected by another foot chain.`);
+            continue;
+        }
+        for (const bone of [root, mid, tip])
+            used.add(bone);
+        legs.push({ root, mid, tip, ankleRatio: restAnkleRatio(scene, { root, mid, tip }) });
+    }
+    const head = options.lookAt === undefined ? null : resolve(options.lookAt.bone, "Look-at bone");
+    if (legs.length === 0 && head === null)
+        return null;
+    let found = options.pelvis !== undefined ? resolve(options.pelvis, "Pelvis") : (legs[0]?.root.parent ?? null);
+    if (options.pelvis === undefined) {
+        while (found !== null && !legs.every((leg) => isAncestor(found, leg.root)))
+            found = found.parent;
+    }
+    const pelvis = found === scene ? null : found;
+    const bones = new Set(legs.flatMap((leg) => [leg.root, leg.mid, leg.tip]));
+    if (pelvis !== null)
+        bones.add(pelvis);
+    if (head !== null)
+        bones.add(head);
+    return {
+        legs,
+        pelvis,
+        head,
+        maxAdjust: options.maxAdjust ?? DEFAULT_MAX_ADJUST,
+        alignToGround: Math.max(0, Math.min(1, options.alignToGround ?? 1)),
+        poses: [...bones].map((bone) => ({
+            bone,
+            animated: { q: bone.quaternion.clone(), p: bone.position.clone() },
+            written: { q: bone.quaternion.clone(), p: bone.position.clone() },
+        })),
+    };
 }
 function writeWorldQuaternion(bone, world) {
     if (bone.parent === null)
         bone.quaternion.copy(world);
-    else {
-        const parent = worldQuaternion(bone.parent).invert();
-        bone.quaternion.copy(parent.multiply(world));
-    }
+    else
+        bone.quaternion.copy(bone.parent.getWorldQuaternion(scratch.parent).invert().multiply(world));
     bone.updateMatrixWorld(true);
 }
-function aimSegment(bone, from, currentTo, solvedTo, weight) {
-    const current = currentTo.clone().sub(from).normalize();
-    const solved = new THREE.Vector3(solvedTo[0] - from.x, solvedTo[1] - from.y, solvedTo[2] - from.z).normalize();
-    if (current.lengthSq() < 1e-8 || solved.lengthSq() < 1e-8)
+function aimSegment(bone, from, currentTo, solvedTo) {
+    const current = scratch.a.copy(currentTo).sub(from);
+    const desired = scratch.b.set(solvedTo[0] - from.x, solvedTo[1] - from.y, solvedTo[2] - from.z);
+    if (current.lengthSq() < 1e-10 || desired.lengthSq() < 1e-10)
         return;
-    const correction = new THREE.Quaternion().setFromUnitVectors(current, solved);
-    const currentWorld = worldQuaternion(bone);
-    const desiredWorld = correction.multiply(currentWorld);
-    currentWorld.slerp(desiredWorld, weight);
-    writeWorldQuaternion(bone, currentWorld);
+    const correction = scratch.q.setFromUnitVectors(current.normalize(), desired.normalize());
+    writeWorldQuaternion(bone, correction.multiply(bone.getWorldQuaternion(scratch.q2)));
 }
-/** Applies one frame of foot IK to a loaded rig. Exported for renderer tests and custom model hosts. */
-export function applyFootIk(scene, config, raycast, weight, cameraTarget) {
-    let grounded = false;
-    scene.updateMatrixWorld(true);
-    for (const foot of config.feet) {
-        const root = scene.getObjectByName(foot.root);
-        const mid = scene.getObjectByName(foot.mid);
-        const tip = scene.getObjectByName(foot.tip);
-        if (root === undefined || mid === undefined || tip === undefined)
-            continue;
-        const rootPosition = root.getWorldPosition(new THREE.Vector3());
-        const midPosition = mid.getWorldPosition(new THREE.Vector3());
-        const tipPosition = tip.getWorldPosition(new THREE.Vector3());
-        const hit = raycast({
-            origin: [tipPosition.x, tipPosition.y + 0.75, tipPosition.z],
-            direction: [0, -1, 0],
-            maxDistance: 2,
-            filter: { entities: false, objects: false, walls: false, terrain: true },
-        });
-        if (hit === null)
-            continue;
-        grounded = true;
-        const target = new THREE.Vector3(hit.point[0], hit.point[1], hit.point[2]);
-        const output = { mid: [0, 0, 0], tip: [0, 0, 0] };
-        solveTwoBone({ root: tuple(rootPosition), mid: tuple(midPosition), tip: tuple(tipPosition), target: tuple(target), pole: [rootPosition.x, rootPosition.y, rootPosition.z + 1] }, output);
-        aimSegment(root, rootPosition, midPosition, output.mid, weight);
-        root.updateMatrixWorld(true);
-        const solvedMid = mid.getWorldPosition(new THREE.Vector3());
-        // Rotating the root also moves the tip; aim the shin from that updated pose.
-        const currentTip = tip.getWorldPosition(new THREE.Vector3());
-        aimSegment(mid, solvedMid, currentTip, output.tip, weight);
+function legLength(leg) {
+    leg.root.getWorldPosition(scratch.root);
+    leg.mid.getWorldPosition(scratch.mid);
+    leg.tip.getWorldPosition(scratch.tip);
+    return scratch.root.distanceTo(scratch.mid) + scratch.mid.distanceTo(scratch.tip);
+}
+function restoreFootIkPose(rig) {
+    for (const record of rig.poses) {
+        if (record.bone.quaternion.equals(record.written.q))
+            record.bone.quaternion.copy(record.animated.q);
+        if (record.bone.position.equals(record.written.p))
+            record.bone.position.copy(record.animated.p);
     }
-    if (config.lookAt !== undefined && cameraTarget !== undefined) {
-        const bone = scene.getObjectByName(config.lookAt.bone);
-        if (bone !== undefined) {
-            const from = bone.getWorldPosition(new THREE.Vector3());
-            const q = lookAt({ from: tuple(from), target: cameraTarget, up: [0, 1, 0] });
-            const desired = new THREE.Quaternion(q[0], q[1], q[2], q[3]);
-            const current = worldQuaternion(bone);
-            current.slerp(desired, weight);
-            writeWorldQuaternion(bone, current);
+}
+/**
+ * Applies one frame of foot IK after the animation mixer: probes the ground under each foot,
+ * resolves targets with `placeFeet`, lowers the pelvis, solves each leg with `solveTwoBone` bending
+ * toward the animated knee, and tilts planted feet to the ground. Returns whether the feet are
+ * grounded; `state` carries the faded weight between frames. Exported for tests and custom hosts.
+ */
+export function applyFootIk(rig, originY, probe, state, delta, cameraTarget) {
+    restoreFootIkPose(rig);
+    for (const record of rig.poses) {
+        record.animated.q.copy(record.bone.quaternion);
+        record.animated.p.copy(record.bone.position);
+    }
+    const samples = [];
+    const normals = [];
+    let length = 0;
+    let ankleHeight = 0;
+    for (const leg of rig.legs) {
+        leg.root.updateWorldMatrix(true, true);
+        const legSize = legLength(leg);
+        length = Math.max(length, legSize);
+        ankleHeight = Math.max(ankleHeight, leg.ankleRatio * legSize);
+        const from = Math.max(scratch.tip.y, originY) + legSize * 0.5;
+        const hit = probe({ origin: [scratch.tip.x, from, scratch.tip.z], direction: [0, -1, 0], maxDistance: legSize * 2 });
+        samples.push({ ankleY: scratch.tip.y, groundY: hit === null ? null : hit.point[1] });
+        normals.push(hit === null ? null : hit.normal);
+    }
+    const placement = placeFeet({ feet: samples, originY, ankleHeight, maxAdjust: rig.maxAdjust * length, airborneGap: length * 0.3 });
+    const blend = Math.min(1, delta * (placement.grounded ? 12 : 6));
+    state.weight += ((placement.grounded ? 1 : 0) - state.weight) * blend;
+    state.pelvis += (placement.pelvisOffset - state.pelvis) * Math.min(1, delta * 15);
+    const weight = state.weight;
+    if (rig.pelvis !== null && weight > 1e-3 && Math.abs(state.pelvis) > 1e-6) {
+        const world = rig.pelvis.getWorldPosition(scratch.a);
+        world.y += state.pelvis * weight;
+        rig.pelvis.position.copy(rig.pelvis.parent === null ? world : rig.pelvis.parent.worldToLocal(world));
+        rig.pelvis.updateMatrixWorld(true);
+    }
+    for (let i = 0; i < rig.legs.length && weight > 1e-3; i += 1) {
+        const target = placement.ankleTargets[i];
+        if (target === null || target === undefined)
+            continue;
+        const leg = rig.legs[i];
+        const root = leg.root.getWorldPosition(scratch.root);
+        const mid = leg.mid.getWorldPosition(scratch.mid);
+        const tip = leg.tip.getWorldPosition(scratch.tip);
+        const bend = scratch.a.copy(root).add(tip).multiplyScalar(0.5);
+        bend.subVectors(mid, bend);
+        if (bend.lengthSq() < 1e-8)
+            bend.set(0, 0, 1).applyQuaternion(leg.root.parent?.getWorldQuaternion(scratch.q) ?? scratch.q.identity());
+        const pole = bend.normalize().multiplyScalar(length).add(mid);
+        const targetY = tip.y + (target - tip.y) * weight;
+        solveTwoBone({ root: [root.x, root.y, root.z], mid: [mid.x, mid.y, mid.z], tip: [tip.x, tip.y, tip.z], target: [tip.x, targetY, tip.z], pole: [pole.x, pole.y, pole.z] }, solved);
+        aimSegment(leg.root, root, mid, solved.mid);
+        // Rotating the thigh also moved the tip; aim the shin from that updated pose.
+        aimSegment(leg.mid, leg.mid.getWorldPosition(scratch.mid), leg.tip.getWorldPosition(scratch.tip), solved.tip);
+        const normal = normals[i];
+        if (normal !== null && normal !== undefined && rig.alignToGround > 0) {
+            const planted = 1 - Math.min(1, Math.max(0, samples[i].ankleY - ankleHeight - samples[i].groundY) / Math.max(ankleHeight, length * 0.05));
+            const tilt = scratch.q.setFromUnitVectors(UP, scratch.b.set(normal[0], normal[1], normal[2]).normalize());
+            const current = leg.tip.getWorldQuaternion(scratch.q2);
+            writeWorldQuaternion(leg.tip, current.slerp(tilt.multiply(current), planted * weight * rig.alignToGround));
         }
     }
-    return grounded;
+    if (rig.head !== null && cameraTarget !== undefined) {
+        const from = rig.head.getWorldPosition(scratch.a);
+        const q = lookAt({ from: [from.x, from.y, from.z], target: cameraTarget, up: [0, 1, 0] });
+        const current = rig.head.getWorldQuaternion(scratch.q2);
+        writeWorldQuaternion(rig.head, current.slerp(scratch.q.set(q[0], q[1], q[2], q[3]), Math.max(weight, rig.legs.length === 0 ? 1 : 0)));
+    }
+    for (const record of rig.poses) {
+        record.written.q.copy(record.bone.quaternion);
+        record.written.p.copy(record.bone.position);
+    }
+    return placement.grounded;
 }
-/** Runs foot IK after the model animation mixer, fading the correction out while the entity is airborne. */
-export function useFootIk(scene, config, ctx, instanceId) {
-    const camera = useThree((state) => state.camera);
-    const weight = useRef(0);
-    useFrame((_state, delta) => {
-        if (config === undefined || ctx === null || instanceId === undefined)
+/**
+ * Runs foot IK after the model's animation mixer for `ModelConfig.ik`. Ground probes hit terrain and
+ * blocking physical objects, never the model's own entity. `groundOffset` is the model-space height
+ * its soles rest on (`ModelConfig.y`).
+ */
+export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
+    const camera = useThree((three) => three.camera);
+    const rig = useMemo(() => (config === undefined ? null : resolveFootIkRig(scene, config)), [scene, config]);
+    const state = useRef({ weight: 0, pelvis: 0 });
+    useLayoutEffect(() => {
+        state.current = { weight: 0, pelvis: 0 };
+        return () => {
+            if (rig !== null) {
+                restoreFootIkPose(rig);
+                scene.updateMatrixWorld(true);
+            }
+        };
+    }, [rig, scene]);
+    useFrame((_three, delta) => {
+        if (rig === null || ctx === null || instanceId === undefined)
             return;
-        const grounded = applyFootIk(scene, config, (input) => ctx.scene.raycast({ ...input, excludeInstanceIds: [instanceId] }), weight.current, tuple(camera.getWorldPosition(new THREE.Vector3())));
-        const target = grounded ? 1 : 0;
-        weight.current += (target - weight.current) * Math.min(1, delta * (grounded ? 12 : 5));
+        const parent = scene.parent;
+        const originY = parent === null ? scene.position.y : parent.localToWorld(scratch.a.set(0, groundOffset, 0)).y;
+        const exclude = [instanceId];
+        applyFootIk(rig, originY, (input) => ctx.scene.raycast({
+            ...input,
+            excludeInstanceIds: exclude,
+            filter: { entities: false, objects: true, walls: false, terrain: true },
+            accept: (hit) => hit.blocks && hit.purpose === "physical",
+        }), state.current, delta, rig.head === null ? undefined : camera.getWorldPosition(scratch.b).toArray());
     });
 }

package/dist/render/useModelAnimation.d.ts

@@ -1,5 +1,53 @@
 import * as THREE from "three";
 import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
+import { type AnimClipOutput, type AnimGraph, type AnimParamValue } from "@jgengine/core/anim/animGraph";
+import type { GameContext } from "@jgengine/core/runtime/gameContextTypes";
+/** A repairable mismatch between a model animation config and its imported rig. */
+export interface ModelAnimationDiagnostic {
+    code: "missing-clip" | "missing-root-track" | "empty-layer-mask" | "incomplete-locomotion" | "missing-auto-idle";
+    message: string;
+}
+/**
+ * Checks clip mappings, masked layers and root-motion assumptions without starting a mixer.
+ *
+ * @capability model-animation-diagnostics inspect imported clip mappings, layer masks and root-track compatibility
+ */
+export declare function diagnoseModelAnimation(scene: THREE.Object3D, animation: ModelAnimationConfig, clips: readonly THREE.AnimationClip[]): readonly ModelAnimationDiagnostic[];
+/**
+ * Refreshes a caller-owned graph parameter dictionary from authored extras and known physical movement.
+ * Grounded, verticalSpeed and crouched use the shared motor's resolved state when available; custom movers
+ * retain their authored values. Speed always uses the supplied measured ground speed. Does not write game state.
+ *
+ * @capability animation-motion-params read resolved player movement into reusable animation graph parameters
+ */
+export declare function readModelAnimationParams(ctx: GameContext, instanceId: string, speed: number, out: Record<string, AnimParamValue>): Record<string, AnimParamValue>;
+/**
+ * For a frame where a `rootMotion` state is current: pins the root bone's horizontal translation to
+ * its bind pose, so the clip plays in place, and returns that step's root travel as a world-space
+ * horizontal delta (through the rig's parent transform, so the entity's facing and the model's
+ * scale apply). The root bone's vertical motion stays in the clip.
+ */
+export declare function takeRootMotion(rootBone: THREE.Object3D, bind: THREE.Vector3, localDelta: readonly [number, number, number] | undefined, out: THREE.Vector3): THREE.Vector3;
+/** A mixer set up to show {@link AnimGraph} output on a rig; see {@link createGraphPose}. */
+export interface GraphPose {
+    /** Clip durations read from the rig, the `clips` argument `runtime.advance` expects. */
+    durations: Readonly<Record<string, {
+        duration: number;
+        rootTrack?: {
+            times: Float32Array;
+            values: Float32Array;
+        };
+    }>>;
+    /** Poses the rig with one advance's clip weights and times. */
+    apply(clips: readonly AnimClipOutput[], rootMotion?: boolean): void;
+    dispose(): void;
+}
+/**
+ * Binds a graph's clips to a rig exactly as `useModelAnimation` does (masked layers get filtered
+ * clips, additive layers additive ones) so a host that runs its own `createAnimGraphRuntime`, such as
+ * the editor's graph preview, poses the rig from the runtime's output.
+ */
+export declare function createGraphPose(scene: THREE.Object3D, graph: AnimGraph, clips: THREE.AnimationClip[]): GraphPose;
 /**
  * The engine's model animation driver as a standalone hook — the same mixer `EntityModel` runs,
  * for games that render a cloned scene themselves (custom materials, procedural composition).
@@ -8,5 +56,7 @@ import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
  * `entity.animation` / `combat.hitReaction` / `entity.died`, held poses, and the death clamp.
  * With `animation.graph` set, the headless `AnimGraph` runtime owns every clip's time and weight
  * and the mixer only applies them; clip events surface as `animation.event`.
+ * Equivalent same-order config data retains playback across rerenders; actual data edits reset it.
+ * Entity-bound playback holds while context game time is frozen; unbound previews keep playing.
  */
 export declare function useModelAnimation(scene: THREE.Object3D, clips: THREE.AnimationClip[], animationInput: ModelAnimationConfig | "auto" | "none" | undefined, instanceId?: string): void;