@jgengine/shell 0.12.0 → 0.14.0

package/dist/render/SceneModels.js

@@ -3,9 +3,12 @@ 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 { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.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 +29,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 +86,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 +122,38 @@ 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);
-        });
-        const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
-            if (event.instanceId === instanceId)
-                fire("hit");
+        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 offDied = ctx.game.events.on("entity.died", (event) => {
-            if (event.instanceId === instanceId)
-                fire("death");
+    }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey, dimsMaxY]);
+    // Runs with or without index dims: the loaded geometry upgrades whatever box the kind resolved
+    // (fitted or measured) to a hitbox that raycasts the model's own triangles.
+    useEffect(() => {
+        if (measureTarget === undefined || measureKey === undefined)
+            return;
+        const triangles = measureLocalCollisionTriangles(scene, {
+            scale,
+            offset: [positionX, positionY, positionZ],
         });
-        return () => {
-            offAnimation();
-            offHit();
-            offDied();
-        };
-    }, [ctx, instanceId, oneShots]);
+        if (triangles !== null)
+            reportMeasuredCollisionMesh(ctx, measureTarget, measureKey, triangles);
+    }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey]);
+    useModelAnimation(scene, gltf.animations, model.animation, instanceId);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
     const paintVersionRef = useRef(-1);
@@ -276,41 +167,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 +190,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,131 @@
+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";
+import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
+/** 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);
+        const triangles = measureLocalCollisionTriangles(group);
+        if (triangles !== null)
+            reportMeasuredCollisionMesh(ctx, target, measureKey, triangles);
+    });
+    return _jsx("group", { ref: groupRef, children: children });
+}

package/dist/render/measureCollisionMesh.d.ts

@@ -0,0 +1,26 @@
+import * as THREE from "three";
+import type { CollisionMeshSource } from "@jgengine/core/scene/collisionMesh";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+/** Entity-local triangle soup of the meshes under a measured root, plus the contributing mesh count
+ * (same async fill-in detection as measured bounds). Satisfies {@link CollisionMeshSource}. */
+export interface MeasuredCollisionTriangles extends CollisionMeshSource {
+    positions: Float32Array;
+    indices: Uint32Array;
+    triangleCount: number;
+    meshCount: number;
+}
+/**
+ * Collect the triangle soup of the meshes under `root` in `root`'s own frame — the mesh-accurate
+ * counterpart to `measureLocalBounds`, with the same visibility/sprite/{@link MEASURE_EXCLUDE_KEY}
+ * exclusions (skinned meshes contribute their bind pose). An optional uniform `scale` + `offset`
+ * maps the result into entity-local space when the caller mounts the root scaled/translated (the
+ * model-primitive path). Returns `null` when nothing is measurable or the soup exceeds the
+ * triangle budget — callers keep their box fallback.
+ */
+export declare function measureLocalCollisionTriangles(root: THREE.Object3D, transform?: {
+    scale: number;
+    offset: readonly [number, number, number];
+}): MeasuredCollisionTriangles | null;
+/** Forward measured triangles into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same soup so remounts and multi-instance kinds don't rebuild the BVH. */
+export declare function reportMeasuredCollisionMesh(ctx: GameContext, target: "entity" | "object", key: string, triangles: MeasuredCollisionTriangles): void;

package/dist/render/measureCollisionMesh.js

@@ -0,0 +1,108 @@
+import * as THREE from "three";
+import { MEASURE_EXCLUDE_KEY } from "./measureBounds.js";
+/** Above this the model is too dense to double as its own hitbox — keep the fitted box instead of
+ * paying BVH build + per-ray traversal on a hero-detail mesh. Game-ready low-poly assets sit far under it. */
+const MAX_COLLISION_TRIANGLES = 60_000;
+const IDENTITY = new THREE.Matrix4();
+const tmpVec = new THREE.Vector3();
+function collectTriangles(object, parentMatrix, sink) {
+    if (sink.overflow)
+        return;
+    if (parentMatrix !== null) {
+        if (!object.visible)
+            return;
+        if (object.isSprite === true)
+            return;
+        if (object.userData[MEASURE_EXCLUDE_KEY] === true)
+            return;
+    }
+    let matrix = null;
+    if (parentMatrix !== null) {
+        if (object.matrixAutoUpdate)
+            object.updateMatrix();
+        matrix = new THREE.Matrix4().multiplyMatrices(parentMatrix, object.matrix);
+    }
+    const mesh = object;
+    if (mesh.isMesh === true && mesh.geometry !== undefined) {
+        const geometry = mesh.geometry;
+        const positionAttribute = geometry.getAttribute("position");
+        if (positionAttribute !== undefined && positionAttribute.itemSize === 3 && positionAttribute.count >= 3) {
+            const base = sink.positions.length / 3;
+            const applied = matrix ?? IDENTITY;
+            for (let v = 0; v < positionAttribute.count; v += 1) {
+                tmpVec.fromBufferAttribute(positionAttribute, v).applyMatrix4(applied);
+                sink.positions.push(tmpVec.x, tmpVec.y, tmpVec.z);
+            }
+            const index = geometry.getIndex();
+            const triangleCount = index !== null ? Math.floor(index.count / 3) : Math.floor(positionAttribute.count / 3);
+            if (sink.triangleCount + triangleCount > MAX_COLLISION_TRIANGLES) {
+                sink.overflow = true;
+                return;
+            }
+            if (index !== null) {
+                for (let i = 0; i + 2 < index.count; i += 3) {
+                    sink.indices.push(base + index.getX(i), base + index.getX(i + 1), base + index.getX(i + 2));
+                }
+            }
+            else {
+                for (let i = 0; i + 2 < positionAttribute.count; i += 3) {
+                    sink.indices.push(base + i, base + i + 1, base + i + 2);
+                }
+            }
+            sink.triangleCount += triangleCount;
+            sink.meshCount += 1;
+        }
+    }
+    const childMatrix = matrix ?? IDENTITY;
+    for (const child of object.children)
+        collectTriangles(child, childMatrix, sink);
+}
+/**
+ * Collect the triangle soup of the meshes under `root` in `root`'s own frame — the mesh-accurate
+ * counterpart to `measureLocalBounds`, with the same visibility/sprite/{@link MEASURE_EXCLUDE_KEY}
+ * exclusions (skinned meshes contribute their bind pose). An optional uniform `scale` + `offset`
+ * maps the result into entity-local space when the caller mounts the root scaled/translated (the
+ * model-primitive path). Returns `null` when nothing is measurable or the soup exceeds the
+ * triangle budget — callers keep their box fallback.
+ */
+export function measureLocalCollisionTriangles(root, transform) {
+    const sink = { positions: [], indices: [], meshCount: 0, triangleCount: 0, overflow: false };
+    collectTriangles(root, null, sink);
+    if (sink.overflow || sink.meshCount === 0 || sink.triangleCount === 0)
+        return null;
+    const positions = new Float32Array(sink.positions);
+    if (transform !== undefined) {
+        const { scale, offset } = transform;
+        for (let v = 0; v < positions.length; v += 3) {
+            positions[v] = positions[v] * scale + offset[0];
+            positions[v + 1] = positions[v + 1] * scale + offset[1];
+            positions[v + 2] = positions[v + 2] * scale + offset[2];
+        }
+    }
+    return {
+        positions,
+        indices: new Uint32Array(sink.indices),
+        triangleCount: sink.triangleCount,
+        meshCount: sink.meshCount,
+    };
+}
+const reportedByContext = new WeakMap();
+/** Forward measured triangles into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same soup so remounts and multi-instance kinds don't rebuild the BVH. */
+export function reportMeasuredCollisionMesh(ctx, target, key, triangles) {
+    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 === triangles.meshCount && prev.triangleCount === triangles.triangleCount) {
+        return;
+    }
+    const accepted = target === "entity"
+        ? ctx.scene.entity.reportCollisionMesh(key, triangles)
+        : ctx.scene.object.reportCollisionMesh(key, triangles);
+    if (accepted)
+        map.set(registryKey, { meshCount: triangles.meshCount, triangleCount: triangles.triangleCount });
+}

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;