@jgengine/shell 0.13.0 → 0.15.0-next.0

package/skills/jgengine-world/capabilities.md

@@ -4,6 +4,18 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
+## ai-driver — difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
+
+- `driveStep` (function) · `import { driveStep } from "@jgengine/core/ai/driver"`
+
+## ai-driver-path-target — pure-pursuit lookahead target on a road/route polyline for street following
+
+- `pathTargetAhead` (function) · `import { pathTargetAhead } from "@jgengine/core/ai/driver"`
+
+## ai-driver-state — fresh serializable state for one difficulty-aware AI driver
+
+- `createDriverState` (function) · `import { createDriverState } from "@jgengine/core/ai/driver"`
+
 ## area-effect-field — source-following area membership with enter/refresh/leave edges, stacking, and cleanup
 
 - `createAreaEffectField` (function) · `import { createAreaEffectField } from "@jgengine/core/world"`
@@ -70,6 +82,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## authored-objects — marker kinds resolved as entity spawns, not static props
 
 - `ENTITY_MARKER_KINDS` (const) · `import { ENTITY_MARKER_KINDS } from "@jgengine/core/world/authoredObjects"`
+- `markerAnimation` (function) · `import { markerAnimation } 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"`
@@ -113,11 +126,23 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `deriveBuildingLots` (function) · `import { deriveBuildingLots } from "@jgengine/core/world/buildingLots"`
 
+## camera-shake — seeded serializable trauma-based camera shake/impulse controller (hit/explosion/landing juice) with pooled per-frame translation+rotation offset and snapshot/restore
+
+- `createCameraShake` (function) · `import { createCameraShake } from "@jgengine/core/world"`
+
 ## city-district — polygon math for road-derived blocks, parcels, and buildable footprints
 
 - `Vec2` (type) · `import { Vec2 } from "@jgengine/core/world/cityGeometry"`
+- `extractGraphBlocks` (function) · `import { extractGraphBlocks } from "@jgengine/core/world/cityBlocks"`
+- `rectClearsPolyline` (function) · `import { rectClearsPolyline } from "@jgengine/core/world/cityGeometry"`
+- `rectsSeparated` (function) · `import { rectsSeparated } from "@jgengine/core/world/cityGeometry"`
 - `resolveCityObject` (function) · `import { resolveCityObject } from "@jgengine/core/world"`
 
+## city-generator — subdivide street blocks into size-tiered street-fronting plots
+
+- `deriveCityPlots` (function) · `import { deriveCityPlots } from "@jgengine/core/world"`
+- `resolveCityLotContent` (function) · `import { resolveCityLotContent } 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"`
@@ -130,14 +155,58 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `chooseContourInterval` (function) · `import { chooseContourInterval } from "@jgengine/core/world"`
 
+## countdown-timers — named countdown/countup timer set on an injected clock — round timers, respawn clocks, ability cooldown/charge; read remaining/elapsed/progress + expiry, snapshot/restore
+
+- `createTimerSet` (function) · `import { createTimerSet } from "@jgengine/core/world"`
+
 ## crouch-prone — stance/pose transitions that change the hitbox
 
 - `createPoseState` (function) · `import { createPoseState } from "@jgengine/core/world"`
 
+## damage-direction — serializable hit-from damage-direction indicator brain — pooled directional arcs that flare on `registerHit(angle, intensity)` and fade on an injected clock, with optional same-direction merging
+
+- `createDamageDirectionTracker` (function) · `import { createDamageDirectionTracker } from "@jgengine/core/world"`
+
+## day-night-cycle — one wired model gives a moving day-night cycle — running clock plus keyframed phase labels and tint/light colors a game drives an existing sky/daylight seam from
+
+- `createDayNightCycle` (function) · `import { createDayNightCycle } 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"`
 
+## difficulty-ability-gate — spend-or-hold ability decision from a scored opportunity window
+
+- `shouldUseAbility` (function) · `import { shouldUseAbility } from "@jgengine/core/ai/difficulty"`
+
+## difficulty-execution-error — symmetric aim/lead/timing error scaled by the profile
+
+- `executionError` (function) · `import { executionError } from "@jgengine/core/ai/difficulty"`
+
+## difficulty-lookahead — depth/width-bounded deterministic planner for turn-based or sequential decisions
+
+- `planLookahead` (function) · `import { planLookahead } from "@jgengine/core/ai/difficulty"`
+
+## difficulty-pick — noisy argmax over scored options; expert picks best, easy blunders
+
+- `pickScored` (function) · `import { pickScored } from "@jgengine/core/ai/difficulty"`
+
+## difficulty-profile — derive a per-game decision-quality profile from a canonical tier
+
+- `difficultyProfile` (function) · `import { difficultyProfile } from "@jgengine/core/ai/difficulty"`
+
+## difficulty-reaction-gate — delay acting on new information by the profile's reaction time
+
+- `advanceReactionGate` (function) · `import { advanceReactionGate } from "@jgengine/core/ai/difficulty"`
+
+## difficulty-reaction-gate-state — fresh serializable reaction-gate state for one observed value
+
+- `createReactionGate` (function) · `import { createReactionGate } from "@jgengine/core/ai/difficulty"`
+
+## difficulty-tiers — canonical easy/standard/expert decision-quality profiles for any opponent
+
+- `DIFFICULTY_TIERS` (const) · `import { DIFFICULTY_TIERS } from "@jgengine/core/ai/difficulty"`
+
 ## elevation-readout — cursor height and delta-from-reference feedback
 
 - `sampleElevation` (function) · `import { sampleElevation } from "@jgengine/core/world"`
@@ -150,6 +219,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `entityMetaOf` (function) · `import { entityMetaOf } from "@jgengine/core/world"`
 
+## fast-travel — network of fast-travel destinations with discovery, distance-sorted queries, nearest lookup, a travel gate, and serializable state
+
+- `createFastTravelNetwork` (function) · `import { createFastTravelNetwork } from "@jgengine/core/world"`
+
 ## flight-dynamics — simulate fixed-wing, helicopter, and VTOL aircraft
 
 - `createAircraftDynamics` (function) · `import { createAircraftDynamics } from "@jgengine/core/world"`
@@ -208,10 +281,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `pointGravity` (function) · `import { pointGravity } from "@jgengine/core/world"`
 - `uniformGravity` (function) · `import { uniformGravity } from "@jgengine/core/world"`
 
+## grounded — ground an XZ point onto the world surface as a pose triple
+
+- `grounded` (function) · `import { grounded } from "@jgengine/core/world"`
+
 ## hold-order — stand-ground order that holds position until preempted or canceled
 
 - `defineHoldOrder` (function) · `import { defineHoldOrder } from "@jgengine/core/world"`
 
+## interaction-prompt — observable nearest-interactable prompt registry over the proximity-prompt resolver — register/resolve/active with priority+range and change-notified snapshot/restore
+
+- `createPromptRegistry` (function) · `import { createPromptRegistry } 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"`
@@ -228,6 +309,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `interestPhase` (function) · `import { interestPhase } from "@jgengine/core/world"`
 
+## key-rebinding — conflict-aware key-remap session over the action-binding model — capture/reassign, conflict detection, reset-to-defaults, persist overrides, snapshot/restore
+
+- `createRebindSession` (function) · `import { createRebindSession } from "@jgengine/core/input/rebindSession"`
+
 ## limb-health — per-body-part/region health tracked separately
 
 - `createMultiRegionHealth` (function) · `import { createMultiRegionHealth } from "@jgengine/core/procedural"`
@@ -240,6 +325,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `generateLock` (function) · `import { generateLock } from "@jgengine/core/world"`
 
+## map-annotations — player-drawn map annotation layer — freehand strokes, area shapes, and pinned notes, projected into the map's routes/zones props and serializable
+
+- `createAnnotationLayer` (function) · `import { createAnnotationLayer } 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"`
@@ -273,6 +362,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createOrderRegistry` (function) · `import { createOrderRegistry } from "@jgengine/core/world"`
 
+## particle-system — deterministic pooled particle emitter with SoA render buffers, burst/continuous emission, gravity/drag, size/color/alpha-over-life, and serializable state
+
+- `createParticleSystem` (function) · `import { createParticleSystem } from "@jgengine/core/world"`
+
 ## path-follow-progress — read normalized/distance/segment progress from follow state
 
 - `pathFollowProgress` (function) · `import { pathFollowProgress } from "@jgengine/core/world"`
@@ -355,6 +448,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `controlGroupKey` (function) · `import { controlGroupKey } from "@jgengine/core/world"`
 - `resolveControlGroupIntent` (function) · `import { resolveControlGroupIntent } from "@jgengine/core/world"`
 
+## scatter-coverage — shared density/budget semantics for scatterable kinds
+
+- `ScatterCoverageKind` (type) · `import { ScatterCoverageKind } from "@jgengine/core/world"`
+
+## screen-effects — serializable, pooled screen-feedback controller — transient flash/vignette and sustained low-health-style pulses with eased opacities, free-string kinds the game styles, and snapshot/restore
+
+- `createScreenEffects` (function) · `import { createScreenEffects } 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"`
@@ -363,6 +464,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createSelectionBookmarks` (function) · `import { createSelectionBookmarks } from "@jgengine/core/world"`
 
+## sequence-director — data-driven cutscene timeline — fire typed camera/dialogue/event cues on one injected clock with play/pause/seek/skip and snapshot/restore
+
+- `createSequenceDirector` (function) · `import { createSequenceDirector } from "@jgengine/core/world"`
+
+## shared-annotations — broadcast local map-drawing edits over the party feed and mirror inbound edits — collaborative annotations over any replicated feed
+
+- `createSharedAnnotations` (function) · `import { createSharedAnnotations } 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"`
@@ -415,7 +524,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineStopOrder` (function) · `import { defineStopOrder } from "@jgengine/core/world"`
 
-## street-generator — build a deterministic street/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+## street-generator — build a deterministic street/track graph (nodes, edges, streets, junctions, sidewalks, bridges, tunnels) from sliders
 
 - `generateStreets` (function) · `import { generateStreets } from "@jgengine/core/world/streetGenerator"`
 
@@ -455,8 +564,9 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `raycastHeightField` (function) · `import { raycastHeightField } from "@jgengine/core/world/terrain"`
 
-## touch-controls — default on-screen button silhouette for a touch action
+## touch-controls — switch the on-screen touch control set when gameplay context changes (enter/exit vehicle, mount, build mode)
 
+- `setTouchControlsMode` (function) · `import { setTouchControlsMode } from "@jgengine/core/input/touchControlsMode"`
 - `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
@@ -467,10 +577,25 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `VolumetricCloudsConfig` (interface) · `import { VolumetricCloudsConfig } from "@jgengine/core/world"`
 
+## wave-runner — observable serializable wave/spawn runner over the seeded spawn director — WAVE N, wave progress, budget/alert readout, onSpawn sink, snapshot/restore
+
+- `createWaveRunner` (function) · `import { createWaveRunner } from "@jgengine/core/world"`
+
+## waypoint-store — serializable player waypoint layer — place/track/clear pins, mirror to a MarkerSet, and on-screen bearing/distance guidance for the tracked waypoint
+
+- `createWaypointStore` (function) · `import { createWaypointStore } 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-intersections — connect sidewalks and lane guidance through generated intersections
+
+- `buildIntersectionMarkings` (function) · `import { buildIntersectionMarkings } from "@jgengine/core/world/roads"`
+- `buildJunctionConnector` (function) · `import { buildJunctionConnector } from "@jgengine/core/world/roads"`
+- `buildTrimmedIntersections` (function) · `import { buildTrimmedIntersections } from "@jgengine/core/world"`
+- `trimBandAtJunctions` (function) · `import { trimBandAtJunctions } 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"`

package/skills/jgengine-world/reference.md

@@ -71,7 +71,7 @@ Pure `@jgengine/core` functions so gameplay reads the same world the shell rende
 | `createRegionField({ regions })` → `RegionField` | `sampleRegion(x,z)` blends content-agnostic biomes by nearest selector — height + `tint`/`water`/`fog`/`speedMultiplier` + opaque `data`. Extends `TerrainField`, so it ground-snaps too |
 | `scatterItems(field, area, layersFor)` → `ScatterInstance[]` | Region-driven content scatter — density per region, grounded, above-water/slope-aware. `pickWeighted` for weighted rolls. (vs `scatter`'s pure geometric points) |
 | `resolveScatterRegion(region, terrain?)` / `resolveScatter(doc, terrain?)` | Deterministic instanced placements for a **freehand polygon** scatter region (the editor's foliage lasso): `density`/`minSpacing`/`seed`, `minScale`/`maxScale`, weighted `palette`, `maxSlope`/`minHeight`/`maxHeight` masks, `edgeFalloff` feathering, `alignToNormal`. Regions ride editor paths of `kind` `SCATTER_PATH_KIND` — `scatterRegionFromPath`/`readScatterRules`/`readScatterPalette` build one from a path's meta, `scatterRegionEstimate` gives the live count readout, `resolveScatter` walks every scatter path in a document. Polygon helpers: `pointInPolygon`, `distanceToPolygonEdge`, `polygonArea`, `polygonBounds`, `isScatterPath`. Same seed → same field; GPU-instanced, never one node per instance. |
-| `resolveAuthoredObjects(doc)` / `placeAuthoredObjects(store, objects, sampleHeight, opts?)` / `placeAuthoredObjectsFromDocument` / `markerCatalogId(marker)` | Catalog mesh props from editor markers: every marker with first-class `catalogId` or `meta.catalogId` → `{ catalogId, x, z, rotationY, instanceId, verticalOffset }[]`. `placeAuthoredObjects` grounds on `sampleHeight` and calls `store.place` (WorldScene renders via `objectModels`). Shell: `<AuthoredObjects document field />` or `<AuthoredScene placeObjects />`. Never hand-loop `document.markers` for prop placement. |
+| `resolveAuthoredObjects(doc)` / `placeAuthoredObjects(store, objects, sampleHeight, opts?)` / `placeAuthoredObjectsFromDocument` / `markerCatalogId(marker)` / `markerAnimation(marker)` | Catalog mesh props from editor markers: every marker with first-class `catalogId` or `meta.catalogId` → `{ catalogId, x, z, rotationY, instanceId, verticalOffset, animation? }[]`. A placement's authored `marker.meta.animation` (#1274) is read by `markerAnimation`, carried as the optional `AuthoredObject.animation`, and threaded through `placeAuthoredObjects` → `store.place` onto the placed object's `ModelConfig.animation`, so a per-placement rig override (role→clip, auto/none, speeds, fade, one-shots) applies at play time (#1276); absent, animation stays catalog-resolved. `placeAuthoredObjects` grounds on `sampleHeight` and calls `store.place` (WorldScene renders via `objectModels`). Shell: `<AuthoredObjects document field />` or `<AuthoredScene placeObjects />`. Never hand-loop `document.markers` for prop placement. |
 | `buildingIndex(district)` → `BuildingIndex` | `at`/`within`/`nearest`/`isInside`/`blockers` over a generated district — placement avoidance, pathfinding |
 
 **Voxel field (`world/voxelField`).** `createVoxelField<T extends string>({ chunkSize? })` (default 16) is a logical block lattice for voxel games and instanced renderers — distinct from the `voxel()` `WorldFeature` descriptor above (that's the runner-level world kind; this is the block data structure a voxel game's gameplay reads and writes). `set`/`remove`/`get`/`has`/`fill`/`clear`/`count`/`cells`/`bounds` are the block CRUD (`set` returns `false` only when the identical type is already there — a no-op write). `neighbors(x, y, z)` returns the 6-adjacent occupied cells; `exposedFaces(x, y, z)` returns the `VoxelFace`s (`"px"|"nx"|"py"|"ny"|"pz"|"nz"`) not touching another voxel — feed that straight into greedy-meshing/face-culling. `raycast(origin, direction, maxDistance)` runs a 3D DDA and returns `{ x, y, z, type, face, adjacent, distance }`, where `adjacent` is the empty cell just in front of the hit — the placement target for block-place tools. Renderers dirty-track via `chunkOf(x, y, z)` + `chunkVersion(chunk)` and `subscribe(listener)`, so an instanced mesh only rebuilds the chunks that changed. For a non-`environment()` voxel world, assert on `field.summary()` (`{ blocks, types, bounds }`) the same way an `environment()` world asserts on `summarizeEnvironment` (see `jgengine-verify`).
@@ -259,3 +259,17 @@ Path progress adapter (`nav/pathFollow`): `PathProgress` is `{ kind: "normalized
 - **Preemption policy** on each issue: `replace` (preempt active + clear pending), `append` (shift-queue), `front` (jump the queue without dropping the active order), `reject` (refuse while busy). Mark an order `uninterruptible` and a replacing order waits until it finishes; explicit `cancelActive` still forces it.
 - **Order kinds** are `OrderKind<Ctx, Payload>` with `start`/`update`/`finish`, composed over two narrow adapters — `OrderMover` (`position`/`moveToward`/`halt`) and `OrderTargeting` (`acquire`/`positionOf`). Built-ins ship as ordinary compositions with a configurable `kind` string so a game re-skins a verb ("harvest") without engine edits: `defineMoveOrder`, `defineStopOrder`, `defineHoldOrder`, `defineAttackMoveOrder`, `defineTargetedOrder`, `definePatrolOrder`. Engagement verbs write `{ engaging, inRange }` into `order.state`; the game reads it to run the actual attack/effect, keeping combat resolution game-side.
 
+
+### AI decision quality (difficulty tiers)
+
+`ai/difficulty` — one serializable `DifficultyProfile` (reaction time, decision noise, execution jitter, ability discipline, perception scale, plan depth/width) owns *how well* any agent decides; the substrates above own *what* it can do. `DIFFICULTY_TIERS` ships canonical `easy`/`standard`/`expert`; `difficultyProfile(tier, overrides)` derives per-game variants. Appliers sit at the universal decision seams, all deterministic under an injected rng:
+
+- **React** — `createReactionGate(initial)` + `advanceReactionGate(state, dt, desired, profile)`: new information (best target, last-seen position) only takes effect after `reactionSeconds` of stability; feed the *returned* value into pursuit/aim, not the raw `desired`.
+- **Choose** — `pickScored(options, profile, rng)`: noisy argmax over any caller-scored list (acquisition candidates, abilities, retreat routes); expert plays optimally, easy blunders at `decisionNoise` rate.
+- **Execute** — `executionError(profile, rng, scale)`: symmetric aim/lead/timing error to add to a yaw, lead, or release time.
+- **Spend** — `shouldUseAbility(opportunity, profile, rng)`: score the moment `0..1` game-side (targets clumped, player mid-animation); low-discipline profiles waste cooldowns, high-discipline ones hold for strong windows.
+- **Plan** — `planLookahead(root, domain, profile, rng)`: depth/width-bounded negamax over a game-owned `LookaheadDomain` (`moves`/`apply`/`evaluate`, `adversarial: false` for own-sequence planning like rotations or build orders). Easy is greedy and walks into forks; expert finds multi-ply tactics. Run at decision cadence, not per frame.
+
+Compose, don't replace: scale `MobBrainConfig.aggroRadius` by `perceptionScale`, route `acquireTarget` scoring through `pickScored`, gate `advancePursuit` target swaps behind the reaction gate.
+
+**Drive** — `ai/driver` is the vehicle consumer of the profile: `driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleAhead?)` turns a pose + goal into the shared `AxisInput` (`throttle`/`brake`/`steer`) for `tickDrivableVehicle`. The profile decides how well the car drives: the steering target is a delay-line resampled every `reactionSeconds` (easy chasers cut to where the target *was*), corners shed speed instead of orbiting at full throttle, obstacle distance is perceived late by `speed × reactionSeconds`, the wheel wobbles by `executionJitter` (resampled on an interval, so it reads as a loose wheel), and a car grinding a wall backs out with counter-steer after a tier-scaled delay (brake past standstill is the sim's reverse). `createDriverState` is one small serializable object; the caller owns the sim, collision, and all spatial queries. For streets and circuits, `pathTargetAhead(path, x, z, lookahead, loop?)` walks a road/route polyline to the pure-pursuit point ahead — feed it back in as the goal each tick and the same brain follows authored roads; give sharper tiers a longer lookahead.