@jgengine/core 0.25.0 → 0.26.0

package/skills/jgengine-world/api.md

@@ -147,6 +147,16 @@
 - `armPursuit` (function): function armPursuit(state: PursuitState, intervalSeconds: number): void — Set the cooldown after an attack fires (clamped at `0`). Call on the step that returned `"attack"`.
 - `createPursuitState` (function): function createPursuitState(attackCooldown = 0): PursuitState — A fresh pursuit state, ready to attack immediately (`attackCooldown` at `0`).
 
+## @jgengine/core/ai/rvo
+
+- `RvoAgentSpec` (interface): interface RvoAgentSpec — One agent's circular footprint and top speed; positions and velocities live in the crowd.
+- `RvoAgentView` (interface): interface RvoAgentView — One agent's live kinematics, as the crowd exposes them.
+- `RvoCrowd` (interface): interface RvoCrowd — Many circular agents steering around each other. `setPreferredVelocity` states where each agent wants to go; `step` turns that into reciprocal collision-free velocities and integrates them. Deterministic: agents are visited in slot order, neighbours in grid and slot order, and head-on ties break on slot index rather than chance.
+- `RvoCrowdOptions` (interface): interface RvoCrowdOptions extends Partial<RvoTunables> — Options for {@link createRvoCrowd}.
+- `RvoSnapshot` (interface): interface RvoSnapshot — Serializable crowd state: tuning plus every agent's position, velocity and footprint.
+- `RvoTunables` (interface): interface RvoTunables — Serializable avoidance tuning, retunable in play through {@link RvoCrowd.retune}.
+- `createRvoCrowd` (function): function createRvoCrowd(options: RvoCrowdOptions = {}): RvoCrowd — Reciprocal velocity obstacle avoidance over circular agents. Each nearby pair contributes one or two half-plane constraints on the agent's velocity, and a small linear program picks the velocity closest to the preferred one that satisfies them all. The neighbour search is a uniform grid capped at `maxNeighbors`, so a tick costs the same for 50 agents and 5,000.
+
 ## @jgengine/core/ai/spawnDirector
 
 - `DirectorContext` (interface): interface DirectorContext { alive: number; players?: number; playerPositions?: readonly NavPoint[] } — ⚠ undocumented
@@ -197,6 +207,24 @@
 - `ThreatTableState` (interface): interface ThreatTableState — Plain JSON state of a {@link ThreatTable}; `entries` keeps insertion order, which breaks ties in `highest`.
 - `createThreatTable` (function): function createThreatTable(config: ThreatTableConfig = {}): ThreatTable — ⚠ undocumented
 
+## @jgengine/core/ai/utilityBrain
+
+- `ResponseCurve` (type): type ResponseCurve = | { readonly kind: "linear"; readonly from: number; readonly to: number } /** Same shape as `linear`, raised to `exponent` (default `2`), so appeal stays flat until it matters. */ | { readonly kind: "quadratic"; readonly from: number; readonly to: number; readonly exponent?: num… — How one need's satisfaction maps to an option's appeal: `1` at `from`, `0` at `to`, clamped outside. Read satisfaction `1` as a full meter; pair with {@link UtilityTerm.invert} when a full meter is what makes the option attractive.
+- `UtilityBrain` (interface): interface UtilityBrain — Utility-scored action selection over decaying needs: score every option's appeal through response curves, pick the best reachable candidate minus its cost, and hold that pick until a rival clears the hysteresis margin — unless a declared interrupt fires.
+- `UtilityBrainConfig` (interface): interface UtilityBrainConfig extends UtilityTunables — Everything a utility brain needs: the shared need set, its scored options, and selection policy.
+- `UtilityBrainSnapshot` (interface): interface UtilityBrainSnapshot — Serializable brain state: the held pick plus any in-play retuning. Needs save separately.
+- `UtilityCandidate` (interface): interface UtilityCandidate — One reachable instance of an option this tick; `cost` is the caller's own effort number.
+- `UtilityDebugSnapshot` (interface): interface UtilityDebugSnapshot — JSON-safe view of a brain for the devtools overlay and bug reports.
+- `UtilityDecision` (interface): interface UtilityDecision — The outcome of one {@link UtilityBrain.decide}. Valid until the next `decide` call.
+- `UtilityInterrupt` (interface): interface UtilityInterrupt — A need level that overrides the sticky pick the moment it is crossed.
+- `UtilityOption` (interface): interface UtilityOption — A thing an agent can decide to do, scored against its needs.
+- `UtilityScore` (interface): interface UtilityScore — One option's need-driven score, ignoring candidate cost.
+- `UtilitySwitchReason` (type): type UtilitySwitchReason = "initial" | "score" | "interrupt" | "unavailable" — Why the brain's pick changed on the tick it changed.
+- `UtilityTerm` (interface): interface UtilityTerm — One need's contribution to an option's appeal.
+- `UtilityTunables` (interface): interface UtilityTunables — In-play dials that stay reachable through {@link UtilityBrain.retune}.
+- `createUtilityBrain` (function): function createUtilityBrain(config: UtilityBrainConfig): UtilityBrain — Create a utility brain over an existing {@link NeedSet}. The need set is injected, not owned, so the game shows the same hunger the brain scores and persists one copy.
+- `sampleResponseCurve` (function): function sampleResponseCurve(curve: ResponseCurve, satisfaction: number): number — Sample a response curve at a `0..1` satisfaction. Deterministic, allocation-free.
+
 ## @jgengine/core/ai/waveRunner
 
 - `WaveRunner` (interface): interface WaveRunner — A live, observable, serializable wave/spawn runner over a seeded spawn director.
@@ -887,6 +915,17 @@
 - `NavConstrainProposed` (interface): interface NavConstrainProposed { position: EntityPosition; rotationY: number; grounded: boolean } — ⚠ undocumented
 - `constrainToNavGrid` (function): function constrainToNavGrid(grid: NavGrid, options?: NavConstrainOptions): (proposed: NavConstrainProposed, entity: NavConstrainEntity) => NavConstrainProposed | null — ⚠ undocumented
 
+## @jgengine/core/nav/navCrowd
+
+- `NavCrowd` (interface): interface NavCrowd — Agents that cross an editor-baked nav mesh: each one plans a corridor with {@link NavRuntime}, walks the funnel-smoothed waypoints, and keeps its distance through reciprocal velocity obstacle avoidance. Goals, arrivals and replans are serializable; a mesh edit only re-plans the agents whose remaining route actually crossed the rebuilt region.
+- `NavCrowdAgentSpec` (interface): interface NavCrowdAgentSpec — How one crowd agent was configured when it joined.
+- `NavCrowdAgentView` (interface): interface NavCrowdAgentView — One crowd agent's live state, as a game or the devtools overlay reads it.
+- `NavCrowdOptions` (interface): interface NavCrowdOptions — Tunables for {@link createNavCrowd}, every one retunable in play.
+- `NavCrowdRevalidate` (interface): interface NavCrowdRevalidate — Result of telling the crowd the nav mesh changed.
+- `NavCrowdSnapshot` (interface): interface NavCrowdSnapshot — Serializable crowd state: agents, their routes, and the avoidance tuning they run under.
+- `NavCrowdStats` (interface): interface NavCrowdStats — Counters a devtools probe or test reads.
+- `createNavCrowd` (function): function createNavCrowd(options: NavCrowdOptions & { nav: NavRuntime }): NavCrowd — Compose {@link createNavRuntime} and {@link createRvoCrowd} into a moving crowd: plan on the mesh, follow the smoothed corridor, avoid each other. Deterministic — agents advance in insertion order and the avoidance solve breaks ties by slot, not chance.
+
 ## @jgengine/core/nav/navFromEnvironment
 
 - `NavObstacleGrid` (interface): interface NavObstacleGrid { blockAabb(aabb: Aabb): void } — ⚠ undocumented · used by `populateNavGridFromEnvironment`: Blocks the footprint of every solid building an environment feature's `structures` generate — the same set `ctx.world.solids` holds for it.
@@ -922,6 +961,19 @@
 - `findPath` (function): function findPath(mesh: NavMeshData, from: Vec3, to: Vec3): NavMeshPath | null — A* over polygon portals with default area costs, straightened by a portal funnel. Use {@link createNavMeshQuery} to price areas.
 - `raycastNav` (function): function raycastNav(mesh: NavMeshData, from: Vec3, to: Vec3): boolean — True when the segment remains over walkable polygons.
 
+## @jgengine/core/nav/navRuntime
+
+- `AuthoredNavLink` (interface): interface AuthoredNavLink — A connection the scene author places between two spots — a door through a wall, a ladder to a deck, a jump across a gap. Authored as world points, not polygon ids, so it survives a re-bake: {@link NavRuntime.applyMesh} resolves each end onto the nearest walkable polygon.
+- `NavLinkKind` (type): type NavLinkKind = "door" | "ladder" | "jump" | "link" — What an authored off-mesh connection crosses; the runtime prices it by kind unless the author sets a cost.
+- `NavRebuildStats` (interface): interface NavRebuildStats — How one {@link NavRuntime.applyMesh} exchange changed the mesh.
+- `NavRegion` (interface): interface NavRegion — An XZ box naming the authored area a scene edit touched, so routing state elsewhere is left alone.
+- `NavRuntime` (interface): interface NavRuntime — Runtime seam over a baked {@link NavMeshData}: route, price areas, resolve authored links, rebuild in place.
+- `NavRuntimeOptions` (interface): interface NavRuntimeOptions extends NavMeshQueryOptions — Options for {@link createNavRuntime}.
+- `NavRuntimeSnapshot` (interface): interface NavRuntimeSnapshot — Serializable tuning and authored links of a {@link NavRuntime}; the baked geometry is replaced by `applyMesh`.
+- `SceneBake` (interface): interface SceneBake — A bake stored on an editor scene document, structurally compatible with `EditorBake`.
+- `createNavRuntime` (function): function createNavRuntime(options: NavRuntimeOptions & { mesh: NavMeshData }): NavRuntime — Route agents over the nav mesh an editor baked. Wraps {@link createNavMeshQuery}, resolves authored off-mesh links (doors, ladders, jumps) onto the current surface, and exchanges the mesh one scene region at a time so untouched polygons keep their ids and the agents routing over them keep their paths.
+- `navMeshFromBake` (function): function navMeshFromBake(bakes: readonly SceneBake[] | undefined, id = "main"): NavMeshData | null — Read the named navigation bake an editor wrote onto a scene document. Returns `null` when the document holds no such bake yet, and throws when the stored bake is not a valid nav mesh — a corrupt bake should fail at load, not as agents walking through walls.
+
 ## @jgengine/core/nav/pathFollow
 
 - `HeightSampler` (interface): interface HeightSampler { sampleHeight(x: number, z: number): number } — ⚠ undocumented · used by `drapePolyline` (@jgengine/core/world): Drapes an XZ polyline onto the surface: subdivides each span to at most `spacing` and lifts every vertex to `sampleHeight + offset`, returni…
@@ -1768,15 +1820,16 @@
 ## @jgengine/core/sensor/perception
 
 - `PerceptionCandidate` (interface): interface PerceptionCandidate — A candidate target considered by a sight check.
-- `PerceptionConfig` (interface): interface PerceptionConfig — Configuration for sight, hearing, memory decay, and optional occlusion.
+- `PerceptionConfig` (interface): interface PerceptionConfig — Configuration for sight, hearing, memory decay, squad sharing and optional occlusion.
 - `PerceptionMemory` (interface): interface PerceptionMemory — A remembered target and its linearly decaying confidence.
 - `PerceptionObserver` (interface): interface PerceptionObserver — The observer pose used for a sight check.
 - `PerceptionPosition` (type): type PerceptionPosition = readonly [number, number, number] — A world position used by perception, in `[x, y, z]` order.
 - `PerceptionService` (interface): interface PerceptionService — Stateful perception API with retuning and save/restore support.
 - `PerceptionSnapshot` (interface): interface PerceptionSnapshot — Serializable state for a perception service.
+- `PerceptionStats` (interface): interface PerceptionStats — Counters a perf test or a devtools probe reads. Reset with {@link PerceptionService.resetStats}.
 - `PerceptionStimulus` (interface): interface PerceptionStimulus — An event that can seed an observer's memory.
 - `PerceptionStimulusKind` (type): type PerceptionStimulusKind = "sight" | "sound" | "damage" — The kinds of stimulus the perception service can retain.
-- `createPerception` (function): function createPerception(initial: PerceptionConfig): PerceptionService — Creates a deterministic sight, sound, and damage perception service with expiring target memory.
+- `createPerception` (function): function createPerception(initial: PerceptionConfig): PerceptionService — Creates a deterministic sight, sound, and damage perception service with expiring target memory. Signals are judged in the order the caller supplies them, never from the wall clock.
 
 ## @jgengine/core/sensor/recordingBuffer
 
@@ -2105,6 +2158,7 @@
 - `AttackMoveOrderPayload` (interface): interface AttackMoveOrderPayload — Payload for an attack-move: advance toward `point`, engaging hostiles encountered en route.
 - `AudioBusDef` (interface): interface AudioBusDef { id: AudioBusId; gain?: number } — ⚠ undocumented · used by `withUiCueSounds` (@jgengine/core/audio/uiCues): Merge the default UI cue patches into a game's sound catalog.
 - `AudioFalloffConfig` (interface): interface AudioFalloffConfig { minDistance?: number; maxDistance?: number; curve?: FalloffCurve } — ⚠ undocumented
+- `AuthoredNavLink` (interface): interface AuthoredNavLink — A connection the scene author places between two spots — a door through a wall, a ladder to a deck, a jump across a gap. Authored as world points, not polygon ids, so it survives a re-bake: {@link NavRuntime.applyMesh} resolves each end onto the nearest walkable polygon.
 - `AuthoredTrigger` (interface): interface AuthoredTrigger — One resolved trigger binding from a document object.
 - `AuthoredTriggerRuntime` (interface): interface AuthoredTriggerRuntime — Runtime handle that watches authored triggers against moving actors each tick.
 - `AutoTargetPolicy` (type): type AutoTargetPolicy = | "nearest" | "farthest" | "random" | "strongest" | "weakest" | "first" | "last" — ⚠ undocumented
@@ -2360,7 +2414,15 @@
 - `MusicInstrument` (type): type MusicInstrument = | "strings" | "flute" | "harp" | "horn" | "choir" | "bell" | "timpani" | "bass" | "stacc" | "pad" | "lute" | "dulcimer" | "frameDrum" | "warDrum" | "reed" | "pipe" | "squareLead" | "woodBlock" | "tinyBell" | "piano" | "shaker" | "brassStab" | "cymSwell" | "oboe" — Named synthesised instrument. Each maps to a voice in the shell's instrument library (`@jgengine/shell/audio/musicVoices`); an unknown name falls back to a plain sine voice so a theme is never silent.
 - `MusicTheme` (interface): interface MusicTheme — A through-composed, looping music track. `events` need not be sorted; the director schedules them ahead against a fixed anchor so loops are seamless.
 - `NOCLIP_FLIGHT_TUNING` (const): const NOCLIP_FLIGHT_TUNING: FreeFlightTuning — Preset for noclip — weightless, noclips, yaw-relative with independent vertical.
+- `NavCrowd` (interface): interface NavCrowd — Agents that cross an editor-baked nav mesh: each one plans a corridor with {@link NavRuntime}, walks the funnel-smoothed waypoints, and keeps its distance through reciprocal velocity obstacle avoidance. Goals, arrivals and replans are serializable; a mesh edit only re-plans the agents whose remaining route actually crossed the rebuilt region.
+- `NavCrowdAgentSpec` (interface): interface NavCrowdAgentSpec — How one crowd agent was configured when it joined.
+- `NavCrowdAgentView` (interface): interface NavCrowdAgentView — One crowd agent's live state, as a game or the devtools overlay reads it.
+- `NavCrowdOptions` (interface): interface NavCrowdOptions — Tunables for {@link createNavCrowd}, every one retunable in play.
+- `NavCrowdRevalidate` (interface): interface NavCrowdRevalidate — Result of telling the crowd the nav mesh changed.
+- `NavCrowdSnapshot` (interface): interface NavCrowdSnapshot — Serializable crowd state: agents, their routes, and the avoidance tuning they run under.
+- `NavCrowdStats` (interface): interface NavCrowdStats — Counters a devtools probe or test reads.
 - `NavGrid` (interface): interface NavGrid { readonly cols: number; readonly rows: number; readonly cellSize: number; readonly bounds: Aabb; readonly diagonal: boolean; isWalkable(col: number, row: number): boolean; setWalkable(col: number, row: number, walkable: boolean): void; blo… — ⚠ undocumented · used by `findPath`: A* over the walkable grid.
+- `NavLinkKind` (type): type NavLinkKind = "door" | "ladder" | "jump" | "link" — What an authored off-mesh connection crosses; the runtime prices it by kind unless the author sets a cost.
 - `NavMeshAdjacency` (interface): interface NavMeshAdjacency — Neighbor relationship for one navigation polygon.
 - `NavMeshData` (interface): interface NavMeshData — Serializable polygon navigation mesh data. Treat it as immutable once queried; queries cache derived geometry per object.
 - `NavMeshLink` (interface): interface NavMeshLink — Explicit traversable connection between two navigation polygons.
@@ -2369,6 +2431,11 @@
 - `NavMeshQueryOptions` (interface): interface NavMeshQueryOptions — Tunable pricing and bounds for a {@link NavMeshQuery}.
 - `NavMeshQuerySnapshot` (interface): interface NavMeshQuerySnapshot — Serializable tuning of a {@link NavMeshQuery}.
 - `NavPoint` (type): type NavPoint = readonly [number, number] — ⚠ undocumented · used by `findPath`: A* over the walkable grid.
+- `NavRebuildStats` (interface): interface NavRebuildStats — How one {@link NavRuntime.applyMesh} exchange changed the mesh.
+- `NavRegion` (interface): interface NavRegion — An XZ box naming the authored area a scene edit touched, so routing state elsewhere is left alone.
+- `NavRuntime` (interface): interface NavRuntime — Runtime seam over a baked {@link NavMeshData}: route, price areas, resolve authored links, rebuild in place.
+- `NavRuntimeOptions` (interface): interface NavRuntimeOptions extends NavMeshQueryOptions — Options for {@link createNavRuntime}.
+- `NavRuntimeSnapshot` (interface): interface NavRuntimeSnapshot — Serializable tuning and authored links of a {@link NavRuntime}; the baked geometry is replaced by `applyMesh`.
 - `NoiseFieldConfig` (interface): interface NoiseFieldConfig — Configuration for {@link noiseField}: seed, amplitude, and fractal noise shaping.
 - `NoiseVoice` (interface): interface NoiseVoice — A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised from a shared 1s noise buffer at a randomised playback rate and start offset, decaying exponentially to silence at `duration * decay`.
 - `NoteEvent` (interface): interface NoteEvent — One scheduled note in a theme, positioned on the loop's quarter-note grid.
@@ -2419,6 +2486,16 @@
 - `PathRetaining` (interface): interface PathRetaining — Retaining behavior for a path corridor's shoulders. A wall rises only where the corridor already cuts or fills into the surrounding ground by at least `threshold` — gentle stretches stay open — so a road through a canyon gets held banks while the same profile on flat ground does not. The wall fades in smoothly across `taper` above the threshold so it never steps on or off between adjacent samples.
 - `PatrolOrderPayload` (interface): interface PatrolOrderPayload — Payload for a patrol: walk a waypoint route, optionally looping forever.
 - `PatrolOrderState` (interface): interface PatrolOrderState — Serializable patrol progress.
+- `PerceptionCandidate` (interface): interface PerceptionCandidate — A candidate target considered by a sight check.
+- `PerceptionConfig` (interface): interface PerceptionConfig — Configuration for sight, hearing, memory decay, squad sharing and optional occlusion.
+- `PerceptionMemory` (interface): interface PerceptionMemory — A remembered target and its linearly decaying confidence.
+- `PerceptionObserver` (interface): interface PerceptionObserver — The observer pose used for a sight check.
+- `PerceptionPosition` (type): type PerceptionPosition = readonly [number, number, number] — A world position used by perception, in `[x, y, z]` order.
+- `PerceptionService` (interface): interface PerceptionService — Stateful perception API with retuning and save/restore support.
+- `PerceptionSnapshot` (interface): interface PerceptionSnapshot — Serializable state for a perception service.
+- `PerceptionStats` (interface): interface PerceptionStats — Counters a perf test or a devtools probe reads. Reset with {@link PerceptionService.resetStats}.
+- `PerceptionStimulus` (interface): interface PerceptionStimulus — An event that can seed an observer's memory.
+- `PerceptionStimulusKind` (type): type PerceptionStimulusKind = "sight" | "sound" | "damage" — The kinds of stimulus the perception service can retain.
 - `PhysicsStats` (interface): interface PhysicsStats { count: number; awake: number; sleeping: number; contacts: number; pairs: number; substeps: number; stepMs: number } — ⚠ undocumented
 - `PhysicsWorld` (class): class PhysicsWorld — ⚠ undocumented
 - `PlaceAssetResult` (interface): interface PlaceAssetResult — Shared place-asset verb: one resolved payload for editor `place_asset` and in-game build-mode commits. Convert with {@link toStructureInput} / {@link toEditorMarker}.
@@ -2460,6 +2537,7 @@
 - `ResolvedPoleLine` (interface): interface ResolvedPoleLine — The renderable payload the resolver returns and the shell renderer consumes.
 - `ResolvedTerrainDetail` (type): type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel" | "material" | "sweeps">> & { waterLevel: number; material?: ResolvedTerrainDetailMaterial; sweeps: { dry: readonly [number, number, number]; wet: readonly [number, number, number] }; } — A {@link TerrainDetailConfig} with every field resolved to a concrete value — the shape the shell's detail material consumes.
 - `ResolvedWeather` (interface): interface ResolvedWeather { grip: number; visibility: number; structureDamage: number; chill: number; ignition: number; spread: number } — ⚠ undocumented
+- `ResponseCurve` (type): type ResponseCurve = | { readonly kind: "linear"; readonly from: number; readonly to: number } /** Same shape as `linear`, raised to `exponent` (default `2`), so appeal stays flat until it matters. */ | { readonly kind: "quadratic"; readonly from: number; readonly to: number; readonly exponent?: num… — How one need's satisfaction maps to an option's appeal: `1` at `from`, `0` at `to`, clamped outside. Read satisfaction `1` as a full meter; pair with {@link UtilityTerm.invert} when a full meter is what makes the option attractive.
 - `RevealHit` (interface): interface RevealHit { instanceId: string; distance: number; tags: readonly string[] } — ⚠ undocumented · used by `useRevealHits` (@jgengine/shell/vision/RevealVision): Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene.
 - `RevealQuery` (interface): interface RevealQuery { inRadius(center: EntityPosition | string, radius: number, tags: readonly string[]): RevealHit[] } — ⚠ undocumented
 - `RoadCut` (interface): interface RoadCut — One trim of a ribbon end back to a junction boundary — the seam the welded surface attaches to.
@@ -2470,6 +2548,12 @@
 - `RosterEntry` (interface): interface RosterEntry { id: string; catalogId: string; capturedAt: number; equipped: boolean } — ⚠ undocumented
 - `RoundGround` (interface): interface RoundGround — A planet/sphere you play on the outside of. Sized by `radius` only.
 - `RoundGroundSize` (interface): interface RoundGroundSize — Size of a `round` ground: the planet/sphere radius in world units. Nothing else.
+- `RvoAgentSpec` (interface): interface RvoAgentSpec — One agent's circular footprint and top speed; positions and velocities live in the crowd.
+- `RvoAgentView` (interface): interface RvoAgentView — One agent's live kinematics, as the crowd exposes them.
+- `RvoCrowd` (interface): interface RvoCrowd — Many circular agents steering around each other. `setPreferredVelocity` states where each agent wants to go; `step` turns that into reciprocal collision-free velocities and integrates them. Deterministic: agents are visited in slot order, neighbours in grid and slot order, and head-on ties break on slot index rather than chance.
+- `RvoCrowdOptions` (interface): interface RvoCrowdOptions extends Partial<RvoTunables> — Options for {@link createRvoCrowd}.
+- `RvoSnapshot` (interface): interface RvoSnapshot — Serializable crowd state: tuning plus every agent's position, velocity and footprint.
+- `RvoTunables` (interface): interface RvoTunables — Serializable avoidance tuning, retunable in play through {@link RvoCrowd.retune}.
 - `SCATTER_COVERAGE_SPECS` (const): const SCATTER_COVERAGE_SPECS: Record<ScatterCoverageKind, ScatterCoverageSpec> — The coverage spec per scatterable kind — the single source for its unit + budget.
 - `SCATTER_INSTANCE_BUDGET` (const): const SCATTER_INSTANCE_BUDGET: 250000 — Max blade/placement instances a single `grass_field` or `scatter` patch places. Mirrors the grass renderer's instance-buffer ceiling; the scatter resolver truncates to it too, so a patch never renders more than this many placements regardless of density × area.
 - `SCATTER_PATH_KIND` (const): const SCATTER_PATH_KIND: "scatter" — The editor path kind that marks a closed polyline as a foliage/scatter region.
@@ -2492,6 +2576,7 @@
 - `ScatterInstance` (interface): interface ScatterInstance — ⚠ undocumented · used by `resolveScatter`: Every scatter region's placements across a document, grounded on `terrain` when provided.
 - `ScatterPoint` (interface): interface ScatterPoint { x: number; z: number; index: number } — ⚠ undocumented
 - `ScatterTerrain` (interface): interface ScatterTerrain — Ground sampler a scatter resolve reads height/normal from (the sculpt terrain or the game's ground).
+- `SceneBake` (interface): interface SceneBake — A bake stored on an editor scene document, structurally compatible with `EditorBake`.
 - `SceneEntity` (interface): interface SceneEntity<TMeta = unknown> { id: string; name: string; position: EntityPosition; rotationY: number; rotationX: number; rotationZ: number; velocity: EntityPosition; role: EntityRole; movement: EntityMovement; behaviors: readonly BehaviorDescriptor[]; hidden?: boolean;… — ⚠ undocumented · used by `entityMetaOf`: Narrow `entity.meta` with a type guard — prefer this over `entity.meta as T` so failed shapes return `null` instead of lying to the type che…
 - `SceneKindObject` (interface): interface SceneKindObject — The raw document object a resolver receives — shape shared by markers, volumes, and paths.
 - `SceneKindResolveContext` (interface): interface SceneKindResolveContext — Ground sampler + options a resolver may read (terrain height/normal snap).
@@ -2591,6 +2676,18 @@
 - `TriggerSourceKind` (type): type TriggerSourceKind = "marker" | "volume" — Document collection a trigger source lives on.
 - `TrimmedIntersections` (interface): interface TrimmedIntersections — Renderer-ready output of {@link buildTrimmedIntersections}: trimmed ribbons + welded junction surfaces.
 - `TrimmedRoad` (interface): interface TrimmedRoad — A street sub-path after trimming, plus the cuts (0–2) that shortened it. Feed `path` to {@link buildRoadRibbon}.
+- `UtilityBrain` (interface): interface UtilityBrain — Utility-scored action selection over decaying needs: score every option's appeal through response curves, pick the best reachable candidate minus its cost, and hold that pick until a rival clears the hysteresis margin — unless a declared interrupt fires.
+- `UtilityBrainConfig` (interface): interface UtilityBrainConfig extends UtilityTunables — Everything a utility brain needs: the shared need set, its scored options, and selection policy.
+- `UtilityBrainSnapshot` (interface): interface UtilityBrainSnapshot — Serializable brain state: the held pick plus any in-play retuning. Needs save separately.
+- `UtilityCandidate` (interface): interface UtilityCandidate — One reachable instance of an option this tick; `cost` is the caller's own effort number.
+- `UtilityDebugSnapshot` (interface): interface UtilityDebugSnapshot — JSON-safe view of a brain for the devtools overlay and bug reports.
+- `UtilityDecision` (interface): interface UtilityDecision — The outcome of one {@link UtilityBrain.decide}. Valid until the next `decide` call.
+- `UtilityInterrupt` (interface): interface UtilityInterrupt — A need level that overrides the sticky pick the moment it is crossed.
+- `UtilityOption` (interface): interface UtilityOption — A thing an agent can decide to do, scored against its needs.
+- `UtilityScore` (interface): interface UtilityScore — One option's need-driven score, ignoring candidate cost.
+- `UtilitySwitchReason` (type): type UtilitySwitchReason = "initial" | "score" | "interrupt" | "unavailable" — Why the brain's pick changed on the tick it changed.
+- `UtilityTerm` (interface): interface UtilityTerm — One need's contribution to an option's appeal.
+- `UtilityTunables` (interface): interface UtilityTunables — In-play dials that stay reachable through {@link UtilityBrain.retune}.
 - `VEGETATION_VOLUME_KIND` (const): const VEGETATION_VOLUME_KIND: "vegetation" — The editor volume kind that marks an area as vegetation fill.
 - `VISIBILITY_HIDDEN` (const): const VISIBILITY_HIDDEN: 0 — Numeric code for a cell no group member has seen, or has fully forgotten.
 - `VISIBILITY_OBSERVED` (const): const VISIBILITY_OBSERVED: 2 — Numeric code for a cell a group currently observes.
@@ -2727,12 +2824,15 @@
 - `createMarkerSet` (function): function createMarkerSet<TMeta = unknown>(now: () => number = Date.now): MarkerSet<TMeta> — ⚠ undocumented
 - `createMarkerSource` (function): function createMarkerSource<TEntity, TMarker extends MarkerView = MarkerView>(options: MarkerSourceOptions<TEntity, TMarker>): MarkerSource<TMarker> — Adapt a caller-owned array/store to an observable marker source. Projection is cached between source changes, so React reads do not copy the collection per frame. The caller retains ownership of entities, updates, persistence, and subscription scheduling.
 - `createMountController` (function): function createMountController(): MountController — ⚠ undocumented
+- `createNavCrowd` (function): function createNavCrowd(options: NavCrowdOptions & { nav: NavRuntime }): NavCrowd — Compose {@link createNavRuntime} and {@link createRvoCrowd} into a moving crowd: plan on the mesh, follow the smoothed corridor, avoid each other. Deterministic — agents advance in insertion order and the avoidance solve breaks ties by slot, not chance.
 - `createNavGrid` (function): function createNavGrid(config: NavGridConfig): NavGrid — ⚠ undocumented
 - `createNavMeshQuery` (function): function createNavMeshQuery(mesh: NavMeshData, options: NavMeshQueryOptions = {}): NavMeshQuery — Create a cached query over a nav mesh: height-aware polygon lookup through a uniform grid, binary-heap A* priced by area costs and bounded by `maxNodes`, portal-funnel path straightening, and edge-walking raycasts.
+- `createNavRuntime` (function): function createNavRuntime(options: NavRuntimeOptions & { mesh: NavMeshData }): NavRuntime — Route agents over the nav mesh an editor baked. Wraps {@link createNavMeshQuery}, resolves authored off-mesh links (doors, ladders, jumps) onto the current surface, and exchanges the mesh one scene region at a time so untouched polygons keep their ids and the agents routing over them keep their paths.
 - `createOrderQueue` (function): function createOrderQueue<TCtx, TPayload = unknown>(registry: OrderRegistry<TCtx>, options: OrderQueueOptions<TPayload> = {}): OrderQueue<TCtx, TPayload> — Create a per-entity order queue over a shared kind registry. The queue owns the deterministic lifecycle and preemption policy; the kinds own behavior. Nothing here is random or unbounded: id generation is injected, activation is bounded by the pending count, and a single `tick` advances at most the active order plus one activation.
 - `createOrderRegistry` (function): function createOrderRegistry<TCtx>(): OrderRegistry<TCtx> — Build an empty order-kind registry. Register the built-in compositions from `orders/orderKinds` or your own verbs, then hand it to `createOrderQueue`. One registry is shared by many per-entity queues.
 - `createParticleSystem` (function): function createParticleSystem(config: EmitterConfig = {}, options: ParticleSystemOptions = {}): ParticleSystem — A generic, allocation-aware particle system: one emitter, a fixed pool, and Structure-of-Arrays buffers a renderer uploads straight to the GPU. It is dt-driven (call `update(dt)` each frame) and deterministic — all randomness flows from an injected `seed`, so the same seed and dt sequence reproduce the same frames, and `snapshot`/`restore` round-trips the live pool. Nothing here is combat- or genre-specific: configure it for smoke, sparks, rain, dust, embers, magic, or confetti. Travel/gameplay stays elsewhere; this owns only the spawn-integrate-fade lifecycle.
 - `createPathFollow` (function): function createPathFollow(config: PathFollowConfig): PathFollowState — ⚠ undocumented
+- `createPerception` (function): function createPerception(initial: PerceptionConfig): PerceptionService — Creates a deterministic sight, sound, and damage perception service with expiring target memory. Signals are judged in the order the caller supplies them, never from the wall clock.
 - `createPlacedStructureStore` (function): function createPlacedStructureStore(): PlacedStructureStore — ⚠ undocumented
 - `createPlacementController` (function): function createPlacementController(config: PlacementControllerConfig): PlacementController — Headless placement ghost: hover → valid/invalid preview, rotate, grid/free/surface snap, commit. Pair with `@jgengine/shell/structures` `PlacementGhost` and {@link placeAssetFromCommit}.
 - `createPlotPermissions` (function): function createPlotPermissions(config: PlotPermissionConfig): PlotPermissions — ⚠ undocumented
@@ -2741,6 +2841,7 @@
 - `createRagdoll` (function): function createRagdoll(world: PhysicsWorld, config: RagdollConfig): Ragdoll — ⚠ undocumented
 - `createRegionField` (function): function createRegionField<T = unknown>(config: RegionFieldConfig<T>): RegionField<T> — ⚠ undocumented
 - `createReputationLedger` (function): function createReputationLedger(config: ReputationLedgerConfig = {}): ReputationLedger — ⚠ undocumented
+- `createRvoCrowd` (function): function createRvoCrowd(options: RvoCrowdOptions = {}): RvoCrowd — Reciprocal velocity obstacle avoidance over circular agents. Each nearby pair contributes one or two half-plane constraints on the agent's velocity, and a small linear program picks the velocity closest to the preferred one that satisfies them all. The neighbour search is a uniform grid capped at `maxNeighbors`, so a tick costs the same for 50 agents and 5,000.
 - `createScreenEffects` (function): function createScreenEffects(options: ScreenEffectsOptions = {}): ScreenEffectsController — A serializable screen-feedback controller: a game triggers transient flashes and edge vignettes (a red damage hit, a green heal flash) or sustained, optionally oscillating tints (a low-health pulse), and reads back a composite of the effects to draw right now with their eased opacities. It is clock-driven — call `advance()` each frame against an injected `now` — and allocation-aware: the composite array and its entries are pooled and reused, so steady-state ticking never allocates. Nothing here is genre-specific: `kind` is a free label the game owns and styles, and vignette / flash / pulse are just parameterizations of the same data (region shape, decay easing, sustained oscillation). A shell overlay subscribes and renders; `snapshot`/`restore` round-trips through a save.
 - `createSelectionBookmarks` (function): function createSelectionBookmarks(snapshot?: SelectionBookmarkSnapshot): SelectionBookmarks — Create a keyed bookmark store, optionally restored from a {@link serialize} snapshot. Restoration re-dedupes and drops empty sets, so a hand-authored or migrated snapshot always normalizes to the same invariants a live store holds.
 - `createSelectionSet` (function): function createSelectionSet(initial?: Iterable<string>): SelectionSet — An ordered, deduplicated set of selected instance ids for RTS unit-command routing.
@@ -2753,6 +2854,7 @@
 - `createTerrainSnapshot` (function): function createTerrainSnapshot(config: EditableTerrainConfig): TerraformSnapshot — A fresh, unedited terrain snapshot sized to `bounds`/`cellSize` — the seed for a new sculpt document.
 - `createThreatTable` (function): function createThreatTable(config: ThreatTableConfig = {}): ThreatTable — ⚠ undocumented
 - `createTimerSet` (function): function createTimerSet(options: TimerSetOptions = {}): TimerSet — Create a serializable set of named countdown / countup timers on an injected clock — one primitive for round timers, respawn clocks, and ability cooldown/charge. Start/pause/resume/stop/reset timers by free-string id, read `{ remainingMs, elapsedMs, durationMs, progress01, running, expired }` for a mm:ss readout or a radial/bar fill, and `poll` for expiry edges. Ids and labels carry no genre meaning; `snapshot`/`restore` round-trip through a save.
+- `createUtilityBrain` (function): function createUtilityBrain(config: UtilityBrainConfig): UtilityBrain — Create a utility brain over an existing {@link NeedSet}. The need set is injected, not owned, so the game shows the same hunger the brain scores and persists one copy.
 - `createVehicleBody` (function): function createVehicleBody(world: PhysicsWorld, config: VehicleBodyConfig): VehicleBody — ⚠ undocumented
 - `createVehicleObstacleClamp` (function): function createVehicleObstacleClamp(options: { /** Solids near the car this tick (already filtered to the relevant, solid set). */ obstacles: () => readonly CollisionObstacle[]; /** Vehicle body radius (units). Default {@link DEFAULT_VEHICLE_RADIUS}. */ radius?: number; /** Current tick dt (seconds)… — Build a slide-along move clamp for a kinematic car (#1051). `obstacles` is sampled fresh each tick — the caller hands back the already-filtered set of solids near the car — and `dt` supplies the current tick length so a blocked move's lost displacement converts to a closing speed. `radius` inflates each obstacle footprint by the car's body radius (default {@link DEFAULT_VEHICLE_RADIUS}).
 - `createVehicleSeats` (function): function createVehicleSeats(controller?: MountController): VehicleSeats — Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy.
@@ -2825,6 +2927,7 @@
 - `migrateTerrainSnapshot` (function): function migrateTerrainSnapshot(snapshot: TerraformSnapshot): TerraformSnapshot — Upgrades a pre-2.0 snapshot in place-safe (copy-on-write) form: derives a {@link TerrainMaterialLayer} stack from the distinct painted surfaces (first-seen order, default params) when none exists. Leaves the lazy `weights` buffer absent — a single-layer terrain stays compact until blended. Idempotent: a snapshot that already carries `layers` is returned unchanged.
 - `minimapBakeToPngDataUri` (function): function minimapBakeToPngDataUri(bake: MinimapBake): string — Encodes a bake as a `data:image/png;base64,...` URI — the exact string the `Minimap` / `WorldMap` `background` prop takes. Deterministic for a fixed bake.
 - `mtof` (function): function mtof(midi: number): number — Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69).
+- `navMeshFromBake` (function): function navMeshFromBake(bakes: readonly SceneBake[] | undefined, id = "main"): NavMeshData | null — Read the named navigation bake an editor wrote onto a scene document. Returns `null` when the document holds no such bake yet, and throws when the stored bake is not a valid nav mesh — a corrupt bake should fail at load, not as agents walking through walls.
 - `normalizeDegrees` (function): function normalizeDegrees(degrees: number): number — Wrap `degrees` into `[0, 360)` — the canonical heading range every policy and conversion here works in. Non-finite input collapses to `0` so bad metadata never leaks a `NaN` heading downstream.
 - `notesInWindow` (function): function notesInWindow(theme: MusicTheme, anchorSec: number, fromSec: number, toSec: number): ScheduledNote[] — Pure lookahead scheduler: every note occurrence of `theme` whose onset falls in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at `anchorSec`. Handles any number of loop wraps, so a director calls it once per tick with a non-overlapping window and never double-schedules a note.
 - `objectVisualScale` (function): function objectVisualScale(visual: ObjectVisual | undefined): readonly [number, number, number] — ⚠ undocumented
@@ -2909,6 +3012,7 @@
 - `sampleElevation` (function): function sampleElevation(sampleHeight: HeightSampler, x: number, z: number, reference = 0): ElevationReadout — Reads the ground elevation under a world point and its signed delta from a reference plane — the measurable cursor/hover feedback ("+3.4 above the pad") an author needs to judge sculpted height.
 - `sampleGripCurve` (function): function sampleGripCurve(curve: GripCurve, slip: number): number — Piecewise-linear tire-grip curve: normalized lateral slip → available grip (0..1). Grip peaks near the breakaway slip then falls off as the tire slides — the shape that separates a planted corner from a drift. Points are read in ascending slip order; ends clamp.
 - `samplePoint` (function): function samplePoint<P extends SamplePoint>(options: SamplePointOptions<P>): SampleResult<P> — Draw one point from `region` that clears every constraint, retrying up to `maxAttempts` times with the injected `rng`, then apply the `fallback` policy. Returns a structured {@link SampleResult} — a clean hit is `ok: true`; exhaustion or a degenerate region is reported with the attempt count and an explicit fallback flag, never a silently-accepted bad point.
+- `sampleResponseCurve` (function): function sampleResponseCurve(curve: ResponseCurve, satisfaction: number): number — Sample a response curve at a `0..1` satisfaction. Deterministic, allocation-free.
 - `sampleStratified` (function): function sampleStratified(options: StratifiedOptions): Vec2[] — Stratified 2D sampling: one jittered point per grid cell over `area`, in deterministic row-major order. Unlike pure rejection sampling this guarantees even coverage (no clumps, no gaps) — the distinct "stratified" distribution policy, kept separate from area-uniform draws.
 - `sanitizeGameTimeScale` (function): function sanitizeGameTimeScale(timeScale?: number | null): number — ⚠ undocumented
 - `scatter` (function): function scatter(config: ScatterConfig): ScatterPoint[] — ⚠ undocumented
@@ -3401,7 +3505,7 @@
 - `RainEnvironmentDescriptor` (type): type RainEnvironmentDescriptor = { kind: "rain" } & Required< Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color" | "width" | "opacity"> > — ⚠ undocumented · used by `rain`: Declares a rainfall weather effect for `environment()` — area, density, speed, wind, and drop width/opacity.
 - `RoadEnvironmentConfig` (interface): interface RoadEnvironmentConfig — Config for {@link road}: a flat asphalt ribbon draped over the terrain along a centerline.
 - `RoadEnvironmentDescriptor` (type): type RoadEnvironmentDescriptor = { kind: "road" } & Required< Pick<RoadEnvironmentConfig, "path" | "width" | "color" | "markings" | "markingColor" | "elevation"> > & { /** Resolved sidewalk band, or `false` when the road has none. */ sidewalk: { width: number; color: string } | false; /** Procedural… — Resolved road descriptor produced by {@link road} and rendered by the shell environment scene.
-- `SkyEnvironmentConfig` (interface): interface SkyEnvironmentConfig { preset?: "day" | "dusk" | "night"; timeOfDay?: boolean; horizonColor?: string; zenithColor?: string; sunIntensity?: number; ambientIntensity?: number; sun?: SkySunConfig; radius?: number; hazeStrength?: number; sunGlowStrength?: number; g… — ⚠ undocumented · used by `CINEMATIC_SKY` (@jgengine/core/render/lookPreset): A static day sky: a real dome plus the shell's view-following shadow-casting sun and hemisphere fill.
+- `SkyEnvironmentConfig` (interface): interface SkyEnvironmentConfig { preset?: "day" | "dusk" | "night"; timeOfDay?: boolean; horizonColor?: string; zenithColor?: string; sunIntensity?: number; ambientIntensity?: number; sunColor?: string; fogColor?: string; moonIntensity?: number; moonColor?: string; sun?:… — ⚠ undocumented · used by `CINEMATIC_SKY` (@jgengine/core/render/lookPreset): A static day sky: a real dome plus the shell's view-following shadow-casting sun and hemisphere fill.
 - `SkyEnvironmentDescriptor` (type): type SkyEnvironmentDescriptor = { kind: "sky" } & Required< Pick<SkyEnvironmentConfig, "preset" | "timeOfDay"> > & Omit<SkyEnvironmentConfig, "preset" | "timeOfDay"> — ⚠ undocumented
 - `SkySunConfig` (interface): interface SkySunConfig — Where the sun sits, as a compass bearing and a height above the horizon, both in degrees. `azimuth` 0 points toward -Z (north), 90 toward +X (east); `elevation` 90 is straight overhead.
 - `SnowEnvironmentConfig` (interface): interface SnowEnvironmentConfig { area?: EnvironmentArea; position?: EnvironmentVec2; density?: number; speed?: number; flakeSize?: number; drift?: number; wind?: EnvironmentVec2; color?: string; opacity?: number } — ⚠ undocumented · used by `snow`: Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity.

package/skills/jgengine-world/capabilities.md

@@ -549,14 +549,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `sweepMovingSphere` (function) · `import { sweepMovingSphere } from "@jgengine/core/physics/ballisticSweep"`
 
+## nav-crowd — move many agents across an editor-baked nav mesh with avoidance
+
+- `createNavCrowd` (function) · `import { createNavCrowd } from "@jgengine/core/world"`
+
 ## nav-from-solids — block world solids on a nav grid
 
 - `populateNavGridFromSolids` (function) · `import { populateNavGridFromSolids } from "@jgengine/core/nav/navFromEnvironment"`
 
+## nav-runtime — route agents on an editor-baked nav mesh with authored links and re-bakes that keep polygon identity
+
+- `createNavRuntime` (function) · `import { createNavRuntime } from "@jgengine/core/world"`
+
 ## navmesh-bake — voxelize scene triangles into an agent-sized polygon nav mesh
 
 - `bakeNavMesh` (function) · `import { bakeNavMesh } from "@jgengine/navbake"`
 
+## navmesh-from-scene — read the editor's baked nav mesh off a scene document
+
+- `navMeshFromBake` (function) · `import { navMeshFromBake } from "@jgengine/core/world"`
+
 ## navmesh-query — route, snap, and raycast on a polygon navmesh with retunable area costs and a bounded search
 
 - `createNavMeshQuery` (function) · `import { createNavMeshQuery } from "@jgengine/core/world"`
@@ -610,9 +622,9 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `definePatrolOrder` (function) · `import { definePatrolOrder } from "@jgengine/core/world"`
 
-## perception-service — retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
+## perception-service — retain sightings, sounds and damage with cone, range, occlusion, decaying memory and shared squad knowledge
 
-- `createPerception` (function) · `import { createPerception } from "@jgengine/core/sensor/perception"`
+- `createPerception` (function) · `import { createPerception } from "@jgengine/core/world"`
 
 ## physics-backend — one interface over interchangeable rigid-body solvers — bodies, joints, raycast, shapecast, snapshot
 
@@ -707,6 +719,10 @@ 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"`
 
+## rvo-avoidance — reciprocal collision avoidance between many steering agents
+
+- `createRvoCrowd` (function) · `import { createRvoCrowd } from "@jgengine/core/world"`
+
 ## scatter-coverage — shared density/budget semantics for scatterable kinds
 
 - `ScatterCoverageKind` (type) · `import { ScatterCoverageKind } from "@jgengine/core/world"`
@@ -889,6 +905,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveTerrainGradeStep` (function) · `import { resolveTerrainGradeStep } from "@jgengine/core/movement/terrainGrade"`
 
+## utility-brain — pick actions by decaying-need appeal with response curves, hysteresis and interrupts
+
+- `createUtilityBrain` (function) · `import { createUtilityBrain } from "@jgengine/core/world"`
+
 ## vehicle-backend-link — collide a vehicle sim with a physics backend — shove props, stop at walls, slide along them
 
 - `createVehicleBackendLink` (function) · `import { createVehicleBackendLink } from "@jgengine/core/physics/vehicleBackendLink"`

package/skills/jgengine-world/recipes/npc-senses.md

@@ -15,8 +15,14 @@ Working example: the `guard-probe` dev demo (`apps/dev/src/demo/guardProbe.ts`),
   senses. Each tick, push the stimuli your game produces (`sound` with a
   `loudness` that scales range, `damage`) and call `observe(npc, candidates, nowMs)`
   with a *bounded* candidate list from a spatial query, never every entity. Pass
-  `occluded` for walls. Memory decays linearly over `memorySeconds`; each observer
-  judges a stimulus once.
+  `isSegmentClear` for walls — a caller function over your collision layer that
+  returns true when nothing blocks the line; it is only called for pairs already
+  inside range and cone, so keep that cheap. Memory decays linearly over
+  `memorySeconds`; each observer judges a stimulus once. Pass `squadMates` so one
+  member's sighting lands in every mate's memory stamped with `sourceId` and
+  `sourceTick`; `maxSharesPerTick` caps the broadcast. `memoryOf(id, target)` is
+  the one question "is this still known, and how sure", and `stats()` says what
+  the pass cost (pairs, range prunes, line checks, shares).
 - **Memory → blackboard.** A small system copies the facts the graph needs into
   the NPC's persistent blackboard: `behaviorControl(ctx).blackboard(id)`. Write
   plain scalars (`alerted`, `lastKnownX`, `lastKnownZ`, `confidence`). Actions