@jgengine/shell 0.18.0 → 0.19.0

package/dist/render/useFootIk.js

@@ -0,0 +1,216 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { 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";
+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 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;
+}
+/**
+ * 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;
+    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);
+    }
+    const legs = [];
+    for (const chain of chains) {
+        const root = scene.getObjectByName(chain.root);
+        const mid = scene.getObjectByName(chain.mid);
+        const tip = scene.getObjectByName(chain.tip);
+        if (root === undefined || mid === undefined || tip === undefined)
+            continue;
+        legs.push({ root, mid, tip, ankleRatio: restAnkleRatio(scene, { root, mid, tip }) });
+    }
+    const head = options.lookAt === undefined ? null : (scene.getObjectByName(options.lookAt.bone) ?? null);
+    if (legs.length === 0 && head === null)
+        return null;
+    const found = options.pelvis !== undefined ? (scene.getObjectByName(options.pelvis) ?? null) : (legs[0]?.root.parent ?? null);
+    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
+        bone.quaternion.copy(bone.parent.getWorldQuaternion(scratch.parent).invert().multiply(world));
+    bone.updateMatrixWorld(true);
+}
+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 = scratch.q.setFromUnitVectors(current.normalize(), desired.normalize());
+    writeWorldQuaternion(bone, correction.multiply(bone.getWorldQuaternion(scratch.q2)));
+}
+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);
+}
+/**
+ * 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) {
+    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);
+        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));
+        }
+    }
+    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'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 });
+    useFrame((_three, delta) => {
+        if (rig === null || ctx === null || instanceId === undefined)
+            return;
+        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,10 +1,36 @@
 import * as THREE from "three";
 import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
+import { type AnimClipOutput, type AnimGraph } from "@jgengine/core/anim/animGraph";
+/**
+ * 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;
+    }>>;
+    /** Poses the rig with one advance's clip weights and times. */
+    apply(clips: readonly AnimClipOutput[]): 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).
  * 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 { animGraphFromConfig, LOCOMOTION_SPEED_PARAM } 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,127 @@ 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}`;
+}
+const rootTravel = new THREE.Vector3();
+const rootBasis = new THREE.Matrix3();
+/**
+ * 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 function takeRootMotion(rootBone, bind, localDelta, out) {
+    rootBone.position.x = bind.x;
+    rootBone.position.z = bind.z;
+    out.set(0, 0, 0);
+    if (localDelta === undefined || rootBone.parent === null)
+        return out;
+    rootBone.parent.updateWorldMatrix(true, false);
+    out.set(localDelta[0], localDelta[1], localDelta[2]).applyMatrix3(rootBasis.setFromMatrix4(rootBone.parent.matrixWorld));
+    out.y = 0;
+    return out;
+}
+function applyGraphClips(actions, clips) {
+    for (const action of actions.values())
+        action.weight = 0;
+    for (const entry of clips) {
+        const action = actions.get(actionKey(entry.layer, entry.clip));
+        if (action === undefined)
+            continue;
+        action.weight += entry.weight;
+        action.time = entry.time;
+    }
+}
+/**
+ * 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 function createGraphPose(scene, graph, clips) {
+    const mixer = new THREE.AnimationMixer(scene);
+    const playback = buildGraphPlayback(scene, mixer, graph, clips);
+    return {
+        durations: playback.durations,
+        apply(output) {
+            applyGraphClips(playback.actions, output);
+            mixer.update(0);
+        },
+        dispose() {
+            mixer.stopAllAction();
+            mixer.uncacheRoot(scene);
+        },
+    };
+}
+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 +194,28 @@ 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 authoredGraph = animation?.graph;
+    const graph = useMemo(() => animGraphFromConfig({ graph: authoredGraph, states, oneShots }), [authoredGraph, 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 +246,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 +273,44 @@ 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);
+            applyGraphClips(playback.actions, out.clips);
+            mixerRef.current.update(0);
+            if (out.rootMotion === true && playback.rootBone !== null && playback.rootBindPosition !== null) {
+                const travel = takeRootMotion(playback.rootBone, playback.rootBindPosition, out.rootDelta, rootTravel);
+                const entity = ctx === null || instanceId === undefined || (travel.x === 0 && travel.z === 0) ? null : ctx.scene.entity.get(instanceId);
+                if (entity !== null && ctx !== null && instanceId !== undefined) {
+                    ctx.scene.entity.setPose(instanceId, {
+                        position: [entity.position[0] + travel.x, entity.position[1], entity.position[2] + travel.z],
+                        dt: delta,
+                    });
+                }
+            }
+            if (ctx !== null && instanceId !== undefined) {
+                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);

package/dist/scene/AuthoredScene.d.ts

@@ -40,6 +40,15 @@ export interface AuthoredObjectsProps {
  * headless twin: `resolveAuthoredObjects` / `placeAuthoredObjects`.
  */
 export declare function AuthoredObjects({ document, field, verticalOffset, onExisting, }: AuthoredObjectsProps): null;
+/**
+ * Writes the document's studio solids (city buildings and any kind with a `solids` hook) into
+ * `ctx.world.solids`, so what the studios draw also blocks the player, NPCs and physics.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export declare function AuthoredSolids({ document, field }: {
+    document: EditorDocument;
+    field: TerrainField;
+}): null;
 /** Props for {@link AuthoredScene}: the document to render and the ground field to drape/ground on. */
 export interface AuthoredSceneProps {
     document: EditorDocument;