@jgengine/shell 0.19.0 → 0.22.0

package/dist/render/rigNode.js

@@ -0,0 +1,32 @@
+/**
+ * Resolves a bone or attachment slot by its exact runtime name first, then by the original
+ * imported name preserved as `userData.name`. GLTFLoader sanitizes names such as `handslot.r`
+ * to `handslotr`; authored references remain usable without renaming the animated hierarchy.
+ * Both lookups require a unique target. Call on model load or slot changes, not each frame,
+ * and keep the result with that model instance rather than reusing a cached asset's node.
+ *
+ * @capability imported-rig-node resolve original imported bone and slot names with ambiguity diagnostics
+ */
+export function resolveRigNode(rig, name) {
+    const exact = [];
+    const authored = [];
+    rig.traverse((node) => {
+        if (node.name === name)
+            exact.push(node);
+        if (node.userData.name === name)
+            authored.push(node);
+    });
+    const matches = exact.length > 0 ? exact : authored;
+    const matchedBy = exact.length > 0 ? "runtime" : "authored";
+    if (matches.length === 1)
+        return { node: matches[0], matchedBy };
+    if (matches.length > 1)
+        return {
+            node: undefined,
+            diagnostic: { code: "ambiguous-node", message: `bone/slot "${name}" matches ${matches.length} ${matchedBy} names on this rig. Choose a unique runtime node name or repair duplicate imported names; no node was selected.` },
+        };
+    return {
+        node: undefined,
+        diagnostic: { code: "missing-node", message: `bone/slot "${name}" was not found by runtime or original imported name on this rig. Check the model's node names and configure a supported slot.` },
+    };
+}

package/dist/render/spriteRender.d.ts

@@ -0,0 +1,4 @@
+import type * as THREE from "three";
+import type { SpriteAtlas } from "@jgengine/core/assets/spriteAtlas";
+/** Update atlas UVs without invalidating the shared image upload. @internal */
+export declare function syncSpriteFrame(texture: THREE.Texture, frame: SpriteAtlas["frames"][string], size: readonly [number, number]): void;

package/dist/render/spriteRender.js

@@ -0,0 +1,5 @@
+/** Update atlas UVs without invalidating the shared image upload. @internal */
+export function syncSpriteFrame(texture, frame, size) {
+    texture.repeat.set(frame.w / size[0], frame.h / size[1]);
+    texture.offset.set(frame.x / size[0], 1 - (frame.y + frame.h) / size[1]);
+}

package/dist/render/staticShapeInstances.d.ts

@@ -0,0 +1,34 @@
+import * as THREE from "three";
+import type { ModelShadowMode } from "./modelRender.js";
+import { type AuthoredSurfaceConfig, type SurfaceShape } from "./authoredSurfaceMaterial.js";
+/** One editor-derived static primitive. A box spans one unit; a cylinder has unit radius and height before scale. */
+export interface StaticShapeInstance {
+    shape: SurfaceShape;
+    position: readonly [number, number, number];
+    rotation?: readonly [number, number, number];
+    scale: readonly [number, number, number];
+    surface: AuthoredSurfaceConfig;
+    shadows?: ModelShadowMode;
+    /** Cylinder tessellation; default 16. */
+    radialSegments?: number;
+}
+/** A compatible static draw group. @internal */
+export interface StaticShapeBatch {
+    key: string;
+    shape: SurfaceShape;
+    radialSegments: number;
+    surface: AuthoredSurfaceConfig;
+    shadows: ModelShadowMode;
+    instances: readonly StaticShapeInstance[];
+}
+/** Plan compatible material/shape/shadow groups without changing authored transforms. @internal */
+export declare function groupStaticShapeInstances(instances: readonly StaticShapeInstance[]): StaticShapeBatch[];
+/** Upload static transforms and refresh conservative aggregate bounds after a prop change. @internal */
+export declare function writeStaticShapeInstances(mesh: THREE.InstancedMesh, instances: readonly StaticShapeInstance[]): void;
+/**
+ * Batch editor-derived boxes/cylinders by shape, PBR metadata and shadows. Uploads and bounds run only when instances change; map loading stays isolated per draw group.
+ * @capability static-shape-instances render authored primitive transforms as static material-compatible instance batches
+ */
+export declare function StaticShapeInstances({ instances }: {
+    instances: readonly StaticShapeInstance[];
+}): import("react").JSX.Element;

package/dist/render/staticShapeInstances.js

@@ -0,0 +1,78 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Suspense, useLayoutEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { AuthoredSurfaceMaterial, authoredSurfaceKey } from "./authoredSurfaceMaterial.js";
+import { ModelFallbackBoundary } from "./SceneModels.js";
+import { useDisposable } from "./useDisposable.js";
+/** Plan compatible material/shape/shadow groups without changing authored transforms. @internal */
+export function groupStaticShapeInstances(instances) {
+    const groups = new Map();
+    for (const instance of instances) {
+        if (![...instance.position, ...instance.scale, ...(instance.rotation ?? [])].every(Number.isFinite) || instance.scale.some(value => value <= 0))
+            throw new Error("Static shape transforms must be finite with positive scale");
+        if ([instance.surface.displacementScale, instance.surface.displacementBias].some(value => value !== undefined && !Number.isFinite(value)))
+            throw new Error("Static shape displacement must be finite");
+        const radialSegments = instance.shape === "cylinder" ? instance.radialSegments ?? 16 : 0;
+        if (instance.shape === "cylinder" && (!Number.isInteger(radialSegments) || radialSegments < 3))
+            throw new Error("Cylinder radialSegments must be an integer >= 3");
+        const shadows = instance.shadows ?? "both";
+        const key = JSON.stringify([instance.shape, radialSegments, shadows, authoredSurfaceKey(instance.surface)]);
+        let group = groups.get(key);
+        if (group === undefined) {
+            group = { key, shape: instance.shape, radialSegments, surface: instance.surface, shadows, instances: [] };
+            groups.set(key, group);
+        }
+        group.instances.push(instance);
+    }
+    return [...groups.values()];
+}
+/** Upload static transforms and refresh conservative aggregate bounds after a prop change. @internal */
+export function writeStaticShapeInstances(mesh, instances) {
+    const transform = new THREE.Object3D();
+    instances.forEach((instance, index) => {
+        transform.position.set(...instance.position);
+        transform.rotation.set(...(instance.rotation ?? [0, 0, 0]));
+        transform.scale.set(...instance.scale);
+        transform.updateMatrix();
+        mesh.setMatrixAt(index, transform.matrix);
+    });
+    mesh.count = instances.length;
+    if (mesh.geometry.boundingBox === null)
+        mesh.geometry.computeBoundingBox();
+    const heightSurface = instances[0]?.surface;
+    const displacedBounds = mesh.geometry.boundingBox.clone();
+    if (heightSurface?.maps?.height !== undefined) {
+        const bias = heightSurface.displacementBias ?? 0;
+        const scale = heightSurface.displacementScale ?? 1;
+        const displacement = Math.max(Math.abs(bias), Math.abs(bias + scale));
+        displacedBounds.expandByScalar(displacement + Number.EPSILON * Math.max(1, displacement) * 8);
+    }
+    mesh.instanceMatrix.needsUpdate = true;
+    mesh.boundingBox = new THREE.Box3();
+    const matrix = new THREE.Matrix4(), bounds = new THREE.Box3();
+    for (let index = 0; index < instances.length; index++) {
+        mesh.getMatrixAt(index, matrix);
+        mesh.boundingBox.union(bounds.copy(displacedBounds).applyMatrix4(matrix));
+    }
+    mesh.boundingSphere = mesh.boundingBox.getBoundingSphere(new THREE.Sphere());
+    // Three scales spheres by the longest matrix column. sqrt(3) also encloses affine parent shear.
+    mesh.boundingSphere.radius *= Math.sqrt(3);
+}
+function ShapeBatch({ batch }) {
+    const ref = useRef(null);
+    const geometry = useDisposable(() => batch.shape === "box" ? new THREE.BoxGeometry(1, 1, 1) : new THREE.CylinderGeometry(1, 1, 1, batch.radialSegments), [batch.shape, batch.radialSegments]);
+    useLayoutEffect(() => {
+        if (ref.current !== null)
+            writeStaticShapeInstances(ref.current, batch.instances);
+    }, [batch.instances]);
+    const fallback = _jsx(AuthoredSurfaceMaterial, { surface: { ...batch.surface, maps: undefined }, shape: batch.shape });
+    return _jsx("instancedMesh", { ref: ref, args: [geometry, undefined, batch.instances.length], castShadow: batch.shadows === "both" || batch.shadows === "cast", receiveShadow: batch.shadows === "both" || batch.shadows === "receive", children: _jsx(ModelFallbackBoundary, { fallback: fallback, url: Object.values(batch.surface.maps ?? {}).join(","), seam: "object", children: _jsx(Suspense, { fallback: fallback, children: _jsx(AuthoredSurfaceMaterial, { surface: batch.surface, shape: batch.shape }) }) }) });
+}
+/**
+ * Batch editor-derived boxes/cylinders by shape, PBR metadata and shadows. Uploads and bounds run only when instances change; map loading stays isolated per draw group.
+ * @capability static-shape-instances render authored primitive transforms as static material-compatible instance batches
+ */
+export function StaticShapeInstances({ instances }) {
+    const batches = useMemo(() => groupStaticShapeInstances(instances), [instances]);
+    return _jsx(_Fragment, { children: batches.map(batch => _jsx(ShapeBatch, { batch: batch }, batch.key)) });
+}

package/dist/render/useFootIk.js

@@ -1,8 +1,9 @@
 import { useFrame, useThree } from "@react-three/fiber";
-import { useMemo, useRef } from "react";
+import { useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { inferLegChains, placeFeet } from "@jgengine/core/anim/footPlacement";
 import { lookAt, solveTwoBone } from "@jgengine/core/anim/ikSolver";
+import { resolveRigNode } from "./rigNode.js";
 const DEFAULT_MAX_ADJUST = 0.4;
 const UP = new THREE.Vector3(0, 1, 0);
 const scratch = {
@@ -45,12 +46,45 @@ function restAnkleRatio(scene, leg) {
     });
     return ratio;
 }
+function isAncestor(ancestor, child) {
+    for (let parent = child.parent; parent !== null; parent = parent.parent) {
+        if (parent === ancestor)
+            return true;
+    }
+    return false;
+}
 /**
  * Resolves foot-IK bones on a loaded rig: explicit chains, or legs found by bone name for `"auto"`
  * and configs without `feet`. Returns `null` when no leg resolves.
  */
 export function resolveFootIkRig(scene, config) {
     const options = config === "auto" ? {} : config;
+    const named = new Map();
+    scene.traverse((object) => {
+        if (object.name.length === 0)
+            return;
+        const matches = named.get(object.name);
+        if (matches === undefined)
+            named.set(object.name, [object]);
+        else
+            matches.push(object);
+    });
+    const available = [...named.keys()].filter((name) => named.get(name).some((object) => object.isBone === true)).slice(0, 12).join(", ");
+    const warn = (message) => console.warn(`[jgengine foot IK] ${message}${available.length > 0 ? ` Available bones include: ${available}.` : ""}`);
+    const resolve = (name, role) => {
+        const matches = named.get(name);
+        if (matches?.length === 1)
+            return matches[0];
+        if (matches === undefined) {
+            const imported = resolveRigNode(scene, name);
+            if (imported.node !== undefined)
+                return imported.node;
+            warn(`${role} "${name}" ${imported.diagnostic.code === "ambiguous-node" ? "matches multiple original imported names; use a unique runtime name or repair duplicate imported names" : "was not found by runtime or original imported name; check the loaded rig names"}.`);
+            return null;
+        }
+        warn(`${role} "${name}" matches multiple objects; use a unique rig name.`);
+        return null;
+    };
     let chains = options.feet;
     if (chains === undefined) {
         const bones = [];
@@ -59,20 +93,37 @@ export function resolveFootIkRig(scene, config) {
                 bones.push({ name: object.name, parent: object.parent?.isBone === true ? object.parent.name : null });
         });
         chains = inferLegChains(bones);
+        if (chains.length === 0 && options.lookAt === undefined)
+            warn("No thigh → shin → foot chain was recognized. Configure feet with the rig's bone names, or disable IK for this model.");
     }
     const legs = [];
+    const used = new Set();
     for (const chain of chains) {
-        const root = scene.getObjectByName(chain.root);
-        const mid = scene.getObjectByName(chain.mid);
-        const tip = scene.getObjectByName(chain.tip);
-        if (root === undefined || mid === undefined || tip === undefined)
+        const root = resolve(chain.root, "Foot-chain root");
+        const mid = resolve(chain.mid, "Foot-chain middle");
+        const tip = resolve(chain.tip, "Foot-chain tip");
+        if (root === null || mid === null || tip === null)
+            continue;
+        if (!isAncestor(root, mid) || !isAncestor(mid, tip)) {
+            warn(`Skipped chain "${chain.root}" → "${chain.mid}" → "${chain.tip}": each joint must descend from the previous joint.`);
             continue;
+        }
+        if ([root, mid, tip].some((bone) => used.has(bone))) {
+            warn(`Skipped chain "${chain.root}" → "${chain.mid}" → "${chain.tip}": a joint is already corrected by another foot chain.`);
+            continue;
+        }
+        for (const bone of [root, mid, tip])
+            used.add(bone);
         legs.push({ root, mid, tip, ankleRatio: restAnkleRatio(scene, { root, mid, tip }) });
     }
-    const head = options.lookAt === undefined ? null : (scene.getObjectByName(options.lookAt.bone) ?? null);
+    const head = options.lookAt === undefined ? null : resolve(options.lookAt.bone, "Look-at bone");
     if (legs.length === 0 && head === null)
         return null;
-    const found = options.pelvis !== undefined ? (scene.getObjectByName(options.pelvis) ?? null) : (legs[0]?.root.parent ?? null);
+    let found = options.pelvis !== undefined ? resolve(options.pelvis, "Pelvis") : (legs[0]?.root.parent ?? null);
+    if (options.pelvis === undefined) {
+        while (found !== null && !legs.every((leg) => isAncestor(found, leg.root)))
+            found = found.parent;
+    }
     const pelvis = found === scene ? null : found;
     const bones = new Set(legs.flatMap((leg) => [leg.root, leg.mid, leg.tip]));
     if (pelvis !== null)
@@ -113,6 +164,14 @@ function legLength(leg) {
     leg.tip.getWorldPosition(scratch.tip);
     return scratch.root.distanceTo(scratch.mid) + scratch.mid.distanceTo(scratch.tip);
 }
+function restoreFootIkPose(rig) {
+    for (const record of rig.poses) {
+        if (record.bone.quaternion.equals(record.written.q))
+            record.bone.quaternion.copy(record.animated.q);
+        if (record.bone.position.equals(record.written.p))
+            record.bone.position.copy(record.animated.p);
+    }
+}
 /**
  * Applies one frame of foot IK after the animation mixer: probes the ground under each foot,
  * resolves targets with `placeFeet`, lowers the pelvis, solves each leg with `solveTwoBone` bending
@@ -120,11 +179,8 @@ function legLength(leg) {
  * grounded; `state` carries the faded weight between frames. Exported for tests and custom hosts.
  */
 export function applyFootIk(rig, originY, probe, state, delta, cameraTarget) {
+    restoreFootIkPose(rig);
     for (const record of rig.poses) {
-        if (record.bone.quaternion.equals(record.written.q))
-            record.bone.quaternion.copy(record.animated.q);
-        if (record.bone.position.equals(record.written.p))
-            record.bone.position.copy(record.animated.p);
         record.animated.q.copy(record.bone.quaternion);
         record.animated.p.copy(record.bone.position);
     }
@@ -200,6 +256,15 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
     const camera = useThree((three) => three.camera);
     const rig = useMemo(() => (config === undefined ? null : resolveFootIkRig(scene, config)), [scene, config]);
     const state = useRef({ weight: 0, pelvis: 0 });
+    useLayoutEffect(() => {
+        state.current = { weight: 0, pelvis: 0 };
+        return () => {
+            if (rig !== null) {
+                restoreFootIkPose(rig);
+                scene.updateMatrixWorld(true);
+            }
+        };
+    }, [rig, scene]);
     useFrame((_three, delta) => {
         if (rig === null || ctx === null || instanceId === undefined)
             return;

package/dist/render/useModelAnimation.d.ts

@@ -1,6 +1,26 @@
 import * as THREE from "three";
 import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
-import { type AnimClipOutput, type AnimGraph } from "@jgengine/core/anim/animGraph";
+import { type AnimClipOutput, type AnimGraph, type AnimParamValue } from "@jgengine/core/anim/animGraph";
+import type { GameContext } from "@jgengine/core/runtime/gameContextTypes";
+/** A repairable mismatch between a model animation config and its imported rig. */
+export interface ModelAnimationDiagnostic {
+    code: "missing-clip" | "missing-root-track" | "empty-layer-mask" | "incomplete-locomotion" | "missing-auto-idle";
+    message: string;
+}
+/**
+ * Checks clip mappings, masked layers and root-motion assumptions without starting a mixer.
+ *
+ * @capability model-animation-diagnostics inspect imported clip mappings, layer masks and root-track compatibility
+ */
+export declare function diagnoseModelAnimation(scene: THREE.Object3D, animation: ModelAnimationConfig, clips: readonly THREE.AnimationClip[]): readonly ModelAnimationDiagnostic[];
+/**
+ * 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 declare function readModelAnimationParams(ctx: GameContext, instanceId: string, speed: number, out: Record<string, AnimParamValue>): Record<string, AnimParamValue>;
 /**
  * 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
@@ -13,9 +33,13 @@ export interface GraphPose {
     /** Clip durations read from the rig, the `clips` argument `runtime.advance` expects. */
     durations: Readonly<Record<string, {
         duration: number;
+        rootTrack?: {
+            times: Float32Array;
+            values: Float32Array;
+        };
     }>>;
     /** Poses the rig with one advance's clip weights and times. */
-    apply(clips: readonly AnimClipOutput[]): void;
+    apply(clips: readonly AnimClipOutput[], rootMotion?: boolean): void;
     dispose(): void;
 }
 /**
@@ -32,5 +56,7 @@ export declare function createGraphPose(scene: THREE.Object3D, graph: AnimGraph,
  * `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 declare function useModelAnimation(scene: THREE.Object3D, clips: THREE.AnimationClip[], animationInput: ModelAnimationConfig | "auto" | "none" | undefined, instanceId?: string): void;