@jgengine/node 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/assetNaming.d.ts

@@ -0,0 +1,16 @@
+/** File extensions the editor treats as placeable models. */
+export declare const MODEL_EXT: RegExp;
+/**
+ * Derives the stable catalog id a model's workspace-relative path resolves under — lowercased,
+ * extension-stripped, non-alphanumerics collapsed to single hyphens. The folder scan and every
+ * durable import share this so a placement referencing the id resolves regardless of how the
+ * asset entered the catalog.
+ * @internal
+ */
+export declare function assetIdFromRel(rel: string): string;
+/**
+ * Strips path components and unsafe characters from an uploaded model filename, keeping its
+ * `.glb`/`.gltf` extension — so an untrusted upload name can never escape its target folder.
+ * @internal
+ */
+export declare function safeAssetFilename(filename: string): string;

package/dist/assetNaming.js

@@ -0,0 +1,32 @@
+import { extname } from "node:path";
+/** File extensions the editor treats as placeable models. */
+export const MODEL_EXT = /\.(glb|gltf)$/i;
+/**
+ * Derives the stable catalog id a model's workspace-relative path resolves under — lowercased,
+ * extension-stripped, non-alphanumerics collapsed to single hyphens. The folder scan and every
+ * durable import share this so a placement referencing the id resolves regardless of how the
+ * asset entered the catalog.
+ * @internal
+ */
+export function assetIdFromRel(rel) {
+    const cleaned = rel
+        .replace(MODEL_EXT, "")
+        .replace(/[^a-z0-9]+/gi, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+    return cleaned.length > 0 ? cleaned : "asset";
+}
+/**
+ * Strips path components and unsafe characters from an uploaded model filename, keeping its
+ * `.glb`/`.gltf` extension — so an untrusted upload name can never escape its target folder.
+ * @internal
+ */
+export function safeAssetFilename(filename) {
+    const base = (filename.split(/[\\/]/).pop() ?? "").trim();
+    const ext = extname(base).toLowerCase();
+    const stem = base
+        .slice(0, base.length - ext.length)
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "");
+    return (stem.length > 0 ? stem : "asset") + ext;
+}

package/dist/editorHostPlugin.d.ts

@@ -15,6 +15,13 @@ export interface EditorManifest {
  * @internal
  */
 export declare function buildEditorManifest(sceneDir: string, assetsDir: string): EditorManifest;
+/**
+ * Persists an uploaded model into the asset folder so it survives reload and the manifest scan re-lists it
+ * under the same id — the durable counterpart to the standalone editor's ephemeral blob imports. Returns the
+ * manifest entry (id/url/label) the scan would produce for the written file. The pure core `/__jgengine/import-asset` serves.
+ * @internal
+ */
+export declare function importEditorAsset(assetsDir: string, filename: string, bytes: Uint8Array): EditorManifestAsset;
 interface DevServerLike {
     middlewares: {
         use(route: string, handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void): void;
@@ -35,8 +42,9 @@ export interface EditorHostOptions {
 /**
  * Dev-server plugin that turns any folder into a standalone-editor workspace: it serves the folder's
  * `editor.scene.json` and every model under it at `/__jgengine/manifest`, streams the model bytes at
- * `/__jgengine/assets/*`, and writes Save back to `editor.scene.json` — the server half of
- * `jgengine editor`, drop-in for a Vite dev config.
+ * `/__jgengine/assets/*`, persists uploaded models into the asset folder at `POST /__jgengine/import-asset`
+ * (so a dropped GLB survives reload as a durable catalog asset), and writes Save back to `editor.scene.json`
+ * — the server half of `jgengine editor`, drop-in for a Vite dev config.
  * @internal
  */
 export declare function editorHostPlugin(options?: EditorHostOptions): EditorHostPluginShape;

package/dist/editorHostPlugin.js

@@ -1,17 +1,12 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { extname, join, relative, resolve, sep } from "node:path";
+import { MODEL_EXT, assetIdFromRel, safeAssetFilename } from "./assetNaming.js";
 import { EDITOR_SCENE_FILENAME, devSavePlugin } from "./devSavePlugin.js";
-const MODEL_EXT = /\.(glb|gltf)$/i;
+import { importPromotedAsset, isPromotedProject } from "./promotedAssetCatalog.js";
 const ASSET_ROUTE = "/__jgengine/assets/";
 const MANIFEST_ROUTE = "/__jgengine/manifest";
-function assetIdFromRel(rel) {
-    const cleaned = rel
-        .replace(MODEL_EXT, "")
-        .replace(/[^a-z0-9]+/gi, "-")
-        .replace(/^-+|-+$/g, "")
-        .toLowerCase();
-    return cleaned.length > 0 ? cleaned : "asset";
-}
+const IMPORT_ROUTE = "/__jgengine/import-asset";
+const MAX_ASSET_BYTES = 128 * 1024 * 1024;
 function walkModels(root, dir = root) {
     if (!existsSync(dir))
         return [];
@@ -46,11 +41,44 @@ export function buildEditorManifest(sceneDir, assetsDir) {
     });
     return { scene, assets };
 }
+/**
+ * Persists an uploaded model into the asset folder so it survives reload and the manifest scan re-lists it
+ * under the same id — the durable counterpart to the standalone editor's ephemeral blob imports. Returns the
+ * manifest entry (id/url/label) the scan would produce for the written file. The pure core `/__jgengine/import-asset` serves.
+ * @internal
+ */
+export function importEditorAsset(assetsDir, filename, bytes) {
+    if (!MODEL_EXT.test(filename)) {
+        throw new Error(`unsupported asset file (expected .glb/.gltf): ${filename}`);
+    }
+    const safe = safeAssetFilename(filename);
+    mkdirSync(assetsDir, { recursive: true });
+    writeFileSync(join(assetsDir, safe), bytes);
+    return { id: assetIdFromRel(safe), url: ASSET_ROUTE + safe, label: safe };
+}
+function readBodyBuffer(req) {
+    return new Promise((resolvePromise, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_ASSET_BYTES) {
+                reject(new Error("asset upload too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolvePromise(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
 /**
  * Dev-server plugin that turns any folder into a standalone-editor workspace: it serves the folder's
  * `editor.scene.json` and every model under it at `/__jgengine/manifest`, streams the model bytes at
- * `/__jgengine/assets/*`, and writes Save back to `editor.scene.json` — the server half of
- * `jgengine editor`, drop-in for a Vite dev config.
+ * `/__jgengine/assets/*`, persists uploaded models into the asset folder at `POST /__jgengine/import-asset`
+ * (so a dropped GLB survives reload as a durable catalog asset), and writes Save back to `editor.scene.json`
+ * — the server half of `jgengine editor`, drop-in for a Vite dev config.
  * @internal
  */
 export function editorHostPlugin(options = {}) {
@@ -70,6 +98,46 @@ export function editorHostPlugin(options = {}) {
                 res.setHeader("content-type", "application/json");
                 res.end(JSON.stringify(buildEditorManifest(dir, assetsDir)));
             });
+            server.middlewares.use(IMPORT_ROUTE, (req, res, next) => {
+                if (req.method !== "POST") {
+                    next();
+                    return;
+                }
+                const header = req.headers["x-jg-filename"];
+                const rawName = Array.isArray(header) ? header[0] : header;
+                void readBodyBuffer(req)
+                    .then((bytes) => {
+                    let filename;
+                    try {
+                        filename = decodeURIComponent(rawName ?? "");
+                    }
+                    catch {
+                        filename = rawName ?? "";
+                    }
+                    let asset;
+                    if (isPromotedProject(dir)) {
+                        // Promoted projects resolve assets through a typed `src/game/assets.ts` catalog, so
+                        // persist a durable `extras` entry there. A thrown transform error (unparseable or
+                        // multi-call source) falls back to the folder-scan import, preserving the contract.
+                        try {
+                            asset = importPromotedAsset(dir, filename, bytes);
+                        }
+                        catch {
+                            asset = importEditorAsset(assetsDir, filename, bytes);
+                        }
+                    }
+                    else {
+                        asset = importEditorAsset(assetsDir, filename, bytes);
+                    }
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify(asset));
+                })
+                    .catch((error) => {
+                    res.statusCode = 400;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+                });
+            });
             server.middlewares.use(ASSET_ROUTE, (req, res, next) => {
                 const rel = decodeURIComponent((req.url ?? "").split("?")[0]).replace(/^\/+/, "");
                 const full = resolve(assetsDir, rel);

package/dist/promotedAssetCatalog.d.ts

@@ -0,0 +1,40 @@
+import type { EditorManifestAsset } from "./editorHostPlugin.js";
+/**
+ * A durable catalog entry the editor writes into a promoted game's `src/game/assets.ts` — the
+ * `extras` literal `buildCatalog` consumes. Mirrors `@jgengine/assets`' `CatalogExtra`, but `label`
+ * is required here because the source literal always carries a human-facing name.
+ * @internal
+ */
+export interface PromotedExtra {
+    id: string;
+    url: string;
+    label: string;
+}
+/**
+ * True when `dir` is an already-promoted game project: one whose assets resolve through a typed
+ * `src/game/assets.ts` catalog rather than a scanned model folder.
+ * @internal
+ */
+export declare function isPromotedProject(dir: string): boolean;
+/**
+ * Adds or replaces one `extras` entry in a promoted game's `src/game/assets.ts` and returns the
+ * rewritten text. PURE and deterministic — it does not touch the filesystem.
+ *
+ * A bounded, non-AST transform: it locates the single `buildCatalog({ ... })` call by brace-depth
+ * scan, then upserts an id-keyed entry into that call's `extras: [ ... ]` array (creating the array
+ * when absent, collapsing it back to no `extras` when it would become empty). Re-import of the same
+ * id replaces its entry in place, so the transform is idempotent and never duplicates an id. If the
+ * source has zero or more than one `buildCatalog(` call it THROWS, so the caller falls back to the
+ * legacy folder-scan import rather than risk corrupting the file.
+ * @internal
+ */
+export declare function upsertCatalogExtra(source: string, extra: PromotedExtra): string;
+/**
+ * Persists an imported model into a promoted game's `public/` and registers a durable `extras`
+ * entry in its `src/game/assets.ts`, so the shipped game resolves the asset through its typed
+ * catalog. Copies the bytes under `public/<basePath>/imported/<safe>` and rewrites the catalog
+ * source via {@link upsertCatalogExtra}. Returns the same `{ id, url, label }` shape the folder-scan
+ * `importEditorAsset` returns — but the url is the shipped `public/` path, not the dev asset route.
+ * @internal
+ */
+export declare function importPromotedAsset(dir: string, filename: string, bytes: Uint8Array): EditorManifestAsset;

package/dist/promotedAssetCatalog.js

@@ -0,0 +1,176 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MODEL_EXT, assetIdFromRel, safeAssetFilename } from "./assetNaming.js";
+/**
+ * True when `dir` is an already-promoted game project: one whose assets resolve through a typed
+ * `src/game/assets.ts` catalog rather than a scanned model folder.
+ * @internal
+ */
+export function isPromotedProject(dir) {
+    return existsSync(join(dir, "src", "game", "assets.ts"));
+}
+/** Scans forward from `open` (index of `{` or `[`) to its matching close, respecting string literals. */
+function matchBracketSpan(source, open) {
+    const openCh = source[open];
+    const closeCh = openCh === "{" ? "}" : "]";
+    let depth = 0;
+    let quote = null;
+    for (let i = open; i < source.length; i++) {
+        const ch = source[i];
+        if (quote !== null) {
+            if (ch === "\\") {
+                i++;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === openCh)
+            depth++;
+        else if (ch === closeCh) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    throw new Error("promotedAssetCatalog: unbalanced brackets in assets.ts");
+}
+/** Serializes one extras entry as a `{ id, url, label }` object literal with stable key order. */
+function serializeEntry(extra) {
+    return `{ id: ${JSON.stringify(extra.id)}, url: ${JSON.stringify(extra.url)}, label: ${JSON.stringify(extra.label)} }`;
+}
+/**
+ * Adds or replaces one `extras` entry in a promoted game's `src/game/assets.ts` and returns the
+ * rewritten text. PURE and deterministic — it does not touch the filesystem.
+ *
+ * A bounded, non-AST transform: it locates the single `buildCatalog({ ... })` call by brace-depth
+ * scan, then upserts an id-keyed entry into that call's `extras: [ ... ]` array (creating the array
+ * when absent, collapsing it back to no `extras` when it would become empty). Re-import of the same
+ * id replaces its entry in place, so the transform is idempotent and never duplicates an id. If the
+ * source has zero or more than one `buildCatalog(` call it THROWS, so the caller falls back to the
+ * legacy folder-scan import rather than risk corrupting the file.
+ * @internal
+ */
+export function upsertCatalogExtra(source, extra) {
+    const callRe = /\bbuildCatalog\(\s*\{/g;
+    const matches = [...source.matchAll(callRe)];
+    if (matches.length !== 1) {
+        throw new Error(`promotedAssetCatalog: expected exactly one buildCatalog({...}) call, found ${matches.length}`);
+    }
+    const match = matches[0];
+    // Brace of the options object literal is the last char of the matched `buildCatalog(\s*{`.
+    const objOpen = match.index + match[0].length - 1;
+    const objClose = matchBracketSpan(source, objOpen);
+    const objBody = source.slice(objOpen, objClose + 1);
+    // Detect indentation of the object's first inner line to keep emitted code consistent.
+    const indentMatch = /\{\s*\n(\s+)\S/.exec(objBody);
+    const indent = indentMatch ? indentMatch[1] : "  ";
+    const extrasRe = /\bextras\s*:\s*\[/;
+    const extrasMatch = extrasRe.exec(objBody);
+    const entries = new Map();
+    if (extrasMatch) {
+        const arrOpenInObj = objBody.indexOf("[", extrasMatch.index);
+        const arrCloseInObj = matchBracketSpan(objBody, arrOpenInObj);
+        const arrInner = objBody.slice(arrOpenInObj + 1, arrCloseInObj);
+        // Parse each `{ ... }` object literal in the array via brace-depth scan + JSON.parse.
+        let cursor = 0;
+        while (cursor < arrInner.length) {
+            const braceOpen = arrInner.indexOf("{", cursor);
+            if (braceOpen === -1)
+                break;
+            const braceClose = matchBracketSpan(arrInner, braceOpen);
+            const literal = arrInner.slice(braceOpen, braceClose + 1);
+            const parsed = parseEntryLiteral(literal);
+            entries.set(parsed.id, parsed);
+            cursor = braceClose + 1;
+        }
+        entries.set(extra.id, extra);
+        const arrOpenAbs = objOpen + arrOpenInObj;
+        const arrCloseAbs = objOpen + arrCloseInObj;
+        // Collapse an emptied array back to no `extras` for clean reversibility. Unreachable via a plain
+        // import (we just added an entry), but keeps the transform's remove-symmetry intact.
+        if (entries.size === 0) {
+            return spliceOutExtras(source, objOpen + extrasMatch.index, arrCloseAbs);
+        }
+        const serialized = serializeArray([...entries.values()], indent);
+        return source.slice(0, arrOpenAbs) + serialized + source.slice(arrCloseAbs + 1);
+    }
+    // No extras yet: splice a fresh `extras: [ <entry> ],` right after the opening `{`.
+    entries.set(extra.id, extra);
+    const serialized = serializeArray([...entries.values()], indent);
+    const insertAt = objOpen + 1;
+    const insertion = `\n${indent}extras: ${serialized},`;
+    return source.slice(0, insertAt) + insertion + source.slice(insertAt);
+}
+/** Removes an `extras: [...]` declaration (and a trailing comma) so the object reverts cleanly. */
+function spliceOutExtras(source, declStartAbs, arrCloseAbs) {
+    let declEndAbs = arrCloseAbs + 1;
+    // Swallow a trailing comma after `]`.
+    if (source[declEndAbs] === ",")
+        declEndAbs++;
+    // Swallow leading whitespace/newline before the declaration.
+    let start = declStartAbs;
+    while (start > 0 && /[ \t]/.test(source[start - 1]))
+        start--;
+    if (source[start - 1] === "\n")
+        start--;
+    return source.slice(0, start) + source.slice(declEndAbs);
+}
+/** Serializes an extras array literal with one entry per indented line. */
+function serializeArray(entries, indent) {
+    if (entries.length === 0)
+        return "[]";
+    const inner = entries.map((e) => `${indent}  ${serializeEntry(e)},`).join("\n");
+    return `[\n${inner}\n${indent}]`;
+}
+/** Parses a `{ id, url, label }` object literal (unquoted keys) into a PromotedExtra via JSON. */
+function parseEntryLiteral(literal) {
+    // Quote bare identifier keys so JSON.parse accepts the source-literal form.
+    const jsonish = literal.replace(/([{,]\s*)([A-Za-z_$][\w$]*)(\s*:)/g, '$1"$2"$3');
+    const obj = JSON.parse(jsonish);
+    if (typeof obj.id !== "string" || typeof obj.url !== "string") {
+        throw new Error("promotedAssetCatalog: malformed extras entry");
+    }
+    return {
+        id: obj.id,
+        url: obj.url,
+        label: typeof obj.label === "string" ? obj.label : obj.id,
+    };
+}
+/** Reads the `basePath` string literal from a promoted `assets.ts`, defaulting to `/models`. */
+function readBasePath(source) {
+    const m = /\bbasePath\s*:\s*["'`]([^"'`]+)["'`]/.exec(source);
+    return m ? m[1] : "/models";
+}
+/**
+ * Persists an imported model into a promoted game's `public/` and registers a durable `extras`
+ * entry in its `src/game/assets.ts`, so the shipped game resolves the asset through its typed
+ * catalog. Copies the bytes under `public/<basePath>/imported/<safe>` and rewrites the catalog
+ * source via {@link upsertCatalogExtra}. Returns the same `{ id, url, label }` shape the folder-scan
+ * `importEditorAsset` returns — but the url is the shipped `public/` path, not the dev asset route.
+ * @internal
+ */
+export function importPromotedAsset(dir, filename, bytes) {
+    if (!MODEL_EXT.test(filename)) {
+        throw new Error(`unsupported asset file (expected .glb/.gltf): ${filename}`);
+    }
+    const assetsTsPath = join(dir, "src", "game", "assets.ts");
+    const source = readFileSync(assetsTsPath, "utf8");
+    const basePath = readBasePath(source);
+    const safe = safeAssetFilename(filename);
+    const publicSub = basePath.replace(/^\/+/, "");
+    const targetDir = join(dir, "public", publicSub, "imported");
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, safe), bytes);
+    const url = `${basePath.replace(/\/+$/, "")}/imported/${safe}`;
+    const id = assetIdFromRel(safe);
+    const label = safe;
+    const rewritten = upsertCatalogExtra(source, { id, url, label });
+    writeFileSync(assetsTsPath, rewritten);
+    return { id, url, label };
+}

package/dist/worldServer.d.ts

@@ -1,5 +1,5 @@
 import type { GameDefinition } from "@jgengine/core/game/defineGame";
-import type { GameContextContent } from "@jgengine/core/runtime/gameContext";
+import type { GameContextContent, GameContextModels } from "@jgengine/core/runtime/gameContext";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
 import { type WorldGameHost } from "@jgengine/ws/worldHost";
 import { type WorldPersistence } from "./persistence.js";
@@ -8,6 +8,8 @@ import { type GameWsServer, type GameWsServerOptions } from "./wsServer.js";
 export interface HostedGameDefinition {
     game: GameDefinition<ModelAssetRef, unknown>;
     content: GameContextContent;
+    /** Render-model lookup for collider auto-fit — pass the same lookup the shell derives (`contextModels(playable)`) so the authoritative host resolves the hitboxes clients see. */
+    models?: GameContextModels;
 }
 /** Config for {@link createWorldGameServer}: how to resolve a game by id, the tick cadence, and the underlying ws-server/router options (minus `host`, which the server builds). */
 export interface WorldGameServerOptions extends Omit<GameWsServerOptions, "host"> {

package/dist/worldServer.js

@@ -19,6 +19,7 @@ export function createWorldGameServer(options) {
                 content: resolved.content,
                 now: clock,
                 store: persistence.store({ gameId, serverId }),
+                ...(resolved.models === undefined ? {} : { models: resolved.models }),
             });
             liveSessions.set(serverId, session);
             return session;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/node",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Standalone authoritative game host for JGengine: in-memory server snapshots, tick loop, save-cadence flush, WebSocket server, memory/file persistence.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,11 +31,12 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.11.0",
-    "@jgengine/ws": "^0.11.0",
+    "@jgengine/core": "^0.13.0",
+    "@jgengine/ws": "^0.13.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@jgengine/assets": "workspace:*",
     "@jgengine/sql": "workspace:*",
     "@types/node": "^24",
     "@types/ws": "^8",

package/skills/jgengine/SKILL.md

@@ -9,16 +9,16 @@ Read the repository [README](../../../README.md) for package truth, commands, la
 
 ## 1. Establish the target
 
-Capture only decisions that change architecture:
+Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
 
 - player point of view and controls
 - world shape and authored content
 - core loop, interaction, combat, and progression
 - solo, local, hosted, or persistent multiplayer
-- HUD/menu states and art direction
+- HUD/menu states and **custom** UI art direction (every game owns its presentation — no stock drop-in face)
 - one observable completion scenario
 
-For a new in-repo game, scaffold with `bun run new:game <id> --name "Title"`. Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
 ## 2. Select domains
 
@@ -26,6 +26,8 @@ Load only rows the target needs. Do not preload every domain.
 
 | Need | Skill | Owner |
 | --- | --- | --- |
+| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
 | scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
 | runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
 | game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
@@ -34,15 +36,17 @@ Load only rows the target needs. Do not preload every domain.
 | models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
 | authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
 
-Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
 
 ## 3. Discover before designing
 
 Within each selected domain:
 
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
 1. Search `capabilities.md` by intent; it maps needs to imports.
 2. Open `api.md` only when exact signatures or export inventory are needed.
 3. Open the linked reference only for a deeper recipe or trap.
+4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
 
 If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.