@jgengine/shell 0.12.0 → 0.14.0

package/dist/environment/RoadJunctions.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { BufferAttribute, BufferGeometry, DoubleSide } from "three";
+import { buildJunctionPatch, buildRoadRibbon } from "@jgengine/core/world/roads";
+import { junctionMarkings } from "@jgengine/core/world/streets";
+function toGeometry(positions, indices) {
+    if (positions.length === 0)
+        return null;
+    const geometry = new BufferGeometry();
+    geometry.setAttribute("position", new BufferAttribute(positions, 3));
+    geometry.setIndex(new BufferAttribute(indices, 1));
+    geometry.computeVertexNormals();
+    return geometry;
+}
+/** Merge many thin marking ribbons (stop lines + crosswalk bars) into one buffer geometry. */
+function mergedBars(bars, width, field, elevation) {
+    const ribbons = bars.map((bar) => buildRoadRibbon(bar, width, (x, z) => field.sampleHeight(x, z), { elevation }));
+    const vertexCount = ribbons.reduce((sum, r) => sum + r.positions.length, 0);
+    const indexCount = ribbons.reduce((sum, r) => sum + r.indices.length, 0);
+    if (vertexCount === 0)
+        return null;
+    const positions = new Float32Array(vertexCount);
+    const indices = new Uint32Array(indexCount);
+    let vertexOffset = 0;
+    let indexOffset = 0;
+    for (const ribbon of ribbons) {
+        positions.set(ribbon.positions, vertexOffset);
+        const base = vertexOffset / 3;
+        for (let i = 0; i < ribbon.indices.length; i += 1)
+            indices[indexOffset + i] = ribbon.indices[i] + base;
+        vertexOffset += ribbon.positions.length;
+        indexOffset += ribbon.indices.length;
+    }
+    return toGeometry(positions, indices);
+}
+/**
+ * Renders welded road intersections: one asphalt disc patch per junction (covering the crossing
+ * ribbons so they read as one intersection instead of stacking/z-fighting), plus white stop lines
+ * and crosswalk bars at each approach. Fed the junctions the scene already computed from its roads.
+ * @internal
+ */
+export function RoadJunctions({ junctions, field, }) {
+    const patches = useMemo(() => junctions
+        .map((junction) => {
+        const patch = buildJunctionPatch(junction.center, junction.radius, (x, z) => field.sampleHeight(x, z), { elevation: junction.elevation + 0.02 });
+        return { color: junction.color, geometry: toGeometry(patch.positions, patch.indices) };
+    })
+        .filter((entry) => entry.geometry !== null), [junctions, field]);
+    const markings = useMemo(() => {
+        const stopBars = [];
+        const crossBars = [];
+        let elevation = 0;
+        for (const junction of junctions) {
+            elevation = Math.max(elevation, junction.elevation);
+            const marks = junctionMarkings(junction);
+            for (const bar of marks.stopLines)
+                stopBars.push(bar);
+            for (const bar of marks.crosswalkBars)
+                crossBars.push(bar);
+        }
+        return {
+            stops: mergedBars(stopBars, 0.5, field, elevation + 0.05),
+            crosswalks: mergedBars(crossBars, 0.55, field, elevation + 0.05),
+        };
+    }, [junctions, field]);
+    if (patches.length === 0)
+        return null;
+    return (_jsxs("group", { children: [patches.map((patch, index) => (_jsx("mesh", { geometry: patch.geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: patch.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }, `junction-${index}`))), markings.stops !== null ? (_jsx("mesh", { geometry: markings.stops, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide }) })) : null, markings.crosswalks !== null ? (_jsx("mesh", { geometry: markings.crosswalks, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide }) })) : null] }));
+}

package/dist/environment/RoadRibbons.d.ts

@@ -1,7 +1,13 @@
 import type { RoadEnvironmentDescriptor } from "@jgengine/core/world/features";
+import { type DashExclusion } from "@jgengine/core/world/roads";
 import type { TerrainField } from "@jgengine/core/world/terrain";
-/** Renders one `road()` descriptor: an asphalt ribbon plus optional dashed centerline, draped on the terrain. */
-export declare function RoadRibbons({ road, field }: {
+/**
+ * Renders one `road()` descriptor: an asphalt ribbon, a curb/edge strip along each border, plus an
+ * optional dashed centerline (draped on the terrain, and interrupted through any `exclusions`
+ * — the welded junction patches — so the center line does not paint across intersections).
+ */
+export declare function RoadRibbons({ road, field, exclusions, }: {
     road: RoadEnvironmentDescriptor;
     field: TerrainField;
+    exclusions?: readonly DashExclusion[];
 }): import("react").JSX.Element | null;

package/dist/environment/RoadRibbons.js

@@ -1,8 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
-import { BufferAttribute, BufferGeometry, DoubleSide } from "three";
+import { BufferAttribute, BufferGeometry, Color, DoubleSide } from "three";
 import { buildRoadRibbon, dashSegments } from "@jgengine/core/world/roads";
-import { offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+import { curbPaths, offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+/** Darken an asphalt color toward black for a curb/edge strip (deterministic, no alloc churn). */
+function darken(hex, amount) {
+    const c = new Color(hex);
+    c.multiplyScalar(1 - amount);
+    return `#${c.getHexString()}`;
+}
 function toGeometry(positions, indices) {
     if (positions.length === 0)
         return null;
@@ -16,9 +22,9 @@ function ribbonGeometry(path, width, field, elevation) {
     const ribbon = buildRoadRibbon(path, width, (x, z) => field.sampleHeight(x, z), { elevation });
     return toGeometry(ribbon.positions, ribbon.indices);
 }
-function mergedDashGeometry(road, field) {
+function mergedDashGeometry(road, field, exclusions) {
     const width = Math.max(0.25, road.width * 0.035);
-    const ribbons = dashSegments(road.path, 3.2, 4).map((dash) => buildRoadRibbon(dash, width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + 0.04 }));
+    const ribbons = dashSegments(road.path, 3.2, 4, exclusions).map((dash) => buildRoadRibbon(dash, width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + 0.04 }));
     const vertexCount = ribbons.reduce((sum, r) => sum + r.positions.length, 0);
     const indexCount = ribbons.reduce((sum, r) => sum + r.indices.length, 0);
     if (vertexCount === 0)
@@ -38,10 +44,22 @@ function mergedDashGeometry(road, field) {
     }
     return toGeometry(positions, indices);
 }
-/** Renders one `road()` descriptor: an asphalt ribbon plus optional dashed centerline, draped on the terrain. */
-export function RoadRibbons({ road, field }) {
+/**
+ * Renders one `road()` descriptor: an asphalt ribbon, a curb/edge strip along each border, plus an
+ * optional dashed centerline (draped on the terrain, and interrupted through any `exclusions`
+ * — the welded junction patches — so the center line does not paint across intersections).
+ */
+export function RoadRibbons({ road, field, exclusions = [], }) {
     const asphalt = useMemo(() => ribbonGeometry(road.path, road.width, field, road.elevation), [road, field]);
-    const dashes = useMemo(() => (road.markings ? mergedDashGeometry(road, field) : null), [road, field]);
+    const dashes = useMemo(() => (road.markings ? mergedDashGeometry(road, field, exclusions) : null), [road, field, exclusions]);
+    const curbColor = useMemo(() => darken(road.color, 0.45), [road.color]);
+    const curbs = useMemo(() => {
+        // A thin strip straddling each asphalt edge, lifted just above the ribbon.
+        const strip = Math.max(0.4, road.width * 0.09);
+        return curbPaths(road, strip / 2)
+            .map((path) => ribbonGeometry(path, strip, field, road.elevation + 0.02))
+            .filter((geometry) => geometry !== null);
+    }, [road, field]);
     const sidewalks = useMemo(() => {
         const width = sidewalkWidthOf(road);
         if (width <= 0)
@@ -53,5 +71,5 @@ export function RoadRibbons({ road, field }) {
     }, [road, field]);
     if (asphalt === null)
         return null;
-    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }), dashes !== null ? (_jsx("mesh", { geometry: dashes, children: _jsx("meshStandardMaterial", { color: road.markingColor, roughness: 0.8, metalness: 0, side: DoubleSide }) })) : null, sidewalks.map((geometry, index) => (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.sidewalk === false ? "#a7adb8" : road.sidewalk.color, roughness: 0.9, metalness: 0, side: DoubleSide }) }, `walk-${index}`)))] }));
+    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }), curbs.map((geometry, index) => (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: curbColor, roughness: 0.9, metalness: 0, side: DoubleSide }) }, `curb-${index}`))), dashes !== null ? (_jsx("mesh", { geometry: dashes, children: _jsx("meshStandardMaterial", { color: road.markingColor, roughness: 0.8, metalness: 0, side: DoubleSide }) })) : null, sidewalks.map((geometry, index) => (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.sidewalk === false ? "#a7adb8" : road.sidewalk.color, roughness: 0.9, metalness: 0, side: DoubleSide }) }, `walk-${index}`)))] }));
 }

package/dist/postfx/PostProcessing.js

@@ -6,6 +6,31 @@ import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
 import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { createGradePass } from "./gradeShader.js";
+import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
+/**
+ * GTAO renders the scene with an `overrideMaterial` normal/depth prepass, which stamps
+ * transparent overlay quads (additive VFX sprites, telegraphs, debug gizmos) into the AO
+ * buffers as opaque squares — the AO composite then multiplies them toward black. Hide
+ * marked overlay subtrees for the whole pass: the beauty buffer it composites over was
+ * already rendered with them in.
+ */
+class OverlayAwareGTAOPass extends GTAOPass {
+    hiddenOverlays = [];
+    render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
+        hidePostfxOverlays(this.scene, this.hiddenOverlays);
+        super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
+        restorePostfxOverlays(this.hiddenOverlays);
+    }
+}
+/** DOF's depth prepass has the same `overrideMaterial` overlay-stamping problem as GTAO. */
+class OverlayAwareBokehPass extends BokehPass {
+    hiddenOverlays = [];
+    render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
+        hidePostfxOverlays(this.scene, this.hiddenOverlays);
+        super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
+        restorePostfxOverlays(this.hiddenOverlays);
+    }
+}
 const TONE_MAPPING = {
     aces: THREE.ACESFilmicToneMapping,
     agx: THREE.AgXToneMapping,
@@ -60,7 +85,7 @@ export function PostProcessing({ config, quality = "high" }) {
         composer.addPass(new RenderPass(scene, camera));
         const heavyPasses = quality === "high";
         if (heavyPasses && config.ao !== undefined && config.ao !== false) {
-            const ao = new GTAOPass(scene, camera, width, height);
+            const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
             ao.blendIntensity = config.ao.blend ?? 1;
             ao.updateGtaoMaterial({
                 radius: config.ao.radius ?? 1.8,
@@ -78,7 +103,7 @@ export function PostProcessing({ config, quality = "high" }) {
         let dof = null;
         if (heavyPasses && config.dof !== undefined && config.dof !== false) {
             const d = config.dof;
-            dof = new BokehPass(scene, camera, {
+            dof = new OverlayAwareBokehPass(scene, camera, {
                 focus: d.focus ?? 18,
                 aperture: d.aperture ?? 0.00025,
                 maxblur: d.maxBlur ?? 0.01,

package/dist/postfx/postfxOverlay.d.ts

@@ -0,0 +1,24 @@
+import type * as THREE from "three";
+/**
+ * Spread onto a group's `userData` to mark its subtree as a screen/world overlay effect —
+ * additive glows, telegraphs, tracers, debug gizmos — that post-processing scene prepasses
+ * (GTAO's normal/depth render, DOF's depth render) must skip. Those prepasses render the
+ * scene with `overrideMaterial`, which turns transparent overlay quads into opaque stamps
+ * in the AO/DOF buffers (visible as black squares over hit sparks). The shell marks its own
+ * combat VFX and collision-debug mounts; games mark custom overlay effects the same way.
+ */
+export declare const POSTFX_OVERLAY_USERDATA: {
+    readonly jgPostfxOverlay: true;
+};
+/** True when the object opted out of postfx scene prepasses via {@link POSTFX_OVERLAY_USERDATA}. */
+export declare function isPostfxOverlay(object: {
+    userData?: Record<string, unknown>;
+}): boolean;
+/**
+ * Hide every currently visible marked object under `scene`, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
+ * undo exactly that set.
+ */
+export declare function hidePostfxOverlays(scene: THREE.Object3D, out: THREE.Object3D[]): void;
+/** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
+export declare function restorePostfxOverlays(hidden: THREE.Object3D[]): void;

package/dist/postfx/postfxOverlay.js

@@ -0,0 +1,35 @@
+/**
+ * Spread onto a group's `userData` to mark its subtree as a screen/world overlay effect —
+ * additive glows, telegraphs, tracers, debug gizmos — that post-processing scene prepasses
+ * (GTAO's normal/depth render, DOF's depth render) must skip. Those prepasses render the
+ * scene with `overrideMaterial`, which turns transparent overlay quads into opaque stamps
+ * in the AO/DOF buffers (visible as black squares over hit sparks). The shell marks its own
+ * combat VFX and collision-debug mounts; games mark custom overlay effects the same way.
+ */
+export const POSTFX_OVERLAY_USERDATA = {
+    jgPostfxOverlay: true,
+};
+/** True when the object opted out of postfx scene prepasses via {@link POSTFX_OVERLAY_USERDATA}. */
+export function isPostfxOverlay(object) {
+    return object.userData?.jgPostfxOverlay === true;
+}
+/**
+ * Hide every currently visible marked object under `scene`, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
+ * undo exactly that set.
+ */
+export function hidePostfxOverlays(scene, out) {
+    out.length = 0;
+    scene.traverse((object) => {
+        if (object.visible && isPostfxOverlay(object)) {
+            object.visible = false;
+            out.push(object);
+        }
+    });
+}
+/** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
+export function restorePostfxOverlays(hidden) {
+    for (const object of hidden)
+        object.visible = true;
+    hidden.length = 0;
+}

package/dist/presentationResolve.d.ts

@@ -5,17 +5,21 @@ 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"`.
+ * 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 {

package/dist/presentationResolve.js

@@ -1,7 +1,8 @@
 /**
  * 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"`.
+ * 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) {
@@ -13,6 +14,7 @@ export function resolveWorldOverlayBars(config) {
         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 = {

package/dist/render/EntityPreview.d.ts

@@ -0,0 +1,53 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import { type StudioMood } from "../scene/StudioStage.js";
+/** Props for {@link EntityPreview}. */
+export interface EntityPreviewProps {
+    /**
+     * The rendered entity — the game's *own* `renderEntity` content (e.g. its procedural body component),
+     * which may call `useEntityRenderCues(id)` / `useGameContext()` internally to mirror the live game.
+     * Takes precedence over `model`. Omit both to render an empty lit stage.
+     */
+    children?: ReactNode;
+    /**
+     * Convenience for engine-native models: render this {@link ModelConfig} via `IsolatedEntityModel`.
+     * Pair with `instanceId` to bind it to a live entity so the preview walks / flinches / topples in
+     * sync with the world. Ignored when `children` is supplied.
+     */
+    model?: ModelConfig;
+    /** Live entity id driving motion cues for `model` (also lets a custom child resolve the same entity). */
+    instanceId?: string;
+    /** Lighting mood for the stage. Default `"studio"`. */
+    mood?: StudioMood;
+    /** Override the backdrop color (hex). Default: the mood's backdrop. */
+    backdrop?: string;
+    /** Turntable spin (rad/s). Default 0 — a still portrait that mirrors the live entity's own motion. */
+    turntable?: number;
+    /** Yaw the subject to face the camera each frame instead of spinning. Overrides `turntable`. */
+    faceCamera?: boolean;
+    /** The subject's declared forward axis for `faceCamera`. Default `[0, 0, 1]`. */
+    forward?: readonly [number, number, number];
+    /** Draw the backdrop + floor (true) or keep a transparent stage as a pure lighting rig (false). Default true. */
+    environment?: boolean;
+    /** Camera position framing the subject. Default `[0, 1, 3]`. */
+    cameraPosition?: [number, number, number];
+    /** Camera field of view. Default 35. */
+    fov?: number;
+    /** Device pixel ratio clamp. Default `[1, 2]`. */
+    dpr?: number | [number, number];
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Drop-in live 3D preview of a single entity — the character-screen portrait, unit inspector, or loadout
+ * viewer. It owns all the plumbing a game would otherwise re-derive by hand: a nested `<Canvas>`, the
+ * {@link GameContextBridge} that carries the running `GameContext` across the R3F reconciler boundary (so
+ * the subject's `useEntityRenderCues` / `useGameContext` hooks resolve and it mirrors the live game), a
+ * {@link StudioStage} 3-point lighting rig with optional turntable / face-camera, and a capture-friendly
+ * GL surface. The game keeps ownership of its `renderEntity`: pass it as `children`, or hand a native
+ * `model` (+ `instanceId`) for an engine-composed body. Bound to a live `instanceId`, the portrait walks,
+ * flinches, and topples in lockstep with the world instead of a canned spin.
+ *
+ * @capability entity-preview live 3D entity portrait — nested Canvas + context bridge + studio stage, driven by the game's own renderEntity
+ */
+export declare function EntityPreview({ children, model, instanceId, mood, backdrop, turntable, faceCamera, forward, environment, cameraPosition, fov, dpr, className, style, }: EntityPreviewProps): import("react").JSX.Element;

package/dist/render/EntityPreview.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Canvas } from "@react-three/fiber";
+import { GameContextBridge, useOptionalGameContext } from "@jgengine/react/provider";
+import { StudioStage } from "../scene/StudioStage.js";
+import { IsolatedEntityModel } from "./SceneModels.js";
+/**
+ * Drop-in live 3D preview of a single entity — the character-screen portrait, unit inspector, or loadout
+ * viewer. It owns all the plumbing a game would otherwise re-derive by hand: a nested `<Canvas>`, the
+ * {@link GameContextBridge} that carries the running `GameContext` across the R3F reconciler boundary (so
+ * the subject's `useEntityRenderCues` / `useGameContext` hooks resolve and it mirrors the live game), a
+ * {@link StudioStage} 3-point lighting rig with optional turntable / face-camera, and a capture-friendly
+ * GL surface. The game keeps ownership of its `renderEntity`: pass it as `children`, or hand a native
+ * `model` (+ `instanceId`) for an engine-composed body. Bound to a live `instanceId`, the portrait walks,
+ * flinches, and topples in lockstep with the world instead of a canned spin.
+ *
+ * @capability entity-preview live 3D entity portrait — nested Canvas + context bridge + studio stage, driven by the game's own renderEntity
+ */
+export function EntityPreview({ children, model, instanceId, mood = "studio", backdrop, turntable = 0, faceCamera = false, forward, environment = true, cameraPosition = [0, 1, 3], fov = 35, dpr = [1, 2], className, style, }) {
+    const ctx = useOptionalGameContext();
+    const subject = children ??
+        (model !== undefined ? _jsx(IsolatedEntityModel, { model: model, instanceId: instanceId }) : null);
+    return (_jsx("div", { "data-jg-entity-preview": "", className: className, style: { position: "relative", width: "100%", height: "100%", ...style }, children: _jsx(Canvas, { shadows: true, dpr: dpr, camera: { position: cameraPosition, fov }, gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: _jsx(GameContextBridge, { context: ctx, children: _jsx(StudioStage, { mood: mood, ...(backdrop === undefined ? {} : { backdrop }), turntable: turntable, faceCamera: faceCamera, ...(forward === undefined ? {} : { forward }), environment: environment, children: subject }) }) }) }));
+}

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;