@jgengine/core 0.18.1 → 0.19.0

package/dist/world/footprintGrid.js

@@ -1,6 +1,9 @@
 function cellKey(cell) {
     return `${cell.col}:${cell.row}`;
 }
+function copyReservation(reservation) {
+    return { id: reservation.id, kind: reservation.kind, cells: reservation.cells.map((cell) => ({ col: cell.col, row: cell.row })) };
+}
 /**
  * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`
  * only owns the ghost preview; this is the persistent claim a committed placement holds so the next
@@ -70,6 +73,19 @@ export function createFootprintGrid(options = {}) {
             occupied.clear();
             reservations.clear();
         },
+        snapshot() {
+            return { reservations: Array.from(reservations.values(), copyReservation) };
+        },
+        restore(next) {
+            occupied.clear();
+            reservations.clear();
+            for (const reservation of next.reservations) {
+                const copy = copyReservation(reservation);
+                reservations.set(copy.id, copy);
+                for (const cell of copy.cells)
+                    occupied.set(cellKey(cell), copy.id);
+            }
+        },
     };
 }
 const CARDINAL_OFFSETS = [

package/dist/world/interiors.d.ts

@@ -32,4 +32,5 @@ export interface Interiors {
     toInterior(id: string, exterior: Vec2): Vec2 | null;
     toExterior(id: string, interior: Vec2): Vec2 | null;
 }
+/** Frame conversion and bounded movement across an exterior and its interiors; holds config only, no play state. */
 export declare function createInteriors(config?: InteriorsConfig): Interiors;

package/dist/world/interiors.js

@@ -14,12 +14,14 @@ function toExteriorFrame(interior, local) {
     const rotated = rotate(local, interior.rotation ?? 0);
     return [rotated[0] + interior.origin[0], rotated[1] + interior.origin[1]];
 }
+function indexInteriors(interiors) {
+    return new Map(interiors.map((interior) => [interior.id, interior]));
+}
+/** Frame conversion and bounded movement across an exterior and its interiors; holds config only, no play state. */
 export function createInteriors(config = {}) {
     const radius = config.radius ?? 0;
     const exterior = config.exterior ?? {};
-    const byId = new Map();
-    for (const interior of config.interiors ?? [])
-        byId.set(interior.id, interior);
+    const byId = indexInteriors(config.interiors ?? []);
     return {
         move(location, delta) {
             if (location.space.kind === "exterior") {

package/dist/world/lod.d.ts

@@ -7,11 +7,17 @@ export interface LodSchedulerConfig {
     beyondInterval?: number | null;
     stagger?: boolean;
 }
+/** Plain JSON state of a {@link LodScheduler}: each id's accumulated seconds. */
+export interface LodSchedulerState {
+    buckets: Record<string, number>;
+}
 export interface LodScheduler {
     bandIndex(distance: number): number;
     step(id: string, distance: number, dtSeconds: number): number;
     remove(id: string): void;
     clear(): void;
     size(): number;
+    snapshot(): LodSchedulerState;
+    restore(next: LodSchedulerState): void;
 }
 export declare function createLodScheduler(config: LodSchedulerConfig): LodScheduler;

package/dist/world/lod.js

@@ -62,5 +62,13 @@ export function createLodScheduler(config) {
         size() {
             return buckets.size;
         },
+        snapshot() {
+            return { buckets: Object.fromEntries(buckets) };
+        },
+        restore(next) {
+            buckets.clear();
+            for (const [id, seconds] of Object.entries(next.buckets))
+                buckets.set(id, seconds);
+        },
     };
 }

package/dist/world/terraform.d.ts

@@ -262,5 +262,13 @@ export interface TerraformBrush {
     config(): Required<Omit<TerraformBrushConfig, "surface">> & {
         surface: string | undefined;
     };
+    /** The retunable brush settings; the terrain keeps its own `snapshot()`. */
+    snapshot(): TerraformBrushState;
+    restore(next: TerraformBrushState): void;
+}
+/** Plain JSON state of a {@link TerraformBrush}. */
+export interface TerraformBrushState {
+    radius: number;
+    strength: number;
 }
 export declare function createTerraformBrush(terrain: Pick<EditableTerrain, "apply">, config?: TerraformBrushConfig): TerraformBrush;

package/dist/world/terraform.js

@@ -787,5 +787,12 @@ export function createTerraformBrush(terrain, config = {}) {
         config() {
             return { radius, strength, falloff, surface };
         },
+        snapshot() {
+            return { radius, strength };
+        },
+        restore(next) {
+            radius = next.radius;
+            strength = next.strength;
+        },
     };
 }

package/dist/world/walls.d.ts

@@ -50,6 +50,11 @@ export interface SurfacePaintStore {
 }
 /** @internal */
 export declare function createSurfacePaint(): SurfacePaintStore;
+/** Plain JSON state of a {@link WallDrawTool}: the drawn points and whether the loop is closed. */
+export interface WallDrawToolState {
+    points: Vec2[];
+    closed: boolean;
+}
 export interface WallDrawTool {
     addPoint(point: Vec2, snap?: number): Vec2;
     undo(): void;
@@ -60,6 +65,8 @@ export interface WallDrawTool {
     isClosed(): boolean;
     footprint(): EnclosedFootprint | null;
     roof(config?: RoofConfig): RoofPlan | null;
+    snapshot(): WallDrawToolState;
+    restore(next: WallDrawToolState): void;
 }
 /** @internal */
 export declare function createWallDrawTool(config?: {

package/dist/world/walls.js

@@ -220,6 +220,13 @@ export function createWallDrawTool(config = {}) {
             const fp = this.footprint();
             return fp === null ? null : autoRoof(fp, roofConfig);
         },
+        snapshot() {
+            return { points: pts.map((point) => [point[0], point[1]]), closed };
+        },
+        restore(next) {
+            pts = next.points.map((point) => [point[0], point[1]]);
+            closed = next.closed;
+        },
     };
 }
 /** @internal */

package/dist/world/worldSolids.d.ts

@@ -0,0 +1,84 @@
+import type { GeneratedBuilding } from "./buildings.js";
+import type { EnvironmentWorldFeature } from "./features.js";
+import type { Aabb } from "./geometry.js";
+import type { WallSegment } from "./walls.js";
+/** One solid box in world space: the collision half of generated or authored world geometry. */
+export interface WorldSolid {
+    center: readonly [number, number, number];
+    halfExtents: readonly [number, number, number];
+    /** Yaw about `center`, radians, in the engine's `rotationY` convention. Default `0`. */
+    rotationY?: number;
+}
+/** Serializable contents of a {@link WorldSolids}: every layer's solids by layer id. */
+export interface WorldSolidsState {
+    layers: Record<string, readonly WorldSolid[]>;
+}
+/**
+ * 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
+ * own set without touching the rest. `solidObstaclesNear` (player and NPC movement),
+ * `syncWorldColliders` (physics backends) and `populateNavGridFromSolids` all read this one store.
+ */
+export interface WorldSolids {
+    /** Replace a layer's solids; an empty list removes the layer. */
+    set(layer: string, solids: readonly WorldSolid[]): void;
+    remove(layer: string): void;
+    /** Run several `set`/`remove` calls as one change: one index rebuild, one notification. */
+    batch(apply: () => void): void;
+    /** Solids in one layer, empty when absent. */
+    layer(layer: string): readonly WorldSolid[];
+    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[];
+    /** Every solid in every layer. */
+    all(): WorldSolid[];
+    count(): number;
+    /** Bumps on every change; cheap cache key for consumers. */
+    version(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): WorldSolidsState;
+    restore(state: WorldSolidsState): void;
+}
+/**
+ * Yaw-expanded world AABB of an oriented solid box.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export declare function worldSolidBounds(solid: WorldSolid): {
+    min: [number, number, number];
+    max: [number, number, number];
+};
+/**
+ * XZ footprint of a solid's world AABB, for 2D consumers such as nav grids.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export declare function worldSolidFootprint(solid: WorldSolid): Aabb;
+/**
+ * A store of static world solids in named layers.
+ * @capability world-solids collision for generated and authored world geometry (buildings, city lots, walls)
+ */
+export declare function createWorldSolids(options?: {
+    cellSize?: number;
+}): WorldSolids;
+/**
+ * One solid per generated building: its `bounds` footprint turned by `rotationY` about `center`,
+ * from the ground under its center up through its floors. `groundHeight` defaults to flat `0`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function buildingSolids(buildings: readonly GeneratedBuilding[], groundHeight?: (x: number, z: number) => number): WorldSolid[];
+/**
+ * Solids for every `structures` descriptor on an environment feature, skipping any marked `solid: false`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function structureSolids(world: EnvironmentWorldFeature, groundHeight?: (x: number, z: number) => number): WorldSolid[];
+/** Wall height, thickness and base for {@link wallSolids}. */
+export interface WallSolidOptions {
+    height: number;
+    thickness: number;
+    /** Ground height under a point; the wall stands on it at each segment's midpoint. Default flat `0`. */
+    groundHeight?: (x: number, z: number) => number;
+}
+/**
+ * One oriented solid per wall segment (see `wallSegments` in `world/walls`).
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function wallSolids(segments: readonly WallSegment[], options: WallSolidOptions): WorldSolid[];

package/dist/world/worldSolids.js

@@ -0,0 +1,240 @@
+import { resolveStructureBuildings } from "./environmentSummary.js";
+const DEFAULT_CELL_SIZE = 16;
+/** A solid covering more cells than this goes on an always-checked list instead of flooding the grid. */
+const MAX_CELLS_PER_SOLID = 256;
+const CELL_OFFSET = 32768;
+/**
+ * Yaw-expanded world AABB of an oriented solid box.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export function worldSolidBounds(solid) {
+    const yaw = solid.rotationY ?? 0;
+    const cos = Math.abs(Math.cos(yaw));
+    const sin = Math.abs(Math.sin(yaw));
+    const [hx, hy, hz] = solid.halfExtents;
+    const ex = hx * cos + hz * sin;
+    const ez = hx * sin + hz * cos;
+    const [cx, cy, cz] = solid.center;
+    return { min: [cx - ex, cy - hy, cz - ez], max: [cx + ex, cy + hy, cz + ez] };
+}
+/**
+ * XZ footprint of a solid's world AABB, for 2D consumers such as nav grids.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export function worldSolidFootprint(solid) {
+    const { min, max } = worldSolidBounds(solid);
+    return { minX: min[0], minZ: min[2], maxX: max[0], maxZ: max[2] };
+}
+/**
+ * A store of static world solids in named layers.
+ * @capability world-solids collision for generated and authored world geometry (buildings, city lots, walls)
+ */
+export function createWorldSolids(options = {}) {
+    const cellSize = options.cellSize ?? DEFAULT_CELL_SIZE;
+    const layerMap = new Map();
+    const grid = new Map();
+    const oversize = [];
+    const listeners = new Set();
+    let stamp = 0;
+    let total = 0;
+    let revision = 0;
+    let batchDepth = 0;
+    let pending = false;
+    const cellOf = (value) => Math.floor(value / cellSize);
+    const keyOf = (ix, iz) => (ix + CELL_OFFSET) * 65536 + (iz + CELL_OFFSET);
+    function index(entry) {
+        const x0 = cellOf(entry.minX);
+        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) {
+            oversize.push(entry);
+            return;
+        }
+        for (let ix = x0; ix <= x1; ix += 1) {
+            for (let iz = z0; iz <= z1; iz += 1) {
+                const key = keyOf(ix, iz);
+                const bucket = grid.get(key);
+                if (bucket === undefined)
+                    grid.set(key, [entry]);
+                else
+                    bucket.push(entry);
+            }
+        }
+    }
+    function rebuildIndex() {
+        grid.clear();
+        oversize.length = 0;
+        total = 0;
+        for (const entries of layerMap.values()) {
+            for (const entry of entries)
+                index(entry);
+            total += entries.length;
+        }
+    }
+    function changed() {
+        if (batchDepth > 0) {
+            pending = true;
+            return;
+        }
+        pending = false;
+        rebuildIndex();
+        revision += 1;
+        for (const listener of listeners)
+            listener();
+    }
+    function indexed(solid) {
+        const { min, max } = worldSolidBounds(solid);
+        return { solid, minX: min[0], minY: min[1], minZ: min[2], maxX: max[0], maxY: max[1], maxZ: max[2], stamp: 0 };
+    }
+    function overlaps(entry, min, max) {
+        return (entry.maxX >= min[0] &&
+            entry.minX <= max[0] &&
+            entry.maxY >= min[1] &&
+            entry.minY <= max[1] &&
+            entry.maxZ >= min[2] &&
+            entry.minZ <= max[2]);
+    }
+    return {
+        set(layer, solids) {
+            if (solids.length === 0) {
+                if (!layerMap.delete(layer))
+                    return;
+            }
+            else {
+                layerMap.set(layer, solids.map(indexed));
+            }
+            changed();
+        },
+        remove(layer) {
+            if (layerMap.delete(layer))
+                changed();
+        },
+        batch(apply) {
+            batchDepth += 1;
+            try {
+                apply();
+            }
+            finally {
+                batchDepth -= 1;
+            }
+            if (batchDepth === 0 && pending)
+                changed();
+        },
+        layer: (layer) => layerMap.get(layer)?.map((entry) => entry.solid) ?? [],
+        layers: () => [...layerMap.keys()],
+        inBox(min, max) {
+            stamp += 1;
+            const out = [];
+            if (total === 0)
+                return out;
+            const x0 = cellOf(min[0]);
+            const x1 = cellOf(max[0]);
+            const z0 = cellOf(min[2]);
+            const z1 = cellOf(max[2]);
+            if ((x1 - x0 + 1) * (z1 - z0 + 1) > grid.size) {
+                for (const entries of layerMap.values()) {
+                    for (const entry of entries)
+                        if (overlaps(entry, min, max))
+                            out.push(entry.solid);
+                }
+                return out;
+            }
+            for (let ix = x0; ix <= x1; ix += 1) {
+                for (let iz = z0; iz <= z1; iz += 1) {
+                    const bucket = grid.get(keyOf(ix, iz));
+                    if (bucket === undefined)
+                        continue;
+                    for (const entry of bucket) {
+                        if (entry.stamp === stamp)
+                            continue;
+                        entry.stamp = stamp;
+                        if (overlaps(entry, min, max))
+                            out.push(entry.solid);
+                    }
+                }
+            }
+            for (const entry of oversize)
+                if (overlaps(entry, min, max))
+                    out.push(entry.solid);
+            return out;
+        },
+        all: () => [...layerMap.values()].flatMap((entries) => entries.map((entry) => entry.solid)),
+        count: () => total,
+        version: () => revision,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        snapshot() {
+            const layers = {};
+            for (const [layer, entries] of layerMap)
+                layers[layer] = entries.map((entry) => entry.solid);
+            return { layers };
+        },
+        restore(state) {
+            layerMap.clear();
+            for (const [layer, solids] of Object.entries(state.layers)) {
+                if (solids.length > 0)
+                    layerMap.set(layer, solids.map(indexed));
+            }
+            changed();
+        },
+    };
+}
+/**
+ * One solid per generated building: its `bounds` footprint turned by `rotationY` about `center`,
+ * from the ground under its center up through its floors. `groundHeight` defaults to flat `0`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export function buildingSolids(buildings, groundHeight = () => 0) {
+    return buildings.map((building) => {
+        const { bounds, center } = building;
+        const yaw = building.rotationY ?? 0;
+        const localX = (bounds.minX + bounds.maxX) / 2 - center[0];
+        const localZ = (bounds.minZ + bounds.maxZ) / 2 - center[1];
+        const cos = Math.cos(yaw);
+        const sin = Math.sin(yaw);
+        const base = groundHeight(center[0], center[1]);
+        const halfHeight = (building.floors * building.floorHeight) / 2;
+        return {
+            center: [center[0] + localX * cos + localZ * sin, base + halfHeight, center[1] - localX * sin + localZ * cos],
+            halfExtents: [(bounds.maxX - bounds.minX) / 2, halfHeight, (bounds.maxZ - bounds.minZ) / 2],
+            ...(yaw === 0 ? {} : { rotationY: yaw }),
+        };
+    });
+}
+/**
+ * Solids for every `structures` descriptor on an environment feature, skipping any marked `solid: false`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export function structureSolids(world, groundHeight) {
+    const solids = [];
+    for (const descriptor of world.structures ?? []) {
+        if (descriptor.solid === false)
+            continue;
+        solids.push(...buildingSolids(resolveStructureBuildings(descriptor), groundHeight));
+    }
+    return solids;
+}
+/**
+ * One oriented solid per wall segment (see `wallSegments` in `world/walls`).
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export function wallSolids(segments, options) {
+    return segments
+        .filter((segment) => segment.length > 0)
+        .map((segment) => {
+        const mid = [(segment.from[0] + segment.to[0]) / 2, (segment.from[1] + segment.to[1]) / 2];
+        const base = options.groundHeight?.(mid[0], mid[1]) ?? 0;
+        // Local x runs along the segment: rotationY maps local +x to (cos, -sin) in XZ.
+        const yaw = -Math.atan2(segment.to[1] - segment.from[1], segment.to[0] - segment.from[0]);
+        return {
+            center: [mid[0], base + options.height / 2, mid[1]],
+            halfExtents: [segment.length / 2, options.height / 2, options.thickness / 2],
+            rotationY: yaw,
+        };
+    });
+}

package/dist/world.d.ts

@@ -32,7 +32,7 @@ export { steerYaw } from "./movement/steering.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
 export { createNavGrid, findPath, slopeStepCost, type NavGrid, type NavPoint } from "./nav/navGrid.js";
-export { buildNavAdjacency, closestPoint, raycastNav, type NavMeshAdjacency, type NavMeshData, type NavMeshLink, type NavMeshPath, } from "./nav/navMesh.js";
+export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, type NavMeshAdjacency, type NavMeshData, type NavMeshLink, type NavMeshPath, type NavMeshQuery, type NavMeshQueryOptions, type NavMeshQuerySnapshot, } from "./nav/navMesh.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, type PathFollowConfig, type PathFollowProgress, type PathFollowState, type PathProgress, type Waypoint, } from "./nav/pathFollow.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, type AttackMoveOrderPayload, type EmptyOrderPayload, type EngagementKindConfig, type EngagementOrderState, type MoveOrderPayload, type OrderKindConfig, type OrderMoveResult, type OrderMover, type OrderTargeting, type PatrolOrderPayload, type PatrolOrderState, type TargetedOrderPayload, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, type Order, type OrderCancelReason, type OrderEvent, type OrderIssueResult, type OrderKind, type OrderOutcome, type OrderPhase, type OrderProgress, type OrderQueue, type OrderQueueOptions, type OrderQueuePolicy, type OrderQueueState, type OrderRegistry, type OrderRejection, type OrderRequest, type OrderStartResult, type OrderTickReport, type OrderVec3, } from "./orders/orderQueue.js";
@@ -58,7 +58,7 @@ 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 BehaviorControl, type BehaviorInspection, type BehaviorResumePolicy, type BehaviorSnapshot, type BehaviorStatus, } from "./scene/behaviorRuntime.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 { createBodyBind } from "./scene/bodyBind.js";
 export { type ColliderPurpose, type EntityColliderSet, type ResolvedCollider } from "./scene/colliders.js";

package/dist/world.js

@@ -32,7 +32,7 @@ export { steerYaw } from "./movement/steering.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
 export { createNavGrid, findPath, slopeStepCost } from "./nav/navGrid.js";
-export { buildNavAdjacency, closestPoint, raycastNav, } from "./nav/navMesh.js";
+export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, } from "./nav/navMesh.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, } from "./nav/pathFollow.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, } from "./orders/orderQueue.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.18.1",
+  "version": "0.19.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

@@ -143,7 +143,7 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 
 ## JGengine notes
 
-- Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked PRs — point at those; do not paste full plan bodies.
+- Multi-session engine work spans GitHub issues and PRs — point at those; do not paste full plan bodies.
 - Prefer `bun run agent:bootstrap --check` status, branch names, and PR links as state anchors.
 - Local parallelism uses `.claude/worktrees/`; never invent `C:\tmp\…` Codex-shared trees.
 - Durable process changes belong in skills, not only the handoff.

package/skills/game-design/SKILL.md

@@ -33,8 +33,8 @@ An audit is not completion for a build/improve request. Finish when the slice is
 
 Before content, write a first-hour balance sheet: starting cash, time to first income, net income per hour at starting hardware and at ten times that hardware, bill cadence versus income, and the insolvency recovery path. Insolvency resets the affected player or changes their options; it never deletes the world. Express clicks and event rewards as a fraction of the designed income rate, never an unrelated flat payout.
 
-Declare currency `decimals` for income paid per second. Anchor time-based decay to `game.createdAt` or a persisted per-instance creation time, never a fixed wall-clock epoch. Test fractional income over real tick cadences before tuning prices.
+Currency precision, elapsed-time anchoring, and reset mechanics are implemented per `jgengine-gameplay` "Persistent economies and input"; test fractional income over real tick cadences before tuning prices.
 
 The first-60-seconds gate requires the first tutorial verb to be executable from spawn with starting inventory. Grant dependencies such as land, power, and slots or let players buy them in-context; the tutorial cannot lock the surface needed to complete itself. Placement previews show cost and affordability inline.
 
-For a persistent shared-world builder, compose neighborhood presence, declared command read scopes, membership storage, online-player batched ticks, territory, chat, and join retry UI through their engine owners. Verify capacity and first-player onboarding before scaling the content catalog.
+For a persistent shared-world builder, verify capacity and first-player onboarding before scaling the content catalog; presence, command read scopes, territory, chat, and join retry UI come from their owners in `jgengine-world`, `jgengine-ui`, and `jgengine-multiplayer`.

package/skills/jgengine/SKILL.md

@@ -5,7 +5,9 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-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.
+This skill decides what to load; it is not an engine manual. Package map, commands, layering, and license live in the JGengine README (repo-root [`README.md`](../../../README.md) in the monorepo, [jgengine.com](https://jgengine.com) from a created project); open it when you need one of those facts.
+
+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/`.
 
 ## 1. Establish the target
 
@@ -20,7 +22,7 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 - HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock face)
 - one observable completion scenario
 
-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/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). 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.
 
@@ -46,9 +48,9 @@ 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) 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.
+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.
+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.