@jgengine/shell 0.17.0 → 0.18.1

package/dist/render/testFixtures/proceduralSpriteAtlas.js

@@ -0,0 +1,30 @@
+/** Draw the deterministic two-frame atlas used by shell sprite-clip captures and tests.
+ * @internal
+ */
+export function drawProceduralSpriteAtlas(canvas) {
+    canvas.width = 64;
+    canvas.height = 32;
+    const context = canvas.getContext("2d");
+    if (context === null)
+        throw new Error("A 2D canvas context is required.");
+    context.clearRect(0, 0, canvas.width, canvas.height);
+    for (const x of [0, 32]) {
+        context.fillStyle = "#172033";
+        context.fillRect(x, 0, 32, 32);
+        context.fillStyle = "#f4c95d";
+        context.beginPath();
+        context.arc(x + 16, 14, 9, 0, Math.PI * 2);
+        context.fill();
+        context.fillStyle = "#e76f51";
+        context.fillRect(x + 8, x === 0 ? 22 : 20, 16, 5);
+    }
+    return {
+        image: canvas.toDataURL(),
+        size: [64, 32],
+        frames: {
+            idle0: { x: 0, y: 0, w: 32, h: 32 },
+            idle1: { x: 32, y: 0, w: 32, h: 32 },
+        },
+        animations: { idle: { frames: ["idle0", "idle1"], fps: 2 } },
+    };
+}

package/dist/render/testFixtures/proceduralTileLayer.d.ts

@@ -0,0 +1,13 @@
+import type { TilemapWorldConfig } from "@jgengine/core/world/features";
+type DrawingContext = Pick<CanvasRenderingContext2D, "clearRect" | "fillRect"> & {
+    fillStyle: string | CanvasGradient | CanvasPattern;
+};
+type CanvasFixture = {
+    width: number;
+    height: number;
+    getContext(contextId: "2d"): DrawingContext | null;
+    toDataURL(): string;
+};
+/** Draw the deterministic tile atlas used by textured tile-layer captures and tests. */
+export declare function drawProceduralTileLayer(canvas: CanvasFixture): TilemapWorldConfig;
+export {};

package/dist/render/testFixtures/proceduralTileLayer.js

@@ -0,0 +1,30 @@
+/** Draw the deterministic tile atlas used by textured tile-layer captures and tests. */
+export function drawProceduralTileLayer(canvas) {
+    canvas.width = 48;
+    canvas.height = 16;
+    const context = canvas.getContext("2d");
+    if (context === null)
+        throw new Error("A 2D canvas context is required.");
+    context.clearRect(0, 0, canvas.width, canvas.height);
+    for (const [x, color] of [[0, "#355070"], [16, "#6b705c"], [32, "#3a86a8"]]) {
+        context.fillStyle = color;
+        context.fillRect(x, 0, 16, 16);
+    }
+    return {
+        map: "aba\nbcb\naba",
+        cellSize: 1,
+        tileSet: {
+            atlas: {
+                image: canvas.toDataURL(),
+                size: [48, 16],
+                frames: {
+                    floor: { x: 0, y: 0, w: 16, h: 16 },
+                    wall: { x: 16, y: 0, w: 16, h: 16 },
+                    water: { x: 32, y: 0, w: 16, h: 16 },
+                },
+                animations: {},
+            },
+            tiles: { a: "floor", b: "wall", c: "water" },
+        },
+    };
+}

package/dist/render/useFootIk.d.ts

@@ -0,0 +1,9 @@
+import * as THREE from "three";
+import type { GameContext } from "@jgengine/core/runtime/gameContextTypes";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+type FootIkConfig = NonNullable<ModelConfig["ik"]>;
+/** Applies one frame of foot IK to a loaded rig. Exported for renderer tests and custom model hosts. */
+export declare function applyFootIk(scene: THREE.Object3D, config: FootIkConfig, raycast: GameContext["scene"]["raycast"], weight: number, cameraTarget?: readonly [number, number, number]): boolean;
+/** Runs foot IK after the model animation mixer, fading the correction out while the entity is airborne. */
+export declare function useFootIk(scene: THREE.Object3D, config: FootIkConfig | undefined, ctx: GameContext | null, instanceId?: string): void;
+export {};

package/dist/render/useFootIk.js

@@ -0,0 +1,89 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { useRef } from "react";
+import * as THREE from "three";
+import { lookAt, solveTwoBone } from "@jgengine/core/anim/ikSolver";
+function tuple(value) {
+    return [value.x, value.y, value.z];
+}
+function worldQuaternion(bone) {
+    const result = new THREE.Quaternion();
+    bone.getWorldQuaternion(result);
+    return result;
+}
+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));
+    }
+    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)
+        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);
+}
+/** 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);
+    }
+    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);
+        }
+    }
+    return 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)
+            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));
+    });
+}

package/dist/render/useModelAnimation.d.ts

@@ -6,5 +6,7 @@ import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
  * Handles `"auto"` derivation from the GLB's clip names, speed-driven idle/walk/run crossfades
  * read from the entity's live position when `instanceId` is set, one-shots fired from
  * `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`.
  */
 export declare function useModelAnimation(scene: THREE.Object3D, clips: THREE.AnimationClip[], animationInput: ModelAnimationConfig | "auto" | "none" | undefined, instanceId?: string): void;

package/dist/render/useModelAnimation.js

@@ -2,8 +2,22 @@ import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
-import { resolveOneShotClip } from "@jgengine/core/game/modelAnimation";
+import { ANIM_PARAMS_KEY, createAnimGraphRuntime, } from "@jgengine/core/anim/animGraph";
+import { LOCOMOTION_SPEED_PARAM, locomotionGraph } from "@jgengine/core/anim/locomotionGraph";
 import { useOptionalGameContext } from "@jgengine/react/provider";
+function graphClipNames(graph) {
+    const names = new Set();
+    for (const layer of graph.layers) {
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "clip")
+                names.add(state.clip);
+            else
+                for (const point of state.points)
+                    names.add(point.clip);
+        }
+    }
+    return names;
+}
 /**
  * An explicit `animation` config always wins over `"auto"`, and both the state machine and the
  * one-shot table degrade quietly when a named clip is absent: states fall back to `clips[0]` (often
@@ -19,7 +33,7 @@ function warnMissingClips(animation, clips) {
         return;
     const available = new Set(clips.map((clip) => clip.name));
     const missing = new Set();
-    const { states, oneShots } = animation;
+    const { states, oneShots, graph } = animation;
     if (states !== undefined) {
         for (const name of [states.idle, states.walk, states.run]) {
             if (name !== undefined && !available.has(name))
@@ -34,6 +48,11 @@ function warnMissingClips(animation, clips) {
             }
         }
     }
+    if (graph !== undefined) {
+        for (const name of graphClipNames(graph))
+            if (!available.has(name))
+                missing.add(name);
+    }
     if (animation.clip !== undefined && !available.has(animation.clip))
         missing.add(animation.clip);
     if (missing.size === 0)
@@ -43,12 +62,77 @@ function warnMissingClips(animation, clips) {
         `States fall back to the first clip and one-shots are skipped — set animation: "auto" to ` +
         `derive states/one-shots from the rig's own clip names.`);
 }
+/** Per-layer action key: a masked or additive layer needs its own clip variant even for a clip another layer plays. */
+function actionKey(layer, clip) {
+    return `${layer}:${clip}`;
+}
+function buildGraphPlayback(scene, mixer, graph, clips) {
+    const actions = new Map();
+    const durations = {};
+    let resolvedRootBone = null;
+    scene.traverse((object) => {
+        if (resolvedRootBone === null && object instanceof THREE.Bone)
+            resolvedRootBone = object;
+    });
+    const rootBone = resolvedRootBone;
+    for (const clip of clips) {
+        const track = rootBone === null ? undefined : clip.tracks.find((candidate) => candidate.name === `${rootBone.name}.position`);
+        durations[clip.name] = {
+            duration: clip.duration,
+            ...(track === undefined ? {} : { rootTrack: { times: new Float32Array(track.times), values: new Float32Array(track.values) } }),
+        };
+    }
+    for (const layer of graph.layers) {
+        const names = new Set();
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "clip")
+                names.add(state.clip);
+            else
+                for (const point of state.points)
+                    names.add(point.clip);
+        }
+        for (const name of names) {
+            const source = THREE.AnimationClip.findByName(clips, name);
+            if (source === null)
+                continue;
+            let clip = source;
+            if (layer.mask !== undefined) {
+                const mask = layer.mask;
+                clip = new THREE.AnimationClip(`${source.name}|${layer.id}`, source.duration, source.tracks.filter((track) => mask.some((prefix) => track.name.startsWith(prefix))));
+            }
+            if (layer.additive === true) {
+                clip = clip === source ? clip.clone() : clip;
+                THREE.AnimationUtils.makeClipAdditive(clip);
+            }
+            const action = mixer.clipAction(clip);
+            action.setLoop(THREE.LoopRepeat, Infinity);
+            action.enabled = true;
+            action.paused = true;
+            action.weight = 0;
+            if (layer.additive === true)
+                action.blendMode = THREE.AdditiveAnimationBlendMode;
+            action.play();
+            actions.set(actionKey(layer.id, name), action);
+        }
+    }
+    return {
+        runtime: createAnimGraphRuntime(graph),
+        actions,
+        durations,
+        rootBone,
+        rootBindPosition: rootBone?.position.clone() ?? null,
+        lastPos: null,
+        smoothedSpeed: 0,
+    };
+}
 /**
  * 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).
  * Handles `"auto"` derivation from the GLB's clip names, speed-driven idle/walk/run crossfades
  * read from the entity's live position when `instanceId` is set, one-shots fired from
  * `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`.
  */
 export function useModelAnimation(scene, clips, animationInput, instanceId) {
     // Optional: a model must still animate its bind pose / auto clip in a preview or inspector that
@@ -60,95 +144,47 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
     const animation = useMemo(() => resolveAnimationConfig(animationInput, clips.map((clip) => clip.name)), [animationInput, clips]);
     const mixerRef = useRef(null);
     const animationPausedRef = useRef(false);
-    const stateActionsRef = useRef(null);
+    const graphRef = useRef(null);
     const states = animation?.states;
     const oneShots = animation?.oneShots;
-    const oneShotPlayRef = useRef(null);
-    const activeOneShotRef = useRef(null);
+    const graph = useMemo(() => {
+        if (animation?.graph !== undefined)
+            return animation.graph;
+        if (states === undefined)
+            return undefined;
+        const graphOneShots = {};
+        for (const [event, spec] of Object.entries(oneShots ?? {})) {
+            const clip = typeof spec === "string" ? spec : spec[0];
+            if (clip !== undefined)
+                graphOneShots[event] = clip;
+        }
+        return locomotionGraph({
+            idle: states.idle,
+            walk: states.walk,
+            ...(states.run === undefined ? {} : { run: states.run }),
+            walkSpeed: states.walkSpeed,
+            runSpeed: states.runSpeed,
+            fadeSec: states.fadeSec,
+            ...(Object.keys(graphOneShots).length === 0 ? {} : { oneShots: graphOneShots }),
+        });
+    }, [animation?.graph, states, oneShots]);
     useEffect(() => {
         if (animation === undefined || clips.length === 0) {
             mixerRef.current = null;
-            stateActionsRef.current = null;
+            graphRef.current = null;
             return;
         }
         warnMissingClips(animation, clips);
         const mixer = new THREE.AnimationMixer(scene);
-        if (states !== undefined) {
-            const clipFor = (name) => THREE.AnimationClip.findByName(clips, name) ?? clips[0];
-            const actions = {
-                idle: mixer.clipAction(clipFor(states.idle)),
-                walk: mixer.clipAction(clipFor(states.walk)),
-                ...(states.run === undefined ? {} : { run: mixer.clipAction(clipFor(states.run)) }),
-            };
-            for (const action of Object.values(actions)) {
-                action.setLoop(THREE.LoopRepeat, Infinity);
-                action.timeScale = animation.timeScale ?? 1;
-                action.enabled = true;
-            }
-            actions.idle.play();
+        if (graph !== undefined) {
+            graphRef.current = buildGraphPlayback(scene, mixer, graph, clips);
             mixer.update(0);
             mixerRef.current = mixer;
-            stateActionsRef.current = { actions, active: "idle", lastPos: null, smoothedSpeed: 0 };
             animationPausedRef.current = false;
-            let onOneShotFinished = null;
-            if (oneShots !== undefined) {
-                const clipNames = new Set();
-                for (const spec of Object.values(oneShots)) {
-                    if (typeof spec === "string")
-                        clipNames.add(spec);
-                    else
-                        for (const name of spec)
-                            clipNames.add(name);
-                }
-                const oneShotActions = new Map();
-                for (const name of clipNames) {
-                    const found = THREE.AnimationClip.findByName(clips, name);
-                    if (found === null)
-                        continue;
-                    const oneShotAction = mixer.clipAction(found);
-                    oneShotAction.setLoop(THREE.LoopOnce, 1);
-                    oneShotAction.enabled = true;
-                    oneShotActions.set(name, oneShotAction);
-                }
-                onOneShotFinished = ({ action }) => {
-                    const active = activeOneShotRef.current;
-                    if (active === null || action !== active.action || active.isDeath)
-                        return;
-                    const machine = stateActionsRef.current;
-                    const back = machine?.actions[machine.active];
-                    action.fadeOut(0.15);
-                    if (back !== undefined)
-                        back.reset().fadeIn(0.15).play();
-                    activeOneShotRef.current = null;
-                };
-                mixer.addEventListener("finished", onOneShotFinished);
-                oneShotPlayRef.current = (event) => {
-                    const active = activeOneShotRef.current;
-                    if (active !== null && active.isDeath)
-                        return;
-                    const clipName = resolveOneShotClip(oneShots, event, Math.random());
-                    if (clipName === null)
-                        return;
-                    const oneShotAction = oneShotActions.get(clipName);
-                    if (oneShotAction === undefined)
-                        return;
-                    const machine = stateActionsRef.current;
-                    machine?.actions[machine.active]?.fadeOut(0.1);
-                    if (active !== null && active.action !== oneShotAction)
-                        active.action.stop();
-                    oneShotAction.clampWhenFinished = event === "death";
-                    oneShotAction.reset().fadeIn(0.1).play();
-                    activeOneShotRef.current = { action: oneShotAction, isDeath: event === "death" };
-                };
-            }
             return () => {
-                if (onOneShotFinished !== null)
-                    mixer.removeEventListener("finished", onOneShotFinished);
-                oneShotPlayRef.current = null;
-                activeOneShotRef.current = null;
                 mixer.stopAllAction();
                 mixerRef.current = null;
-                stateActionsRef.current = null;
+                graphRef.current = null;
             };
         }
         const clip = (animation.clip !== undefined ? THREE.AnimationClip.findByName(clips, animation.clip) : undefined) ??
@@ -179,11 +215,16 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
         animation?.time,
         states,
         oneShots,
+        graph,
     ]);
     useEffect(() => {
-        if (ctx === null || instanceId === undefined || oneShots === undefined)
+        if (ctx === null || instanceId === undefined || (oneShots === undefined && graph === undefined))
             return;
-        const fire = (event) => oneShotPlayRef.current?.(event);
+        const fire = (event) => {
+            const playback = graphRef.current;
+            if (playback !== null)
+                playback.runtime.trigger(event);
+        };
         const offAnimation = ctx.game.events.on("entity.animation", (event) => {
             if (event.instanceId === instanceId)
                 fire(event.event);
@@ -201,39 +242,54 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             offHit();
             offDied();
         };
-    }, [ctx, instanceId, oneShots]);
+    }, [ctx, instanceId, oneShots, graph]);
     useFrame((_state, delta) => {
-        const stateMachine = stateActionsRef.current;
-        if (stateMachine !== null && states !== undefined && instanceId !== undefined && delta > 0 && ctx !== null) {
-            const entity = ctx.scene.entity.get(instanceId);
-            if (entity !== null) {
-                const [x, , z] = entity.position;
-                if (stateMachine.lastPos !== null) {
-                    const instantSpeed = Math.hypot(x - stateMachine.lastPos[0], z - stateMachine.lastPos[2]) / delta;
-                    stateMachine.smoothedSpeed +=
-                        (instantSpeed - stateMachine.smoothedSpeed) * Math.min(1, delta * 12);
-                }
-                stateMachine.lastPos = [x, entity.position[1], z];
-                const walkSpeed = states.walkSpeed ?? 0.5;
-                const runSpeed = states.runSpeed ?? 6;
-                const next = stateMachine.smoothedSpeed < walkSpeed
-                    ? "idle"
-                    : stateMachine.actions.run !== undefined && stateMachine.smoothedSpeed >= runSpeed
-                        ? "run"
-                        : "walk";
-                if (next !== stateMachine.active) {
-                    if (activeOneShotRef.current === null) {
-                        const fade = states.fadeSec ?? 0.2;
-                        const from = stateMachine.actions[stateMachine.active];
-                        const to = stateMachine.actions[next];
-                        if (from !== undefined && to !== undefined) {
-                            to.reset().fadeIn(fade).play();
-                            from.fadeOut(fade);
-                        }
+        const playback = graphRef.current;
+        if (playback !== null && mixerRef.current !== null) {
+            const params = {};
+            if (ctx !== null && instanceId !== undefined) {
+                const entity = ctx.scene.entity.get(instanceId);
+                if (entity !== null && delta > 0) {
+                    const [x, , z] = entity.position;
+                    if (playback.lastPos !== null) {
+                        const instantSpeed = Math.hypot(x - playback.lastPos[0], z - playback.lastPos[2]) / delta;
+                        playback.smoothedSpeed += (instantSpeed - playback.smoothedSpeed) * Math.min(1, delta * 12);
                     }
-                    stateMachine.active = next;
+                    playback.lastPos = [x, entity.position[1], z];
                 }
+                const extra = ctx.scene.entity.blackboard.get(instanceId, ANIM_PARAMS_KEY);
+                if (extra !== undefined)
+                    Object.assign(params, extra);
+            }
+            params[LOCOMOTION_SPEED_PARAM] = playback.smoothedSpeed;
+            const out = playback.runtime.advance(delta * (animation?.timeScale ?? 1), params, playback.durations);
+            for (const action of playback.actions.values())
+                action.weight = 0;
+            for (const entry of out.clips) {
+                const action = playback.actions.get(actionKey(entry.layer, entry.clip));
+                if (action === undefined)
+                    continue;
+                action.weight += entry.weight;
+                action.time = entry.time;
+            }
+            mixerRef.current.update(0);
+            const currentPlayback = graphRef.current;
+            if (currentPlayback !== null && currentPlayback.rootBone !== null && currentPlayback.rootBindPosition !== null) {
+                currentPlayback.rootBone.position.copy(currentPlayback.rootBindPosition);
             }
+            if (ctx !== null && instanceId !== undefined) {
+                const rootDelta = out.rootDelta;
+                const entity = rootDelta === undefined ? null : ctx.scene.entity.get(instanceId);
+                if (entity !== null && rootDelta !== undefined) {
+                    ctx.scene.entity.setPose(instanceId, {
+                        position: [entity.position[0] + rootDelta[0], entity.position[1] + rootDelta[1], entity.position[2] + rootDelta[2]],
+                        dt: delta,
+                    });
+                }
+                for (const event of out.events)
+                    ctx.game.events.emit("animation.event", { instanceId, name: event.name, clip: event.clip });
+            }
+            return;
         }
         if (mixerRef.current !== null && !animationPausedRef.current)
             mixerRef.current.update(delta);