@jgengine/shell 0.12.0 → 0.14.0

package/dist/render/useModelAnimation.js

@@ -0,0 +1,198 @@
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
+import { resolveOneShotClip } from "@jgengine/core/game/modelAnimation";
+import { useGameContext } from "@jgengine/react/provider";
+/**
+ * The engine's model animation driver as a standalone hook — the same mixer `EntityModel` runs,
+ * for games that render a cloned scene themselves (custom materials, procedural composition).
+ * Handles `"auto"` derivation from the GLB's clip names, speed-driven idle/walk/run crossfades
+ * read from the entity's live position when `instanceId` is set, one-shots fired from
+ * `entity.animation` / `combat.hitReaction` / `entity.died`, held poses, and the death clamp.
+ */
+export function useModelAnimation(scene, clips, animationInput, instanceId) {
+    const ctx = useGameContext();
+    // "auto" (stamped by catalog resolution, or set inline) derives states/one-shots from the
+    // loaded GLB's actual clip names; "none" and absent render the bind pose.
+    const animation = useMemo(() => resolveAnimationConfig(animationInput, clips.map((clip) => clip.name)), [animationInput, clips]);
+    const mixerRef = useRef(null);
+    const animationPausedRef = useRef(false);
+    const stateActionsRef = useRef(null);
+    const states = animation?.states;
+    const oneShots = animation?.oneShots;
+    const oneShotPlayRef = useRef(null);
+    const activeOneShotRef = useRef(null);
+    useEffect(() => {
+        if (animation === undefined || clips.length === 0) {
+            mixerRef.current = null;
+            stateActionsRef.current = null;
+            return;
+        }
+        const mixer = new THREE.AnimationMixer(scene);
+        if (states !== undefined) {
+            const clipFor = (name) => THREE.AnimationClip.findByName(clips, name) ?? clips[0];
+            const actions = {
+                idle: mixer.clipAction(clipFor(states.idle)),
+                walk: mixer.clipAction(clipFor(states.walk)),
+                ...(states.run === undefined ? {} : { run: mixer.clipAction(clipFor(states.run)) }),
+            };
+            for (const action of Object.values(actions)) {
+                action.setLoop(THREE.LoopRepeat, Infinity);
+                action.timeScale = animation.timeScale ?? 1;
+                action.enabled = true;
+            }
+            actions.idle.play();
+            mixer.update(0);
+            mixerRef.current = mixer;
+            stateActionsRef.current = { actions, active: "idle", lastPos: null, smoothedSpeed: 0 };
+            animationPausedRef.current = false;
+            let onOneShotFinished = null;
+            if (oneShots !== undefined) {
+                const clipNames = new Set();
+                for (const spec of Object.values(oneShots)) {
+                    if (typeof spec === "string")
+                        clipNames.add(spec);
+                    else
+                        for (const name of spec)
+                            clipNames.add(name);
+                }
+                const oneShotActions = new Map();
+                for (const name of clipNames) {
+                    const found = THREE.AnimationClip.findByName(clips, name);
+                    if (found === null)
+                        continue;
+                    const oneShotAction = mixer.clipAction(found);
+                    oneShotAction.setLoop(THREE.LoopOnce, 1);
+                    oneShotAction.enabled = true;
+                    oneShotActions.set(name, oneShotAction);
+                }
+                onOneShotFinished = ({ action }) => {
+                    const active = activeOneShotRef.current;
+                    if (active === null || action !== active.action || active.isDeath)
+                        return;
+                    const machine = stateActionsRef.current;
+                    const back = machine?.actions[machine.active];
+                    action.fadeOut(0.15);
+                    if (back !== undefined)
+                        back.reset().fadeIn(0.15).play();
+                    activeOneShotRef.current = null;
+                };
+                mixer.addEventListener("finished", onOneShotFinished);
+                oneShotPlayRef.current = (event) => {
+                    const active = activeOneShotRef.current;
+                    if (active !== null && active.isDeath)
+                        return;
+                    const clipName = resolveOneShotClip(oneShots, event, Math.random());
+                    if (clipName === null)
+                        return;
+                    const oneShotAction = oneShotActions.get(clipName);
+                    if (oneShotAction === undefined)
+                        return;
+                    const machine = stateActionsRef.current;
+                    machine?.actions[machine.active]?.fadeOut(0.1);
+                    if (active !== null && active.action !== oneShotAction)
+                        active.action.stop();
+                    oneShotAction.clampWhenFinished = event === "death";
+                    oneShotAction.reset().fadeIn(0.1).play();
+                    activeOneShotRef.current = { action: oneShotAction, isDeath: event === "death" };
+                };
+            }
+            return () => {
+                if (onOneShotFinished !== null)
+                    mixer.removeEventListener("finished", onOneShotFinished);
+                oneShotPlayRef.current = null;
+                activeOneShotRef.current = null;
+                mixer.stopAllAction();
+                mixerRef.current = null;
+                stateActionsRef.current = null;
+            };
+        }
+        const clip = (animation.clip !== undefined ? THREE.AnimationClip.findByName(clips, animation.clip) : undefined) ??
+            clips[0];
+        const action = mixer.clipAction(clip);
+        action.setLoop(animation.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Infinity);
+        action.clampWhenFinished = animation.loop === false;
+        action.timeScale = animation.timeScale ?? 1;
+        action.enabled = true;
+        action.paused = animation.paused === true;
+        action.play();
+        if (animation.time !== undefined)
+            action.time = animation.time;
+        mixer.update(0);
+        mixerRef.current = mixer;
+        animationPausedRef.current = animation.paused === true;
+        return () => {
+            mixer.stopAllAction();
+            mixerRef.current = null;
+        };
+    }, [
+        scene,
+        clips,
+        animation?.clip,
+        animation?.loop,
+        animation?.timeScale,
+        animation?.paused,
+        animation?.time,
+        states,
+        oneShots,
+    ]);
+    useEffect(() => {
+        if (instanceId === undefined || oneShots === undefined)
+            return;
+        const fire = (event) => oneShotPlayRef.current?.(event);
+        const offAnimation = ctx.game.events.on("entity.animation", (event) => {
+            if (event.instanceId === instanceId)
+                fire(event.event);
+        });
+        const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
+            if (event.instanceId === instanceId)
+                fire("hit");
+        });
+        const offDied = ctx.game.events.on("entity.died", (event) => {
+            if (event.instanceId === instanceId)
+                fire("death");
+        });
+        return () => {
+            offAnimation();
+            offHit();
+            offDied();
+        };
+    }, [ctx, instanceId, oneShots]);
+    useFrame((_state, delta) => {
+        const stateMachine = stateActionsRef.current;
+        if (stateMachine !== null && states !== undefined && instanceId !== undefined && delta > 0) {
+            const entity = ctx.scene.entity.get(instanceId);
+            if (entity !== null) {
+                const [x, , z] = entity.position;
+                if (stateMachine.lastPos !== null) {
+                    const instantSpeed = Math.hypot(x - stateMachine.lastPos[0], z - stateMachine.lastPos[2]) / delta;
+                    stateMachine.smoothedSpeed +=
+                        (instantSpeed - stateMachine.smoothedSpeed) * Math.min(1, delta * 12);
+                }
+                stateMachine.lastPos = [x, entity.position[1], z];
+                const walkSpeed = states.walkSpeed ?? 0.5;
+                const runSpeed = states.runSpeed ?? 6;
+                const next = stateMachine.smoothedSpeed < walkSpeed
+                    ? "idle"
+                    : stateMachine.actions.run !== undefined && stateMachine.smoothedSpeed >= runSpeed
+                        ? "run"
+                        : "walk";
+                if (next !== stateMachine.active) {
+                    if (activeOneShotRef.current === null) {
+                        const fade = states.fadeSec ?? 0.2;
+                        const from = stateMachine.actions[stateMachine.active];
+                        const to = stateMachine.actions[next];
+                        if (from !== undefined && to !== undefined) {
+                            to.reset().fadeIn(fade).play();
+                            from.fadeOut(fade);
+                        }
+                    }
+                    stateMachine.active = next;
+                }
+            }
+        }
+        if (mixerRef.current !== null && !animationPausedRef.current)
+            mixerRef.current.update(delta);
+    });
+}

package/dist/structures/GeneratedBuilding.d.ts

@@ -43,6 +43,10 @@ export interface GeneratedBuildingProps {
 export interface InstancedBuildingPlacement {
     building: GeneratedBuildingData;
     position?: readonly [number, number, number];
+    /** Building yaw (radians) applied to the whole massing about `pivot` — street-aware facing. */
+    rotationY?: number;
+    /** World XZ the `rotationY` turns about (the building center); defaults to the world origin. */
+    pivot?: readonly [number, number];
 }
 export interface InstancedBuildingsProps {
     buildings: readonly InstancedBuildingPlacement[];

package/dist/structures/GeneratedBuilding.js

@@ -70,25 +70,35 @@ function bucketPartMatrices(buildings, visible) {
     const buckets = new Map();
     for (const placement of buildings) {
         const [ox, oy, oz] = placement.position ?? [0, 0, 0];
+        // Building yaw turns the whole massing about its center. Engine Y-rotation convention (matches
+        // dummy.rotation.y below): a local vector (x, z) maps to (x·cos + z·sin, −x·sin + z·cos).
+        const yaw = placement.rotationY ?? 0;
+        const [px0, pz0] = placement.pivot ?? [0, 0];
+        const cos = Math.cos(yaw);
+        const sin = Math.sin(yaw);
         for (const part of placement.building.parts) {
             if (visible !== null && !visible.has(part.kind))
                 continue;
             const [nx, nz] = normalFor(part.facade);
             const offset = outwardOffset(part);
-            const px = ox + part.position[0] + nx * offset;
+            // Local offset from the pivot (part position + facade-normal nudge), then rotated by the yaw.
+            const lx = part.position[0] - px0 + nx * offset;
+            const lz = part.position[2] - pz0 + nz * offset;
+            const px = ox + px0 + lx * cos + lz * sin;
             const py = oy + part.position[1];
-            const pz = oz + part.position[2] + nz * offset;
+            const pz = oz + pz0 - lx * sin + lz * cos;
+            const partYaw = part.rotationY + yaw;
             let bucket = buckets.get(part.kind);
             if (bucket === undefined) {
                 bucket = [];
                 buckets.set(part.kind, bucket);
             }
             if (part.kind === "clothesline") {
-                const sin = Math.sin(part.rotationY);
-                const cos = Math.cos(part.rotationY);
+                const rowSin = Math.sin(partYaw);
+                const rowCos = Math.cos(partYaw);
                 for (const row of CLOTHESLINE_ROW_OFFSETS) {
-                    dummy.position.set(px + row * sin, py, pz + row * cos);
-                    dummy.rotation.set(0, part.rotationY, 0);
+                    dummy.position.set(px + row * rowSin, py, pz + row * rowCos);
+                    dummy.rotation.set(0, partYaw, 0);
                     dummy.scale.set(part.scale[0], Math.max(part.scale[1], 0.025), 0.025);
                     dummy.updateMatrix();
                     bucket.push(dummy.matrix.clone());
@@ -96,7 +106,7 @@ function bucketPartMatrices(buildings, visible) {
                 continue;
             }
             dummy.position.set(px, py, pz);
-            dummy.rotation.set(0, part.rotationY, 0);
+            dummy.rotation.set(0, partYaw, 0);
             dummy.scale.set(part.scale[0], part.scale[1], part.scale[2]);
             dummy.updateMatrix();
             bucket.push(dummy.matrix.clone());

package/dist/world/WorldHud.d.ts

@@ -23,6 +23,8 @@ export interface WorldNameplatesProps {
     maxDistance?: number;
     /** Minimum ms between position/health refreshes — trades smoothness for fewer re-renders at scale. Default 120. */
     tickMs?: number;
+    /** Draw the built-in HP bar under the name. Set `false` for a name-only plate when the game already draws its own health bar (its own HUD, or `worldHealthBars`). Default true. */
+    showHealth?: boolean;
     className?: string;
     nameplateClassName?: string;
     nameClassName?: string;
@@ -39,7 +41,7 @@ export interface WorldNameplatesProps {
  *
  * @capability nameplates billboarded name + HP bar over nearby entities
  */
-export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, tickMs, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
+export declare function WorldNameplates({ statId, height, roles, resolveRole, maxDistance, tickMs, showHealth, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): import("react").JSX.Element;
 /** Props for {@link WorldObjectHighlights}. */
 export interface WorldObjectHighlightsProps {
     /** Ring tint. Default a construction-select amber. */

package/dist/world/WorldHud.js

@@ -50,7 +50,7 @@ export function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxD
  *
  * @capability nameplates billboarded name + HP bar over nearby entities
  */
-export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, tickMs = 120, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
+export function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, tickMs = 120, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }) {
     const ctx = useGameContext();
     const camera = useThree((state) => state.camera);
     const size = useThree((state) => state.size);
@@ -83,7 +83,7 @@ export function WorldNameplates({ statId = "health", height = 2.3, roles, resolv
                             color: "#f1f5f9",
                             textShadow: "0 1px 3px rgba(0,0,0,0.9)",
                             whiteSpace: "nowrap",
-                        }, children: sample.name }), sample.percent !== null ? (_jsx("span", { className: barClassName, "data-nameplate-bar": true, style: {
+                        }, children: sample.name }), showHealth && sample.percent !== null ? (_jsx("span", { className: barClassName, "data-nameplate-bar": true, style: {
                             display: "block",
                             width: 78,
                             height: 6,

package/dist/world/WorldScene.js

@@ -9,6 +9,7 @@ import { useGameContext } from "@jgengine/react/provider";
 import { useSceneEntityIds, useSceneObjectIds, useGameStore, usePlayer, useTarget } from "@jgengine/react/hooks";
 import { colorFromId } from "../worldSky.js";
 import { DefaultSurface, detailMaps } from "../render/defaultSurface.js";
+import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
 import { resolveModel, resolveEntityModel, tryResolveCatalogModel } from "../render/resolveModel.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
@@ -41,7 +42,7 @@ function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, select
             const live = ctx.scene.entity.get(entityId);
             if (live !== null)
                 onSelect(live);
-        }, children: [selected ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [0.8, 0.95, 32] }), _jsx("meshBasicMaterial", { color: "#34d399", transparent: true, opacity: 0.9 })] })) : null, custom !== undefined && custom !== null ? (custom) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: entityId, fallback: sprite !== undefined ? _jsx(EntitySprite, { sprite: sprite }) : undefined })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, castShadow: true, receiveShadow: true, children: [_jsx("sphereGeometry", { args: [0.45, 24, 24] }), _jsx(DefaultSurface, { color: color })] })) : (_jsxs("group", { scale: ctx.scene.entity.visualScaleOf(entityId), children: [_jsxs("mesh", { "position-y": 0.95, castShadow: true, receiveShadow: true, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx(DefaultSurface, { color: color, roughness: 0.6 })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
+        }, children: [selected ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [0.8, 0.95, 32] }), _jsx("meshBasicMaterial", { color: "#34d399", transparent: true, opacity: 0.9 })] })) : null, custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "entity", measureKey: name, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: entityId, measure: { target: "entity", key: name }, fallback: sprite !== undefined ? _jsx(EntitySprite, { sprite: sprite }) : undefined })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, castShadow: true, receiveShadow: true, children: [_jsx("sphereGeometry", { args: [0.45, 24, 24] }), _jsx(DefaultSurface, { color: color })] })) : (_jsxs("group", { scale: ctx.scene.entity.visualScaleOf(entityId), children: [_jsxs("mesh", { "position-y": 0.95, castShadow: true, receiveShadow: true, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx(DefaultSurface, { color: color, roughness: 0.6 })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
 }
 function ObjectMarker({ object, custom, model, style, }) {
     const groupRef = useRef(null);
@@ -61,7 +62,7 @@ function ObjectMarker({ object, custom, model, style, }) {
         writeEntityPose(group, live);
         group.visible = visibleRef.current(instanceId);
     });
-    return (_jsx("group", { ref: groupRef, userData: { [POINTER_OBJECT_KEY]: instanceId }, children: custom !== undefined && custom !== null ? (custom) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: instanceId })) : style?.hidden === true ? null : (_jsxs("mesh", { "position-y": 0.5 * scaleY, scale: [scaleX, scaleY, scaleZ], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx(DefaultSurface, { color: color, transparent: opacity < 1, opacity: opacity })] })) }));
+    return (_jsx("group", { ref: groupRef, userData: { [POINTER_OBJECT_KEY]: instanceId }, children: custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "object", measureKey: object.catalogId, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: instanceId, measure: { target: "object", key: object.catalogId } })) : style?.hidden === true ? null : (_jsxs("mesh", { "position-y": 0.5 * scaleY, scale: [scaleX, scaleY, scaleZ], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx(DefaultSurface, { color: color, transparent: opacity < 1, opacity: opacity })] })) }));
 }
 function GroundPlane() {
     const geometry = useMemo(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.12.0",
-    "@jgengine/react": "^0.12.0",
-    "@jgengine/ws": "^0.12.0"
+    "@jgengine/core": "^0.14.0",
+    "@jgengine/react": "^0.14.0",
+    "@jgengine/ws": "^0.14.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/SKILL.md

@@ -5,7 +5,7 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
 
 ## 1. Establish the target
 
@@ -20,6 +20,8 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 
 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/*`.
 
+For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -42,7 +44,8 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-1. Search `capabilities.md` by intent; it maps needs to imports.
+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. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
 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.

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -38,7 +38,7 @@
 - `WorldFeature` (type): type WorldFeature = | PlaceWorldFeature | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape passed to `defineGame`. The preferred model is the place feature from `world()` (`@jgengine/core/world/place`): substrate + laws, with all dressing authored in the editor. The remaining members — biomes, voxel grid, plots, tilemap, environment, flat — are the legacy code-declared shapes kept for existing games.
 - `auditManifest` (function): function auditManifest(manifest: SceneOwnershipManifest): OwnershipDiagnostic[] — Audit every declaration in a manifest, keying diagnostics by each object's provenance id. An empty result means the manifest declares all of its content cleanly — every object is authored, generated, bakeable, or a reasoned runtime/transient object.
 - `biomes` (function): function biomes(config: BiomesWorldConfig): WorldFeature — Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain.
-- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style.
+- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`.
 - `classifyOwnership` (function): function classifyOwnership(declaration: SceneOwnershipDeclaration): OwnershipVerdict — Resolve one declaration into a single boundary verdict.
 - `collectOwnershipDiagnostics` (function): function collectOwnershipDiagnostics(entries: Iterable<readonly [string, SceneOwnershipDeclaration]>): OwnershipDiagnostic[] — Audit a keyed set of declarations and return one diagnostic per object that breaks the boundary contract (a `reject` verdict carrying a `violation`). Deterministic: diagnostics come back in the iteration order of `entries`.
 - `contextVerb` (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb — Builds a {@link ContextVerb} for a right-click menu entry.
@@ -209,11 +209,18 @@
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
+## @jgengine/core/devtools/urlFlags
+
+- `readUrlFlag` (function): function readUrlFlag(param: string): boolean — True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`).
+- `readUrlParam` (function): function readUrlParam(param: string): string | null — The current query value of `param`, or null when absent (or no DOM).
+- `subscribeUrlChange` (function): function subscribeUrlChange(listener: () => void): () => void — Fires `listener` whenever the query string may have changed out from under a flag — browser back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+- `writeUrlParam` (function): function writeUrlParam(param: string, value: string | null): void — Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with `history.replaceState` so the rest of the query and the hash survive and no history entry is pushed. No-ops without a DOM, and skips the write when the URL already matches.
+
 ## @jgengine/core/meta/changelog
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -276,7 +283,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 - `createGameContext` (function): function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext — ⚠ undocumented
 
@@ -307,7 +314,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 
 ## @jgengine/core/runtime/gameRuntime
@@ -322,6 +329,7 @@
 
 ## @jgengine/core/runtime/headlessRunner
 
+- `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
 - `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — ⚠ undocumented

package/skills/jgengine-ui/SKILL.md

@@ -14,9 +14,9 @@ Search [capabilities.md](capabilities.md), use [api.md](api.md) for signatures,
 ## Canonical workflow
 
 1. Write the game's UI art direction first (see [reference.md](reference.md) §1) — fantasy, shape/material language, hierarchy, forbidden patterns. Stock glass widgets are not a stand-in for this step.
-2. Define the real UI states: attract/menu, live play, pause, results, empty/error, and relevant overlays.
+2. Define the real UI states: attract, main menu (the game's front-end), character create/select where relevant, live play, pause, settings, credits, results, empty/error, and relevant overlays.
 3. Read state through selectors/hooks; keep simulation mutation behind commands.
-4. Compose custom markup for this game. Prefer headless data + game-owned chrome. When a second presentation is plausible, split data / renderer / chrome (minimap stack example: `useLiveMarkers` → track/renderer → game frame; see reference §6).
+4. Compose this game's UI, reaching first for the shipped building blocks — `InventoryGrid`, `usePanels`/`PanelHost`/`Window`, `CharacterSheet`/`Paperdoll`, and the action/selection bars — and composing + reskinning them; only hand-roll custom markup where no building block fits. Toggleable windows (bag `B`, character `C`, etc.) come from `usePanels`, not hand-rolled open/close state — and `PanelHost` already stacks windows above the HUD (`zIndexBase`) and wires hotkeys/ESC, so never hand-roll a `z-*` or keydown listener for them. A live 3D character-screen portrait is `EntityPreview` (`@jgengine/shell/render/EntityPreview`): it owns the nested `<Canvas>`, the `GameContextBridge` across the R3F boundary, and the `StudioStage` lighting — pass the game's own `renderEntity` as children (or a native `model`+`instanceId`) and it mirrors the live entity; don't re-derive the context bridge by hand. Prefer headless data + game-owned chrome. When a second presentation is plausible, split data / renderer / chrome (minimap stack example: `useLiveMarkers` → track/renderer → game frame; see reference §6).
 5. Make keyboard, pointer, touch, controller, focus, and screen-reader behavior explicit.
 6. Add preview fixtures using the real components for fast deterministic capture.
 7. Verify desktop and mobile layouts through `jgengine-verify`. A HUD that could pass for another game's default chrome fails visual review.
@@ -28,8 +28,12 @@ Existing React games keep their entity store and use the focused
 ## Product rules
 
 - **Every game owns its UI end-to-end.** Custom composition, skin, placement, terminology, motion, and one main menu. The website/runner is a bare loader.
-- Engine packages do not supply a finished game face. Shared UI is headless or unskinned building blocks: layout (`HudCanvas`/`HudPanel`), data hooks, interaction models, tokens. Optional styled widgets exist for previews and scaffolding only — shipping them unskinned as the product is out of policy (see [AGENTS.md](../../../AGENTS.md)).
-- Never reach for genre HUD kits, theme presets, or "default RPG/FPS chrome" as the game's identity. Build the look this pitch needs.
+- **The main menu is a game front-end, not marketing.** The runner loads straight into the game's own menu; it offers the real front-end verbs the game supports — New Game, Continue/Load (save slots), Create/Choose character or class, Settings, Credits — each an authored screen in the game's art direction, not a landing page or raw scaffold. See [reference.md](reference.md) §"Main menu".
+- **Settings is game-owned and reachable from a sensible place.** Every game ships settings as *its* settings — skinned and placed inline with its UI (main menu and pause), never the engine's stock face floated into a corner. Credits are a reachable in-game screen, not attribution buried in a build artifact.
+- Engine packages ship both headless seams *and* good drop-in building blocks. The seams are layout (`HudCanvas`/`HudPanel`), data hooks, interaction models, and tokens; the building blocks are the parts almost every game needs — inventory grids (`InventoryGrid`), toggleable windows (`usePanels`/`PanelHost`/`Window`), character sheets (`CharacterSheet`/`Paperdoll`), stat/vitals bars, and action/selection bars. Composing and reskinning these is using the engine correctly, not out of policy. What stays out of scope is a whole finished game *face* or a genre theme preset shipped as the product (see [AGENTS.md](../../../AGENTS.md)).
+- **Skin the shared chrome with one `HudTheme` token object.** `hudThemeVars(theme)` emits the `--jg-*` custom properties that the atomic bars, `HudFrame variation="themed"`, painted slots, and the minimap ring all read, so one theme spread on any HUD ancestor reskins the whole subtree — palette, frame material, corner radius, glow, and slot chrome. Author your own theme (tower-guard's `fieldkitVars` is the model); `HUD_THEME_PRESETS` / `resolveHudTheme("<preset>")` are demo/scaffold starting points, never a game's identity. Caller `style`/`renderItem` overrides still win over the theme default.
+- **Paint slot icons with `IconTreatment`, never render raw `itemId` strings.** It draws a `GameIcon` glyph (or any node) over a school/element-keyed radial gradient with a gloss + vignette and optional count/keycap badges, and reads the `--jg-slot-*` / `--jg-accent` `HudTheme` tokens so a theme change reskins every treated icon. `schoolForItem`/`schoolForAction` infer the gradient from an id; `treatedItemIcon(itemId)` / `treatedActionIcon(action)` are ready adapters. Use it in hotbars and ability bars so slots read as painted icons, not debug text.
+- Never reach for a genre HUD kit, theme preset, or "default RPG/FPS chrome" as the game's *identity*. Composing the shared building blocks (bag, character, spellbook, action-bar windows) is fine and expected — it's a prefab genre *look/identity* dropped in unchanged that's discouraged. Build the look this pitch needs on top of them.
 - Layout and skin remain caller-controlled; shared primitives own reusable behavior, not product look.
 - SSR-visible output is hydration-stable; round computed SVG values at the boundary.
 
@@ -39,3 +43,4 @@ Existing React games keep their entity store and use the focused
 - Do not duplicate inventory, combat, quest, or selection state inside components.
 - A static facsimile preview does not test the real UI; compose production components with fixtures.
 - Visual quality is judged from rendered evidence, not component counts or prose.
+- Shown HUD UI must fit the player viewport. `HudCanvas` runs a live boundary check on every registered `HudPanel`, any element tagged `data-hud-window`, and its own direct children: if a *visible* surface crosses a viewport edge it draws a red dev overlay on the offender, `console.warn`s, and sets `data-hud-overflow` (which fails the `bun run shoot` gate). A closed/parked/hidden surface (off-screen drawer, unopened menu, `visibility:hidden`, `aria-hidden`) never trips it — only surfaces partly on screen and partly past an edge. Deliberate bleed opts out with `data-hud-allow-overflow`. Mount custom windows inside `HudCanvas` (tag deeper ones `data-hud-window`) so the check can see them.