@jgengine/shell 0.18.1 → 0.21.0

package/dist/render/useModelAnimation.js

@@ -1,16 +1,21 @@
-import { useFrame } from "@react-three/fiber";
+import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
 import { ANIM_PARAMS_KEY, createAnimGraphRuntime, } from "@jgengine/core/anim/animGraph";
-import { LOCOMOTION_SPEED_PARAM, locomotionGraph } from "@jgengine/core/anim/locomotionGraph";
+import { animGraphFromConfig, LOCOMOTION_CROUCHED_PARAM, LOCOMOTION_GROUNDED_PARAM, LOCOMOTION_SPEED_PARAM, LOCOMOTION_VERTICAL_SPEED_PARAM } from "@jgengine/core/anim/locomotionGraph";
+import { playerMovementTelemetry } from "@jgengine/core/movement/playerMovement";
+import { seededRng } from "@jgengine/core/random/rng";
 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")
+            if (state.kind === "clip") {
                 names.add(state.clip);
+                for (const variant of state.variants ?? [])
+                    names.add(variant);
+            }
             else
                 for (const point of state.points)
                     names.add(point.clip);
@@ -19,54 +24,165 @@ function graphClipNames(graph) {
     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
- * an attack clip, so an actor "idles" mid-swing) and one-shots are dropped, so deaths and attacks
- * never play. Neither leaves a trace, which makes a mistyped or wrong-pack clip name one of the
- * hardest render bugs to see — the model loads, animates, and is simply wrong forever.
+ * Checks clip mappings, masked layers and root-motion assumptions without starting a mixer.
  *
- * Warn once per mount with the names that missed and the names the rig actually has, so the fix
- * (usually deleting the hand-written config and letting `"auto"` derive it) is obvious.
+ * @capability model-animation-diagnostics inspect imported clip mappings, layer masks and root-track compatibility
  */
-function warnMissingClips(animation, clips) {
-    if (typeof console === "undefined")
-        return;
+export function diagnoseModelAnimation(scene, animation, clips) {
+    const diagnostics = [];
+    if (animation.auto === true) {
+        const automatic = resolveAnimationConfig(animation, clips.map((clip) => clip.name));
+        if (automatic === undefined)
+            return [{
+                    code: "missing-auto-idle",
+                    message: `explicit automatic playback needs an identifiable idle clip on this rig. Available: ${clips.length === 0 ? "none" : clips.map((clip) => clip.name).join(", ")}. The bind pose is retained; use a supported animated asset or disable automatic derivation and author this rig's clip mapping.`,
+                }];
+        animation = automatic;
+    }
     const available = new Set(clips.map((clip) => clip.name));
     const missing = new Set();
-    const { states, oneShots, graph } = animation;
-    if (states !== undefined) {
-        for (const name of [states.idle, states.walk, states.run]) {
-            if (name !== undefined && !available.has(name))
-                missing.add(name);
-        }
+    const resolved = animGraphFromConfig(animation);
+    const { states } = animation;
+    if (animation.graph === undefined && states !== undefined) {
+        if (typeof states.idle !== "string" || states.idle.trim().length === 0)
+            diagnostics.push({
+                code: "incomplete-locomotion", message: `locomotion needs a nonempty idle clip. Configure this rig's idle role; ${animation.clip === undefined ? "the bind pose is retained" : `single clip "${animation.clip}" remains active`} until then.`,
+            });
+        else if (typeof states.walk !== "string" || states.walk.trim().length === 0)
+            diagnostics.push({
+                code: "incomplete-locomotion", message: `locomotion has no walk clip; idle "${states.idle}" is held at walking speeds until this rig's walk role is configured.`,
+            });
     }
-    if (oneShots !== undefined) {
-        for (const spec of Object.values(oneShots)) {
-            for (const name of typeof spec === "string" ? [spec] : spec) {
-                if (!available.has(name))
-                    missing.add(name);
-            }
-        }
-    }
-    if (graph !== undefined) {
-        for (const name of graphClipNames(graph))
+    if (resolved !== undefined) {
+        for (const name of graphClipNames(resolved))
             if (!available.has(name))
                 missing.add(name);
     }
-    if (animation.clip !== undefined && !available.has(animation.clip))
+    else if (animation.clip !== undefined && !available.has(animation.clip))
         missing.add(animation.clip);
-    if (missing.size === 0)
+    if (missing.size > 0)
+        diagnostics.push({ code: "missing-clip", message: `clip(s) ${[...missing].map((name) => `"${name}"`).join(", ")} ` +
+                `not found on this rig. Available: ${clips.map((clip) => clip.name).join(", ")}. ` +
+                `Missing clips contribute no pose; an invalid single-clip config retains the bind pose. Set animation: "auto" to ` +
+                `derive states/one-shots from the rig's own clip names.`,
+        });
+    if (resolved !== undefined) {
+        let root;
+        scene.traverse((node) => { if (root === undefined && node.isBone === true)
+            root = node; });
+        const rootTrackName = root === undefined ? undefined : `${root.name}.position`;
+        for (const layer of resolved.layers) {
+            const layerNames = graphClipNames({ layers: [layer] });
+            if (layer.mask !== undefined && !clips.some((clip) => layerNames.has(clip.name) && clip.tracks.some((track) => layer.mask.some((prefix) => track.name.startsWith(prefix))))) {
+                diagnostics.push({ code: "empty-layer-mask", message: `layer "${layer.id}" mask matches no imported animation tracks. Use this rig's bone-name prefixes.` });
+            }
+            for (const [id, state] of Object.entries(layer.states)) {
+                if (state.rootMotion !== true)
+                    continue;
+                const names = state.kind === "clip" ? state.variants ?? [state.clip] : state.points.map((point) => point.clip);
+                const missingTracks = names.filter((name) => {
+                    const clip = clips.find((candidate) => candidate.name === name);
+                    return clip !== undefined && (rootTrackName === undefined || !clip.tracks.some((track) => track.name === rootTrackName && (layer.mask === undefined || layer.mask.some((prefix) => track.name.startsWith(prefix)))));
+                });
+                if (missingTracks.length > 0)
+                    diagnostics.push({ code: "missing-root-track", message: `root-motion state "${layer.id}/${id}" has no assigned position track for ${root === undefined ? "a root bone" : `first bone "${root.name}"`} in ${missingTracks.join(", ")}. ` +
+                            `Root travel cannot be extracted; use an in-place state or supply a supported root-bone track.`,
+                    });
+            }
+        }
+    }
+    return diagnostics;
+}
+function warnAnimationDiagnostics(scene, animation, clips) {
+    if (typeof console === "undefined")
         return;
-    console.warn(`[jgengine] model animation: clip(s) ${[...missing].map((name) => `"${name}"`).join(", ")} ` +
-        `not found on this rig. Available: ${clips.map((clip) => clip.name).join(", ")}. ` +
-        `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.`);
+    for (const diagnostic of diagnoseModelAnimation(scene, animation, clips))
+        console.warn(`[jgengine] model animation: ${diagnostic.message}`);
+}
+/**
+ * Refreshes a caller-owned graph parameter dictionary from authored extras and known physical movement.
+ * Grounded, verticalSpeed and crouched use the shared motor's resolved state when available; custom movers
+ * retain their authored values. Speed always uses the supplied measured ground speed. Does not write game state.
+ *
+ * @capability animation-motion-params read resolved player movement into reusable animation graph parameters
+ */
+export function readModelAnimationParams(ctx, instanceId, speed, out) {
+    const extra = ctx.scene.entity.blackboard.get(instanceId, ANIM_PARAMS_KEY);
+    const motion = playerMovementTelemetry(ctx, instanceId);
+    if (out === extra || out === motion)
+        throw new Error("readModelAnimationParams requires a caller-owned output dictionary distinct from the entity blackboard and movement telemetry");
+    for (const key in out)
+        if (Object.hasOwn(out, key))
+            delete out[key];
+    if (extra !== undefined)
+        Object.assign(out, extra);
+    if (motion !== null) {
+        out[LOCOMOTION_GROUNDED_PARAM] = motion.grounded;
+        out[LOCOMOTION_VERTICAL_SPEED_PARAM] = motion.verticalVelocity;
+        out[LOCOMOTION_CROUCHED_PARAM] = motion.crouching;
+    }
+    out[LOCOMOTION_SPEED_PARAM] = speed;
+    return out;
 }
 /** Per-layer action key: a masked or additive layer needs its own clip variant even for a clip another layer plays. */
 function actionKey(layer, clip) {
     return `${layer}:${clip}`;
 }
-function buildGraphPlayback(scene, mixer, graph, clips) {
+const 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) {
+    warnAnimationDiagnostics(scene, { graph }, clips);
+    const mixer = new THREE.AnimationMixer(scene);
+    const playback = buildGraphPlayback(scene, mixer, graph, clips);
+    return {
+        durations: playback.durations,
+        apply(output, rootMotion = false) {
+            applyGraphClips(playback.actions, output);
+            mixer.update(0);
+            if (rootMotion && playback.rootBone !== null && playback.rootBindPosition !== null) {
+                playback.rootBone.position.x = playback.rootBindPosition.x;
+                playback.rootBone.position.z = playback.rootBindPosition.z;
+            }
+        },
+        dispose() {
+            mixer.stopAllAction();
+            mixer.uncacheRoot(scene);
+        },
+    };
+}
+function buildGraphPlayback(scene, mixer, graph, clips, rng) {
     const actions = new Map();
     const durations = {};
     let resolvedRootBone = null;
@@ -85,8 +201,11 @@ function buildGraphPlayback(scene, mixer, graph, clips) {
     for (const layer of graph.layers) {
         const names = new Set();
         for (const state of Object.values(layer.states)) {
-            if (state.kind === "clip")
+            if (state.kind === "clip") {
                 names.add(state.clip);
+                for (const variant of state.variants ?? [])
+                    names.add(variant);
+            }
             else
                 for (const point of state.points)
                     names.add(point.clip);
@@ -95,13 +214,13 @@ function buildGraphPlayback(scene, mixer, graph, clips) {
             const source = THREE.AnimationClip.findByName(clips, name);
             if (source === null)
                 continue;
-            let clip = source;
+            // Mixer actions are cached by clip UUID; each layer needs independent time and weight.
+            let clip = source.clone();
             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);
@@ -116,13 +235,14 @@ function buildGraphPlayback(scene, mixer, graph, clips) {
         }
     }
     return {
-        runtime: createAnimGraphRuntime(graph),
+        runtime: createAnimGraphRuntime(graph, { rng }),
         actions,
         durations,
         rootBone,
         rootBindPosition: rootBone?.position.clone() ?? null,
         lastPos: null,
         smoothedSpeed: 0,
+        params: {},
     };
 }
 /**
@@ -133,62 +253,67 @@ function buildGraphPlayback(scene, mixer, graph, clips) {
  * `entity.animation` / `combat.hitReaction` / `entity.died`, held poses, and the death clamp.
  * With `animation.graph` set, the headless `AnimGraph` runtime owns every clip's time and weight
  * and the mixer only applies them; clip events surface as `animation.event`.
+ * Equivalent same-order config data retains playback across rerenders; actual data edits reset it.
+ * Entity-bound playback holds while context game time is frozen; unbound previews keep playing.
  */
 export function useModelAnimation(scene, clips, animationInput, instanceId) {
+    const invalidate = useThree((state) => state.invalidate);
     // Optional: a model must still animate its bind pose / auto clip in a preview or inspector that
     // has no running game — a hard context requirement made every part composition unviewable outside
     // the world, which is half of why #1588 took a session to see.
     const ctx = useOptionalGameContext();
     // "auto" (stamped by catalog resolution, or set inline) derives states/one-shots from the
     // loaded GLB's actual clip names; "none" and absent render the bind pose.
-    const animation = useMemo(() => resolveAnimationConfig(animationInput, clips.map((clip) => clip.name)), [animationInput, clips]);
+    // Equivalent fresh JSON data retains playback, pending triggers and visual RNG.
+    // The private snapshot observes edits on render, including reused nested objects.
+    // Preserve one-shot insertion order: simultaneous non-death triggers depend on it.
+    const animationKey = JSON.stringify(animationInput);
+    const animation = useMemo(() => resolveAnimationConfig(animationKey === undefined ? undefined : JSON.parse(animationKey), clips.map((clip) => clip.name)), [animationKey, clips]);
     const mixerRef = useRef(null);
+    const actionRef = useRef(null);
     const animationPausedRef = useRef(false);
     const graphRef = useRef(null);
+    const advancedSecondsRef = useRef(undefined);
     const states = animation?.states;
     const oneShots = animation?.oneShots;
-    const graph = useMemo(() => {
-        if (animation?.graph !== undefined)
-            return animation.graph;
-        if (states === undefined)
-            return undefined;
-        const graphOneShots = {};
-        for (const [event, spec] of Object.entries(oneShots ?? {})) {
-            const clip = typeof spec === "string" ? spec : spec[0];
-            if (clip !== undefined)
-                graphOneShots[event] = clip;
-        }
-        return locomotionGraph({
-            idle: states.idle,
-            walk: states.walk,
-            ...(states.run === undefined ? {} : { run: states.run }),
-            walkSpeed: states.walkSpeed,
-            runSpeed: states.runSpeed,
-            fadeSec: states.fadeSec,
-            ...(Object.keys(graphOneShots).length === 0 ? {} : { oneShots: graphOneShots }),
-        });
-    }, [animation?.graph, states, oneShots]);
+    const authoredGraph = animation?.graph;
+    const graph = useMemo(() => animGraphFromConfig({ graph: authoredGraph, states, oneShots }), [authoredGraph, states, oneShots]);
+    const usesGameClock = animation?.clock === "game" && ctx !== null && instanceId !== undefined;
     useEffect(() => {
+        advancedSecondsRef.current = usesGameClock ? ctx.time.advancedSeconds?.() : undefined;
+        if (usesGameClock && advancedSecondsRef.current === undefined) {
+            console.warn('[jgengine] model animation: bound game playback requires time.advancedSeconds() accepted progress. Playback is held; provide an engine clock or select clock: "real".');
+        }
+        if (animation !== undefined)
+            warnAnimationDiagnostics(scene, animation, clips);
+        else if (typeof animationInput === "object" && animationInput.auto === true)
+            warnAnimationDiagnostics(scene, animationInput, clips);
         if (animation === undefined || clips.length === 0) {
             mixerRef.current = null;
+            actionRef.current = null;
             graphRef.current = null;
             return;
         }
-        warnMissingClips(animation, clips);
         const mixer = new THREE.AnimationMixer(scene);
         if (graph !== undefined) {
-            graphRef.current = buildGraphPlayback(scene, mixer, graph, clips);
+            // Rendering/culling must never advance simulation randomness. Each model has its own
+            // reproducible visual stream, independent of other mounted models and gameplay draws.
+            const visualRng = seededRng(JSON.stringify(["model-animation", instanceId ?? "preview", clips.map((clip) => clip.name).sort()]));
+            graphRef.current = buildGraphPlayback(scene, mixer, graph, clips, visualRng);
             mixer.update(0);
             mixerRef.current = mixer;
-            animationPausedRef.current = false;
+            animationPausedRef.current = animation.paused === true;
+            invalidate();
             return () => {
                 mixer.stopAllAction();
+                mixer.uncacheRoot(scene);
                 mixerRef.current = null;
                 graphRef.current = null;
             };
         }
-        const clip = (animation.clip !== undefined ? THREE.AnimationClip.findByName(clips, animation.clip) : undefined) ??
-            clips[0];
+        const clip = animation.clip !== undefined ? THREE.AnimationClip.findByName(clips, animation.clip) : states === undefined ? clips[0] : undefined;
+        if (clip === null || clip === undefined)
+            return;
         const action = mixer.clipAction(clip);
         action.setLoop(animation.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Infinity);
         action.clampWhenFinished = animation.loop === false;
@@ -200,14 +325,19 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             action.time = animation.time;
         mixer.update(0);
         mixerRef.current = mixer;
+        actionRef.current = action;
         animationPausedRef.current = animation.paused === true;
+        invalidate();
         return () => {
             mixer.stopAllAction();
+            mixer.uncacheRoot(scene);
             mixerRef.current = null;
+            actionRef.current = null;
         };
     }, [
         scene,
         clips,
+        animationKey,
         animation?.clip,
         animation?.loop,
         animation?.timeScale,
@@ -216,14 +346,19 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
         states,
         oneShots,
         graph,
+        ctx,
+        instanceId,
+        invalidate,
     ]);
     useEffect(() => {
         if (ctx === null || instanceId === undefined || (oneShots === undefined && graph === undefined))
             return;
         const fire = (event) => {
             const playback = graphRef.current;
-            if (playback !== null)
+            if (playback !== null) {
                 playback.runtime.trigger(event);
+                invalidate();
+            }
         };
         const offAnimation = ctx.game.events.on("entity.animation", (event) => {
             if (event.instanceId === instanceId)
@@ -242,56 +377,67 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             offHit();
             offDied();
         };
-    }, [ctx, instanceId, oneShots, graph]);
+    }, [ctx, instanceId, oneShots, graph, invalidate]);
     useFrame((_state, delta) => {
+        // Checkpoint held frames too, so resuming never replays their accepted time.
+        const advancedSeconds = usesGameClock ? ctx.time.advancedSeconds?.() : undefined;
+        const previousSeconds = advancedSecondsRef.current;
+        advancedSecondsRef.current = advancedSeconds;
+        if (animationPausedRef.current || animation?.timeScale === 0)
+            return;
+        if (ctx !== null && instanceId !== undefined && (ctx.time.speed() === 0 || ctx.time.timescale() === 0))
+            return;
+        let playbackDelta = delta;
+        if (usesGameClock) {
+            if (advancedSeconds === undefined || previousSeconds === undefined || advancedSeconds <= previousSeconds)
+                return;
+            playbackDelta = advancedSeconds - previousSeconds;
+        }
         const playback = graphRef.current;
         if (playback !== null && mixerRef.current !== null) {
-            const params = {};
+            const params = playback.params;
             if (ctx !== null && instanceId !== undefined) {
                 const entity = ctx.scene.entity.get(instanceId);
-                if (entity !== null && delta > 0) {
+                if (entity !== null && playbackDelta > 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);
+                        const dx = x - playback.lastPos[0];
+                        const dy = entity.position[1] - playback.lastPos[1];
+                        const dz = z - playback.lastPos[2];
+                        const snapDistance = ctx.sim.loop.config().snapDistance;
+                        if (dx * dx + dy * dy + dz * dz > snapDistance * snapDistance) {
+                            playback.smoothedSpeed = 0;
+                        }
+                        else {
+                            const instantSpeed = Math.hypot(dx, dz) / playbackDelta;
+                            playback.smoothedSpeed += (instantSpeed - playback.smoothedSpeed) * Math.min(1, playbackDelta * 12);
+                        }
                     }
                     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);
+                readModelAnimationParams(ctx, instanceId, playback.smoothedSpeed, params);
             }
-            params[LOCOMOTION_SPEED_PARAM] = playback.smoothedSpeed;
-            const out = playback.runtime.advance(delta * (animation?.timeScale ?? 1), params, playback.durations);
-            for (const action of playback.actions.values())
-                action.weight = 0;
-            for (const entry of out.clips) {
-                const action = playback.actions.get(actionKey(entry.layer, entry.clip));
-                if (action === undefined)
-                    continue;
-                action.weight += entry.weight;
-                action.time = entry.time;
+            else {
+                for (const key in params)
+                    if (Object.hasOwn(params, key))
+                        delete params[key];
+                params[LOCOMOTION_SPEED_PARAM] = playback.smoothedSpeed;
             }
+            const out = playback.runtime.advance(playbackDelta * (animation?.timeScale ?? 1), params, playback.durations);
+            applyGraphClips(playback.actions, out.clips);
             mixerRef.current.update(0);
-            const currentPlayback = graphRef.current;
-            if (currentPlayback !== null && currentPlayback.rootBone !== null && currentPlayback.rootBindPosition !== null) {
-                currentPlayback.rootBone.position.copy(currentPlayback.rootBindPosition);
+            if (out.rootMotion === true && playback.rootBone !== null && playback.rootBindPosition !== null) {
+                playback.rootBone.position.x = playback.rootBindPosition.x;
+                playback.rootBone.position.z = playback.rootBindPosition.z;
             }
             if (ctx !== null && instanceId !== undefined) {
-                const rootDelta = out.rootDelta;
-                const entity = rootDelta === undefined ? null : ctx.scene.entity.get(instanceId);
-                if (entity !== null && rootDelta !== undefined) {
-                    ctx.scene.entity.setPose(instanceId, {
-                        position: [entity.position[0] + rootDelta[0], entity.position[1] + rootDelta[1], entity.position[2] + rootDelta[2]],
-                        dt: delta,
-                    });
-                }
                 for (const event of out.events)
                     ctx.game.events.emit("animation.event", { instanceId, name: event.name, clip: event.clip });
             }
             return;
         }
-        if (mixerRef.current !== null && !animationPausedRef.current)
-            mixerRef.current.update(delta);
+        if (mixerRef.current !== null && actionRef.current?.isRunning()) {
+            mixerRef.current.update(playbackDelta);
+        }
     });
 }

package/dist/render/useModelInstance.d.ts

@@ -0,0 +1,25 @@
+import { Group, type Object3D } from "three";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+/** Model loading, placement, shadows and animation for a custom renderer. */
+export type ModelInstanceConfig = Pick<ModelConfig, "url" | "scale" | "targetHeight" | "y" | "anchor" | "dims" | "shadows" | "animation" | "hiddenNodes">;
+/** Caller-owned styling runs on the isolated clone, never the loader cache. */
+export interface ModelInstanceOptions {
+    instanceId?: string;
+    /** Configure each new clone before placement measurement. Memoize this callback; changing it replaces the instance. Materials are isolated; geometry/textures stay borrowed. */
+    configure?: (content: Object3D) => void;
+}
+/** Render `scene` with `position` and uniform `scale`; animate or deform `content` inside that placement frame. */
+export interface ModelInstance {
+    content: Object3D;
+    scene: Group;
+    scale: number;
+    position: [number, number, number];
+}
+/**
+ * Load and own an isolated model instance, preserving imported transforms and measuring placement at bind pose.
+ * Apply hiddenNodes to the configured clone before measurement; equivalent name lists retain the instance.
+ * Mount `scene` with the returned position/scale. Custom materials, deformation and surrounding geometry stay caller-owned.
+ * Must run inside an R3F canvas and Suspense boundary; a game provider is optional.
+ * @capability model-instance own loading, clone cleanup, placement and animation for a custom model renderer
+ */
+export declare function useModelInstance(model: ModelInstanceConfig, options?: ModelInstanceOptions): ModelInstance;

package/dist/render/useModelInstance.js

@@ -0,0 +1,43 @@
+import { useLoader, useThree } from "@react-three/fiber";
+import { useEffect, useMemo } from "react";
+import { Group } from "three";
+import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility";
+import { measureLocalBounds } from "./measureBounds.js";
+import { detectKtx2Support, sharedGltfLoader } from "./modelLoad.js";
+import { cloneModelScene, disposeModelScene, modelPlacementTransform } from "./modelRender.js";
+import { useModelAnimation } from "./useModelAnimation.js";
+import { applyModelNodeVisibility, modelHiddenNodesKey } from "./modelNodeVisibility.js";
+/**
+ * Load and own an isolated model instance, preserving imported transforms and measuring placement at bind pose.
+ * Apply hiddenNodes to the configured clone before measurement; equivalent name lists retain the instance.
+ * Mount `scene` with the returned position/scale. Custom materials, deformation and surrounding geometry stay caller-owned.
+ * Must run inside an R3F canvas and Suspense boundary; a game provider is optional.
+ * @capability model-instance own loading, clone cleanup, placement and animation for a custom model renderer
+ */
+export function useModelInstance(model, options = {}) {
+    const hiddenNodes = parseModelHiddenNodes(model.hiddenNodes);
+    const renderer = useThree(state => state.gl);
+    if (renderer.isWebGLRenderer)
+        detectKtx2Support(renderer);
+    const gltf = useLoader(sharedGltfLoader, model.url);
+    const { configure, instanceId } = options;
+    const hiddenNodesKey = modelHiddenNodesKey(hiddenNodes);
+    const { content, scene, bindBounds } = useMemo(() => {
+        const content = cloneModelScene(gltf.scene, { shadows: model.shadows });
+        try {
+            configure?.(content);
+            for (const diagnostic of applyModelNodeVisibility(content, hiddenNodes))
+                console.warn(`Model ${model.url} hiddenNodes: ${diagnostic.message}`);
+            const scene = new Group().add(content);
+            return { content, scene, bindBounds: measureLocalBounds(scene) };
+        }
+        catch (error) {
+            disposeModelScene(content);
+            throw error;
+        }
+    }, [gltf.scene, model.shadows, configure, hiddenNodesKey]);
+    const placement = useMemo(() => modelPlacementTransform(scene, model, bindBounds), [scene, bindBounds, model.scale, model.targetHeight, model.y, model.anchor, model.dims]);
+    useEffect(() => () => disposeModelScene(content), [content]);
+    useModelAnimation(content, gltf.animations, model.animation, instanceId);
+    return { content, scene, ...placement };
+}

package/dist/scatter/scatterModels.d.ts

@@ -5,6 +5,8 @@ export interface ScatterModelSource {
     geometry: THREE.BufferGeometry;
     material: THREE.Material | THREE.Material[];
     localMatrix: THREE.Matrix4;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
 }
 /**
  * Clones a loaded GLTF scene (so shared cache materials stay untouched), applies the model's material
@@ -18,8 +20,7 @@ export declare function buildScatterModelSources(gltfScene: THREE.Object3D, mode
     root: THREE.Object3D;
 };
 /**
- * Disposes the cloned materials harvested by {@link buildScatterModelSources}; never disposes geometry
- * (still owned by the loader cache).
+ * Releases the instance resources harvested by {@link buildScatterModelSources}, retaining cached assets.
  * @internal
  */
 export declare function disposeScatterModelSources(root: THREE.Object3D): void;

package/dist/scatter/scatterModels.js

@@ -1,6 +1,7 @@
 import * as THREE from "three";
+import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility";
 import { applyMaterialOverride } from "../materialOverride.js";
-import { cloneModelScene, disposeClonedMaterials } from "../render/modelRender.js";
+import { cloneModelScene, disposeModelScene, ownModelMaterial } from "../render/modelRender.js";
 /** The scale + position offset a `ModelConfig` applies before any per-instance transform — same anchor/targetHeight rules as the single-instance entity renderer. */
 function scatterModelBaseTransform(scene, model) {
     let scale = model.scale ?? 1;
@@ -33,13 +34,19 @@ function scatterModelBaseTransform(scene, model) {
  * @internal — the GLB-harvesting behind `InstancedScatter`'s `resolveItem` override.
  */
 export function buildScatterModelSources(gltfScene, model) {
-    const root = cloneModelScene(gltfScene);
+    if (parseModelHiddenNodes(model.hiddenNodes)?.length)
+        throw new Error("Instanced model node visibility requires the individual model renderer; use EntityModel for hidden nodes");
+    if (model.materialAssignments?.length)
+        throw new Error("Instanced model material assignments require the individual model renderer; use EntityModel for authored slots");
+    if (model.material?.maps !== undefined)
+        throw new Error("Instanced model override maps require an owned texture loader; use EntityModel for authored maps");
+    const root = cloneModelScene(gltfScene, { shadows: model.shadows });
     if (model.material !== undefined)
-        applyMaterialOverride(root, model.material, { clone: false });
+        applyMaterialOverride(root, model.material, { clone: false, ownMaterial: material => ownModelMaterial(root, material) });
     root.updateMatrixWorld(true);
     const base = scatterModelBaseTransform(root, model);
     const sources = [];
-    root.traverse((node) => {
+    root.traverseVisible((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
@@ -47,15 +54,16 @@ export function buildScatterModelSources(gltfScene, model) {
             geometry: mesh.geometry,
             material: mesh.material,
             localMatrix: base.clone().multiply(mesh.matrixWorld),
+            castShadow: mesh.castShadow,
+            receiveShadow: mesh.receiveShadow,
         });
     });
     return { sources, root };
 }
 /**
- * Disposes the cloned materials harvested by {@link buildScatterModelSources}; never disposes geometry
- * (still owned by the loader cache).
+ * Releases the instance resources harvested by {@link buildScatterModelSources}, retaining cached assets.
  * @internal
  */
 export function disposeScatterModelSources(root) {
-    disposeClonedMaterials(root);
+    disposeModelScene(root);
 }