@jgengine/core 0.19.0 → 0.22.0

package/dist/world/worldSolids.d.ts

@@ -13,6 +13,15 @@ export interface WorldSolid {
 export interface WorldSolidsState {
     layers: Record<string, readonly WorldSolid[]>;
 }
+/** Caller-owned work counters, reset by each world-solid ray candidate query. */
+export interface WorldSolidRayWork {
+    /** Hash-grid cell lookups, including empty cells. */
+    cells: number;
+    /** Indexed entry visits, including duplicates removed before bounds tests. */
+    entries: number;
+    /** Cached AABB ray tests after deduplication. */
+    bounds: number;
+}
 /**
  * Static collision for world geometry that is not a scene object: generated buildings, studio
  * volumes like `city`, wall runs. Solids live in named layers so a feature can replace or drop its
@@ -30,6 +39,8 @@ export interface WorldSolids {
     layers(): readonly string[];
     /** Every solid whose world AABB overlaps `min`..`max`. Bounded by a uniform XZ hash grid. */
     inBox(min: readonly [number, number, number], max: readonly [number, number, number]): WorldSolid[];
+    /** Optional accelerated ray candidates; finite coordinates/direction and nonnegative finite distance, normalized internally. */
+    inRay?(origin: readonly [number, number, number], direction: readonly [number, number, number], maxDistance: number, work?: WorldSolidRayWork): WorldSolid[];
     /** Every solid in every layer. */
     all(): WorldSolid[];
     count(): number;

package/dist/world/worldSolids.js

@@ -31,6 +31,8 @@ export function worldSolidFootprint(solid) {
  */
 export function createWorldSolids(options = {}) {
     const cellSize = options.cellSize ?? DEFAULT_CELL_SIZE;
+    if (!Number.isFinite(cellSize) || cellSize <= 0)
+        throw new RangeError("World solid cellSize must be finite and positive");
     const layerMap = new Map();
     const grid = new Map();
     const oversize = [];
@@ -47,7 +49,7 @@ export function createWorldSolids(options = {}) {
         const x1 = cellOf(entry.maxX);
         const z0 = cellOf(entry.minZ);
         const z1 = cellOf(entry.maxZ);
-        if ((x1 - x0 + 1) * (z1 - z0 + 1) > MAX_CELLS_PER_SOLID) {
+        if (![x0, x1, z0, z1].every(Number.isSafeInteger) || (x1 - x0 + 1) * (z1 - z0 + 1) > MAX_CELLS_PER_SOLID) {
             oversize.push(entry);
             return;
         }
@@ -95,6 +97,28 @@ export function createWorldSolids(options = {}) {
             entry.maxZ >= min[2] &&
             entry.minZ <= max[2]);
     }
+    function rayOverlaps(entry, origin, direction, maxDistance) {
+        let near = 0;
+        let far = maxDistance;
+        for (let axis = 0; axis < 3; axis++) {
+            const min = axis === 0 ? entry.minX : axis === 1 ? entry.minY : entry.minZ;
+            const max = axis === 0 ? entry.maxX : axis === 1 ? entry.maxY : entry.maxZ;
+            const from = origin[axis];
+            const delta = direction[axis];
+            if (delta === 0) {
+                if (from < min || from > max)
+                    return false;
+                continue;
+            }
+            const a = (min - from) / delta;
+            const b = (max - from) / delta;
+            near = Math.max(near, Math.min(a, b));
+            far = Math.min(far, Math.max(a, b));
+            if (near > far)
+                return false;
+        }
+        return true;
+    }
     return {
         set(layer, solids) {
             if (solids.length === 0) {
@@ -159,6 +183,93 @@ export function createWorldSolids(options = {}) {
                     out.push(entry.solid);
             return out;
         },
+        inRay(origin, direction, maxDistance, work) {
+            if (work !== undefined) {
+                work.cells = 0;
+                work.entries = 0;
+                work.bounds = 0;
+            }
+            if (!origin.every(Number.isFinite) || !direction.every(Number.isFinite) || !Number.isFinite(maxDistance) || maxDistance < 0) {
+                throw new RangeError("World solid rays require finite coordinates, direction and nonnegative distance");
+            }
+            const length = Math.hypot(...direction);
+            if (!Number.isFinite(length))
+                throw new RangeError("World solid ray direction length must be finite");
+            const out = [];
+            if (length === 0 || total === 0)
+                return out;
+            const normalized = [direction[0] / length, direction[1] / length, direction[2] / length];
+            stamp++;
+            const consider = (entry) => {
+                if (work !== undefined)
+                    work.entries++;
+                if (entry.stamp === stamp)
+                    return;
+                entry.stamp = stamp;
+                if (work !== undefined)
+                    work.bounds++;
+                if (rayOverlaps(entry, origin, normalized, maxDistance))
+                    out.push(entry.solid);
+            };
+            const scan = () => {
+                for (const entries of layerMap.values())
+                    for (const entry of entries)
+                        consider(entry);
+            };
+            const visit = (x, z) => {
+                if (work !== undefined)
+                    work.cells++;
+                const bucket = grid.get(keyOf(x, z));
+                if (bucket !== undefined)
+                    for (const entry of bucket)
+                        consider(entry);
+            };
+            let x = cellOf(origin[0]);
+            let z = cellOf(origin[2]);
+            const stepX = Math.sign(normalized[0]);
+            const stepZ = Math.sign(normalized[2]);
+            const deltaX = stepX === 0 ? Infinity : cellSize / Math.abs(normalized[0]);
+            const deltaZ = stepZ === 0 ? Infinity : cellSize / Math.abs(normalized[2]);
+            let nextX = stepX === 0 ? Infinity : ((x + (stepX > 0 ? 1 : 0)) * cellSize - origin[0]) / normalized[0];
+            let nextZ = stepZ === 0 ? Infinity : ((z + (stepZ > 0 ? 1 : 0)) * cellSize - origin[2]) / normalized[2];
+            const estimatedCells = 3 * (Math.ceil(maxDistance * Math.abs(normalized[0]) / cellSize) + Math.ceil(maxDistance * Math.abs(normalized[2]) / cellSize) + 1);
+            if (!Number.isSafeInteger(x) || !Number.isSafeInteger(z) || estimatedCells > total) {
+                scan();
+                return out;
+            }
+            if (grid.size > 0) {
+                visit(x, z);
+                while (Math.min(nextX, nextZ) <= maxDistance) {
+                    const crossX = nextX <= nextZ;
+                    const crossZ = nextZ <= nextX;
+                    if (crossX && crossZ) {
+                        visit(x + stepX, z);
+                        visit(x, z + stepZ);
+                    }
+                    const oldX = x;
+                    const oldZ = z;
+                    const oldNextX = nextX;
+                    const oldNextZ = nextZ;
+                    if (crossX) {
+                        x += stepX;
+                        nextX += deltaX;
+                    }
+                    if (crossZ) {
+                        z += stepZ;
+                        nextZ += deltaZ;
+                    }
+                    if (!Number.isSafeInteger(x) || !Number.isSafeInteger(z) ||
+                        (crossX && (x === oldX || nextX <= oldNextX)) || (crossZ && (z === oldZ || nextZ <= oldNextZ))) {
+                        scan();
+                        return out;
+                    }
+                    visit(x, z);
+                }
+            }
+            for (const entry of oversize)
+                consider(entry);
+            return out;
+        },
         all: () => [...layerMap.values()].flatMap((entries) => entries.map((entry) => entry.solid)),
         count: () => total,
         version: () => revision,

package/dist/world.d.ts

@@ -58,12 +58,12 @@ export { partsBounds, registerAssetGenerator, type GeneratedAsset, type Generate
 export { applyRotationPolicy, headingToRotationY, normalizeDegrees, parseAssetSpace, parseRotationPolicy, resolveAnchorOffset, resolveFacingRotationY, rotatedFootprint, rotationYToHeading, snapHeading, toEngineUnits, validateAssetSpace, type AssetAnchor, type AssetSpace, type AssetSpaceIssue, type PlacementRotationPolicy, } from "./scene/assetSpace.js";
 export { collectAuthoredTriggers, createAuthoredTriggerRuntime, getTriggerAction, listTriggerActions, pointInVolume, registerTriggerAction, type AuthoredTrigger, type AuthoredTriggerRuntime, type TriggerActionDefinition, type TriggerDispatchEvent, type TriggerEvent, type TriggerHandlers, type TriggerSourceKind, } from "./scene/authoredTriggers.js";
 export { selectAutoTarget, type AutoTargetPolicy } from "./scene/autoTarget.js";
-export { advanceBehaviors, behaviorControl, registerBehaviorActions, type BehaviorAction, type BehaviorActionContext, type BehaviorActionOptions, type BehaviorControl, type BehaviorInspection, type BehaviorResumePolicy, type BehaviorSnapshot, type BehaviorStatus, } from "./scene/behaviorRuntime.js";
-export { patrol, player, talkable, wander, type BehaviorDescriptor, type DecisionGraphBehavior, } from "./scene/behaviors.js";
+export { advanceBehaviors, behaviorControl, registerBehaviorActions, type BehaviorAction, type BehaviorActionContext, type BehaviorActionOptions, type BehaviorControl, type BehaviorInspection, type BehaviorResumePolicy, type BehaviorSnapshot, type BehaviorStatus, type PursueBehaviorSnapshot, } from "./scene/behaviorRuntime.js";
+export { patrol, player, pursue, talkable, wander, type BehaviorDescriptor, type DecisionGraphBehavior, type PursueBehavior, } from "./scene/behaviors.js";
 export { createBodyBind } from "./scene/bodyBind.js";
 export { type ColliderPurpose, type EntityColliderSet, type ResolvedCollider } from "./scene/colliders.js";
 export { type StatCatalog, type StatValue } from "./scene/entityStats.js";
-export { entityMetaOf, groundSpeed, type EntityPosition, type SceneEntity } from "./scene/entityStore.js";
+export { entityMetaOf, groundSpeed, type EntityPosition, type EntityStore, type SceneEntity, } from "./scene/entityStore.js";
 export { DEFAULT_FORWARD } from "./scene/facing.js";
 export { readNamedSockets, type ModelNode } from "./scene/modelSockets.js";
 export { MountController, createMountController } from "./scene/mount.js";
@@ -77,7 +77,7 @@ export { createSelectionBookmarks, recallSelectionBookmark, type BookmarkRecallM
 export { createSequenceDirector, type CueListener, type EmittedCue, type SequenceCue, type SequenceDirector, type SequenceDirectorOptions, type SequenceSnapshot, type SequenceState, } from "./scene/sequenceDirector.js";
 export { type Aim } from "./scene/spatial.js";
 export { createStationClaim, type Station } from "./scene/stationClaim.js";
-export { VehicleSeats, createVehicleSeats } from "./scene/vehicleSeat.js";
+export { VehicleSeats, boardVehicle, createVehicleSeats, leaveVehicle, type BoardVehicleOptions, type LeaveVehicleOptions, } from "./scene/vehicleSeat.js";
 export { type ConcealmentSensor } from "./sensor/concealment.js";
 export { type FreezeMonitor, type FreezeViolation } from "./sensor/freezeMonitor.js";
 export { type FramingConfig, type FrustumProjection, type FrustumSample, type FrustumSensor, type FrustumTarget, } from "./sensor/frustumSensor.js";
@@ -114,7 +114,7 @@ export { resolveStructureBuildings, summarizeEnvironment } from "./world/environ
 export { createFastTravelNetwork, type FastTravelNetwork, type FastTravelOptions, type FastTravelSnapshot, type TravelPointDef, type TravelPointView, } from "./world/fastTravel.js";
 export { biomes, building, environment, flat, grass, ocean, pad, plots, rain, road, sky, snow, terrain, tilemap, voxel, type BiomeBand, type BuildingEnvironmentDescriptor, type EnvironmentWorldFeature, type GrassEnvironmentDescriptor, type OceanEnvironmentDescriptor, type PadEnvironmentDescriptor, type PadSize, type RainEnvironmentDescriptor, type RoadEnvironmentDescriptor, type SkyEnvironmentDescriptor, type SnowEnvironmentDescriptor, type TerrainCircleRegion, type TerrainDetailConfig, type TerrainDetailMaterialConfig, type TerrainEnvironmentDescriptor, type TerrainFlattenMask, type TerrainMaterialRegion, type TerrainPolylineRegion, type TerrainRectRegion, type TerrainRegionStyle, type WeatherEnvironmentDescriptor, type WorldFeature, type WorldGridCell, type WorldGridConfig, } from "./world/features.js";
 export { createFogField, type FogCells, type FogField } from "./world/fog.js";
-export { boundaryNeighbors, createFootprintGrid, footprintObstacles, hasValidAdjacency } from "./world/footprintGrid.js";
+export { boundaryNeighbors, canMerge, createFootprintGrid, footprintObstacles, hasValidAdjacency, mergeFootprints, splitRegion, type FootprintRegion, type MergedRegion, type RegionContribution, type RegionFootprint, type RegionSplitIds, type RegionWorkBudget, } from "./world/footprintGrid.js";
 export { type Aabb, type AvoidZone } from "./world/geometry.js";
 export { GRASS_SCHEMA } from "./world/grassKind.js";
 export { resolveGridInstances } from "./world/gridInstances.js";

package/dist/world.js

@@ -59,11 +59,11 @@ export { applyRotationPolicy, headingToRotationY, normalizeDegrees, parseAssetSp
 export { collectAuthoredTriggers, createAuthoredTriggerRuntime, getTriggerAction, listTriggerActions, pointInVolume, registerTriggerAction, } from "./scene/authoredTriggers.js";
 export { selectAutoTarget } from "./scene/autoTarget.js";
 export { advanceBehaviors, behaviorControl, registerBehaviorActions, } from "./scene/behaviorRuntime.js";
-export { patrol, player, talkable, wander, } from "./scene/behaviors.js";
+export { patrol, player, pursue, talkable, wander, } from "./scene/behaviors.js";
 export { createBodyBind } from "./scene/bodyBind.js";
 export {} from "./scene/colliders.js";
 export {} from "./scene/entityStats.js";
-export { entityMetaOf, groundSpeed } from "./scene/entityStore.js";
+export { entityMetaOf, groundSpeed, } from "./scene/entityStore.js";
 export { DEFAULT_FORWARD } from "./scene/facing.js";
 export { readNamedSockets } from "./scene/modelSockets.js";
 export { MountController, createMountController } from "./scene/mount.js";
@@ -77,7 +77,7 @@ export { createSelectionBookmarks, recallSelectionBookmark, } from "./scene/sele
 export { createSequenceDirector, } from "./scene/sequenceDirector.js";
 export {} from "./scene/spatial.js";
 export { createStationClaim } from "./scene/stationClaim.js";
-export { VehicleSeats, createVehicleSeats } from "./scene/vehicleSeat.js";
+export { VehicleSeats, boardVehicle, createVehicleSeats, leaveVehicle, } from "./scene/vehicleSeat.js";
 export {} from "./sensor/concealment.js";
 export {} from "./sensor/freezeMonitor.js";
 export {} from "./sensor/frustumSensor.js";
@@ -114,7 +114,7 @@ export { resolveStructureBuildings, summarizeEnvironment } from "./world/environ
 export { createFastTravelNetwork, } from "./world/fastTravel.js";
 export { biomes, building, environment, flat, grass, ocean, pad, plots, rain, road, sky, snow, terrain, tilemap, voxel, } from "./world/features.js";
 export { createFogField } from "./world/fog.js";
-export { boundaryNeighbors, createFootprintGrid, footprintObstacles, hasValidAdjacency } from "./world/footprintGrid.js";
+export { boundaryNeighbors, canMerge, createFootprintGrid, footprintObstacles, hasValidAdjacency, mergeFootprints, splitRegion, } from "./world/footprintGrid.js";
 export {} from "./world/geometry.js";
 export { GRASS_SCHEMA } from "./world/grassKind.js";
 export { resolveGridInstances } from "./world/gridInstances.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.19.0",
+  "version": "0.22.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/ce-handoff/SKILL.md

@@ -25,7 +25,7 @@ Create one immutable handoff at the destination the user requested, or use the m
 ### Build the handoff
 
 1. Distill the current objective and the user's latest intent. If a focus was supplied, make it the `resume_focus`.
-2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md` / `CLAUDE.md`, `workflow`, domain skills).
+2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md`, `workflow`, domain skills).
 3. Point to plans, issues, commits, diffs, documentation, and relevant files instead of reproducing their contents. Prefer repository-relative paths (`docs/plans/…`, `packages/…`, `Games/…`).
 4. Redact secrets, credentials, tokens, and unrelated personal information. Preserve operational paths only when the next agent needs them.
 5. Write or publish with existing tools. If the user named another path, folder, format, or publication destination, honor it. Do not also create a managed-store copy unless asked.

package/skills/game-design/SKILL.md

@@ -11,6 +11,8 @@ Own the intended player experience and the rules that produce it: fantasy, pilla
 
 Use `level-design` for spatial realization; route implementation to `jgengine-gameplay`, `jgengine-world`, `jgengine-combat`, `jgengine-ui`, `jgengine-multiplayer` once intent is coherent.
 
+For a substantial existing-game quality pass spanning concept, depth, world and presentation, use `game-improvement` to sequence these owners and keep a per-game implementation plan and acceptance evidence.
+
 For a greenfield build, read [references/application-playbook.md](references/application-playbook.md) and produce its greenfield contract (promise, pillars, anti-pillars, core decision, and falsifier) before writing code. Audits may read only the playbook's audit sections. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
 
 ## Choose the mode

package/skills/jgengine/SKILL.md

@@ -9,6 +9,22 @@ This skill decides what to load; it is not an engine manual. Package map, comman
 
 A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
+Created projects pin their scaffolding CLI as a local devDependency, separately from SDK versions. Run `npx jgengine doctor` after SDK upgrades to check CLI compatibility. Skill installation preserves newer or differing unversioned copies; update the project CLI first, and use `skills -p --force` only when replacement is intended. Each packaged skill install records its CLI and SDK versions in `.jgengine-version.json`.
+
+## Framework-first decisions
+
+For every requested interaction, feature, fix or visual change, follow the boundary in
+[AGENTS.md](../../../AGENTS.md): discover the installed
+capability, adopt it, or improve its shared owner before adding reusable game-local code.
+Games keep unique rules, content, assets and presentation. Custom markup is not a reason
+to copy focus handling, input tracking, storage or model lifecycle.
+
+Check installed versions before recreating an upstream fix. A published upgrade may
+replace a workaround; a beta merge does not update consumers. In the games workspace,
+the root catalog owns SDK versions. After adoption, remove superseded local machinery
+and verify the actual game. Outside these repositories, report missing SDK contracts
+upstream rather than treating a local engine implementation as the finished solution.
+
 ## 1. Establish the target
 
 For greenfield builds, write `src/art-direction.md` before any code.
@@ -26,6 +42,10 @@ Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player
 
 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.
 
+`doctor` and `upgrade` resolve Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs`, and follow hoisted SDK installs. Missing or malformed catalog entries fail diagnostics. `upgrade` is read-only by default. For catalog-owned versions, run `upgrade --plan --to <published-version>` at the workspace root or in a game, review the whole root catalog plan and migrations, then run `upgrade --apply --to <published-version>`. Apply preserves per-game `catalog:` declarations, unrelated text, CLI/github versions, and a held editor override; it verifies published SDK targets and refuses files changed while planning. Apply changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there to check installed SDK identities across declared workspace owners. Rebuild, migrate, and verify game behavior afterward. `--json` includes exact before/after text; an apply prints its plan before writing and reports write status on stderr. A report without installed packages labels its resolved pins as a declared baseline.
+
+When a linked consumer renders differently despite matching root SDK versions, `doctor` checks direct consumers and SDK dependency/peer paths, including private copies with the same version. Review the reported importer and real paths, align the shared catalog and linked-consumer declarations, then reinstall at the root and rerun `doctor --workspace`; a root install may leave private linked-package installs intact. Restart running games after reinstall. Workspace mode checks installed identities only, reports coverage, and refuses unsupported patterns, escaped symlinks or exhausted traversal budgets. The default project audit stays scoped; neither mode covers custom bundler aliases or indirect non-SDK chains.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -33,6 +53,7 @@ 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 |
+| substantial existing-game improvement across depth, world and presentation | `game-improvement` | ordered improvement plan and per-game completion |
 | 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 |
@@ -49,12 +70,12 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 Within each selected domain:
 
 0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); agents can use `--json --limit 5` for ranked imports and recipes with total, partial-match, and truncation fields. In the monorepo, `rg -i "<intent>" .claude/skills/*/capabilities.md` does the same search. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
 2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 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.
+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 and a reviewed consumer cleanup; coordinate a differently composed second consumer when applicable. Recipes wire SDK APIs, not copied implementations. If editor-owned content cannot be expressed, file the editor gap first; track any fallback and its removal path.
 
 ## 4. Build and finish
 

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.19.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.22.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -232,7 +232,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.19.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.22.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -260,10 +260,20 @@
 ## @jgengine/core/runtime/cameraDirector
 
 - `CHASE_VIEWS` (const): const CHASE_VIEWS: readonly ChaseView[] — Default order {@link nextChaseView} cycles through.
-- `CameraDirector` (interface): interface CameraDirector { follow(entityId: string | null): void; followedEntityId(): string | null | undefined; setCinematic(config: CinematicCameraConfig | null): void; cinematic(): CinematicCameraConfig | null; setChaseTuning(tuning: ChaseCameraTuning | null): v… — ⚠ undocumented
-- `ChaseCameraTuning` (type): type ChaseCameraTuning = Partial< Pick< ChaseCameraConfig, | "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse" | "distanceBySpeed" | "pitchFollow" | "fovKick" | "lookBackAction" | "collision" | "view" > > — Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), a whole driving-feel overlay applied only while a vehicle is piloted (#1299), or a `view` switch between chase and seat cameras.
+- `CameraDirector` (interface): interface CameraDirector { follow(entityId: string | null): void; followedEntityId(): string | null | undefined; setRig(kind: CameraRigKind | null, config?: CameraRigConfig): void; rig(): CameraRigOverride | null; setCinematic(config: CinematicCameraConfig | null):… — ⚠ undocumented
+- `CameraDirectorSnapshot` (type): type CameraDirectorSnapshot = CameraSerialized<CameraDirectorState> — JSON-safe camera policy; documented instant chase responses use an explicit Infinity marker.
+- `CameraDirectorState` (interface): interface CameraDirectorState — Camera policy state before the JSON-safe snapshot number encoding.
+- `CameraRigConfig` (type): type CameraRigConfig = Omit<GameCameraConfig, "rig" | "projection" | "pixelPerfect" | "frustum" | "playerFov" | "weapon" | "onCameraFollow"> — Data overlay for an existing rig; callbacks and Canvas projection/preferences remain configured by the game.
+- `CameraRigOverride` (interface): interface CameraRigOverride — Runtime rig selection and detached data overlay over the configured camera.
+- `ChaseCameraTuning` (type): type ChaseCameraTuning = Partial< Pick< ChaseCameraConfig, | "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse" | "headingSource" | "distanceBySpeed" | "pitchFollow" | "fovKick" | "lookBackAction" | "collision" | "view" … — Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), a whole driving-feel overlay applied only while a vehicle is piloted (#1299), or a `view` switch between chase and seat cameras.
 - `nextChaseView` (function): function nextChaseView(current: ChaseView, views: readonly ChaseView[] = CHASE_VIEWS): ChaseView — The view after `current` in `views`, wrapping at the end; a view missing from the list starts the cycle over. Pair with `setChaseTuning` to bind a "change camera" key: `ctx.camera.setChaseTuning({ ...ctx.camera.chaseTuning(), view: nextChaseView(view) })`.
 
+## @jgengine/core/runtime/commandDispatch
+
+- `DispatchedCommandResult` (type): type DispatchedCommandResult = CommandResult<GameContext> | Promise<CommandResult<GameContext>> — A UI command completes locally or after its authoritative host acknowledges it.
+- `bindCommandTransport` (function): function bindCommandTransport(ctx: GameContext, route: Route): () => void — Bind UI command dispatch to the host for this context. A missing join rejects; it never mutates the local replica.
+- `dispatchCommand` (function): function dispatchCommand(ctx: GameContext, name: string, input: unknown): DispatchedCommandResult — Dispatch a player's command through the bound host, or locally for an unbound offline context. Await the result before showing success.
+
 ## @jgengine/core/runtime/commandInput
 
 - `QuantityResult` (type): type QuantityResult = { ok: true; quantity: number } | { ok: false; reason: "invalid-quantity" } — Validated integer quantity or a stable input rejection.
@@ -318,7 +328,7 @@
 - `GameContextWorld` (interface): interface GameContextWorld { ground: TerrainField; groundHeightAt(x: number, z: number): number; solids: WorldSolids } — ⚠ undocumented
 - `HitReactionInput` (interface): interface HitReactionInput — ⚠ undocumented · used by `resolveHitReaction` (@jgengine/core/combat): Resolves hit feel (hitstop, knockback impulse, camera shake) from either a named `impactPresets` event (`resolveHitReaction("explosion", inp…
 - `MoveTowardCommitOptions` (interface): interface MoveTowardCommitOptions extends MoveTowardOptions — Options for {@link SceneEntityContext.moveTowardCommit}: {@link MoveTowardOptions} plus an optional facing turn.
-- `SceneEntityContext` (interface): interface SceneEntityContext { spawn(name: string, options?: SpawnOptions): string; despawn(instanceId: string): boolean; update: EntityStore["update"]; setPose(instanceId: string, pose: EntityPose): boolean; setPoseConstraint: EntityStore["setPoseConstraint"]; get(ins… — ⚠ undocumented
+- `SceneEntityContext` (interface): interface SceneEntityContext { spawn(name: string, options?: SpawnOptions): string; despawn(instanceId: string): boolean; update: EntityStore["update"]; setPose(instanceId: string, pose: EntityPose): boolean; setVelocity: EntityStore["setVelocity"]; setPoseConstraint: … — ⚠ undocumented
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore { catalog(instanceId: string): GameContextObjectEntry | null; raycast(input: ObjectRaycastInput): ObjectRaycastHit | null; raycastAll(input: ObjectRaycastInput): readonly ObjectRaycastHit[]; setColliders(instanceId: string, colliders: Entit… — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — `ctx.scene.worldItem`: items lying in the world — spawn, list, find the nearest, and pick up into a player's bag.
 - `TelegraphInput` (interface): interface TelegraphInput { from: string; shape: TelegraphShape; at: [number, number, number]; dir?: number; windupMs: number; kind?: string; effect?: {effect: string; via?: EffectVia; radius?: number; falloff?: "linear" | "none"; los?: boolean;} } — ⚠ undocumented
@@ -349,7 +359,7 @@
 - `GameContextWorld` (interface): interface GameContextWorld { ground: TerrainField; groundHeightAt(x: number, z: number): number; solids: WorldSolids } — ⚠ undocumented
 - `HitReactionInput` (interface): interface HitReactionInput { from: string; to: string; config: HitReactionConfig | ImpactPresetName; power?: number } — ⚠ undocumented · used by `resolveHitReaction` (@jgengine/core/combat): Resolves hit feel (hitstop, knockback impulse, camera shake) from either a named `impactPresets` event (`resolveHitReaction("explosion", inp…
 - `MoveTowardCommitOptions` (interface): interface MoveTowardCommitOptions extends MoveTowardOptions — Options for {@link SceneEntityContext.moveTowardCommit}: {@link MoveTowardOptions} plus an optional facing turn.
-- `SceneEntityContext` (interface): interface SceneEntityContext { spawn(name: string, options?: SpawnOptions): string; despawn(instanceId: string): boolean; update: EntityStore["update"]; setPose(instanceId: string, pose: EntityPose): boolean; setPoseConstraint: EntityStore["setPoseConstraint"]; get(ins… — ⚠ undocumented
+- `SceneEntityContext` (interface): interface SceneEntityContext { spawn(name: string, options?: SpawnOptions): string; despawn(instanceId: string): boolean; update: EntityStore["update"]; setPose(instanceId: string, pose: EntityPose): boolean; setVelocity: EntityStore["setVelocity"]; setPoseConstraint: … — ⚠ undocumented
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore { catalog(instanceId: string): GameContextObjectEntry | null; raycast(input: ObjectRaycastInput): ObjectRaycastHit | null; raycastAll(input: ObjectRaycastInput): readonly ObjectRaycastHit[]; setColliders(instanceId: string, colliders: Entit… — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — `ctx.scene.worldItem`: items lying in the world — spawn, list, find the nearest, and pick up into a player's bag.
 - `TelegraphInput` (interface): interface TelegraphInput { from: string; shape: TelegraphShape; at: [number, number, number]; dir?: number; windupMs: number; kind?: string; effect?: {effect: string; via?: EffectVia; radius?: number; falloff?: "linear" | "none"; los?: boolean;} } — ⚠ undocumented
@@ -420,7 +430,7 @@
 - `HostedGameRunner` (interface): interface HostedGameRunner — The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext` per world, driven server-side. `onInit` runs once at construction; `onNewPlayer`/`onPlayerLeave` fire per join/leave; `tick` advances `onTick` then commits a revision. Clients pull a full {@link WorldSnapshot} baseline once, then per-tick {@link WorldDiff}s from their last revision. Games ship only normal GameContext code — the runner adds no per-game surface.
 - `HostedGameRunnerOptions` (interface): interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — Config for {@link createHostedGameRunner}: the game definition, its content lookup, and an optional host identity.
 - `INPUT_COMMAND` (const): const INPUT_COMMAND: "engine.input" — Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire.
-- `InputFrame` (interface): interface InputFrame — One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player.
+- `InputFrame` (interface): interface InputFrame — One client's serializable held state and discrete edges for a simulation tick.
 
 ## @jgengine/core/runtime/hostedWorldSession
 
@@ -429,7 +439,7 @@
 - `HostedWorldSessionOptions` (interface): interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — Config for {@link createHostedWorldSession}: the game, its persistence store, and the auto-save cadence.
 - `HostedWorldStore` (interface): interface HostedWorldStore — Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`. Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and saves on a cadence; a stateless host reconstructs from `load()` each invocation.
 - `HostedWorldSync` (type): type HostedWorldSync = | { kind: "baseline"; revision: number; snapshot: WorldSnapshot } | { kind: "diff"; diff: WorldDiff } — A client replication pull: a full baseline (first sync / fell behind) or a diff since the client's cursor.
-- `SyncHostedWorldStore` (interface): interface SyncHostedWorldStore — Synchronous store adapter retained for deterministic in-process tests.
+- `SyncHostedWorldStore` (interface): interface SyncHostedWorldStore — Already-loaded store adapter: synchronous reads, with synchronous or asynchronous writes.
 - `asyncMemoryWorldStore` (function): function asyncMemoryWorldStore(seed?: HostedWorldRecord): HostedWorldStore — Async in-process store for callers exercising the production persistence contract.
 - `createHostedWorldSessionAsync` (function): function createHostedWorldSessionAsync<TAssetRef extends ModelAssetRef, TMultiplayer>(options: Omit<HostedWorldSessionOptions<TAssetRef, TMultiplayer>, "store"> & { store: HostedWorldStore }): Promise<HostedWorldSession> — Build a hosted session from an asynchronous persistence backend.
 
@@ -437,7 +447,7 @@
 
 - `HostedWorldRecord` (interface): interface HostedWorldRecord — One hosted world's persisted authoritative state — the unit a {@link HostedWorldStore} loads and saves.
 - `HostedWorldStore` (interface): interface HostedWorldStore — Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`. Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and saves on a cadence; a stateless host reconstructs from `load()` each invocation.
-- `SyncHostedWorldStore` (interface): interface SyncHostedWorldStore — Synchronous store adapter retained for deterministic in-process tests.
+- `SyncHostedWorldStore` (interface): interface SyncHostedWorldStore — Already-loaded store adapter: synchronous reads, with synchronous or asynchronous writes.
 
 ## @jgengine/core/runtime/inputRecorder
 
@@ -448,8 +458,9 @@
 
 ## @jgengine/core/runtime/inputSnapshot
 
-- `InputFrame` (interface): interface InputFrame — One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player.
-- `InputSnapshot` (interface): interface InputSnapshot { rumble(userId: string, options: {strong: number; weak: number; ms: number}): Promise<boolean>; haptics(userId: string): HapticChannels; publish(held: readonly string[]): void; publishPointer(state: PointerAxisState | null): void; publishA… — ⚠ undocumented · used by `GamepadSource` (@jgengine/shell/input/gamepadSource): Poll browser gamepads and feed semantic actions into the shell tracker.
+- `InputFrame` (interface): interface InputFrame — One client's serializable held state and discrete edges for a simulation tick.
+- `InputPress` (interface): interface InputPress — One discrete press, identified across retransmitted live input frames.
+- `InputSnapshot` (interface): interface InputSnapshot { rumble(userId: string, options: {strong: number; weak: number; ms: number}): Promise<boolean>; haptics(userId: string): HapticChannels; publish(held: readonly string[], edges?: {pressed?: readonly string[]; reset?: boolean}): void; beginS… — ⚠ undocumented · used by `GamepadSource` (@jgengine/shell/input/gamepadSource): Poll browser gamepads and feed semantic actions into the shell tracker.
 - `createInputSnapshot` (function): function createInputSnapshot(): InputSnapshot — ⚠ undocumented
 
 ## @jgengine/core/runtime/localPlayers
@@ -509,11 +520,11 @@
 
 ## @jgengine/core/runtime/runtimeSave
 
-- `RuntimeSave` (interface): interface RuntimeSave — Whole-world save/load bound to a live world and a pluggable backend. `save()` captures `target.snapshot()` and writes it; `load()` reads it back and `target.hydrate()`s the whole world. In `autosave` mode it also writes on a trailing timer while the world keeps changing. Named slots, versioned migration, and offline↔cloud (backend swap) all come for free from the underlying save store.
+- `RuntimeSave` (interface): interface RuntimeSave — Whole-world save/load bound to a live world and a pluggable backend. `save()` captures `target.state()` and writes it; `load()` reads it back and calls `target.restore()`. Older targets use `snapshot()`/`hydrate()`. In `autosave` mode it also writes on a trailing timer while the world keeps changing. Named slots, versioned migration, and offline↔cloud (backend swap) all come for free from the underlying save store.
 - `RuntimeSaveConfig` (interface): interface RuntimeSaveConfig — How {@link createRuntimeSave} is wired — the live world `target`, the `backend` it persists through, and optional mode/slot/versioning/cadence knobs.
 - `RuntimeSaveMode` (type): type RuntimeSaveMode = "autosave" | "manual" — `"autosave"` writes a fresh capture on a trailing timer while the world changes (at most once per `autosaveMs`, so a never-idle world still persists); `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model.
 - `RuntimeSaveOptions` (type): type RuntimeSaveOptions = Omit<RuntimeSaveConfig, "target"> — {@link RuntimeSaveConfig} without `target` — what a host (`createGameContext`) accepts to build `ctx.game.save` and bind it to the context itself.
-- `RuntimeSaveTarget` (interface): interface RuntimeSaveTarget — The narrow slice of a live `GameContext` a runtime save reads and writes — a `GameContext` satisfies it directly (`ctx.snapshot`/`ctx.hydrate`/`ctx.subscribe`). Depending on this instead of the full context keeps the save controller a deep, decoupled module: it captures and restores the *whole* opted-in world without knowing any subsystem.
+- `RuntimeSaveTarget` (interface): interface RuntimeSaveTarget — The narrow slice of a live `GameContext` a runtime save reads and writes — a `GameContext` satisfies it directly (`ctx.state`/`ctx.restore`/`ctx.subscribe`). Depending on this instead of the full context keeps the save controller a deep, decoupled module: it captures and restores the *whole* opted-in world without knowing any subsystem.
 - `createRuntimeSave` (function): function createRuntimeSave(config: RuntimeSaveConfig): RuntimeSave — Bridge a live world to a pluggable save backend: whole-state capture/restore with autosave, save points, named slots, and versioned migration — the same call for offline (localStorage) and cloud (Convex), only the `backend` differs. The game keeps control of *when* it saves (the `mode` plus explicit `checkpoint()` calls from quests/areas) and *when* it restores (`load()` on boot), so any save mechanic — continuous autosave, manual save points, checkpoint triggers — is expressible without new engine code.
 
 ## @jgengine/core/runtime/save
@@ -527,7 +538,7 @@
 - `SimContextState` (interface): interface SimContextState — Serializable `ctx.sim` state: loop position plus the interpolation pose history.
 - `SimStage` (interface): interface SimStage — Extra work a game or engine seam (a physics backend, a netcode buffer) runs inside every simulation step.
 - `SimStagePhase` (type): type SimStagePhase = "beforeMovement" | "afterMovement" | "afterTick" — Where a registered stage runs inside one simulation step.
-- `createSimContext` (function): function createSimContext(options: { config?: SimulationConfig; entities: EntityStore }): SimContext — Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`.
+- `createSimContext` (function): function createSimContext(options: { config?: SimulationConfig; entities: EntityStore; time?: Pick<SimClock, "advance"> }): SimContext — Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`.
 
 ## @jgengine/core/runtime/simLoop
 
@@ -640,7 +651,7 @@
 ## @jgengine/shell/GameHost
 
 - `EditorSummonModule` (interface): interface EditorSummonModule — Structural shape of the module `GameHost`'s `editor` loader resolves — `import("@jgengine/editor")` satisfies it.
-- `GameHost` (function): function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor }: GameHostProps): 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).
+- `GameHost` (function): function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor, creator, creatorOpen = false, onCreatorOpenChange }: GameHostProps): 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).
 - `GameHostProps` (interface): interface GameHostProps — Props for {@link GameHost}: the playable, optional multiplayer overrides, and the optional editor loader that enables the engine-owned F2+E summon.
 
 ## @jgengine/shell/defineGame
@@ -659,7 +670,7 @@
 - `GameCameraConfig` (interface): interface GameCameraConfig — Camera tuning for the shell's rig stack: pick the rig via `rig`, then tune it through its matching config block. All fields optional — the default is the third-person orbit rig.
 - `GameConfig` (type): type GameConfig<TAssetRef extends ModelAssetRef = ModelAssetRef> = EngineFields<TAssetRef> & PresentationFields — ⚠ undocumented · used by `defineGame`: The one public authoring entry point: compose engine fields (systems, world, physics, input) and presentation fields (camera, HUD, audio, au…
 - `GameContext` (interface): interface GameContext — The live engine handle a game's loop, systems, commands, and UI read and mutate — entities, objects, the reactive store, opted-in `game.*` subsystems, world queries, and the sim clock. One context = one running world.
-- `GameHost` (function): function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor }: GameHostProps): 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).
+- `GameHost` (function): function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor, creator, creatorOpen = false, onCreatorOpenChange }: GameHostProps): 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).
 - `GameHostProps` (interface): interface GameHostProps — Props for {@link GameHost}: the playable, optional multiplayer overrides, and the optional editor loader that enables the engine-owned F2+E summon.
 - `GameLoop` (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
 - `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: (item… — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
@@ -673,7 +684,7 @@
 - `collectAuthoredTriggers` (function): function collectAuthoredTriggers(document: SceneDocumentLike): AuthoredTrigger[] — Collect every authored trigger on a document's markers and volumes. Pure — no runtime state. Action params use the live {@link registerTriggerAction} registry when present.
 - `defineGame` (function): function defineGame<TAssetRef extends ModelAssetRef = ModelAssetRef>(config: GameConfig<TAssetRef>): PlayableGame — The one public authoring entry point: compose engine fields (systems, world, physics, input) and presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`. Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
 - `defineKeyedStore` (function): function defineKeyedStore<T>(keyFor: (id: string) => string, initial: T | (() => T)): KeyedStoreHandle<T> — Define a typed per-owner keyed family on the game store: game code expresses `read(ctx, userId)`/`write(ctx, userId, v)`/`update(...)` with the value type it means, and both the `` `prefix:${id}` `` key composition and the `unknown → T` cast live once, here, behind the boundary. Reach for this over N separate `defineStore` calls whenever the owning id varies at runtime (per-user class, per-instance auras) — `defineStore` stays the right call for a single fixed slot.
-- `defineStore` (function): function defineStore<T>(key: string, initial: T | (() => T)): StoreHandle<T> — Define a typed slot on the game store: game code expresses `read(ctx)`/`write(ctx, v)`/`update(...)` with the value type it means, and the `unknown → T` cast lives once, here, behind the boundary. Pass a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most once and its result is reused, so an unwritten slot keeps a stable identity across reads (no per-read churn for a React selector, no allocation on a hot path).
+- `defineStore` (function): function defineStore<T>(key: string, initial: T | (() => T)): StoreHandle<T> — Define a typed slot on the game store: game code expresses `read(ctx)`/`write(ctx, v)`/`update(...)` with the value type it means, and the `unknown → T` cast lives once, here, behind the boundary. Pass a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most once and its result is reused, so an unwritten slot keeps a stable identity across reads (no per-read churn for a React selector, no allocation on a hot path). A value that carries functions (a closure-based run store, an input handle) is runtime-only: snapshots, saves and replication skip it and hydration keeps it in place. Hold such objects with `perContext` when they need no store notifications.
 - `defineSystem` (function): function defineSystem(definition: SystemDefinition): SystemDefinition — Declare a composable game system. Pure data + hooks — the engine compiles the schedule and installs lifecycle when the game boots.
 - `environment` (function): function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature — Composes an `environment()` feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
 - `environmentContentFromDocument` (function): function environmentContentFromDocument(doc: EditorDocument, options?: EnvironmentContentOptions): EnvironmentContent — Derives the coordinate/placement content of an `environment()` world from its scene document: terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that lets a game author its world footprint and flatten regions in the editor instead of hardcoding them — the `world.ts` that consumes it carries only engine tuning.

package/skills/jgengine/recipes/minimal-game.md

@@ -6,6 +6,11 @@ authored scene edited in the browser, one system, one store slot, an empty-canva
 and a win condition. Every new game starts here; add combat, multiplayer, or deeper
 world features only after this loop plays.
 
+Every extension follows the [framework-first decision](../SKILL.md#framework-first-decisions):
+compose an installed SDK capability, improve its upstream contract if needed, then
+remove superseded game glue after published adoption. The game owns its rules and art;
+it should not recreate input, model lifecycle, storage or UI accessibility machinery.
+
 ## 1. Scaffold
 
 `npx jgengine create <name>` (inside the engine monorepo: `bun run new:game "<id-or-title>"`).
@@ -80,8 +85,8 @@ direction. Compose the shipped building blocks the moment you need them (`StatBa
 `Coins`, `InventoryGrid`, `CharacterSheet`, window shells from `jgengine-ui`), then reskin via
 `HudTheme` tokens. Reaching for those is using the engine correctly, not incomplete work. What
 the engine does not ship is a whole finished game *face* or genre theme preset — do not leave an
-unarranged, unskinned generic dashboard as the product. Hand-roll markup only where no building
-block fits (see `jgengine-ui`).
+unarranged, unskinned generic dashboard as the product. Custom markup can use headless
+SDK behavior; a missing reusable behavior is an upstream gap (see `jgengine-ui`).
 
 ## 3. Author, play, win
 

package/skills/jgengine-combat/SKILL.md

@@ -19,6 +19,9 @@ a parallel entity store. To bolt firing onto an existing game, compose
 `resolveDamageHit`) per the
 [portable weapon-plumbing recipe](recipes/portable-weapon-plumbing.md); never add
 a default gun or FPS kit.
+For scene-backed `createProjectileSystem`, inject authoritative `rng`; spread
+samples independent pellet rays and prediction stays on the center ray. The
+weapon-plumbing recipe covers the bounded cone and cover contracts.
 Tune how a weapon feels (recoil, bloom, ADS, shake and rumble) with the
 [weapon-feel recipe](recipes/weapon-feel.md): feel target → `measureWeapon`
 numbers → handling knobs, and `createWeaponFeedbackSignals` into the feedback mixer.
@@ -28,8 +31,11 @@ receiver, interceptor, and status stages remain pure. Follow the
 [portable damage/effects recipe](recipes/portable-damage-effects.md) to compose
 them over an existing store, clock, RNG, spatial index, and death flow.
 
-Closure-backed magazines and stat modifiers expose plain snapshot/restore
-state for caller-owned saves, rollback, replay, and workers. Follow the
+Closure-backed magazines expose snapshot/restore and `retune` for capacity/reload
+changes without reconstructing ammo state; capacity overflow is explicit.
+Stat modifiers expose snapshot/restore; ability
+kits, shields, and meters expose state/restore for caller-owned saves,
+rollback, replay, and workers. Follow the
 [portable runtime-state recipe](recipes/portable-runtime-state.md); the caller
 keeps its clock, reserve state, schema, and authority.