@jgengine/shell 0.11.0 → 0.13.0

package/dist/gameKit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The happy-path game kit — one import surface covering a whole simple game: authoring
+ * (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
+ * (`defineSystem`), the authored-scene document helpers, HUD primitives, and deterministic
+ * randomness. Start here; reach for deep package paths only when a game outgrows the kit.
+ *
+ * @capability game-kit one-stop happy-path import surface for authoring, mounting, state, systems, authored scenes, and HUD
+ */
+export { defineGame, type GameConfig } from "./defineGame.js";
+export { GameHost, type GameHostProps, type EditorSummonModule } from "./GameHost.js";
+export type { PlayableGame } from "./registry.js";
+export { defineStore, type StoreHandle } from "@jgengine/core/store/defineStore";
+export { defineKeyedStore } from "@jgengine/core/store/defineKeyedStore";
+export { defineSystem, type SystemDefinition } from "@jgengine/core/game/defineSystem";
+export type { GameContext } from "@jgengine/core/runtime/gameContext";
+export type { GameLoop } from "@jgengine/core/game/defineGame";
+export { normalizeEditorLayers } from "@jgengine/core/editor/document";
+export type { EditorDocument, EditorCatalogDefinition } from "@jgengine/core/editor/types";
+export { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn";
+export { collectAuthoredTriggers } from "@jgengine/core/scene/authoredTriggers";
+export { environmentContentFromDocument } from "@jgengine/core/editor/environment";
+export { environment } from "@jgengine/core/world/features";
+export type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+export { HudCanvas, HudPanel, useHudLayout } from "@jgengine/react/hudLayout";
+export { StatBar, Hotbar, Clock, Coins } from "@jgengine/react/hud";
+export { seededRng } from "@jgengine/core/random/rng";
+export { offline } from "@jgengine/core/runtime/adapter";

package/dist/gameKit.js

@@ -0,0 +1,29 @@
+/**
+ * The happy-path game kit — one import surface covering a whole simple game: authoring
+ * (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
+ * (`defineSystem`), the authored-scene document helpers, HUD primitives, and deterministic
+ * randomness. Start here; reach for deep package paths only when a game outgrows the kit.
+ *
+ * @capability game-kit one-stop happy-path import surface for authoring, mounting, state, systems, authored scenes, and HUD
+ */
+// Authoring + mounting — the one public path from config to a running game.
+export { defineGame } from "./defineGame.js";
+export { GameHost } from "./GameHost.js";
+// Serializable state + composable behavior.
+export { defineStore } from "@jgengine/core/store/defineStore";
+export { defineKeyedStore } from "@jgengine/core/store/defineKeyedStore";
+export { defineSystem } from "@jgengine/core/game/defineSystem";
+// Authored scene document — normalize `editor.scene.json`, read spawns and trigger volumes.
+export { normalizeEditorLayers } from "@jgengine/core/editor/document";
+export { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn";
+export { collectAuthoredTriggers } from "@jgengine/core/scene/authoredTriggers";
+export { environmentContentFromDocument } from "@jgengine/core/editor/environment";
+// World + camera.
+export { environment } from "@jgengine/core/world/features";
+// HUD layout + optional building blocks — games own custom chrome (not a stock face).
+export { HudCanvas, HudPanel, useHudLayout } from "@jgengine/react/hudLayout";
+export { StatBar, Hotbar, Clock, Coins } from "@jgengine/react/hud";
+// Deterministic randomness (inject seeds; never Math.random in game logic).
+export { seededRng } from "@jgengine/core/random/rng";
+// Multiplayer story: omit `multiplayer` entirely for solo — offline is the shell default.
+export { offline } from "@jgengine/core/runtime/adapter";

package/dist/map/MapMarkerBeacons.d.ts

@@ -1,6 +1,7 @@
-import { type MarkerKindStyle, type MarkerSet } from "@jgengine/core/world/markers";
+import { type MarkerCollection, type MarkerKindStyle } from "@jgengine/core/world/markers";
 export interface MapMarkerBeaconsProps {
-    markers: MarkerSet;
+    /** Static views, an external marker source, or a native JGengine MarkerSet. */
+    markers: MarkerCollection;
     kindStyles?: Record<string, MarkerKindStyle>;
     height?: number;
 }

package/dist/postfx/PostProcessing.d.ts

@@ -1,10 +1,18 @@
 import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
  * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
+ *
+ * `quality` (the player's graphics-quality setting) gates the passes whose cost
+ * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
+ * the whole scene for depth/normals and runs a multi-sample full-screen pass,
+ * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
+ * tone mapping, and grade stay on every tier.
  */
-export declare function PostProcessing({ config }: {
+export declare function PostProcessing({ config, quality }: {
     config: PostProcessingConfig;
+    quality?: GraphicsQuality;
 }): null;

package/dist/postfx/PostProcessing.js

@@ -36,8 +36,14 @@ function syncSize(built, width, height, pixelRatio) {
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
  * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
+ *
+ * `quality` (the player's graphics-quality setting) gates the passes whose cost
+ * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
+ * the whole scene for depth/normals and runs a multi-sample full-screen pass,
+ * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
+ * tone mapping, and grade stay on every tier.
  */
-export function PostProcessing({ config }) {
+export function PostProcessing({ config, quality = "high" }) {
     const gl = useThree((s) => s.gl);
     const scene = useThree((s) => s.scene);
     const camera = useThree((s) => s.camera);
@@ -52,7 +58,8 @@ export function PostProcessing({ config }) {
         });
         const composer = new EffectComposer(gl, target);
         composer.addPass(new RenderPass(scene, camera));
-        if (config.ao !== undefined && config.ao !== false) {
+        const heavyPasses = quality === "high";
+        if (heavyPasses && config.ao !== undefined && config.ao !== false) {
             const ao = new GTAOPass(scene, camera, width, height);
             ao.blendIntensity = config.ao.blend ?? 1;
             ao.updateGtaoMaterial({
@@ -69,7 +76,7 @@ export function PostProcessing({ config }) {
             composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
         }
         let dof = null;
-        if (config.dof !== undefined && config.dof !== false) {
+        if (heavyPasses && config.dof !== undefined && config.dof !== false) {
             const d = config.dof;
             dof = new BokehPass(scene, camera, {
                 focus: d.focus ?? 18,
@@ -91,7 +98,7 @@ export function PostProcessing({ config }) {
             disposeGraph(graph);
             builtRef.current = null;
         };
-    }, [gl, scene, camera, config]);
+    }, [gl, scene, camera, config, quality]);
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;

package/dist/presentationResolve.d.ts

@@ -0,0 +1,39 @@
+import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
+import type { PresentationEffectsConfig } from "@jgengine/core/game/playableGame";
+/** Resolved world-bar / nameplate config, or `null` when the feature is off. @internal */
+export interface ResolvedWorldOverlayBars {
+    statId: string;
+    roles?: readonly CatalogEntityRole[];
+    maxDistance?: number;
+    /** Nameplates only: draw the built-in HP bar. `false` yields a name-only plate. Defaults to `true`. */
+    showHealth?: boolean;
+}
+/**
+ * Normalize `worldHealthBars` / `nameplates` (`boolean | object | undefined`) into a
+ * single resolved shape. `undefined` / `false` → `null` (off); `true` → default stat `"health"`;
+ * object → explicit fields with `statId` defaulting to `"health"`. `showHealth` is nameplate-only
+ * (ignored by `worldHealthBars`, which is itself a bar).
+ * @internal
+ */
+export declare function resolveWorldOverlayBars(config: boolean | {
+    statId?: string;
+    roles?: readonly CatalogEntityRole[];
+    maxDistance?: number;
+    showHealth?: boolean;
+} | undefined): ResolvedWorldOverlayBars | null;
+/** Resolved combat presentation channels (each boolean is whether that stack piece mounts). @internal */
+export interface ResolvedPresentationEffects {
+    telegraphs: boolean;
+    vfx: boolean;
+    floatText: boolean;
+    tracers: boolean;
+    shake: boolean;
+}
+/**
+ * Resolve `presentationEffects` for the 3D shell.
+ * - `undefined` / `true` → all channels on (historical default).
+ * - `false` → none.
+ * - object → per-channel; missing keys default to on so games can disable one channel.
+ * @internal
+ */
+export declare function resolvePresentationEffects(config: boolean | PresentationEffectsConfig | undefined): ResolvedPresentationEffects;

package/dist/presentationResolve.js

@@ -0,0 +1,53 @@
+/**
+ * Normalize `worldHealthBars` / `nameplates` (`boolean | object | undefined`) into a
+ * single resolved shape. `undefined` / `false` → `null` (off); `true` → default stat `"health"`;
+ * object → explicit fields with `statId` defaulting to `"health"`. `showHealth` is nameplate-only
+ * (ignored by `worldHealthBars`, which is itself a bar).
+ * @internal
+ */
+export function resolveWorldOverlayBars(config) {
+    if (config === undefined || config === false)
+        return null;
+    if (config === true)
+        return { statId: "health" };
+    return {
+        statId: config.statId ?? "health",
+        ...(config.roles === undefined ? {} : { roles: config.roles }),
+        ...(config.maxDistance === undefined ? {} : { maxDistance: config.maxDistance }),
+        ...(config.showHealth === undefined ? {} : { showHealth: config.showHealth }),
+    };
+}
+const ALL_ON = {
+    telegraphs: true,
+    vfx: true,
+    floatText: true,
+    tracers: true,
+    shake: true,
+};
+const ALL_OFF = {
+    telegraphs: false,
+    vfx: false,
+    floatText: false,
+    tracers: false,
+    shake: false,
+};
+/**
+ * Resolve `presentationEffects` for the 3D shell.
+ * - `undefined` / `true` → all channels on (historical default).
+ * - `false` → none.
+ * - object → per-channel; missing keys default to on so games can disable one channel.
+ * @internal
+ */
+export function resolvePresentationEffects(config) {
+    if (config === false)
+        return ALL_OFF;
+    if (config === undefined || config === true)
+        return ALL_ON;
+    return {
+        telegraphs: config.telegraphs !== false,
+        vfx: config.vfx !== false,
+        floatText: config.floatText !== false,
+        tracers: config.tracers !== false,
+        shake: config.shake !== false,
+    };
+}

package/dist/registry.d.ts

@@ -5,6 +5,7 @@ import type { SceneObject } from "@jgengine/core/scene/objectStore";
 import type { ViewmodelProps } from "./camera/GameFirstPersonCamera.js";
 export type RenderEntity = (entity: SceneEntity) => ReactNode;
 export type RenderObject = (object: SceneObject) => ReactNode;
+/** The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle. */
 export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps>>;
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;
 export declare function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined;

package/dist/render/PartMotion.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import type { ModelConfig, ModelPart } from "@jgengine/core/game/playableGame";
+/**
+ * Procedural motion rig for a rig-less part-composed character (`ModelPart.role` — see
+ * `@jgengine/core/game/partAnimation`). Wraps the whole composition in a root group that bobs,
+ * breathes, flinches on `combat.hitReaction`, and topples on `entity.died`, while each
+ * role-tagged part swings around its authored transform — legs/arms counter-phase from the
+ * entity's live movement speed, head counter-sway, tail wag, wing flap. Untagged parts render
+ * as static kit pieces. Children are the base model content (primitive, attachments).
+ */
+export declare function PartMotionRig({ parts, model, instanceId, renderPart, children, }: {
+    parts: readonly ModelPart[];
+    model: ModelConfig;
+    instanceId?: string;
+    /** Renders one part's model content (the shell passes its part renderer to avoid an import cycle). */
+    renderPart: (part: ModelPart, index: number) => ReactNode;
+    children: ReactNode;
+}): ReactNode;

package/dist/render/PartMotion.js

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

package/dist/render/SceneModels.d.ts

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

package/dist/render/SceneModels.js

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

package/dist/render/assetBase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolves a root-absolute asset URL (`/models/…`, `/materials/…`) against the
+ * installed app base. Relative, protocol-relative, absolute-scheme (`https:`,
+ * `blob:`, `data:`), and already-based URLs pass through unchanged. Installed
+ * as the URL modifier on THREE loading managers so every model and texture
+ * load resolves correctly wherever the app is mounted.
+ */
+export declare function resolveAssetBaseUrl(url: string): string;
+/**
+ * Installs the app base URL (pass `import.meta.env.BASE_URL`) so root-absolute
+ * asset paths load from under it. Call once at app startup, before any game
+ * loads. Bases that are not root-absolute (`/`, `./`) reset to the pass-through
+ * default. Also registers {@link resolveAssetBaseUrl} on
+ * `THREE.DefaultLoadingManager`, covering `TextureLoader`, drei's `useTexture`
+ * / `useGLTF`, and every other loader on the default manager.
+ */
+export declare function installAssetBase(base: string): void;