@jgengine/shell 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -10,7 +10,79 @@ let consumers pick up the better stuff, not just to list what moved.
 Agents building on the published SDK can also read this programmatically:
 `import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
 same data as typed values, so an updater can diff its installed version against
-the latest and surface the migration steps.
+the latest and surface the migration steps. Easier still: `npx jgengine upgrade`
+run inside a game project diffs the installed `@jgengine/*` versions against the
+latest release and prints every Migrate step and Adopt-worthy addition in
+between (`--json` for structured output).
+
+## [Unreleased]
+
+<!--
+Every PR that changes `packages/*/src` records its consumer-facing change here, so
+the next release's notes are complete by construction. Add a bullet under the right
+subhead below. `bun run check-changelog` fails a source PR whose `[Unreleased]` block
+is untouched; pure refactors/tests bypass with `[skip changelog]` in a commit message.
+At publish, rename this heading to the new version and mirror the entries into
+`packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
+-->
+
+### Migrate
+
+- _Nothing yet._
+
+### Added
+
+### Changed
+
+### Removed
+
+## 0.14.0
+
+### Migrate
+
+- **Nothing required** — this release is additive drop-in primitives, editor authoring, CLI discovery, and fixes. Bump `@jgengine/*` pins to `^0.14.0` (CLI `jgengine` is 0.11.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- One behavior fix to know about: in a `rig: "chase"` game, on-foot movement and aim are now camera-relative (the chase rig reports its yaw to the shell like every other rig). If a game somehow relied on world-yaw-0 movement under a chase camera, that was the bug this fixes.
+
+### Added
+
+- One authoring gesture for scatterable coverage: `@jgengine/core/world/scatterCoverage` owns shared density/budget semantics (per-kind unit, requested→count→capped, one clamp-and-warn phrasing) for `grass_field`/`scatter`/`city`; the editor inspector leads each kind with the same Area → Assets → Density coverage section, scatter truncates to the shared 250k instance budget, and city single-sources its 2,600-lot cap.
+- **Created games ship a drive/playtest script** (#1248) — `npx jgengine create` scaffolds now include `scripts/drive.mjs` (`bun run drive`): dependency-free headless play/testing of the running game — ordered `--click`/`--key`/`--wait`/`--shot`/`--rpc` steps against the agent bridge, plus `--playtest --strict` progress/softlock verdicts off `capture.probe`. Shared Chrome/CDP machinery lives in `scripts/browser.mjs`; `scripts/shoot.mjs` is unchanged in behavior, now a thin CLI over it.
+- Editor: viewport clip preview for rigged assets (Animation dock "Clips" mode — pick a rig or placed instance, play/scrub/loop/speed any catalog clip) and an Inspector "Animation" section that authors a placement's `ModelConfig.animation` (role→clip dropdowns, auto/none, walk/run/fade, one-shot event bindings) as undoable `marker.meta.animation` edits. New subpaths: `@jgengine/editor/shell/clipPreview`, `@jgengine/editor/modelAnimationAuthoring`, `@jgengine/editor/ClipPreviewLayer`.
+- **`npx jgengine find <intent>`** — active capability discovery: searches every shipped domain's `capabilities.md` (staged inside the CLI tarball, so it works regardless of which `@jgengine/*` packages a project installed) and prints the drop-in primitive + its import for an intent like `"toggleable window"`, `inventory`, or `minimap`. Scaffolded games are now briefed (in `AGENTS.md` and the `jgengine` intake skill) to reach for it before hand-rolling a HUD/inventory/window/rig.
+- **`EntityPreview`** (`@jgengine/shell/render/EntityPreview`) — drop-in live 3D entity portrait for character screens, unit inspectors, and loadout viewers. Owns the nested `<Canvas>`, the `GameContextBridge`, and a `StudioStage` lighting rig with optional turntable / face-camera; the game passes its own `renderEntity` as children (or a native `model` + `instanceId`) and, bound to a live entity, the portrait walks/flinches/topples in sync with the world.
+- **`GameContextBridge`** (`@jgengine/react`) — re-provide the running `GameContext` across a nested React reconciler boundary (the R3F `<Canvas>`), so a game building its own preview canvas no longer re-derives the bridge by hand.
+
+### Changed
+
+- **Chase rig reports its yaw to the shell** — `ChaseRig` now writes the camera yaw back to the shared yaw ref like every other player-facing rig, so on-foot movement and aim in a `rig: "chase"` game are camera-relative instead of frozen to world yaw 0 (WASD no longer fights the camera the moment it swings behind the player). Interior views (cockpit/hood/rear) report the vehicle heading.
+- **Combat VFX no longer render as black squares under AO/DOF post-processing** (#1247) — GTAO/Bokeh scene prepasses skip overlay effects. Games with custom additive overlay effects opt out the same way: spread `POSTFX_OVERLAY_USERDATA` (`@jgengine/shell/postfx/postfxOverlay`) onto the overlay group's `userData`.
+- **`PanelHost` windows stack above the HUD by default** (`@jgengine/react`) — the host establishes its own stacking context at `zIndexBase` (default 40), so open windows always paint over stat bars / nameplates / frames instead of bleeding through. Overridable per instance.
+
+## 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
 

package/dist/CombatPresentation.js

@@ -2,7 +2,8 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { CombatCameraShake, ProjectileTracers, WorldFloatText, WorldTelegraphs, } from "./world/WorldHud.js";
 import { WorldSpellVfx } from "./world/WorldVfx.js";
 import { RetainedVfx } from "./world/RetainedVfx.js";
+import { POSTFX_OVERLAY_USERDATA } from "./postfx/postfxOverlay.js";
 /** Mounts the opt-in combat VFX stack inside the 3D canvas. @internal */
 export function CombatPresentation({ effects }) {
-    return (_jsxs(_Fragment, { children: [effects.telegraphs ? _jsx(WorldTelegraphs, {}) : null, effects.vfx ? (_jsxs(_Fragment, { children: [_jsx(WorldSpellVfx, {}), _jsx(RetainedVfx, {})] })) : null, effects.floatText ? _jsx(WorldFloatText, {}) : null, effects.tracers ? _jsx(ProjectileTracers, {}) : null, effects.shake ? _jsx(CombatCameraShake, {}) : null] }));
+    return (_jsxs("group", { userData: POSTFX_OVERLAY_USERDATA, children: [effects.telegraphs ? _jsx(WorldTelegraphs, {}) : null, effects.vfx ? (_jsxs(_Fragment, { children: [_jsx(WorldSpellVfx, {}), _jsx(RetainedVfx, {})] })) : null, effects.floatText ? _jsx(WorldFloatText, {}) : null, effects.tracers ? _jsx(ProjectileTracers, {}) : null, effects.shake ? _jsx(CombatCameraShake, {}) : null] }));
 }

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);
@@ -452,6 +448,7 @@ export function ChaseRig(props) {
             if (lookBack) {
                 pose.position = seatPose(follow, yaw, seat, fov).position;
             }
+            props.yawRef.current = yaw;
             commit(pose, dt);
             return;
         }
@@ -464,6 +461,9 @@ export function ChaseRig(props) {
             anchorYaw = smoothYaw(anchorYawRef.current ?? targetYaw, targetYaw, resolved.velocityYawResponse, dt);
             anchorYawRef.current = anchorYaw;
         }
+        // Report camera yaw back to the shell like every other player-facing rig, so
+        // on-foot movement and aim stay camera-relative instead of frozen at yaw 0.
+        props.yawRef.current = anchorYaw;
         const led = leadFollowPoint(follow, last, dt, resolved);
         const desired = chaseDesiredPosition(led, anchorYaw, resolved);
         const prev = posRef.current ?? desired;

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/devtools/CollisionDebugWorld.js

@@ -4,6 +4,7 @@ import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
+import { POSTFX_OVERLAY_USERDATA } from "../postfx/postfxOverlay.js";
 import { aimProbeNeeded, anyCollisionLayerOn, colliderScanNeeded, collisionDebug, projectileListenNeeded, } from "./collisionDebug.js";
 import { AIM_DAMAGE_COLOR, AIM_LASER_COLOR, AIM_MISS_COLOR, AIM_SOLID_COLOR, BODY_WIRE_COLOR, collectDebugShapes, computeAimLaser, HITBOX_WIRE_COLOR, muzzleMarkerFromOrigin, PROJECTILE_PATH_COLOR, } from "./collisionDebugMath.js";
 function useCollisionDebugState() {
@@ -15,11 +16,24 @@ function WireSphere({ center, radius, color, label, }) {
 function WireAabb({ center, halfExtents, rotationY, color, label, }) {
     return (_jsxs("group", { position: [center[0], center[1], center[2]], rotation: [0, rotationY, 0], children: [_jsxs("mesh", { children: [_jsx("boxGeometry", { args: [halfExtents[0] * 2, halfExtents[1] * 2, halfExtents[2] * 2] }), _jsx("meshBasicMaterial", { color: color, wireframe: true, transparent: true, opacity: 0.85, depthTest: false })] }), _jsx(Html, { position: [0, halfExtents[1] + 0.15, 0], center: true, distanceFactor: 14, zIndexRange: [25, 0], style: { pointerEvents: "none" }, children: _jsx("span", { className: "rounded bg-black/70 px-1 text-[9px] font-medium text-white/90", children: label }) })] }));
 }
+function WireTriangleMesh({ entry, shape, color, }) {
+    const geometry = useMemo(() => {
+        const built = new THREE.BufferGeometry();
+        built.setAttribute("position", new THREE.BufferAttribute(shape.mesh.positions, 3));
+        built.setIndex(new THREE.BufferAttribute(shape.mesh.indices, 1));
+        return built;
+    }, [shape.mesh]);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    return (_jsxs("group", { children: [_jsx("group", { position: [entry.position[0], entry.position[1], entry.position[2]], rotation: [0, entry.rotationY, 0], children: _jsx("group", { position: [shape.meshTranslate[0], shape.meshTranslate[1], shape.meshTranslate[2]], scale: shape.meshScale, children: _jsx("mesh", { geometry: geometry, children: _jsx("meshBasicMaterial", { color: color, wireframe: true, transparent: true, opacity: 0.85, depthTest: false }) }) }) }), _jsx(Html, { position: [shape.center[0], shape.center[1] + shape.halfExtents[1] + 0.15, shape.center[2]], center: true, distanceFactor: 14, zIndexRange: [25, 0], style: { pointerEvents: "none" }, children: _jsx("span", { className: "rounded bg-black/70 px-1 text-[9px] font-medium text-white/90", children: entry.label }) })] }));
+}
 function ColliderShapeMesh({ entry }) {
     const color = entry.style === "hitbox" ? HITBOX_WIRE_COLOR : BODY_WIRE_COLOR;
     if (entry.shape.kind === "sphere") {
         return (_jsx(WireSphere, { center: entry.shape.center, radius: entry.shape.radius, color: color, label: entry.label }));
     }
+    if (entry.shape.kind === "mesh") {
+        return _jsx(WireTriangleMesh, { entry: entry, shape: entry.shape, color: color });
+    }
     return (_jsx(WireAabb, { center: entry.shape.center, halfExtents: entry.shape.halfExtents, rotationY: entry.rotationY, color: color, label: entry.label }));
 }
 function endpointColor(kind) {
@@ -174,7 +188,7 @@ export function CollisionDebugWorld() {
     }, [state.layers.muzzles, state.layers.aimLaser, state.projectileTraces, laser]);
     if (!anyCollisionLayerOn(state.layers))
         return null;
-    return (_jsxs("group", { children: [shapes.map((entry) => (_jsx(ColliderShapeMesh, { entry: entry }, entry.key))), projectilePoints.map((path) => (_jsx(Line, { points: path.points, color: PROJECTILE_PATH_COLOR, lineWidth: 2, transparent: true, opacity: 0.9, depthTest: false }, path.id))), muzzleOrigins.map((entry) => (_jsx(MuzzleMark, { origin: entry.origin }, `muzzle-${entry.id}`))), laser !== null ? (_jsxs(_Fragment, { children: [_jsx(Line, { points: [
+    return (_jsxs("group", { userData: POSTFX_OVERLAY_USERDATA, children: [shapes.map((entry) => (_jsx(ColliderShapeMesh, { entry: entry }, entry.key))), projectilePoints.map((path) => (_jsx(Line, { points: path.points, color: PROJECTILE_PATH_COLOR, lineWidth: 2, transparent: true, opacity: 0.9, depthTest: false }, path.id))), muzzleOrigins.map((entry) => (_jsx(MuzzleMark, { origin: entry.origin }, `muzzle-${entry.id}`))), laser !== null ? (_jsxs(_Fragment, { children: [_jsx(Line, { points: [
                             new THREE.Vector3(laser.origin[0], laser.origin[1], laser.origin[2]),
                             new THREE.Vector3(laser.end[0], laser.end[1], laser.end[2]),
                         ], color: AIM_LASER_COLOR, lineWidth: 1.5, transparent: true, opacity: 0.95, depthTest: false }), _jsx(AimEndpointMark, { point: laser.end, kind: laser.kind })] })) : null] }));

package/dist/devtools/collisionDebugMath.d.ts

@@ -1,5 +1,6 @@
 import type { EntityPosition } from "@jgengine/core/scene/entityStore";
 import { type ColliderPurpose, type EntityColliderSet, type ResolvedCollider } from "@jgengine/core/scene/colliders";
+import type { PreparedCollisionMesh } from "@jgengine/core/scene/collisionMesh";
 import { type SceneRaycastApi, type SceneRaycastHit } from "@jgengine/core/scene/sceneRaycast";
 import { type ShotOriginPolicy } from "@jgengine/core/combat/shotOrigin";
 import type { Aim } from "@jgengine/core/scene/spatial";
@@ -24,6 +25,13 @@ export interface DebugShapeEntry {
         kind: "aabb";
         halfExtents: EntityPosition;
         center: EntityPosition;
+    } | {
+        kind: "mesh";
+        mesh: PreparedCollisionMesh;
+        meshScale: number;
+        meshTranslate: EntityPosition;
+        halfExtents: EntityPosition;
+        center: EntityPosition;
     };
     label: string;
     style: "hitbox" | "body";

package/dist/devtools/collisionDebugMath.js

@@ -36,11 +36,20 @@ function pushResolved(out, targetKind, instanceId, catalogId, position, rotation
         const center = shapeWorldCenter(collider, position, rotationY);
         const shape = collider.shape.kind === "sphere"
             ? { kind: "sphere", radius: collider.shape.radius, center }
-            : {
-                kind: "aabb",
-                halfExtents: collider.shape.halfExtents,
-                center,
-            };
+            : collider.shape.kind === "mesh"
+                ? {
+                    kind: "mesh",
+                    mesh: collider.shape.mesh,
+                    meshScale: collider.shape.meshScale,
+                    meshTranslate: collider.shape.meshTranslate,
+                    halfExtents: collider.shape.halfExtents,
+                    center,
+                }
+                : {
+                    kind: "aabb",
+                    halfExtents: collider.shape.halfExtents,
+                    center,
+                };
         out.push({
             key: `${targetKind}:${instanceId}:${collider.purpose}:${collider.name}`,
             targetKind,

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;