@jgengine/shell 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,58 @@ 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
+
+- **Author games through `defineGame` from `@jgengine/shell`** — it is the single public authoring entry (and carries the define-game capability tag). Core's constructor was renamed `defineGame` → `defineGameDefinition` (`@jgengine/core/game/defineGame`); only hosts and tooling call it. If you imported `defineGame` from core, switch the import to `@jgengine/shell`. `GamePlayer`/`GamePlayerShell` are `@internal` now — `GameHost` is the documented mount, and it owns the editor summon (`?mode=editor`, F2+E, dev save endpoint), so delete any per-game editor bootstrap.
+- **Declare your world with `world()`** (`@jgengine/core/world/place`): `world({ id, ground: { mode, size, surface? }, physics? })` with `flat` / `round` / `voxel` / `board` ground. New scaffolds emit a thin infinite flat place instead of the old 96 m meadow. `environment()` still works but is demoted to the legacy consumption path for editor-written scene data — **nothing required** for existing games; new worlds should use `world()` and author all dressing in the editor.
+- Everything else is additive — stat pools, minimap marker sources, auction house, city/path generation, editor workspaces require no changes to existing games.
+
+### Added
+
+- **World = place: `world()` API** (#1178) — a world is substrate + laws, not a coded diorama. `@jgengine/core/world/place` ships `world({ id, ground: { mode, size, surface?, generator? }, physics? })`; size is discriminated by mode (flat `{x,z}` with `Infinity` axes, round `{radius}`, voxel generator domain, board `{x,y}` cells — TS and runtime both reject mismatches). `ground.surface` carries matter/feel laws (metal vs slime vs felt) read by the same rule systems; per-place `physics` resolves over the game default; multiple worlds per game are first-class. The shell renders place substrates (`PlaceScene`) under the engine default sky; seeds derive from world id + save via `seedForPlace`.
+- **`@jgengine/shell/gameKit`** — happy-path authoring surface: authoring, mount, stores, systems, authored-scene helpers, HUD primitives, seeded rng in one import.
+- **Portable generic stat pools** — `@jgengine/core/stats/statPool`: bounded named pools (health, energy, heat, ammo…) with the entity-stats integration rebuilt on them; recipe in skill `jgengine-combat`.
+- **Auction-house economy primitives** (#1086) — `@jgengine/core/economy/auctionBook` (timed bid auctions, escrowed bids, outbid refunds, optional buyout, anti-snipe close extension, seller settlement minus house cut) plus market price history.
+- **Portable minimap marker sources** — core world seam feeding game minimaps; recipe in skill `jgengine-ui`.
+- **Unified seed-driven path network + city generation v2** (#1103, #1106) — streets/blocks/buildings with grid-ness, curviness, branching and block-size dials; zone bands, weighted building-class mixes, massing pieces, balance presets, junction-centered clustering, road-derived block polygons and parcels. Shell renders realistic roads: real intersections, curbs, lane lines, tunnels, and roads riding bridge decks.
+- **Physical fidelity** — mesh-accurate hitboxes (shots pass through holes in concave models, #1075), auto-fit entity/object colliders from measured model bounds (#1072), movement obstruction reading fitted boxes + compound-box openings (#1077).
+- **Editor overhaul** (#1110) — materials / lighting / scripting / animation-timeline / multiplayer workspaces, command palette, minimap bake wired end-to-end (#1036), real offscreen GLB thumbnails in the content browser, hierarchy drag-drop + keyboard + context menus + per-object visibility/lock, multi-select inspector, console RPC, asset drag-place, ortho projection, pivot modes, play chrome.
+- **Editor authoring pipeline** — author entity definitions and starter catalogs (#1012), author catalogs/schema fields in the Data tab (#1043), promote an authored scene folder into a runnable game (#1011), authored triggers promoted to a shared primitive with goal/win rules (#1013), asset import rewrites the game's `game/assets.ts` (#1042).
+- **Skills** — research-backed `game-design` and `level-design` skills (#962); every-game-owns-custom-UI invariant codified (#1148).
+
+### Changed
+
+- `npx jgengine create` scaffolds a thin infinite flat `world()` place; the editor `blankWorld` no longer pre-bakes seeded grass. Dressing belongs in `editor.scene.json`.
+- Environment studio visual-quality pass — turf tufts, depth-aware water, relief soil, weathered poles; grass fields no longer rebuild geometry per frame (#1090).
+
 ## 0.11.0
 
 ### Migrate

package/dist/CombatPresentation.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedPresentationEffects } from "./presentationResolve.js";
+/** Mounts the opt-in combat VFX stack inside the 3D canvas. @internal */
+export declare function CombatPresentation({ effects }: {
+    effects: ResolvedPresentationEffects;
+}): import("react").JSX.Element;

package/dist/CombatPresentation.js

@@ -0,0 +1,8 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CombatCameraShake, ProjectileTracers, WorldFloatText, WorldTelegraphs, } from "./world/WorldHud.js";
+import { WorldSpellVfx } from "./world/WorldVfx.js";
+import { RetainedVfx } from "./world/RetainedVfx.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] }));
+}

package/dist/GameHost.d.ts

@@ -1,5 +1,18 @@
+import { type ComponentType } from "react";
+import type { EditorCatalogDefinition } from "@jgengine/core/editor/types";
 import { type ResolveShellMultiplayerArgs, type ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
+/** Structural shape of the module `GameHost`'s `editor` loader resolves — `import("@jgengine/editor")` satisfies it. */
+export interface EditorSummonModule {
+    EditorApp: ComponentType<{
+        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. */
 export interface GameHostProps {
     playable: PlayableGame;
     gameId?: string;
@@ -8,5 +21,18 @@ export interface GameHostProps {
     multiplayer?: ShellMultiplayer | null;
     /** Tried before the built-in {@link resolveShellMultiplayer}; falls back to it when this returns `null`. */
     resolveMultiplayer?: (args: ResolveShellMultiplayerArgs) => ShellMultiplayer | null;
+    /**
+     * Editor loader — pass `() => import("@jgengine/editor")` and the host owns the whole summon:
+     * `?mode=editor`, the F2+E chord, `window.__jgengineSummonEditor`, the dev save endpoint, and the
+     * lazy `EditorApp` mount (with the playable's `editorLayers`/`editorCatalogs`). The editor package
+     * stays a lazy chunk the game bundles only when this prop is set.
+     */
+    editor?: () => Promise<EditorSummonModule>;
 }
-export declare function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer }: GameHostProps): import("react").JSX.Element;
+/**
+ * The one documented mount: resolves multiplayer for the playable and renders the shell. With the
+ * `editor` loader prop it also owns the whole editor summon (F2+E, `?mode=editor`, dev save endpoint).
+ *
+ * @capability mount-game mount a defined game in the browser — `<GameHost playable={game} editor={() => import("@jgengine/editor")} />`
+ */
+export declare function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor }: GameHostProps): import("react").JSX.Element;

package/dist/GameHost.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from "react";
+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";
@@ -11,13 +13,87 @@ 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.");
 }
-export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer }) {
+/** 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 readUrlParam(EDITOR_MODE_PARAM) === EDITOR_MODE_VALUE;
+}
+/**
+ * The one documented mount: resolves multiplayer for the playable and renders the shell. With the
+ * `editor` loader prop it also owns the whole editor summon (F2+E, `?mode=editor`, dev save endpoint).
+ *
+ * @capability mount-game mount a defined game in the browser — `<GameHost playable={game} editor={() => import("@jgengine/editor")} />`
+ */
+export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor }) {
+    const resolvedGameId = gameId ?? playable.game.name;
+    const [editorOpen, setEditorOpen] = useState(() => initialEditorMode(editor !== undefined));
+    useEffect(() => {
+        if (editor === undefined)
+            return;
+        // 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;
+        const summon = () => setEditorOpen(true);
+        const host = window;
+        host.__jgengineSummonEditor = summon;
+        let f2Held = false;
+        const onKeyDown = (event) => {
+            if (event.code === "F2")
+                f2Held = true;
+            else if (event.code === "KeyE" && f2Held) {
+                event.preventDefault();
+                summon();
+            }
+        };
+        const onKeyUp = (event) => {
+            if (event.code === "F2")
+                f2Held = false;
+        };
+        window.addEventListener("keydown", onKeyDown);
+        window.addEventListener("keyup", onKeyUp);
+        return () => {
+            window.removeEventListener("keydown", onKeyDown);
+            window.removeEventListener("keyup", onKeyUp);
+            if (host.__jgengineSummonEditor === summon)
+                delete host.__jgengineSummonEditor;
+        };
+    }, [editor, editorOpen]);
+    const EditorLazy = useMemo(() => {
+        if (editor === undefined)
+            return null;
+        return lazy(async () => ({ default: (await editor()).EditorApp }));
+    }, [editor]);
     const resolved = useMemo(() => {
         if (multiplayer !== undefined)
             return multiplayer;
         const args = {
             game: playable.game,
-            gameId: gameId ?? playable.game.name,
+            gameId: resolvedGameId,
             url: wsUrl,
             force: wsUrl !== undefined,
         };
@@ -28,6 +104,9 @@ export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultipla
                 warnUndrivenAdapter(kind);
         }
         return session;
-    }, [playable, gameId, wsUrl, multiplayer, resolveMultiplayer]);
+    }, [playable, resolvedGameId, wsUrl, multiplayer, resolveMultiplayer]);
+    if (editorOpen && EditorLazy !== null) {
+        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/GamePlayer.d.ts

@@ -8,4 +8,9 @@ export type GamePlayerProps = {
     loading?: ReactNode;
     multiplayer?: ShellMultiplayer | null;
 };
+/**
+ * Registry-driven lazy loader over {@link GamePlayerShell} for multi-game hosts.
+ * Games mount through `GameHost` — the one documented mount.
+ * @internal
+ */
 export declare function GamePlayer({ gameId, registry, fallbackGameId, loading, multiplayer }: GamePlayerProps): import("react").JSX.Element;

package/dist/GamePlayer.js

@@ -2,6 +2,11 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { GamePlayerShell } from "./GamePlayerShell.js";
 import { resolveGameLoader } from "./registry.js";
+/**
+ * Registry-driven lazy loader over {@link GamePlayerShell} for multi-game hosts.
+ * Games mount through `GameHost` — the one documented mount.
+ * @internal
+ */
 export function GamePlayer({ gameId, registry, fallbackGameId, loading = null, multiplayer = null }) {
     const [playable, setPlayable] = useState(null);
     useEffect(() => {

package/dist/GamePlayerShell.d.ts

@@ -5,6 +5,11 @@ export { applyMotionImpulses } from "@jgengine/core/runtime/motionIntents";
 export { nearbyObstacles } from "@jgengine/core/movement/movementModel";
 export { resolvePhysicsTuning } from "@jgengine/core/movement/playerMovement";
 export { hasEnvironmentTerrain } from "@jgengine/core/world/terrain";
+/**
+ * The shell body `GameHost` renders after resolving multiplayer. Hosts that resolve their own
+ * sessions (the dev runner) render it directly; games mount through `GameHost`.
+ * @internal
+ */
 export declare function GamePlayerShell({ playable, multiplayer: rawMultiplayer, poster, onContextReady, }: {
     playable: PlayableGame;
     multiplayer?: ShellMultiplayer | null;