@jgengine/shell 0.18.1 → 0.21.0

package/dist/render/resolveModel.js

@@ -1,3 +1,4 @@
+import { warnOnce } from "@jgengine/core/devtools/warnOnce";
 /**
  * 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
@@ -7,6 +8,7 @@
 function catalogModelConfig(ref) {
     return {
         url: ref.url,
+        ...(ref.anchor === undefined ? {} : { anchor: ref.anchor }),
         ...(ref.dims === undefined ? {} : { dims: ref.dims }),
         ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
         animation: "auto",
@@ -39,6 +41,18 @@ export function tryResolveCatalogModel(id, assets) {
         return undefined;
     return catalogModelConfig(ref);
 }
+/** Resolve a live object's catalog and animation, retaining unchanged base model identities. @internal */
+export function resolveObjectModel(object, models, assets, cache) {
+    const input = models?.[object.catalogId];
+    const ref = assets.resolve(typeof input === "string" ? input : object.catalogId);
+    const cached = cache.get(object.catalogId);
+    const resolved = cached !== undefined && cached.input === input && cached.ref === ref ? cached.model :
+        resolveModel(input, assets, { seam: "objectModels", key: object.catalogId }) ?? tryResolveCatalogModel(object.catalogId, assets);
+    if (cached === undefined || cached.model !== resolved || cached.input !== input || cached.ref !== ref) {
+        cache.set(object.catalogId, { input, ref, model: resolved });
+    }
+    return resolved !== undefined && object.animation !== undefined ? { ...resolved, animation: object.animation } : resolved;
+}
 /**
  * Resolve an entity model plus bone-attachment / kit-of-parts models through the catalog
  * so mounts receive fully-resolved `ModelConfig`s.
@@ -74,6 +88,9 @@ export function resolveEntityModel(value, assets, key) {
  * @internal
  */
 export function pickModel(assets, pick) {
+    if (pick.fallbackModel !== undefined && !assets.has(pick.fallbackModel)) {
+        warnOnce(`pickModel:fallback:${pick.fallbackModel}`, `[jgengine] fallbackModel "${pick.fallbackModel}" is not in the asset catalog, so it can never stand in for "${pick.model ?? "(none)"}" — fix the id or declare its pack in the catalog sources.`);
+    }
     for (const id of [pick.model, pick.fallbackModel]) {
         if (id === undefined)
             continue;
@@ -110,17 +127,21 @@ function softModelLookup(map, assets) {
  * The `createGameContext` `models` lookup derived from a playable's render maps: what each entity kind /
  * object catalog id actually renders as, so colliders auto-fit the rendered mesh. Soft-resolves string
  * ids (a missing catalog id keeps the default collider instead of throwing — the render path already
- * reports it), passes inline configs through. `undefined` when the playable maps no models at all.
+ * reports it), passes inline configs through. Unmapped objects resolve their own catalog id,
+ * matching WorldScene; `undefined` when both the catalog and model maps are empty.
  * @internal
  */
 export function contextModels(playable) {
     const entity = softModelLookup(playable.entityModels, playable.game.assets);
-    const object = softModelLookup(playable.objectModels, playable.game.assets);
-    if (entity === undefined && object === undefined)
+    const explicitObject = softModelLookup(playable.objectModels, playable.game.assets);
+    if (entity === undefined && explicitObject === undefined && playable.game.assets.ids().length === 0)
         return undefined;
+    const object = (key) => playable.objectModels?.[key] === undefined
+        ? tryResolveCatalogModel(key, playable.game.assets)
+        : explicitObject?.(key);
     return {
         ...(entity === undefined ? {} : { entity }),
-        ...(object === undefined ? {} : { object }),
+        object,
     };
 }
 /**

package/dist/render/rigNode.d.ts

@@ -0,0 +1,26 @@
+import type { Object3D } from "three";
+/** A missing or nonunique node reference that a rig author can repair. */
+export interface RigNodeDiagnostic {
+    code: "missing-node" | "ambiguous-node";
+    message: string;
+}
+/** A node on this model instance, or a diagnostic instead of an arbitrary attachment target. */
+export type RigNodeResolution = {
+    node: Object3D;
+    matchedBy: "runtime" | "authored";
+    diagnostic?: undefined;
+} | {
+    node: undefined;
+    matchedBy?: undefined;
+    diagnostic: RigNodeDiagnostic;
+};
+/**
+ * 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 declare function resolveRigNode(rig: Object3D, name: string): RigNodeResolution;

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.d.ts

@@ -1,9 +1,58 @@
 import * as THREE from "three";
 import type { GameContext } from "@jgengine/core/runtime/gameContextTypes";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { SceneRaycastHit, SceneRaycastInput } from "@jgengine/core/scene/sceneRaycast";
 type FootIkConfig = NonNullable<ModelConfig["ik"]>;
-/** Applies one frame of foot IK to a loaded rig. Exported for renderer tests and custom model hosts. */
-export declare function applyFootIk(scene: THREE.Object3D, config: FootIkConfig, raycast: GameContext["scene"]["raycast"], weight: number, cameraTarget?: readonly [number, number, number]): boolean;
-/** Runs foot IK after the model animation mixer, fading the correction out while the entity is airborne. */
-export declare function useFootIk(scene: THREE.Object3D, config: FootIkConfig | undefined, ctx: GameContext | null, instanceId?: string): void;
+type GroundProbe = (input: SceneRaycastInput) => SceneRaycastHit | null;
+interface IkLeg {
+    root: THREE.Object3D;
+    mid: THREE.Object3D;
+    tip: THREE.Object3D;
+    /** Rest-pose ankle height above the sole divided by rest leg length, so it survives any scale. */
+    ankleRatio: number;
+}
+interface PoseRecord {
+    bone: THREE.Object3D;
+    animated: {
+        q: THREE.Quaternion;
+        p: THREE.Vector3;
+    };
+    written: {
+        q: THREE.Quaternion;
+        p: THREE.Vector3;
+    };
+}
+/** Bones resolved once per loaded scene for {@link applyFootIk}. */
+export interface FootIkRig {
+    legs: IkLeg[];
+    pelvis: THREE.Object3D | null;
+    head: THREE.Object3D | null;
+    maxAdjust: number;
+    alignToGround: number;
+    /** Pose before and after last frame's correction, so a bone no clip animates never accumulates it. */
+    poses: PoseRecord[];
+}
+/** Per-model state carried between frames: the faded weight and the smoothed pelvis drop. */
+export interface FootIkState {
+    weight: number;
+    pelvis: number;
+}
+/**
+ * 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 declare function resolveFootIkRig(scene: THREE.Object3D, config: FootIkConfig): FootIkRig | null;
+/**
+ * Applies one frame of foot IK after the animation mixer: probes the ground under each foot,
+ * resolves targets with `placeFeet`, lowers the pelvis, solves each leg with `solveTwoBone` bending
+ * toward the animated knee, and tilts planted feet to the ground. Returns whether the feet are
+ * grounded; `state` carries the faded weight between frames. Exported for tests and custom hosts.
+ */
+export declare function applyFootIk(rig: FootIkRig, originY: number, probe: GroundProbe, state: FootIkState, delta: number, cameraTarget?: readonly [number, number, number]): boolean;
+/**
+ * Runs foot IK after the model's animation mixer for `ModelConfig.ik`. Ground probes hit terrain and
+ * blocking physical objects, never the model's own entity. `groundOffset` is the model-space height
+ * its soles rest on (`ModelConfig.y`).
+ */
+export declare function useFootIk(scene: THREE.Object3D, config: FootIkConfig | undefined, ctx: GameContext | null, instanceId?: string, groundOffset?: number): void;
 export {};