@jgengine/core 0.18.0 → 0.19.0

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

@@ -21,6 +21,7 @@ export { evaluateQteSequence, pendingQteStep, type QteStep } from "./interaction
 export { evaluateSkillCheck, skillCheckZoneAt, type SkillCheckConfig, type SkillCheckResult, } from "./interaction/skillCheck.js";
 export { resolveLocalAvoidance, type AvoidanceAgent, type LocalAvoidanceOptions } from "./movement/avoidance.js";
 export { assignFormationSlots, boxFormation, circleFormation, facingYaw, lineFormation, placeFormation, wedgeFormation, type BoxFormationOptions, type CircleFormationOptions, type FormationSlotGenerator, type LineFormationOptions, type SlotAssignmentOptions, type WedgeFormationOptions, } from "./movement/formation.js";
+export { CREATIVE_FLIGHT_TUNING, HOVER_FLIGHT_TUNING, NOCLIP_FLIGHT_TUNING, SPECTATOR_FLIGHT_TUNING, advanceFreeFlight, createFreeFlightController, createFreeFlightState, resolveFlightStep, resolveFreeFlightIntent, resolveFreeFlightIntentFromInput, type FreeFlightBindings, type FreeFlightController, type FreeFlightIntent, type FreeFlightMode, type FreeFlightState, type FreeFlightStep, type FreeFlightTuning, } from "./movement/freeFlight.js";
 export { createGlideModel } from "./movement/glideModel.js";
 export { createGrappleSwing } from "./movement/grappleSwing.js";
 export { createLeaderTrail } from "./movement/leaderTrail.js";
@@ -31,6 +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, 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";
@@ -39,7 +41,7 @@ export { createBuoyantBody } from "./physics/buoyancy.js";
 export { Carryable, carrySpeedMultiplier } from "./physics/carryable.js";
 export { createDamageModel } from "./physics/damageZones.js";
 export { tickDrivableVehicle } from "./physics/drivableVehicle.js";
-export { createAircraftDynamics, type AircraftDynamics, type AircraftKind, type AircraftOptions, type AircraftStep, type AircraftTuning, type FlightControlInput, type FlightControlRates, type FlightVector, } from "./physics/flightDynamics.js";
+export { createAircraftDynamics, type AircraftAxis, type AircraftDynamics, type AircraftKind, type AircraftOptions, type AircraftStep, type AircraftTuning, type FlightControlInput, type FlightControlRates, type FlightVector, } from "./physics/flightDynamics.js";
 export { ForceVolume, PlatformCarry } from "./physics/forceVolume.js";
 export { combineGravity, pointGravity, uniformGravity, type GravityField, type GravityVector, type PointGravityOptions, } from "./physics/gravityField.js";
 export { createKinematicVehicle, type KinematicChassisTuning, type KinematicDynamicsTuning, type KinematicPowertrainTuning, type KinematicSteeringTuning, type KinematicVehicle, type KinematicVehicleStep, type KinematicVehicleTuning, } from "./physics/kinematicVehicle.js";
@@ -56,8 +58,8 @@ 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, type BehaviorControl, type BehaviorInspection, type BehaviorResumePolicy, type BehaviorSnapshot, type BehaviorStatus, } from "./scene/behaviorRuntime.js";
-export { patrol, player, talkable, wander, type BehaviorDescriptor } from "./scene/behaviors.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";
 export { type StatCatalog, type StatValue } from "./scene/entityStats.js";

package/dist/world.js

@@ -21,6 +21,7 @@ export { evaluateQteSequence, pendingQteStep } from "./interaction/qte.js";
 export { evaluateSkillCheck, skillCheckZoneAt, } from "./interaction/skillCheck.js";
 export { resolveLocalAvoidance } from "./movement/avoidance.js";
 export { assignFormationSlots, boxFormation, circleFormation, facingYaw, lineFormation, placeFormation, wedgeFormation, } from "./movement/formation.js";
+export { CREATIVE_FLIGHT_TUNING, HOVER_FLIGHT_TUNING, NOCLIP_FLIGHT_TUNING, SPECTATOR_FLIGHT_TUNING, advanceFreeFlight, createFreeFlightController, createFreeFlightState, resolveFlightStep, resolveFreeFlightIntent, resolveFreeFlightIntentFromInput, } from "./movement/freeFlight.js";
 export { createGlideModel } from "./movement/glideModel.js";
 export { createGrappleSwing } from "./movement/grappleSwing.js";
 export { createLeaderTrail } from "./movement/leaderTrail.js";
@@ -31,6 +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, 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";
@@ -56,8 +58,8 @@ export { partsBounds, registerAssetGenerator } from "./scene/assetGenerator.js";
 export { applyRotationPolicy, headingToRotationY, normalizeDegrees, parseAssetSpace, parseRotationPolicy, resolveAnchorOffset, resolveFacingRotationY, rotatedFootprint, rotationYToHeading, snapHeading, toEngineUnits, validateAssetSpace, } from "./scene/assetSpace.js";
 export { collectAuthoredTriggers, createAuthoredTriggerRuntime, getTriggerAction, listTriggerActions, pointInVolume, registerTriggerAction, } from "./scene/authoredTriggers.js";
 export { selectAutoTarget } from "./scene/autoTarget.js";
-export { advanceBehaviors, behaviorControl, } from "./scene/behaviorRuntime.js";
-export { patrol, player, talkable, wander } from "./scene/behaviors.js";
+export { advanceBehaviors, behaviorControl, registerBehaviorActions, } from "./scene/behaviorRuntime.js";
+export { patrol, player, talkable, wander, } from "./scene/behaviors.js";
 export { createBodyBind } from "./scene/bodyBind.js";
 export {} from "./scene/colliders.js";
 export {} from "./scene/entityStats.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.18.0",
+  "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.
-- Papercuts and durable process changes belong in `PAPERCUTS.md` / skills, not only the handoff.
+- Durable process changes belong in skills, not only the handoff.

package/skills/game-design/SKILL.md

@@ -11,7 +11,7 @@ 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.
 
-Read [references/application-playbook.md](references/application-playbook.md) only when the task explicitly calls for design depth — a design brief, a redesign, or "make this fun/better" work; it is not a mandatory step of creating a game. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
+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
 
@@ -28,3 +28,13 @@ Every design pass yields an observed journey, a north star (promise, pillars, an
 An audit is not completion for a build/improve request. Finish when the slice is playable, a fresh player can state goal/choice/consequence, failure/recovery behave as intended, and evidence supports the pillars. Use `jgengine-verify` and `workflow` to ship.
 
 **Required: player death is a designed, visible moment.** If the game can kill or down the player, death is part of the experience contract, not an invisible state reset. A lethal hit must resolve into an authored beat the player perceives and understands — a death or downed moment, the stakes it carries, and a legible path back into play (respawn, revive, restart) — never a silent teleport to spawn. Design what death means for this pitch (permadeath, checkpoint, bleed-out-and-revive, run reset) and treat "player dies with no acknowledged consequence" as a failure/recovery defect. `jgengine-ui` owns building the screen and respawn feedback.
+
+## Persistent-builder checks
+
+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.
+
+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, 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,10 +5,14 @@ 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
 
+For greenfield builds, write `src/art-direction.md` before any code.
+
 Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
 
 - player point of view and controls
@@ -18,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.
 
@@ -44,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.