@jgengine/shell 0.12.0 → 0.13.0

package/dist/render/PartMotion.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { createPartPose, partMotionPhase, sampleBodyPose, samplePartPose, } from "@jgengine/core/game/partAnimation";
+import { useGameContext } from "@jgengine/react/provider";
+const FLINCH_RELEASE_SEC = 0.35;
+const DEATH_RAMP_PER_SEC = 2.5;
+const SPEED_SMOOTHING = 12;
+/**
+ * Procedural motion rig for a rig-less part-composed character (`ModelPart.role` — see
+ * `@jgengine/core/game/partAnimation`). Wraps the whole composition in a root group that bobs,
+ * breathes, flinches on `combat.hitReaction`, and topples on `entity.died`, while each
+ * role-tagged part swings around its authored transform — legs/arms counter-phase from the
+ * entity's live movement speed, head counter-sway, tail wag, wing flap. Untagged parts render
+ * as static kit pieces. Children are the base model content (primitive, attachments).
+ */
+export function PartMotionRig({ parts, model, instanceId, renderPart, children, }) {
+    const ctx = useGameContext();
+    const rootRef = useRef(null);
+    const partRefs = useRef([]);
+    const motionRef = useRef({
+        lastPos: null,
+        speed: 0,
+        flinch: 0,
+        death: 0,
+    });
+    const phase = useMemo(() => partMotionPhase(instanceId ?? model.url), [instanceId, model.url]);
+    useEffect(() => {
+        if (instanceId === undefined)
+            return;
+        const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
+            if (event.instanceId === instanceId)
+                motionRef.current.flinch = 1;
+        });
+        const offDied = ctx.game.events.on("entity.died", (event) => {
+            if (event.instanceId === instanceId)
+                motionRef.current.death = Math.max(motionRef.current.death, 1e-6);
+        });
+        return () => {
+            offHit();
+            offDied();
+        };
+    }, [ctx, instanceId]);
+    const input = useMemo(() => ({ timeSec: 0, speed: 0, phase, flinch: 0, death: 0 }), [phase]);
+    const pose = useMemo(() => createPartPose(), []);
+    useFrame((frameState, delta) => {
+        const motion = motionRef.current;
+        if (delta > 0 && instanceId !== undefined) {
+            const entity = ctx.scene.entity.get(instanceId);
+            if (entity !== null) {
+                const [x, , z] = entity.position;
+                if (motion.lastPos !== null) {
+                    const instantSpeed = Math.hypot(x - motion.lastPos[0], z - motion.lastPos[2]) / delta;
+                    motion.speed += (instantSpeed - motion.speed) * Math.min(1, delta * SPEED_SMOOTHING);
+                }
+                motion.lastPos = [x, entity.position[1], z];
+            }
+            motion.flinch = Math.max(0, motion.flinch - delta / FLINCH_RELEASE_SEC);
+            if (motion.death > 0)
+                motion.death = Math.min(1, motion.death + delta * DEATH_RAMP_PER_SEC);
+        }
+        input.timeSec = frameState.clock.elapsedTime;
+        input.speed = motion.speed;
+        input.flinch = motion.flinch;
+        input.death = motion.death;
+        const root = rootRef.current;
+        if (root !== null) {
+            sampleBodyPose(input, model.partMotion, pose);
+            root.position.set(pose.position[0], pose.position[1], pose.position[2]);
+            root.rotation.set(pose.rotation[0], pose.rotation[1], pose.rotation[2]);
+            root.scale.set(pose.scale[0], pose.scale[1], pose.scale[2]);
+        }
+        for (let index = 0; index < parts.length; index += 1) {
+            const part = parts[index];
+            const group = partRefs.current[index];
+            if (group === null || group === undefined || part.role === undefined)
+                continue;
+            samplePartPose(part.role, input, model.partMotion, pose);
+            const base = part.position ?? [0, 0, 0];
+            const baseRotation = part.rotation ?? [0, 0, 0];
+            group.position.set(base[0] + pose.position[0], base[1] + pose.position[1], base[2] + pose.position[2]);
+            group.rotation.set(baseRotation[0] + pose.rotation[0], baseRotation[1] + pose.rotation[1], baseRotation[2] + pose.rotation[2]);
+            const baseScale = part.scale ?? 1;
+            group.scale.set(baseScale * pose.scale[0], baseScale * pose.scale[1], baseScale * pose.scale[2]);
+        }
+    });
+    return (_jsxs("group", { ref: rootRef, children: [children, parts.map((part, index) => (_jsx("group", { ref: (group) => {
+                    partRefs.current[index] = group;
+                }, position: part.position ?? [0, 0, 0], rotation: part.rotation ?? [0, 0, 0], scale: part.scale ?? 1, children: renderPart(part, index) }, index)))] }));
+}

package/dist/render/SceneModels.d.ts

@@ -3,12 +3,19 @@ import type { EntitySpriteConfig, ModelConfig } from "@jgengine/core/game/playab
 export declare function EntitySprite({ sprite }: {
     sprite: EntitySpriteConfig;
 }): import("react").JSX.Element;
-export declare function IsolatedEntityModel({ model, instanceId, fallback, }: {
+export declare function IsolatedEntityModel({ model, instanceId, measure, fallback, }: {
     model: ModelConfig;
     instanceId?: string;
+    measure?: MeasureTarget;
     fallback?: ReactNode;
 }): import("react").JSX.Element;
-export declare function EntityModel({ model, instanceId }: {
+/** Where a measured model reports its rendered bounds: an entity kind or an object catalog id. */
+export interface MeasureTarget {
+    target: "entity" | "object";
+    key: string;
+}
+export declare function EntityModel({ model, instanceId, measure, }: {
     model: ModelConfig;
     instanceId?: string;
+    measure?: MeasureTarget;
 }): import("react").JSX.Element;

package/dist/render/SceneModels.js

@@ -3,9 +3,11 @@ import { useFrame, useLoader } from "@react-three/fiber";
 import { useTexture } from "@react-three/drei";
 import { Component, Suspense, useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
-import { resolveOneShotClip } from "@jgengine/core/game/modelAnimation";
 import { useGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "./modelLoad.js";
+import { measureLocalBounds, reportMeasuredBounds } from "./measureBounds.js";
+import { useModelAnimation } from "./useModelAnimation.js";
+import { PartMotionRig } from "./PartMotion.js";
 import { applyMaterialOverride } from "../materialOverride.js";
 import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeClonedMaterials, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
 export function EntitySprite({ sprite }) {
@@ -26,8 +28,8 @@ class ModelFallbackBoundary extends Component {
         return this.state.failed ? this.props.fallback : this.props.children;
     }
 }
-export function IsolatedEntityModel({ model, instanceId, fallback, }) {
-    return (_jsx(ModelFallbackBoundary, { fallback: fallback ?? null, children: _jsx(Suspense, { fallback: null, children: _jsx(EntityModel, { model: model, instanceId: instanceId }) }) }));
+export function IsolatedEntityModel({ model, instanceId, measure, fallback, }) {
+    return (_jsx(ModelFallbackBoundary, { fallback: fallback ?? null, children: _jsx(Suspense, { fallback: null, children: _jsx(EntityModel, { model: model, instanceId: instanceId, measure: measure }) }) }));
 }
 function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
     const gltf = useLoader(sharedGltfLoader, model.url);
@@ -83,7 +85,7 @@ function ModelMaterialMapsApplier({ scene, maps }) {
     }, [scene, textures]);
     return null;
 }
-export function EntityModel({ model, instanceId }) {
+export function EntityModel({ model, instanceId, measure, }) {
     const gltf = useLoader(sharedGltfLoader, model.url);
     const ctx = useGameContext();
     const material = model.material;
@@ -119,150 +121,26 @@ export function EntityModel({ model, instanceId }) {
     useEffect(() => () => {
         disposeClonedMaterials(scene);
     }, [scene]);
-    const animation = model.animation;
-    const mixerRef = useRef(null);
-    const animationPausedRef = useRef(false);
-    const stateActionsRef = useRef(null);
-    const states = animation?.states;
-    const oneShots = animation?.oneShots;
-    const oneShotPlayRef = useRef(null);
-    const activeOneShotRef = useRef(null);
+    // A model without index-measured dims can't drive the fitted-collider path, so report the live
+    // measurement (the primitive mounts with only this uniform scale + position) instead of letting
+    // the kind fall back to a fixed-size box. Index dims keep priority — skip when they exist.
+    const measureTarget = measure?.target;
+    const measureKey = measure?.key;
+    const dimsMaxY = dims?.maxY;
+    const [positionX, positionY, positionZ] = position;
     useEffect(() => {
-        if (animation === undefined || gltf.animations.length === 0) {
-            mixerRef.current = null;
-            stateActionsRef.current = null;
+        if (measureTarget === undefined || measureKey === undefined || dimsMaxY !== undefined)
             return;
-        }
-        const mixer = new THREE.AnimationMixer(scene);
-        if (states !== undefined) {
-            const clipFor = (name) => THREE.AnimationClip.findByName(gltf.animations, name) ?? gltf.animations[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();
-            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(gltf.animations, 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;
-            };
-        }
-        const clip = (animation.clip !== undefined ? THREE.AnimationClip.findByName(gltf.animations, animation.clip) : undefined) ??
-            gltf.animations[0];
-        const action = mixer.clipAction(clip);
-        action.setLoop(animation.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Infinity);
-        action.clampWhenFinished = animation.loop === false;
-        action.timeScale = animation.timeScale ?? 1;
-        action.enabled = true;
-        action.paused = animation.paused === true;
-        action.play();
-        if (animation.time !== undefined)
-            action.time = animation.time;
-        mixer.update(0);
-        mixerRef.current = mixer;
-        animationPausedRef.current = animation.paused === true;
-        return () => {
-            mixer.stopAllAction();
-            mixerRef.current = null;
-        };
-    }, [
-        scene,
-        gltf,
-        animation?.clip,
-        animation?.loop,
-        animation?.timeScale,
-        animation?.paused,
-        animation?.time,
-        states,
-        oneShots,
-    ]);
-    useEffect(() => {
-        if (instanceId === undefined || oneShots === undefined)
+        const raw = measureLocalBounds(scene);
+        if (raw === null)
             return;
-        const fire = (event) => oneShotPlayRef.current?.(event);
-        const offAnimation = ctx.game.events.on("entity.animation", (event) => {
-            if (event.instanceId === instanceId)
-                fire(event.event);
+        reportMeasuredBounds(ctx, measureTarget, measureKey, {
+            min: [raw.min[0] * scale + positionX, raw.min[1] * scale + positionY, raw.min[2] * scale + positionZ],
+            max: [raw.max[0] * scale + positionX, raw.max[1] * scale + positionY, raw.max[2] * scale + positionZ],
+            meshCount: raw.meshCount,
         });
-        const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
-            if (event.instanceId === instanceId)
-                fire("hit");
-        });
-        const offDied = ctx.game.events.on("entity.died", (event) => {
-            if (event.instanceId === instanceId)
-                fire("death");
-        });
-        return () => {
-            offAnimation();
-            offHit();
-            offDied();
-        };
-    }, [ctx, instanceId, oneShots]);
+    }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey, dimsMaxY]);
+    useModelAnimation(scene, gltf.animations, model.animation, instanceId);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
     const paintVersionRef = useRef(-1);
@@ -276,41 +154,7 @@ export function EntityModel({ model, instanceId }) {
         paintVersionRef.current = -1;
         materialCacheRef.current = null;
     }, [scene]);
-    useFrame((_state, delta) => {
-        const stateMachine = stateActionsRef.current;
-        if (stateMachine !== null && states !== undefined && instanceId !== undefined && delta > 0) {
-            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);
-                        }
-                    }
-                    stateMachine.active = next;
-                }
-            }
-        }
-        if (mixerRef.current !== null && !animationPausedRef.current)
-            mixerRef.current.update(delta);
+    useFrame(() => {
         if (instanceId === undefined)
             return;
         const paint = ctx.scene.entity.paint;
@@ -333,5 +177,12 @@ export function EntityModel({ model, instanceId }) {
         }
         paintDrawnCountRef.current = syncPaintCanvas(paintCanvasRef.current, cache.seedColor, strokes, paintDrawnCountRef.current);
     });
-    return (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }, `${attachment.slot}-${index}`))), (model.parts ?? []).map((part, index) => typeof part.model === "string" ? null : (_jsx(ModelPartGroup, { model: part.model, position: part.position, rotation: part.rotation, scale: part.scale }, index)))] }));
+    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }, `${attachment.slot}-${index}`)))] }));
+    const parts = model.parts ?? [];
+    // Any role-tagged part switches the composition onto the procedural part-motion rig:
+    // root bob/flinch/topple plus per-role limb swing, driven from the entity's live state.
+    if (parts.some((part) => part.role !== undefined)) {
+        return (_jsx(PartMotionRig, { parts: parts, model: model, instanceId: instanceId, renderPart: (part) => (typeof part.model === "string" ? null : _jsx(EntityModel, { model: part.model })), children: base }));
+    }
+    return (_jsxs(_Fragment, { children: [base, parts.map((part, index) => typeof part.model === "string" ? null : (_jsx(ModelPartGroup, { model: part.model, position: part.position, rotation: part.rotation, scale: part.scale }, index)))] }));
 }

package/dist/render/measureBounds.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import * as THREE from "three";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+/** Subtrees flagged with this userData key are excluded from bounds measurement — debug gizmos,
+ * selection quads, effect billboards that should not inflate the hitbox. Sprites and invisible
+ * subtrees are always excluded. */
+export declare const MEASURE_EXCLUDE_KEY = "jgMeasureExclude";
+/** Entity-local AABB of the meshes under a measured root, plus how many meshes contributed — the
+ * count lets callers detect async subtree fill-in without diffing bounds. */
+export interface MeasuredLocalBounds {
+    min: [number, number, number];
+    max: [number, number, number];
+    meshCount: number;
+}
+/**
+ * Measure the meshes under `root` in `root`'s own frame (root's transform is the measuring frame,
+ * children compose their local matrices below it). Returns `null` when nothing measurable is
+ * mounted. Skinned meshes measure at bind pose — the standard engine approximation.
+ */
+export declare function measureLocalBounds(root: THREE.Object3D): MeasuredLocalBounds | null;
+/** Forward a measured result into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same shape so remounts and multi-instance kinds don't churn collider resolution. */
+export declare function reportMeasuredBounds(ctx: GameContext, target: "entity" | "object", key: string, bounds: MeasuredLocalBounds): void;
+/**
+ * Wraps custom-rendered actor content (`renderEntity` / `renderObject`) and reports its measured
+ * entity-local bounds into collider resolution, so the hitbox wraps what is actually on screen
+ * instead of the fixed-size fallback box. A successful measure re-reports only when the subtree
+ * gained or lost meshes (async fill-in), not when idle animation nudges the same meshes.
+ */
+export declare function MeasuredBoundsGroup({ target, measureKey, children, }: {
+    target: "entity" | "object";
+    measureKey: string;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/render/measureBounds.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useRef } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+/** Subtrees flagged with this userData key are excluded from bounds measurement — debug gizmos,
+ * selection quads, effect billboards that should not inflate the hitbox. Sprites and invisible
+ * subtrees are always excluded. */
+export const MEASURE_EXCLUDE_KEY = "jgMeasureExclude";
+const IDENTITY = new THREE.Matrix4();
+const tmpBox = new THREE.Box3();
+/**
+ * Measure the meshes under `root` in `root`'s own frame (root's transform is the measuring frame,
+ * children compose their local matrices below it). Returns `null` when nothing measurable is
+ * mounted. Skinned meshes measure at bind pose — the standard engine approximation.
+ */
+export function measureLocalBounds(root) {
+    const box = new THREE.Box3();
+    box.makeEmpty();
+    const meshCount = collectBounds(root, null, box);
+    if (meshCount === 0 || box.isEmpty())
+        return null;
+    return {
+        min: [box.min.x, box.min.y, box.min.z],
+        max: [box.max.x, box.max.y, box.max.z],
+        meshCount,
+    };
+}
+function collectBounds(object, parentMatrix, into) {
+    if (parentMatrix !== null) {
+        if (!object.visible)
+            return 0;
+        if (object.isSprite === true)
+            return 0;
+        if (object.userData[MEASURE_EXCLUDE_KEY] === true)
+            return 0;
+    }
+    let matrix = null;
+    if (parentMatrix !== null) {
+        if (object.matrixAutoUpdate)
+            object.updateMatrix();
+        matrix = new THREE.Matrix4().multiplyMatrices(parentMatrix, object.matrix);
+    }
+    let count = 0;
+    const mesh = object;
+    if (mesh.isMesh === true && mesh.geometry !== undefined) {
+        const geometry = mesh.geometry;
+        if (geometry.boundingBox === null)
+            geometry.computeBoundingBox();
+        const bounds = geometry.boundingBox;
+        if (bounds !== null && !bounds.isEmpty()) {
+            tmpBox.copy(bounds);
+            if (matrix !== null)
+                tmpBox.applyMatrix4(matrix);
+            into.union(tmpBox);
+            count += 1;
+        }
+    }
+    const childMatrix = matrix ?? IDENTITY;
+    for (const child of object.children)
+        count += collectBounds(child, childMatrix, into);
+    return count;
+}
+const reportedByContext = new WeakMap();
+const EPSILON = 0.01;
+function boundsClose(a, b) {
+    for (let axis = 0; axis < 3; axis += 1) {
+        if (Math.abs(a.min[axis] - b.min[axis]) > EPSILON)
+            return false;
+        if (Math.abs(a.max[axis] - b.max[axis]) > EPSILON)
+            return false;
+    }
+    return true;
+}
+/** Forward a measured result into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same shape so remounts and multi-instance kinds don't churn collider resolution. */
+export function reportMeasuredBounds(ctx, target, key, bounds) {
+    let map = reportedByContext.get(ctx);
+    if (map === undefined) {
+        map = new Map();
+        reportedByContext.set(ctx, map);
+    }
+    const registryKey = `${target}:${key}`;
+    const prev = map.get(registryKey);
+    if (prev !== undefined && prev.meshCount === bounds.meshCount && boundsClose(prev, bounds))
+        return;
+    const accepted = target === "entity"
+        ? ctx.scene.entity.reportBounds(key, bounds)
+        : ctx.scene.object.reportBounds(key, bounds);
+    if (accepted)
+        map.set(registryKey, bounds);
+}
+/** Frames-since-mount at which a marker re-measures — bounded retries catch content that fills in
+ * asynchronously after first mount without paying a traversal every frame forever. */
+const MEASURE_FRAMES = [1, 15, 30, 60];
+/**
+ * Wraps custom-rendered actor content (`renderEntity` / `renderObject`) and reports its measured
+ * entity-local bounds into collider resolution, so the hitbox wraps what is actually on screen
+ * instead of the fixed-size fallback box. A successful measure re-reports only when the subtree
+ * gained or lost meshes (async fill-in), not when idle animation nudges the same meshes.
+ */
+export function MeasuredBoundsGroup({ target, measureKey, children, }) {
+    const ctx = useGameContext();
+    const groupRef = useRef(null);
+    const frameRef = useRef(0);
+    const attemptRef = useRef(0);
+    const lastMeshCountRef = useRef(null);
+    useFrame(() => {
+        if (attemptRef.current >= MEASURE_FRAMES.length)
+            return;
+        frameRef.current += 1;
+        if (frameRef.current < MEASURE_FRAMES[attemptRef.current])
+            return;
+        attemptRef.current += 1;
+        const group = groupRef.current;
+        if (group === null)
+            return;
+        const measured = measureLocalBounds(group);
+        if (measured === null)
+            return;
+        if (lastMeshCountRef.current === measured.meshCount)
+            return;
+        lastMeshCountRef.current = measured.meshCount;
+        reportMeasuredBounds(ctx, target, measureKey, measured);
+    });
+    return _jsx("group", { ref: groupRef, children: children });
+}

package/dist/render/resolveModel.js

@@ -1,3 +1,17 @@
+/**
+ * The `ModelConfig` a resolved catalog ref renders as. Stamps `animation: "auto"` so any rigged
+ * catalog asset animates by default — the shell derives idle/walk/run states and one-shots from
+ * the loaded GLB's clip names; clipless models are unaffected. An explicit `style.animation`
+ * (merged after resolve) or `"none"` overrides.
+ */
+function catalogModelConfig(ref) {
+    return {
+        url: ref.url,
+        ...(ref.dims === undefined ? {} : { dims: ref.dims }),
+        ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
+        animation: "auto",
+    };
+}
 /**
  * Resolve a string asset id or a direct ModelConfig. Missing/misspelled catalog
  * ids throw — silent generic-primitive fallback only happens when the mapping
@@ -14,11 +28,7 @@ export function resolveModel(value, assets, context) {
         const where = context === undefined ? `model asset "${value}"` : `${context.seam}["${context.key}"] → "${value}"`;
         throw new Error(`[jgengine] missing ${where} — not in the asset catalog. Fix the id, register it, or omit the mapping to keep the deliberate primitive/sprite fallback.`);
     }
-    return {
-        url: ref.url,
-        ...(ref.dims === undefined ? {} : { dims: ref.dims }),
-        ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
-    };
+    return catalogModelConfig(ref);
 }
 /** Soft lookup used when an object catalog id may double as a model asset id.
  * @internal
@@ -27,11 +37,7 @@ export function tryResolveCatalogModel(id, assets) {
     const ref = assets.resolve(id);
     if (ref === null)
         return undefined;
-    return {
-        url: ref.url,
-        ...(ref.dims === undefined ? {} : { dims: ref.dims }),
-        ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
-    };
+    return catalogModelConfig(ref);
 }
 /**
  * Resolve an entity model plus bone-attachment / kit-of-parts models through the catalog

package/dist/render/useModelAnimation.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from "three";
+import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
+/**
+ * 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.
+ */
+export declare function useModelAnimation(scene: THREE.Object3D, clips: THREE.AnimationClip[], animationInput: ModelAnimationConfig | "auto" | "none" | undefined, instanceId?: string): void;