@jgengine/shell 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,32 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.13.0
+
+### Migrate
+
+- **Nothing required** — this release is additive fixes, defaults, and new drop-in primitives. Bump `@jgengine/*` pins to `^0.13.0` (CLI `jgengine` is 0.10.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- Two defaults changed in the player's favor, both overridable: **offline games now persist to localStorage automatically** (#1207) and **rigged catalog assets animate by default** via clip metadata + semantic clip roles (#1209). If a game relied on rigged models staying frozen or on saves being memory-only, opt out explicitly; otherwise you get better behavior for free.
+
+### Added
+
+- **Drop-in inventory grid, window manager, and character sheet** (#1220) — `@jgengine/react` ships `InventoryGrid` (real drag/stack/split), a toggleable-window system (`panels`: bag, character sheet, spellbook-style windows with `@jgengine/core/ui/panelModel` state), and a `CharacterSheet` paperdoll, all HudTheme-skinnable — wire in a line or two instead of re-deriving from raw divs.
+- **Serializable runtime snapshots** (#1179) — capture/restore of live runtime state, including magazine state (`@jgengine/core/combat/magazine`) and stat modifiers, for saves and replication.
+- **Portable weapon plumbing** (#1211) — `@jgengine/core/combat/weaponFire` composes trigger → magazine → spread → projectile/hitscan as data, no game-local glue.
+- **Portable leveling** (#1206) and **portable damage-pool access** (#1208) — progression and damage pools exposed as genre-agnostic seams on the game context.
+- **Named combat VFX presets** (#1204) — `@jgengine/core/combat/vfxPresets`: a visible attack is one line.
+- **Runtime-measured render-bounds hitboxes** (#1227) — colliders wrap what the shell actually mounts, not the raw asset bounds.
+- **Character motion feel** — procedural part motion for rig-less part-composed characters (#1222) plus squash & stretch and death splat (#1229).
+- **City fabric** (#1191) — `streetGenerator` + `cityGenerator`, editor bake verb, street-aware lots, road junctions, grounding, and a web playground.
+- **`jgengine recipe` CLI** (#1214, #1231) — vetted wired compositions, compile-pinned against the SDK, listed and copied from the CLI.
+- **Editor/debug modes mirror to the URL** with a proper editor exit (#1203); game template ships a dependency-free WebGL screenshot script (#1202).
+
+### Changed
+
+- Offline games persist to localStorage by default (#1207); rigged assets animate by default (#1209).
+- RTS camera pan inversion fixed (#1228); sprite raycast warning silenced and duplicate nameplate health bars removed (#1194); scaffolded F2+E editor Tailwind `@source` renders its theme (#1195).
+- Outside-game DX: stat-pool no-op stability, camera-transparent decor, cleaner install/version output, headless UI-intent seam (#1223); new-game briefs direct engine bugs/gaps upstream (#1200).
+
 ## 0.12.0
 
 ### Migrate

package/dist/GameHost.d.ts

@@ -8,6 +8,8 @@ export interface EditorSummonModule {
         gameId: string;
         playable: PlayableGame;
         catalogs?: readonly EditorCatalogDefinition[];
+        /** Passed by the host when the editor was summoned over a game — powers the "Exit to game" control. */
+        onExitEditor?: () => void;
     }>;
 }
 /** Props for {@link GameHost}: the playable, optional multiplayer overrides, and the optional editor loader that enables the engine-owned F2+E summon. */

package/dist/GameHost.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { lazy, Suspense, useEffect, useMemo, useState } from "react";
 import { installSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
+import { readUrlParam, subscribeUrlChange, writeUrlParam } from "@jgengine/core/devtools/urlFlags";
 import { multiplayerAdapterKind } from "@jgengine/core/runtime/adapter";
 import { GamePlayerShell } from "./GamePlayerShell.js";
 import { resolveShellMultiplayer } from "./multiplayer.js";
@@ -12,10 +13,13 @@ function warnUndrivenAdapter(kind) {
     console.warn(`GameHost: game declares multiplayer adapter "${kind}", which the built-in shell resolver cannot drive. ` +
         "Running offline. Pass a prebuilt session via the multiplayer prop, or a resolveMultiplayer prop, to GameHost.");
 }
+/** The query param that mirrors editor mode into the URL — strip it (and reload) to drop back to the game. */
+const EDITOR_MODE_PARAM = "mode";
+const EDITOR_MODE_VALUE = "editor";
 function initialEditorMode(enabled) {
     if (!enabled || typeof window === "undefined")
         return false;
-    return new URLSearchParams(window.location.search).get("mode") === "editor";
+    return readUrlParam(EDITOR_MODE_PARAM) === EDITOR_MODE_VALUE;
 }
 /**
  * The one documented mount: resolves multiplayer for the playable and renders the shell. With the
@@ -32,6 +36,25 @@ export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultipla
         // Self-guards against production builds; the endpoint just marks where dev saves land.
         return installSaveEndpoint("/__jgengine/save", resolvedGameId);
     }, [editor, resolvedGameId]);
+    // Mirror editor mode into the URL so the address bar is the honest record of what's open: sharing
+    // the URL reopens the editor, and stripping `?mode=editor` (then reloading) drops back to the game.
+    // Only ever clear a `mode` we set to editor — never a stray value the app put there.
+    useEffect(() => {
+        if (editor === undefined)
+            return;
+        if (editorOpen)
+            writeUrlParam(EDITOR_MODE_PARAM, EDITOR_MODE_VALUE);
+        else if (readUrlParam(EDITOR_MODE_PARAM) === EDITOR_MODE_VALUE)
+            writeUrlParam(EDITOR_MODE_PARAM, null);
+    }, [editor, editorOpen]);
+    // Keep in step with browser back/forward: navigating away from `?mode=editor` closes the editor.
+    useEffect(() => {
+        if (editor === undefined)
+            return;
+        return subscribeUrlChange(() => {
+            setEditorOpen(readUrlParam(EDITOR_MODE_PARAM) === EDITOR_MODE_VALUE);
+        });
+    }, [editor]);
     useEffect(() => {
         if (editor === undefined || editorOpen)
             return;
@@ -83,7 +106,7 @@ export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultipla
         return session;
     }, [playable, resolvedGameId, wsUrl, multiplayer, resolveMultiplayer]);
     if (editorOpen && EditorLazy !== null) {
-        return (_jsx(Suspense, { fallback: null, children: _jsx(EditorLazy, { gameId: resolvedGameId, playable: playable, catalogs: playable.editorCatalogs }) }));
+        return (_jsx(Suspense, { fallback: null, children: _jsx(EditorLazy, { gameId: resolvedGameId, playable: playable, catalogs: playable.editorCatalogs, onExitEditor: () => setEditorOpen(false) }) }));
     }
     return _jsx(GamePlayerShell, { playable: playable, multiplayer: resolved });
 }

package/dist/GamePlayerShell.js

@@ -11,6 +11,7 @@ import { createSettingsStore } from "@jgengine/core/settings/settingsModel";
 import { applyBindingOverrides, clearBindingOverride, loadBindingOverrides, saveBindingOverride, } from "@jgengine/core/input/bindingOverrides";
 import { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "@jgengine/core/ui/orientation";
 import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams";
+import { readUrlFlag, subscribeUrlChange, writeUrlParam } from "@jgengine/core/devtools/urlFlags";
 import { createAudioEngine } from "./audio/audioEngine.js";
 import { attachAudioEventWire } from "./audio/audioWire.js";
 import { installAgentBridge } from "./devtools/agentBridge.js";
@@ -25,6 +26,8 @@ import { useShellMultiplayerSync } from "./useShellMultiplayerSync.js";
 import { ShellHudPresentation } from "./ShellHudPresentation.js";
 import { Shell3dPresentation } from "./Shell3dPresentation.js";
 const DEV_USER_ID = "dev-player";
+/** The query param that mirrors the devtools overlay into the URL — present = open. */
+const DEBUG_PARAM = "debug";
 export { applyMotionImpulses } from "@jgengine/core/runtime/motionIntents";
 export { nearbyObstacles } from "@jgengine/core/movement/movementModel";
 export { resolvePhysicsTuning } from "@jgengine/core/movement/playerMovement";
@@ -38,9 +41,20 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     const multiplayer = useMemo(() => (rawMultiplayer === null ? null : withDevtoolsLatency(rawMultiplayer)), [rawMultiplayer]);
     const devtoolsEnabled = playable.devtools !== false && !poster;
     armFallbackSeams(devtoolsEnabled);
-    const [devtoolsOpen, setDevtoolsOpen] = useState(false);
+    // `?debug` mirrors the devtools overlay into the URL: open with a link, strip the param to close.
+    const [devtoolsOpen, setDevtoolsOpen] = useState(() => devtoolsEnabled && readUrlFlag(DEBUG_PARAM));
     const devtoolsOpenRef = useRef(false);
     devtoolsOpenRef.current = devtoolsOpen;
+    useEffect(() => {
+        if (!devtoolsEnabled)
+            return;
+        writeUrlParam(DEBUG_PARAM, devtoolsOpen ? "1" : null);
+    }, [devtoolsEnabled, devtoolsOpen]);
+    useEffect(() => {
+        if (!devtoolsEnabled)
+            return;
+        return subscribeUrlChange(() => setDevtoolsOpen(readUrlFlag(DEBUG_PARAM)));
+    }, [devtoolsEnabled]);
     useEffect(() => installAgentBridge({
         playable,
         devtoolsEnabled,

package/dist/Shell3dPresentation.js

@@ -19,7 +19,7 @@ import { PostProcessing } from "./postfx/PostProcessing.js";
 import { EnvironmentLighting } from "./render/EnvironmentLighting.js";
 import { CollisionDebugWorld } from "./devtools/CollisionDebugWorld.js";
 import { DevtoolsRendererProbe } from "./devtools/DevtoolsOverlay.js";
-import { GameCameraRig, PlayerFovProvider, PlayerFovSlider, resolveRigKind, rtsPanKeysConflict, } from "./camera/index.js";
+import { CAMERA_TRANSPARENT_USERDATA, GameCameraRig, PlayerFovProvider, PlayerFovSlider, resolveRigKind, rtsPanKeysConflict, } from "./camera/index.js";
 import { CullingProvider } from "./visibility/CullingProvider.js";
 import { SkyDaylight, TimeOfDayDaylight } from "./environment.js";
 import { resolveSkyLightOwnership, skyEmitsLights } from "./environment/skyLightingPolicy.js";
@@ -289,7 +289,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                             fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
                                             far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? _jsx(EnvironmentLighting, {}) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? _jsx(WorldOverlay, { ctx: ctx }) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
+                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? _jsx(EnvironmentLighting, {}) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
                                                         cameraDraggingRef.current = dragging;
                                                     } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled }), _jsx(DevtoolsRendererProbe, {}), resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality })) : null] }), !poster &&
                                     !orientationGate &&

package/dist/camera/GameOrbitCamera.js

@@ -3,6 +3,7 @@ import { OrbitControls } from "@react-three/drei";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { MOUSE, PerspectiveCamera, Raycaster, Vector3 } from "three";
+import { isCameraOccluderTransparent } from "./cameraCollision.js";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
 import { cameraLookPitch, compensatedFov, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
@@ -81,6 +82,10 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
                 ray.set(collisionOriginRef.current.set(t.x, t.y, t.z), dir);
                 ray.near = config.collision.minTargetDistance;
                 ray.far = dist;
+                // Sprites (VFX, billboards) live in the scene; three's Sprite.raycast
+                // errors every frame unless the raycaster has a camera, even though we
+                // discard sprite hits below. Setting it silences that per-frame log.
+                ray.camera = camera;
                 let blocked = 0;
                 for (const hit of ray.intersectObjects(scene.children, true)) {
                     const obj = hit.object;
@@ -88,7 +93,8 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
                         continue;
                     if (obj.isSprite === true)
                         continue;
-                    if (obj.userData.jgCameraTransparent === true)
+                    // Inheritable: decor flags a group jgCameraTransparent and all children pass through.
+                    if (isCameraOccluderTransparent(obj))
                         continue;
                     blocked = hit.distance;
                     break;

package/dist/camera/cameraCollision.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Camera spring-arm occlusion filtering.
+ *
+ * The orbit rig raycasts target→camera each frame and pulls the boom in past
+ * occluders. Author decor mounted through the `WorldOverlay` presentation seam
+ * is dressing, not collision geometry, so it should never yank the camera. A
+ * decor group flags itself camera-transparent once (`jgCameraTransparent`) and
+ * every descendant inherits it — a child can opt back into blocking the camera
+ * with `jgCameraCollide`.
+ */
+/** Minimal structural view of a raycast hit object: its own tags plus a parent link to walk. Keeps this filter free of a three.js import so it stays unit-testable. */
+export interface CameraOccluder {
+    readonly userData?: Record<string, unknown>;
+    readonly parent?: CameraOccluder | null;
+}
+/** userData applied to the group wrapping author `WorldOverlay` decor so the spring-arm ignores it by default. */
+export declare const CAMERA_TRANSPARENT_USERDATA: {
+    readonly jgCameraTransparent: true;
+};
+/**
+ * Should the camera spring-arm ignore this raycast hit? Walks the object up its
+ * `.parent` chain and honors the nearest camera tag: `jgCameraCollide === true`
+ * blocks (opt back in), `jgCameraTransparent === true` passes through. Untagged
+ * geometry blocks as before, so engine-owned ground/entities are unaffected.
+ *
+ * @capability camera-transparent-decor let author decor pass through the orbit spring-arm; a child opts back in with jgCameraCollide
+ */
+export declare function isCameraOccluderTransparent(object: CameraOccluder | null | undefined): boolean;

package/dist/camera/cameraCollision.js

@@ -0,0 +1,34 @@
+/**
+ * Camera spring-arm occlusion filtering.
+ *
+ * The orbit rig raycasts target→camera each frame and pulls the boom in past
+ * occluders. Author decor mounted through the `WorldOverlay` presentation seam
+ * is dressing, not collision geometry, so it should never yank the camera. A
+ * decor group flags itself camera-transparent once (`jgCameraTransparent`) and
+ * every descendant inherits it — a child can opt back into blocking the camera
+ * with `jgCameraCollide`.
+ */
+/** userData applied to the group wrapping author `WorldOverlay` decor so the spring-arm ignores it by default. */
+export const CAMERA_TRANSPARENT_USERDATA = {
+    jgCameraTransparent: true,
+};
+/**
+ * Should the camera spring-arm ignore this raycast hit? Walks the object up its
+ * `.parent` chain and honors the nearest camera tag: `jgCameraCollide === true`
+ * blocks (opt back in), `jgCameraTransparent === true` passes through. Untagged
+ * geometry blocks as before, so engine-owned ground/entities are unaffected.
+ *
+ * @capability camera-transparent-decor let author decor pass through the orbit spring-arm; a child opts back in with jgCameraCollide
+ */
+export function isCameraOccluderTransparent(object) {
+    for (let node = object ?? null; node != null; node = node.parent ?? null) {
+        const data = node.userData;
+        if (data === undefined)
+            continue;
+        if (data.jgCameraCollide === true)
+            return false;
+        if (data.jgCameraTransparent === true)
+            return true;
+    }
+    return false;
+}

package/dist/camera/cameraRigs.js

@@ -4,7 +4,7 @@ import { PerspectiveCamera, Quaternion, Vector3 } from "three";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useGameContext } from "@jgengine/react/provider";
 import { ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
-import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, velocityYawTarget, } from "./rigMath.js";
+import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, rtsPanWorldDir, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, velocityYawTarget, } from "./rigMath.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
 import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
@@ -262,13 +262,9 @@ export function RtsRig(props) {
         }
         const center = centerRef.current;
         if (panX !== 0 || panZ !== 0) {
-            const cos = Math.cos(yawRef.current);
-            const sin = Math.sin(yawRef.current);
-            const worldX = panX * cos + panZ * sin;
-            const worldZ = panZ * cos - panX * sin;
-            const len = Math.hypot(worldX, worldZ) || 1;
-            center.x += (worldX / len) * panSpeed * dt;
-            center.z += (worldZ / len) * panSpeed * dt;
+            const dir = rtsPanWorldDir(panX, panZ, yawRef.current);
+            center.x += dir.x * panSpeed * dt;
+            center.z += dir.z * panSpeed * dt;
         }
         else {
             const follow = readFollow(ctx, followId);

package/dist/camera/index.d.ts

@@ -7,3 +7,4 @@ export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, type PlayerFovState,
 export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCameraShakeChannel, useCameraShake, type CameraShakeChannel, } from "./shakeChannel.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
+export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, type CameraOccluder, } from "./cameraCollision.js";

package/dist/camera/index.js

@@ -7,3 +7,4 @@ export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, } from "./PlayerFov.j
 export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCameraShakeChannel, useCameraShake, } from "./shakeChannel.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
+export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, } from "./cameraCollision.js";

package/dist/camera/rigMath.d.ts

@@ -37,6 +37,13 @@ export declare function resolveTopDown(config: TopDownCameraConfig | undefined):
   * @internal
   */
 export declare function topDownPose(follow: Vec3, resolved: ResolvedTopDown, fov: number): CameraPose;
+/**
+ * World-space direction for RTS pan input: `panX` slides along screen-right,
+ * `panZ` along the camera's ground-plane forward, for a camera posed by
+ * `topDownPose` at the same yaw. Normalized; zero input returns zero.
+ * @internal
+ */
+export declare function rtsPanWorldDir(panX: number, panZ: number, yaw: number): Vec3;
 /** Exponential spring-arm approach toward a desired point (frame-rate independent).
  * @internal
  */

package/dist/camera/rigMath.js

@@ -74,6 +74,22 @@ export function topDownPose(follow, resolved, fov) {
         fov,
     };
 }
+/**
+ * World-space direction for RTS pan input: `panX` slides along screen-right,
+ * `panZ` along the camera's ground-plane forward, for a camera posed by
+ * `topDownPose` at the same yaw. Normalized; zero input returns zero.
+ * @internal
+ */
+export function rtsPanWorldDir(panX, panZ, yaw) {
+    const forward = forwardVector(yaw);
+    const right = rightVector(yaw);
+    const x = panX * right.x + panZ * forward.x;
+    const z = panX * right.z + panZ * forward.z;
+    const len = Math.hypot(x, z);
+    if (len === 0)
+        return { x: 0, y: 0, z: 0 };
+    return { x: x / len, y: 0, z: z / len };
+}
 /** Exponential spring-arm approach toward a desired point (frame-rate independent).
  * @internal
  */

package/dist/environment/EnvironmentScene.js

@@ -6,8 +6,10 @@ import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
 import { resolveStructureBuildings } from "@jgengine/core/world/environmentSummary";
+import { findRoadJunctions, junctionExclusions } from "@jgengine/core/world/streets";
 import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { GroundPad } from "./GroundPad.js";
+import { RoadJunctions } from "./RoadJunctions.js";
 import { RoadRibbons } from "./RoadRibbons.js";
 import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
@@ -142,6 +144,7 @@ function Structures({ structures, field }) {
     const placements = useMemo(() => resolveStructureBuildings(structures).map((building) => ({
         building,
         position: [0, field.sampleHeight(building.center[0], building.center[1]), 0],
+        ...(building.rotationY === undefined ? {} : { rotationY: building.rotationY, pivot: building.center }),
     })), [structures, field]);
     const palette = useMemo(() => resolveBuildingPalette(structures.style, structures.palette), [structures.style, structures.palette]);
     return _jsx(InstancedBuildings, { buildings: placements, palette: palette });
@@ -154,5 +157,7 @@ export function EnvironmentScene({ feature }) {
     const pads = feature.pads ?? [];
     const islands = feature.islands ?? [];
     const roads = feature.roads ?? [];
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field }, `road-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    const junctions = useMemo(() => findRoadJunctions(roads), [roads]);
+    const exclusions = useMemo(() => junctionExclusions(junctions), [junctions]);
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, exclusions: exclusions }, `road-${index}`))), _jsx(RoadJunctions, { junctions: junctions, field: field }), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/RoadJunctions.d.ts

@@ -0,0 +1,12 @@
+import { type RoadJunction } from "@jgengine/core/world/streets";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+/**
+ * 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 declare function RoadJunctions({ junctions, field, }: {
+    junctions: readonly RoadJunction[];
+    field: TerrainField;
+}): import("react").JSX.Element | null;

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/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/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;