@jgengine/shell 0.10.0 → 0.12.0

package/skills/jgengine-world/capabilities.md

@@ -0,0 +1,476 @@
+<!-- GENERATED by scripts/gen-capability-index.ts — do not edit. Regenerate: bun run gen:capabilities -->
+
+# jgengine-world — capability index
+
+Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
+
+## area-effect-field — source-following area membership with enter/refresh/leave edges, stacking, and cleanup
+
+- `createAreaEffectField` (function) · `import { createAreaEffectField } from "@jgengine/core/world"`
+
+## area-stack-additive — sum a magnitude across overlapping area memberships
+
+- `sumMagnitude` (function) · `import { sumMagnitude } from "@jgengine/core/world"`
+
+## area-stack-capped — cap area memberships per stack key at a maximum count
+
+- `cappedStacks` (function) · `import { cappedStacks } from "@jgengine/core/world"`
+
+## area-stack-extremum — keep only the strongest or weakest overlapping area membership
+
+- `extremumStack` (function) · `import { extremumStack } from "@jgengine/core/world"`
+
+## area-stack-independent — apply every overlapping area membership independently
+
+- `independentStacks` (function) · `import { independentStacks } from "@jgengine/core/world"`
+
+## area-stack-unique — keep one area membership per stack key, strongest wins
+
+- `uniqueByStackKey` (function) · `import { uniqueByStackKey } from "@jgengine/core/world"`
+
+## asset-anchor — resolve a model's pivot offset from its footprint center
+
+- `resolveAnchorOffset` (function) · `import { resolveAnchorOffset } from "@jgengine/core/world"`
+
+## asset-facing — resolve a placement heading into a Three.js Y-rotation using canonical forward
+
+- `resolveFacingRotationY` (function) · `import { resolveFacingRotationY } from "@jgengine/core/world"`
+
+## asset-footprint — rotate a rectangular footprint into its axis-aligned extent
+
+- `rotatedFootprint` (function) · `import { rotatedFootprint } from "@jgengine/core/world"`
+
+## asset-heading — turn a north-relative degree heading into a Three.js Y-rotation
+
+- `headingToRotationY` (function) · `import { headingToRotationY } from "@jgengine/core/world"`
+- `normalizeDegrees` (function) · `import { normalizeDegrees } from "@jgengine/core/world"`
+- `rotationYToHeading` (function) · `import { rotationYToHeading } from "@jgengine/core/world"`
+
+## asset-load-diagnostics — classify a model fetch (missing / HTML fallback / corrupt / unsupported) before parsing
+
+- `classifyAssetResponse` (function) · `import { classifyAssetResponse } from "@jgengine/core/scene/assetDiagnostics"`
+
+## asset-space — parse serialized asset-space metadata into a validated shape
+
+- `parseAssetSpace` (function) · `import { parseAssetSpace } from "@jgengine/core/world"`
+- `validateAssetSpace` (function) · `import { validateAssetSpace } from "@jgengine/core/world"`
+
+## asset-units — convert a source-space length to engine meters via catalog unit scale
+
+- `toEngineUnits` (function) · `import { toEngineUnits } from "@jgengine/core/world"`
+
+## attack-move-order — advance-and-engage order that pursues hostiles en route and completes at its destination
+
+- `defineAttackMoveOrder` (function) · `import { defineAttackMoveOrder } from "@jgengine/core/world"`
+
+## authored-entities — spawn authored mob/boss markers from the editor document at runtime
+
+- `authoredEntitySpawns` (function) · `import { authoredEntitySpawns } from "@jgengine/core/world/authoredEntities"`
+
+## authored-objects — marker kinds resolved as entity spawns, not static props
+
+- `ENTITY_MARKER_KINDS` (const) · `import { ENTITY_MARKER_KINDS } from "@jgengine/core/world/authoredObjects"`
+- `markerCatalogId` (function) · `import { markerCatalogId } from "@jgengine/core/world"`
+- `placeAuthoredObjects` (function) · `import { placeAuthoredObjects } from "@jgengine/core/world"`
+- `resolveAuthoredObjects` (function) · `import { resolveAuthoredObjects } from "@jgengine/core/world"`
+
+## authored-spawn — read spawn points and markers from the editor document
+
+- `authoredSpawnPosition` (function) · `import { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn"`
+- `authoredSpawnRotation` (function) · `import { authoredSpawnRotation } from "@jgengine/core/world/authoredSpawn"`
+- `markersOfKind` (function) · `import { markersOfKind } from "@jgengine/core/world/authoredSpawn"`
+
+## authored-triggers — built-in announce/win/advance actions authorable on any marker or volume
+
+- `BUILTIN_TRIGGER_ACTIONS` (const) · `import { BUILTIN_TRIGGER_ACTIONS } from "@jgengine/core/scene/authoredTriggers"`
+- `collectAuthoredTriggers` (function) · `import { collectAuthoredTriggers } from "@jgengine/core/world"`
+- `createAuthoredTriggerRuntime` (function) · `import { createAuthoredTriggerRuntime } from "@jgengine/core/world"`
+- `createTriggerOutcome` (function) · `import { createTriggerOutcome } from "@jgengine/core/scene/authoredTriggers"`
+- `registerBuiltinTriggerActions` (function) · `import { registerBuiltinTriggerActions } from "@jgengine/core/scene/authoredTriggers"`
+- `registerTriggerAction` (function) · `import { registerTriggerAction } from "@jgengine/core/world"`
+
+## behavior-control — pause/disable/resume/seek/inspect behavior instances per entity
+
+- `behaviorControl` (function) · `import { behaviorControl } from "@jgengine/core/world"`
+
+## behavior-tick — auto-advance patrol/wander behaviors on spawned entities, no per-game route loop
+
+- `advanceBehaviors` (function) · `import { advanceBehaviors } from "@jgengine/core/world"`
+
+## body-bind — mirror sim-body snapshots onto scene entities each tick, no per-body setPose
+
+- `createBodyBind` (function) · `import { createBodyBind } from "@jgengine/core/world"`
+
+## build-footprint-cells — grid cells a snapped build piece footprint covers (footprintGrid occupancy bridge)
+
+- `footprintCells` (function) · `import { footprintCells } from "@jgengine/core/world/buildSockets"`
+
+## build-socket-catalog — data-driven named-socket snap catalog for modular base building
+
+- `createBuildSocketCatalog` (function) · `import { createBuildSocketCatalog } from "@jgengine/core/world/buildSockets"`
+
+## city-district — polygon math for road-derived blocks, parcels, and buildable footprints
+
+- `Vec2` (type) · `import { Vec2 } from "@jgengine/core/world/cityGeometry"`
+- `resolveCityObject` (function) · `import { resolveCityObject } from "@jgengine/core/world"`
+
+## companion-intent — resolve a companion's command + threat context into a per-tick follow/hold/engage/assist intent
+
+- `resolveCompanionIntent` (function) · `import { resolveCompanionIntent } from "@jgengine/core/scene/companion"`
+
+## companion-roster — manage tamed companions — allegiance, commands, per-companion stats/leveling, and mobBrain-shaped intent
+
+- `createCompanionRoster` (function) · `import { createCompanionRoster } from "@jgengine/core/scene/companion"`
+
+## contour-interval — readable auto-spacing for elevation contours
+
+- `chooseContourInterval` (function) · `import { chooseContourInterval } from "@jgengine/core/world"`
+
+## crouch-prone — stance/pose transitions that change the hitbox
+
+- `createPoseState` (function) · `import { createPoseState } from "@jgengine/core/world"`
+
+## decay-meter — survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+
+- `createDecayMeterSet` (function) · `import { createDecayMeterSet } from "@jgengine/core/procedural"`
+
+## elevation-readout — cursor height and delta-from-reference feedback
+
+- `sampleElevation` (function) · `import { sampleElevation } from "@jgengine/core/world"`
+
+## elevation-summary — selection min/max/mean and relief over a region
+
+- `summarizeElevation` (function) · `import { summarizeElevation } from "@jgengine/core/world"`
+
+## entity-meta — cast-free narrow of SceneEntity.meta via a type guard
+
+- `entityMetaOf` (function) · `import { entityMetaOf } from "@jgengine/core/world"`
+
+## flight-dynamics — simulate fixed-wing, helicopter, and VTOL aircraft
+
+- `createAircraftDynamics` (function) · `import { createAircraftDynamics } from "@jgengine/core/world"`
+
+## follow-trail — trailing follower/snake formation that chases a leader
+
+- `createLeaderTrail` (function) · `import { createLeaderTrail } from "@jgengine/core/world"`
+
+## footprint-grid — multi-cell footprint occupancy/reservation on a shared build grid
+
+- `createFootprintGrid` (function) · `import { createFootprintGrid } from "@jgengine/core/world"`
+
+## formation-assignment — stable deterministic member-to-slot matching for a group formation
+
+- `assignFormationSlots` (function) · `import { assignFormationSlots } from "@jgengine/core/world"`
+
+## formation-box — box/grid slot generator for group destinations
+
+- `boxFormation` (function) · `import { boxFormation } from "@jgengine/core/world"`
+
+## formation-circle — ring/cordon slot generator for group destinations
+
+- `circleFormation` (function) · `import { circleFormation } from "@jgengine/core/world"`
+
+## formation-facing — group facing yaw from a travel direction on the XZ plane
+
+- `facingYaw` (function) · `import { facingYaw } from "@jgengine/core/world"`
+
+## formation-line — line (abreast) slot generator for group destinations
+
+- `lineFormation` (function) · `import { lineFormation } from "@jgengine/core/world"`
+
+## formation-placement — place a group formation's world slots around a destination
+
+- `placeFormation` (function) · `import { placeFormation } from "@jgengine/core/world"`
+
+## formation-wedge — wedge/arrowhead slot generator for group destinations
+
+- `wedgeFormation` (function) · `import { wedgeFormation } from "@jgengine/core/world"`
+
+## forward-axis — declared front convention for parametric assets — auto-orient product shots
+
+- `DEFAULT_FORWARD` (const) · `import { DEFAULT_FORWARD } from "@jgengine/core/world"`
+
+## glide — gliding/wingsuit descent control from a launch
+
+- `createGlideModel` (function) · `import { createGlideModel } from "@jgengine/core/world"`
+
+## grapple-swing — grappling-hook rope swing physics with reel-in
+
+- `createGrappleSwing` (function) · `import { createGrappleSwing } from "@jgengine/core/world"`
+
+## gravity-field — sample configurable uniform, radial, or combined gravity
+
+- `combineGravity` (function) · `import { combineGravity } from "@jgengine/core/world"`
+- `pointGravity` (function) · `import { pointGravity } from "@jgengine/core/world"`
+- `uniformGravity` (function) · `import { uniformGravity } from "@jgengine/core/world"`
+
+## hold-order — stand-ground order that holds position until preempted or canceled
+
+- `defineHoldOrder` (function) · `import { defineHoldOrder } from "@jgengine/core/world"`
+
+## interest-census — running active/dormant gate tally folded into the caller's tick loop
+
+- `createInterestCensus` (function) · `import { createInterestCensus } from "@jgengine/core/world"`
+
+## interest-gate — per-agent sleep/wake + cadence gate state so far agents skip expensive ticks
+
+- `createInterestGateState` (function) · `import { createInterestGateState } from "@jgengine/core/world"`
+
+## interest-scheduler — advance a sleep/wake gate with hysteresis, cadence tiers, and stagger
+
+- `advanceInterestGate` (function) · `import { advanceInterestGate } from "@jgengine/core/world"`
+
+## interest-stagger — deterministic per-id cadence phase that spreads sibling gate ticks across frames
+
+- `interestPhase` (function) · `import { interestPhase } from "@jgengine/core/world"`
+
+## limb-health — per-body-part/region health tracked separately
+
+- `createMultiRegionHealth` (function) · `import { createMultiRegionHealth } from "@jgengine/core/procedural"`
+
+## local-avoidance — bounded deterministic local collision avoidance for moving agents
+
+- `resolveLocalAvoidance` (function) · `import { resolveLocalAvoidance } from "@jgengine/core/world"`
+
+## lockpick — a solvable grid depth-puzzle with fog-of-war, gates, and hidden traps
+
+- `generateLock` (function) · `import { generateLock } from "@jgengine/core/world"`
+
+## mesh-hitboxes — shots pass through holes in concave models — opted-in catalog assets raycast their actual triangles instead of the fitted box.
+
+- `ColliderShape` (type) · `import { ColliderShape } from "@jgengine/core/scene/colliders"`
+
+## mesh-movement — the walking player slides against a mesh collider's compound `boxes` — a capsule walks THROUGH an opted-in archway opening and is stopped by its pillars/lintel instead of one outer box.
+
+- `ColliderShape` (type) · `import { ColliderShape } from "@jgengine/core/scene/colliders"`
+
+## minimap-bake — rasterize authored terrain + zones into a top-down minimap image
+
+- `bakeMinimapImage` (function) · `import { bakeMinimapImage } from "@jgengine/core/world"`
+- `minimapBakeToPngDataUri` (function) · `import { minimapBakeToPngDataUri } from "@jgengine/core/world"`
+
+## minimap-track — project a world point to a 0..1 fraction along a linear track axis
+
+- `trackFraction` (function) · `import { trackFraction } from "@jgengine/core/world/minimapTrack"`
+
+## model-sockets — named attachment points read from a model
+
+- `ModelNode` (interface) · `import { ModelNode } from "@jgengine/core/world"`
+
+## move-order — go-to-point order that completes on arrival, composed over a motion adapter
+
+- `defineMoveOrder` (function) · `import { defineMoveOrder } from "@jgengine/core/world"`
+
+## order-queue — serializable per-entity command queue with lifecycle, preemption, and pluggable order kinds
+
+- `createOrderQueue` (function) · `import { createOrderQueue } from "@jgengine/core/world"`
+
+## order-registry — register order verbs (move/attack/custom) as data so engine code never branches on a verb
+
+- `createOrderRegistry` (function) · `import { createOrderRegistry } from "@jgengine/core/world"`
+
+## path-follow-progress — read normalized/distance/segment progress from follow state
+
+- `pathFollowProgress` (function) · `import { pathFollowProgress } from "@jgengine/core/world"`
+
+## path-follow-seek — jump a path-follower to normalized/distance/segment progress
+
+- `pathFollowSeek` (function) · `import { pathFollowSeek } from "@jgengine/core/world"`
+
+## path-length — total polyline distance for progress math and seeding
+
+- `pathLength` (function) · `import { pathLength } from "@jgengine/core/world"`
+
+## path-network — build a deterministic road/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+
+- `buildPathNetwork` (function) · `import { buildPathNetwork } from "@jgengine/core/world/pathNetwork"`
+
+## path-terrain — apply flatten/grade/carve/retaining path profiles to a terrain field
+
+- `applyPathProfiles` (function) · `import { applyPathProfiles } from "@jgengine/core/world"`
+- `withPathProfiles` (function) · `import { withPathProfiles } from "@jgengine/core/world"`
+
+## patrol-order — waypoint-route order that cycles a path, looping or completing at the end
+
+- `definePatrolOrder` (function) · `import { definePatrolOrder } from "@jgengine/core/world"`
+
+## piece-sockets-from-model — derive build-piece snap sockets from a model's named attach points
+
+- `pieceSocketsFromModel` (function) · `import { pieceSocketsFromModel } from "@jgengine/core/world/buildSockets"`
+
+## place-asset — resolve a placement commit into a shared asset placement payload
+
+- `PlaceAssetResult` (interface) · `import { PlaceAssetResult } from "@jgengine/core/world"`
+- `placeAssetFromCommit` (function) · `import { placeAssetFromCommit } from "@jgengine/core/world"`
+- `resolvePlaceAsset` (function) · `import { resolvePlaceAsset } from "@jgengine/core/world"`
+
+## placement-controller — interactive build-mode ghost preview and commit
+
+- `createPlacementController` (function) · `import { createPlacementController } from "@jgengine/core/world"`
+
+## placement-math — grid/surface footprint validity for build mode
+
+- `validatePlacement` (function) · `import { validatePlacement } from "@jgengine/core/world"`
+
+## placement-rotation — apply a rotation policy to a candidate placement heading
+
+- `applyRotationPolicy` (function) · `import { applyRotationPolicy } from "@jgengine/core/world"`
+- `parseRotationPolicy` (function) · `import { parseRotationPolicy } from "@jgengine/core/world"`
+- `snapHeading` (function) · `import { snapHeading } from "@jgengine/core/world"`
+
+## pole-line — editor-authorable poles + sagging cables along a path
+
+- `POLE_LINE_KIND` (const) · `import { POLE_LINE_KIND } from "@jgengine/core/world/poleLineKind"`
+
+## population-director — ambient per-region creature population manager with timed weighted respawns and caps
+
+- `createPopulationDirector` (function) · `import { createPopulationDirector } from "@jgengine/core/ai/populationDirector"`
+
+## portable-marker-source — project caller-owned arrays or subscribable stores into cached minimap marker snapshots without a MarkerSet
+
+- `createMarkerSource` (function) · `import { createMarkerSource } from "@jgengine/core/world"`
+
+## proximity-prompt — a "press E" contextual prompt shown near an interactable
+
+- `resolveActivePrompt` (function) · `import { resolveActivePrompt } from "@jgengine/core/world"`
+
+## pursuit — chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+
+- `advancePursuit` (function) · `import { advancePursuit } from "@jgengine/core/ai/pursuit"`
+
+## qte — a quick-time-event timed input sequence with hit windows
+
+- `evaluateQteSequence` (function) · `import { evaluateQteSequence } from "@jgengine/core/world"`
+
+## reputation — faction standing that crosses named reputation tiers
+
+- `tierForStanding` (function) · `import { tierForStanding } from "@jgengine/core/world"`
+
+## resource-node — depletable, respawning harvest nodes with tool-dependent yields
+
+- `createResourceNodeField` (function) · `import { createResourceNodeField } from "@jgengine/core/world/resourceNode"`
+
+## rts-control-groups — map Ctrl+digit / digit / double-tap presses onto selection-bookmark bind / recall / focus intents
+
+- `controlGroupKey` (function) · `import { controlGroupKey } from "@jgengine/core/world"`
+- `resolveControlGroupIntent` (function) · `import { resolveControlGroupIntent } from "@jgengine/core/world"`
+
+## selection-bookmark-recall — fold a saved set into the active selection with stale-ref pruning and a caller focus hook
+
+- `recallSelectionBookmark` (function) · `import { recallSelectionBookmark } from "@jgengine/core/world"`
+
+## selection-bookmarks — keyed saved-set store (RTS control groups, camera bookmarks, saved squads) with prune + serialize
+
+- `createSelectionBookmarks` (function) · `import { createSelectionBookmarks } from "@jgengine/core/world"`
+
+## skill-check — a timing-bar skill check where you release inside a zone
+
+- `skillCheckZoneAt` (function) · `import { skillCheckZoneAt } from "@jgengine/core/world"`
+
+## soil-patch — editor-authorable terrain crack/moss material variation
+
+- `SOIL_KIND` (const) · `import { SOIL_KIND } from "@jgengine/core/world"`
+
+## spatial-region-box — sample uniformly within an axis-aligned 3D box
+
+- `boxRegion` (function) · `import { boxRegion } from "@jgengine/core/world"`
+
+## spatial-region-custom — wrap a caller-defined sampler and bounds test as a region
+
+- `customRegion` (function) · `import { customRegion } from "@jgengine/core/world"`
+
+## spatial-region-point-set — sample from a fixed, optionally weighted candidate point table
+
+- `pointSetRegion` (function) · `import { pointSetRegion } from "@jgengine/core/world"`
+
+## spatial-region-polygon — sample within an arbitrary closed polygon on the XZ plane
+
+- `polygonRegion` (function) · `import { polygonRegion } from "@jgengine/core/world"`
+
+## spatial-region-shell — sample within a 3D spherical shell, volume- or radius-uniform
+
+- `shellRegion` (function) · `import { shellRegion } from "@jgengine/core/world"`
+
+## spatial-region-sphere — sample within a filled 3D ball, volume- or radius-uniform
+
+- `sphereRegion` (function) · `import { sphereRegion } from "@jgengine/core/world"`
+
+## spatial-region-weighted — compose sub-regions behind a weighted selection policy
+
+- `weightedRegion` (function) · `import { weightedRegion } from "@jgengine/core/world"`
+
+## spatial-sample — draw one deterministic position from a region under include/exclude/distance constraints
+
+- `samplePoint` (function) · `import { samplePoint } from "@jgengine/core/world"`
+
+## spatial-sample-batch — place many deterministic spaced points from a region with minimum separation
+
+- `sampleBatch` (function) · `import { sampleBatch } from "@jgengine/core/world"`
+
+## spatial-sample-stratified — evenly cover an area with one jittered point per grid cell, deterministic
+
+- `sampleStratified` (function) · `import { sampleStratified } from "@jgengine/core/world"`
+
+## stop-order — halt-and-complete order that brings a unit to an immediate standstill
+
+- `defineStopOrder` (function) · `import { defineStopOrder } from "@jgengine/core/world"`
+
+## surface-drape — lift an XZ polyline onto sculpted terrain
+
+- `drapePolyline` (function) · `import { drapePolyline } from "@jgengine/core/world"`
+
+## surface-grid — terrain-following reference grid that is not occluded by relief
+
+- `surfaceGridLines` (function) · `import { surfaceGridLines } from "@jgengine/core/world"`
+
+## surface-ring — surface-following placement guide ring
+
+- `surfaceRing` (function) · `import { surfaceRing } from "@jgengine/core/world"`
+
+## target-acquirer — stateful held-target wrapper over an acquisition policy with retention
+
+- `createTargetAcquirer` (function) · `import { createTargetAcquirer } from "@jgengine/core/world"`
+
+## target-acquisition — composable candidate/eligibility/range/perception/score/tie-break/retention target pick
+
+- `acquireTarget` (function) · `import { acquireTarget } from "@jgengine/core/world"`
+
+## targeted-order — pursue-a-target order with leash/standoff that ends when the target is gone
+
+- `defineTargetedOrder` (function) · `import { defineTargetedOrder } from "@jgengine/core/world"`
+
+## terrain-contours — iso-elevation contour lines that drape on sculpted terrain
+
+- `extractContours` (function) · `import { extractContours } from "@jgengine/core/world"`
+
+## terrain-guides — one-call adaptive contours for a terrain field
+
+- `terrainContourGuides` (function) · `import { terrainContourGuides } from "@jgengine/core/world"`
+
+## terrain-raycast — pick a point on a heightfield along a camera/pointer ray
+
+- `raycastHeightField` (function) · `import { raycastHeightField } from "@jgengine/core/world/terrain"`
+
+## touch-controls — default on-screen button silhouette for a touch action
+
+- `touchButtonShape` (function) · `import { touchButtonShape } from "@jgengine/core/input/touchScheme"`
+
+## visibility-field — per-viewer-group observed/remembered/hidden fog-of-war knowledge with terrain memory and authoritative entity disclosure
+
+- `createVisibilityField` (function) · `import { createVisibilityField } from "@jgengine/core/world"`
+
+## volumetric-clouds — raymarched cloud layer sky option
+
+- `VolumetricCloudsConfig` (interface) · `import { VolumetricCloudsConfig } from "@jgengine/core/world"`
+
+## world-environment — compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+
+- `environment` (function) · `import { environment } from "@jgengine/core/world"`
+
+## world-place — declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
+
+- `world` (function) · `import { world } from "@jgengine/core/world"`
+
+## world-seed — derive a deterministic generator/scatter seed from world id + save/run seed
+
+- `seedForPlace` (function) · `import { seedForPlace } from "@jgengine/core/world"`

package/skills/jgengine-world/recipes/commanding-entities.md

@@ -0,0 +1,128 @@
+# Recipe — commanding entities (select → order → tick → resolve)
+
+**What this wires:** direct command over a group of entities — pick some, issue
+intent, watch them carry it out and interact on arrival. This is a *composition*,
+not a genre. The exact same wiring is the command layer of a base-defense wave, a
+squad-tactics turn, a creature-herding puzzle, or the topdown-survival phase of a
+game that was a card game a minute ago. You swap content, camera, and
+win-condition — never this architecture.
+
+It composes four primitives across three seams. The engine never touches your
+entity store directly; you supply narrow adapters, so the same command loop runs
+over any movement/combat model.
+
+## The seams
+
+- **Pick → ids.** `createSelectionSet` is an ordered, de-duplicated set of entity
+  ids. What *fills* it is up to you — a pointer marquee, a card that names a lane,
+  an ability that grabs everything in a radius, an AI planner. Selection is just
+  ids; it does not know or care how they were chosen.
+- **Intent → per-entity queue.** Build one shared `createOrderRegistry` and give
+  each commandable entity its own `createOrderQueue`. Register verbs as *data*
+  (`defineMoveOrder`, `defineAttackMoveOrder`, `defineTargetedOrder`, or your
+  own). Every verb composes over two adapters **you** implement against your
+  entity store: `OrderMover` (`position` / `moveToward` / `halt`) and
+  `OrderTargeting` (`acquire` / `positionOf`). This adapter boundary is what makes
+  the loop genre-free.
+- **Resolve → your effect.** In `onTick`, advance each queue. Engagement verbs
+  write `{ engaging, inRange }` into `order.state`; you read that flag and resolve
+  the actual interaction your way — damage, harvest, repair, heal, dialogue —
+  through the combat seam `ctx.scene.entity.effect(...)`. Orders decide *when*;
+  the game decides *what*.
+
+## Connected wiring
+
+```ts
+import { createSelectionSet } from "@jgengine/core/scene/selection";
+import {
+  createOrderRegistry,
+  createOrderQueue,
+  defineMoveOrder,
+  defineAttackMoveOrder,
+  defineTargetedOrder,
+} from "@jgengine/core/world";
+
+// --- once, at setup -------------------------------------------------------
+
+// Adapters bind orders to YOUR entity store — the only game-specific glue.
+const mover = {
+  position: (id) => entities.get(id).pos,
+  moveToward: (id, to, dt) => stepToward(entities.get(id), to, dt), // your movement
+  halt: (id) => (entities.get(id).vel = [0, 0, 0]),
+};
+const targeting = {
+  positionOf: (id) => entities.get(id)?.pos,
+  acquire: (id) => nearestEnemyOf(id), // your target pick (kd-tree, grid, faction…)
+};
+
+const registry = createOrderRegistry();
+registry.register(defineMoveOrder({ kind: "move", mover }));
+registry.register(defineAttackMoveOrder({ kind: "attack-move", mover, targeting }));
+registry.register(defineTargetedOrder({ kind: "attack", mover, targeting }));
+
+const queues = new Map(); // entityId -> OrderQueue
+const queueOf = (id) => {
+  let q = queues.get(id);
+  if (!q) queues.set(id, (q = createOrderQueue(registry)));
+  return q;
+};
+
+const selection = createSelectionSet();
+
+// --- on a command (pointer marquee, a card play, an ability, an AI plan) --
+
+function commandSelection(kind, payload) {
+  for (const id of selection) {
+    queueOf(id).issue({ kind, payload, policy: "replace" }); // shift-queue => "append"
+  }
+}
+// e.g. commandSelection("attack-move", { point: worldHit });
+
+// --- every frame ----------------------------------------------------------
+
+function onTick(ctx, dt) {
+  for (const [id, q] of queues) {
+    q.tick(ctx, dt); // activates/advances/completes orders, drives the mover
+    const active = q.active;
+    if (active?.state?.inRange) {
+      // Engagement verb says a target is in range — resolve it the game's way.
+      ctx.scene.entity.effect({ from: id, to: active.state.target, effect: "damage" });
+    }
+  }
+}
+```
+
+That is the whole command loop. Everything genre-specific lives in the three
+functions you supplied (`stepToward`, `nearestEnemyOf`, and the `"damage"` effect)
+— never in the order/selection primitives.
+
+## Composing it into different games (and hybrids)
+
+The wiring above is fixed; four independent knobs turn it into different play:
+
+- **Who fills the selection.** Pointer marquee for an RTS; a targeting card for a
+  card-driven skirmish; an AoE ability for a spell; an AI director for autobattle.
+  Same `selection`, different caller.
+- **Which camera renders it.** `topDown`, `rts`, `shoulder`, or `first` — camera is
+  presentation and reads none of this. Swapping the rig never touches the loop.
+- **What the effect does.** `"damage"` for combat; register a `defineTargetedOrder`
+  with a `"harvest"` / `"repair"` / `"talk"` effect for non-combat command. The
+  engagement seam is generic; combat is one instance.
+- **When intent arrives.** A **mutating** game reuses one set of queues across
+  phases: the card-game phase calls `issue()` from card plays; when it turns into
+  a topdown-survival phase, the *same* queues now take `move` / `attack-move` from
+  pointer input. You changed who calls `issue()`, not the architecture.
+
+## Where to go next
+
+- Marquee/box-select and right-click-to-command come from the shell pointer seam
+  (`PlayableGame.pointer`: `select`, `selectFilter`, `orderCommand`) — that is the
+  pointer *picker* that fills `selection` and calls `commandSelection`; see
+  `jgengine-ui` for the pointer wiring.
+- Pathing for `moveToward` can use `findPath` (`@jgengine/core/nav/navGrid`) over a
+  walkable grid; the mover adapter is where it plugs in.
+- Formations, order preemption policies, save/replication of in-flight orders, and
+  the full order-kind contract are in [../reference.md](../reference.md) under
+  *Entity orders (command queue)*.
+- Damage numbers, death, and rewards are `jgengine-combat`; the effect call above
+  is the seam into it.