@jgengine/core 0.25.0 → 0.26.0

package/dist/editor/types.d.ts

@@ -7,6 +7,7 @@ import type { MinimapBakeBounds } from "../world/minimapBake.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
 import type { EditorGridLayer } from "./grid.js";
 import type { EnvironmentSource } from "../render/environment.js";
+import type { IrradianceBakeSettings, IrradianceVolume } from "../render/lightProbes.js";
 import type { PointLightingConfig } from "../game/playableGame.js";
 /** Runtime point-light shape reused by authored editor light markers. */
 export type { PointLightingConfig } from "../game/playableGame.js";
@@ -196,6 +197,17 @@ export interface EditorBake {
 }
 /** Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`. */
 export type EditorSkyPreset = "day" | "dusk" | "night";
+/**
+ * An irradiance volume authored on the scene document: a grid of baked SH probes over a box, plus
+ * the bake settings that produced them so a scene can re-bake without the editor session.
+ * @capability light-probes author a baked irradiance volume on the scene document
+ */
+export interface EditorLightProbe extends IrradianceVolume {
+    /** Label shown in the lighting workspace. */
+    label?: string;
+    /** The authored bake inputs; absent means the volume was authored elsewhere and only the probe data matters. */
+    bake?: IrradianceBakeSettings;
+}
 /**
  * Linear distance fog authored on the scene document — serializable subset of sky/backdrop fog.
  * Absent fields keep engine defaults when the document is applied at runtime.
@@ -205,6 +217,40 @@ export interface EditorFogConfig {
     near?: number;
     far?: number;
 }
+/**
+ * Authored colour grading for the scene document's final image. The editor bakes a small
+ * display-space LUT from these controls and the shell applies it after tone mapping, so a game's
+ * grade is authored data like its sky, not a hardcoded pass in the game's config.
+ *
+ * The three band colours are display swatches (`#rrggbb`) that the pixels of that band are pulled
+ * toward, by `tint`. `saturation` and `contrast` are applied before the bands. Baking at a small cube
+ * size keeps the whole grade — including the LUT — a few hundred bytes of JSON.
+ */
+export interface EditorColorGrading {
+    /** Cube edge length the runtime bakes, 2..16. Default 8 — small enough to read, smooth enough for a grade. */
+    size?: number;
+    /** Swatch shadows are tinted toward, e.g. `#2a3a52` for a cool night. Absent leaves shadows alone. */
+    shadows?: string;
+    /** Swatch midtones are tinted toward. Absent leaves midtones alone. */
+    midtones?: string;
+    /** Swatch highlights are tinted toward, e.g. `#ffe9c4` for a warm sun. Absent leaves highlights alone. */
+    highlights?: string;
+    /** How far each band is pulled toward its swatch, 0..1. Default 0.45. */
+    tint?: number;
+    /** Display saturation around luma. Default 1. */
+    saturation?: number;
+    /** Display contrast around mid-grey. Default 1. */
+    contrast?: number;
+    /** Clamped auto-exposure authored with the grade; absent uses the pipeline's default range. */
+    autoExposure?: EditorAutoExposure;
+}
+/** Authored clamped auto-exposure range: how far the meter may pull a dark room or a bright street. */
+export interface EditorAutoExposure {
+    /** Lowest exposure multiplier the meter may reach. Default 0.5. */
+    min?: number;
+    /** Highest exposure multiplier the meter may reach. Default 2.5. */
+    max?: number;
+}
 /**
  * Scene-document environment/lighting authoring (#1110): sky preset, optional time-of-day drive,
  * horizon/zenith tints, sun/ambient intensity, and fog. Serializable and genre-agnostic — games
@@ -216,8 +262,16 @@ export interface EditorFogConfig {
 export interface EditorEnvironment {
     /** Optional runtime environment map source; absent keeps the procedural gradient. */
     source?: EnvironmentSource;
+    /** Authored clamped auto-exposure and colour grade; the shell applies it to the post chain. */
+    grading?: EditorColorGrading;
     /** Authored local point lights; the runtime clamps these to its bounded light budget. */
     pointLights?: readonly PointLightingConfig[];
+    /**
+     * Authored irradiance volumes: baked light probes for interiors and shaded streets. The runtime
+     * samples them at the camera and feeds three.js's scene light probe, so a room's ambient comes
+     * from its own lights instead of the sky.
+     */
+    probes?: readonly EditorLightProbe[];
     /** Fixed sky look when `timeOfDay` is off (or no clock is available). */
     preset?: EditorSkyPreset;
     /** Drive sun/sky from the world clock's day fraction instead of the fixed `preset`. */

package/dist/gameplay.d.ts

@@ -95,6 +95,10 @@ export { createTriggeredRuleEngine, type ActiveEffect, type EffectRef, type Firi
 export { createRing, ringSampleAt, type Ring, type RingConfig, type RingPhase } from "./session/ring.js";
 export { type RoleSpec } from "./session/roles.js";
 export { type RoundConfig, type RoundSnapshot } from "./session/roundState.js";
+export { createNearAgents, type NearAgentSnapshot, type NearAgentView, type NearAgentsOptions, type NearCrowdAgents, } from "./sim/nearAgents.js";
+export { createNeedSet, type NeedDefinition, type NeedReading, type NeedSet, type NeedSnapshot } from "./sim/needs.js";
+export { createOffScreenWorld, type NearAgents, type NearHandoff, type NearSpawn, type OffScreenAgentView, type OffScreenMode, type OffScreenOptions, type OffScreenPolicy, type OffScreenPolicyPatch, type OffScreenResidentSpec, type OffScreenSnapshot, type OffScreenStats, type OffScreenWorld, } from "./sim/offScreen.js";
+export { resolveRoutine, type RoutineConfig, type RoutinePhase, type RoutineStop, type RoutineStopSpec, type RoutineTimeline, } from "./sim/routine.js";
 export { createDecayMeterSet, decayMeterMoodles, decayMeterSnapshot, decayMeterState, decayMeters, initDecayMeters, refillMeter, type DecayMeterSet, type DecayMeterValues, type DecayModifier, } from "./survival/decayMeter.js";
 export { createMoodleStack, stackMoodles, type Moodle, type MoodleStack } from "./survival/moodle.js";
 export { createMultiRegionHealth, type MultiRegionHealth } from "./survival/regionHealth.js";

package/dist/gameplay.js

@@ -95,6 +95,10 @@ export { createTriggeredRuleEngine, } from "./rules/triggeredRules.js";
 export { createRing, ringSampleAt } from "./session/ring.js";
 export {} from "./session/roles.js";
 export {} from "./session/roundState.js";
+export { createNearAgents, } from "./sim/nearAgents.js";
+export { createNeedSet } from "./sim/needs.js";
+export { createOffScreenWorld, } from "./sim/offScreen.js";
+export { resolveRoutine, } from "./sim/routine.js";
 export { createDecayMeterSet, decayMeterMoodles, decayMeterSnapshot, decayMeterState, decayMeters, initDecayMeters, refillMeter, } from "./survival/decayMeter.js";
 export { createMoodleStack, stackMoodles } from "./survival/moodle.js";
 export { createMultiRegionHealth } from "./survival/regionHealth.js";

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.25.0";
+export declare const VERSION = "0.26.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,62 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.25.0";
+export const VERSION = "0.26.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.26.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.26.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.23.0`; `@jgengine/github` is `0.13.0`.",
+        ],
+        added: [
+            "`createLogBus` (`@jgengine/core/devtools/logBus`): a fixed-capacity ring of log lines tagged by owning system, with a separate ring for warnings and errors so a crash line is never pushed out by info traffic. `devtools.logs` now writes through it (`write(level, system, message)`, `snapshot()`, `counts()`, `dropped()`); `DevtoolsLogEntry` gained `system`.",
+            "`devtools.probes.registerSystem(id, { counters, timers, state })`: a system reports its own counters, named timings and one state line in a few lines, with no shell wiring. Readings surface as `systems` in `devtools.snapshot()`, in `debug_snapshot`, and in every perf record.",
+            "`PerfReport` (`@jgengine/core/devtools/report`): the one perf record shape shared by `bun run perf` and the in-page report.",
+            "The shell samples frame telemetry in-page in dev builds: `window.__JG.report()` returns that record, and the page pushes it about once a second to the dev server's `GET/POST /__jgengine/report` route. `bun run debug <game>` prints the record of a game already open and exits non-zero on a budget breach in `scripts/perf-budget.json`.",
+            "`createNeedSet` (`@jgengine/core/gameplay`) drains named needs on game time and reads them by index — decaying hunger, energy, fun with snapshot/restore and per-need rate retuning.",
+            "`createUtilityBrain` (`@jgengine/core/world`) picks an action from decaying-need appeal: linear, quadratic, logistic, exponential and threshold response curves, candidate cost (travel, queues, price), a switch margin plus minimum hold (hysteresis), declared interrupts, optional seeded jitter, and a devtools probe string.",
+            "`createNavRuntime` (`@jgengine/core/world`) consumes an editor-baked nav mesh: reads the `nav` bake off a scene document (`navMeshFromBake`), routes with the mesh query, resolves authored doors, ladders and jumps (`AuthoredNavLink`, priced by kind) onto the current surface, and swaps in a new bake after an edit while matching polygon identity by geometry — `applyMesh` returns a `remap` so only routes over changed polygons need re-planning.",
+            "`createNavCrowd` (`@jgengine/core/world`) moves many agents across that mesh: plans a corridor, follows the funnel-smoothed waypoints, keeps agents apart with reciprocal velocity obstacle avoidance, bounds path searches per tick by count and milliseconds, fans converging agents out with `spread`, and round-trips through `snapshot`/`restore`.",
+            "`createRvoCrowd` (`@jgengine/core/world`) is the avoidance solver on its own: RVO/ORCA half-plane solve over a uniform-grid neighbour search capped at `maxNeighbors`, deterministic tie-breaking, overlap relief, retunable `timeHorizon`/`neighborDist`/`maxNeighbors`/`sideBias`/`overlapRelief`, and `snapshot`/`restore` for saves and replays.",
+            "`resolveRoutine` (`@jgengine/core/gameplay`) resolves an authored day into real arrival and departure times against the world clock. Travel time is injected per stop or as a callback, so a stop departs early enough to walk to the next one and an arrival that runs late slips instead of teleporting; `phaseAt(time)` returns the held place, the walking leg and its progress, and `nextChangeAfter(time)` drives a scheduler. A day whose walks cannot fit its cycle throws at construction.",
+            "`createOffScreenWorld` (`@jgengine/core/gameplay`) keeps a whole population without simulating it: residents beyond the injected radius are cheap state (position, routine phase, needs) that only moves when the clock crosses a routine boundary, and they spawn into the game's own near simulation through a `NearAgents` interface when they come close. The radius, an optional per-agent cost model, a near budget and a per-tick switch budget are all injected; `snapshot`/`restore` round-trip the whole population, and crossing the boundary preserves identity, schedule progress, need values and position.",
+            "`createNearAgents` (`@jgengine/core/gameplay`) is the default near half of that seam: a nav crowd with a need set and utility brain per agent, goal-tracking as routines move residents between places, and a decision counter for tests and probes.",
+            "`createPerception` shares squad knowledge: `squadMates(observerId)` names an observer's roster, and a sighting one member makes is written into every mate's memory with `sourceId` (who saw it) and `sourceTick` (the observe pass it was recorded on). A mate's own sighting at the same instant replaces the hand-off. `maxSharesPerTick` (default 64, per observer pass) bounds a large roster and reports elided shares.",
+            "Perception memory is auditable without guessing: `memoryOf(observerId, targetId)` returns the one remembered target with its confidence right now or `null` once it has faded, and `stats()` counts pair checks, range prunes, cone tests, line-of-sight calls, sightings, heard stimuli, shares and dropped shares. The check order is range → cone → line of sight, so occlusion work only sees the pruned set. `resetStats()` opens a measurement window; `memories` are pruned per observer so a 200-observer pass does not rescan every memory.",
+            "`devtoolsName` registers a probe showing observers, remembered targets and the work counters, and `dispose()` removes it.",
+            "`createCoverField` and `coverPointsFromSolids` (`@jgengine/core/combat`) derive stand-able cover from authored solid boxes instead of a coordinate list: one row of points per vertical face, clear of the corners, filtered by an injected `walkable` test, rebuilt when the world is edited, and queried through a bounded `near(position, radius, limit)`. `CoverSource` is the seam, so a game with its own spatial index can supply cover without the box generator.",
+            "`selectCover` / `scoreCoverPoint` choose cover by threat: `hidden` is the confidence-weighted share of remembered threats whose line of sight the point (and a body-sized footprint at it) blocks, scored against the role's preferred fighting range, flank angle around the threat, distance, a squadmate's claim on the point, and whether the walk to it is a detour. Fading memories stop steering at `minConfidence`, and a point that hides from only one of two shooters is not cover.",
+            "`createSquadCombat` (`@jgengine/core/combat`) drives a squad over existing seams: role-driven cover selection, fire discipline (hold, lean out, shoot), suppression from `underFire()`, retreat below a role's health threshold, and relocation under sustained fire. Threat comes only from `threatsFromMemory`, i.e. the perception memory the game already keeps; movement goes through `NavCrowd` with a tighter arrival tolerance so a body actually reaches the stand point. Serializable through `snapshot()`/`restore()` (member decisions, crowd, tuning), retunable, and a `devtoolsName` probe reports pins, peeks, shots and the worst exposure.",
+            "`assignSquadRoles` and `threatsFromMemory` (`@jgengine/core/combat`): deterministic role assignment over a caller-authored `SquadComposition` (role ids, counts, ranges, flank angles, retreat thresholds and cover weights are all content), and a bounded, confidence-ranked threat list from one observer's memory.",
+            "A 2v4 arena soak proves the behavior: 90 simulated seconds, 2700 ticks, 4 squad members against 2 scripted raiders, worst exposure 2.33 s (bar 3 s), 0 of 38 exposure spells over 3 s, per-tick cost p50 0.05 ms / p95 0.19 ms.",
+            "`createDamageRuntime` (`@jgengine/core/combat`) composes a damage table, hit zones, the armor curve and carried statuses into one stateful model: `hit()` returns every stage of the number (`base × zone multiplier × type multiplier × (1 − armor mitigation)`), `tick()` runs status effects through the same table and armor, `timeToKill()` quotes a fight, and `table()` reads the whole chart. `snapshot()`/`restore()` carry registered targets and carried statuses; `retune()` swaps table, zones or status definitions without dropping either; a `devtoolsName` probe reports hits, crits, ticks and the last hit.",
+            "A damage table (`combat/damageTable`) of damage type × resistance class, with `armor / (armor + halfValue)` mitigation — armor equal to the half value halves the hit — a per-type `bypassArmor`, and `readDamageTable` / `formatDamageTable` to read every row at given armor values. An unknown damage type throws instead of silently dealing 1×.",
+            "Hit zones and crits (`combat/hitZones`): a zone carries a normal multiplier and an optional crit multiplier, `resolveHitZone` rolls once and returns one multiplier, and a crit replaces the zone multiplier rather than compounding with it. `hitZoneMultiplier` quotes the same number without a roll.",
+            "`createStatusRuntime` (`combat/statusRuntime`): data-defined statuses with the existing `StatusStackPolicy` (`refresh`, stack to `max`, `replace`, `ignore`) as the only thing that changes stacks, per-tick effects of `{ kind: \"damage\", channel }` or `{ kind: \"stat\", stat }`, damage routed through an injected `applyDamage` so resistances and armor still apply, bounded ticks per call, and plain-data state out and back.",
+            "Numbers from the tests: 25 base kinetic against a 150 HP target, 0.15 s between shots — 8 shots / 1.05 s unarmored, 20 shots / 2.85 s at 60 armor, 36 shots / 5.25 s at 200 armor; two stacked burns of 4 per tick deal 8, not 16; a 1.5× head zone with a 2.5× crit multiplier deals 2.5×, not 3.75×.",
+            "`createWeaponSystem` (`@jgengine/core/combat`) runs one `WeaponDefinition`: single, automatic or burst fire, hitscan or ballistic projectiles, recoil that moves the aim the shot flies down, spread bloom, interrupted/resumed reloads, a readable ammo economy (`ammo()`, `stats()`), `snapshot()`/`restore()` and a devtools probe. Every hit, hitscan or projectile, resolves through `createDamageRuntime`. Pellet work is bounded per tick (`maxShotsPerTick`, default 4) and per weapon (`maxInFlight`, default 32).",
+            "`WeaponDefinition` (`@jgengine/core/combat/weaponDefinition`) as plain JSON — rate, fire mode, delivery, magazine, handling, damage, falloff — with `assertWeaponDefinition`, `weaponIntervalMs`, `weaponDamageAt` and `weaponMaxInFlight`. A generated gun is the same shape.",
+            "`Magazine.pauseReload()` / `resumeReload()` / `isPaused()` suspend a reload and keep its progress; a paused reload is not `isReloading()`, does not advance in `tick`, and round-trips through `snapshot()`/`restore()`.",
+            "`environment.grading` on the scene document authors a per-game colour grade: shadow/midtone/highlight swatches plus tint, saturation and contrast bake into a small display-space LUT (`lutCubeFromGrading`, `colorGradeFromDocument` in `@jgengine/core/editor/environment`), edited in the Lighting workspace. The shell applies it from `editorLayers`, and a graded game needs no LUT asset or hardcoded pass.",
+            "Clamped auto-exposure: `postProcessing.autoExposure: { min, max, adaptationSeconds } | false` meters the pre-tone-map frame every four frames toward 18% grey and stays inside the authored range. `WHITE_POINT` and `MID_GREY` in `@jgengine/core/render/colorPipeline` are the single documented calibration the pipeline uses.",
+            "`GradeConfig.lut` also accepts a baked `{ cube: { size, data } }` LUT, sampled trilinearly after the numeric grade.",
+            "`MATERIAL_LIBRARY` (`@jgengine/assets/catalogs/materialLibrary`) names 56 PBR surfaces — wet asphalt, painted metal, stucco, brick, wood, foliage with cut-out coverage and sheen, glass, water, sand, concrete and more — each mapping a name to an ambientCG source, a world tile size in metres and a physical response. `libraryMaterialAsset(\"asphalt/wet\")` returns the editable `MaterialAsset` those names resolve to, and `filterLibraryMaterials` backs pickers. `assets pull library` pulls every pinned map set.",
+            "`TriplanarAssetMaterial` / `useTriplanarAssetMaterial` / `applyTriplanarProjection` (`@jgengine/shell/render/triplanarMaterial`) render a material asset from world position, so world geometry without a `uv` attribute still gets colour, normal, roughness and AO maps. Tile size is world metres; instanced meshes project in instanced space.",
+            "The editor's Materials workspace browses the library by name and writes the chosen entry into the document's material assets.",
+        ],
+        changed: [
+            "`createPerception` (`@jgengine/core/world`, also `@jgengine/core/sensor/perception`) takes `isSegmentClear` instead of `occluded`: the game supplies collision as a \"nothing blocks this segment\" test, and it is only called for pairs already inside range and cone. Migration: flip the predicate — a `occluded: (from, to) => blocked(from, to)` becomes `isSegmentClear: (from, to) => !blocked(from, to)`.",
+            "`MagazineSnapshot` gains an optional `paused: true` field, present only while a reload is suspended, so existing snapshots and idle shapes are unchanged.",
+            "AgX is the pipeline's tone map: `postProcessing.toneMapping` defaults to `\"agx\"`, and the `cinematic`, `photoreal`, `comic`, `retro` and `STUDIO_STAGE_POST` configs now pick it too. `\"toon\"` keeps `\"linear\"` on purpose. Games that authored `\"aces\"` explicitly are unchanged.",
+            "The grade pass samples LUT tiles at texel centres and blends the blue axis by hand, so a supplied strip LUT no longer bleeds across slices.",
+            "`bun run debug <game>` now finds the server `bun dev` started. The website dev server publishes the same checkout marker the runner does (`scripts/devServerMarker.ts`, written at listen, removed on shutdown, dev builds only), and the marker records the host that answers, since Vite's default `localhost` can be IPv6-only where `127.0.0.1` hangs.",
+            "The website dev server serves `GET/POST /__jgengine/report` too, so a game opened at `/games/<id>` reports from the `/play` runner it embeds.",
+            "The in-page sampler installs when the dev report route answers, not on a build-time `PROD` check: the `/play` runner is a production build, so the old check silently disabled the report on `bun dev`.",
+            "A report taken inside the sampler's warmup is no longer judged on link/framebuffer counts, which only mean something after the warmup baseline exists.",
+            "`extractMaterialMaps` and `buildMaterialCatalog` now recognise ambientCG's `_Opacity` map, so cut-out foliage and decal scans keep their coverage instead of rendering as solid cards.",
+            "Capture runs no longer leak a ~150 MB temp Chrome profile each. `shoot`, `drive` and `perf` delete their profile on every exit path — success, throw, watchdog and SIGINT — `bun run shoot` reclaims profiles a killed run left untouched for three hours, the capture guard sweeps the profile of a run it force-kills, and the generated `browser.mjs` harness for game repos removes its own. A capture also refuses to start when the temp drive has less free space than it needs.",
+            "The post-processing chain, graphics settings and textured terrain material keep a stable identity across renders. Before, every render rebuilt the effect composer and recompiled shaders, which dropped games to single-digit FPS.",
+        ],
+        removed: [],
+    },
     "0.25.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.25.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.22.0`; `@jgengine/github` is `0.12.0`.",

package/dist/nav/navCrowd.d.ts

@@ -0,0 +1,138 @@
+import type { Vec3 } from "../world/geometry.js";
+import type { NavRebuildStats, NavRegion, NavRuntime } from "./navRuntime.js";
+import { type RvoTunables } from "../ai/rvo.js";
+/** How one crowd agent was configured when it joined. */
+export interface NavCrowdAgentSpec {
+    position: Vec3;
+    goal: Vec3;
+    /** World units per second; defaults to the crowd's `speed`. */
+    speed?: number;
+    /** Avoidance radius; defaults to the crowd's `radius`. */
+    radius?: number;
+}
+/** One crowd agent's live state, as a game or the devtools overlay reads it. */
+export interface NavCrowdAgentView {
+    id: string;
+    position: Vec3;
+    velocity: readonly [number, number];
+    goal: Vec3;
+    /** Index of the waypoint it is steering toward; equals the waypoint count once the route is done. */
+    waypoint: number;
+    waypoints: number;
+    arrived: boolean;
+    /** True while the agent waits for its turn in the bounded re-plan budget. */
+    waitingForPlan: boolean;
+}
+/** Result of telling the crowd the nav mesh changed. */
+export interface NavCrowdRevalidate {
+    /** Agents whose remaining route crossed replaced polygons and were queued for a new plan. */
+    queued: number;
+    /** Agents whose route stayed entirely on kept polygons and was left alone. */
+    untouched: number;
+}
+/** Counters a devtools probe or test reads. */
+export interface NavCrowdStats {
+    agents: number;
+    arrived: number;
+    waitingForPlan: number;
+    /** Path searches run since creation — add, setGoal, queued plans and repaths. */
+    plans: number;
+    /** Path searches that returned no route. */
+    unroutable: number;
+    ticks: number;
+    /** Slowest single `tick` seen so far, in milliseconds. */
+    slowestTickMs: number;
+}
+/** Serializable crowd state: agents, their routes, and the avoidance tuning they run under. */
+export interface NavCrowdSnapshot {
+    tunables: {
+        speed: number;
+        radius: number;
+        goalRadius: number;
+        spread: number;
+        waypointRadius: number;
+        replanBudget: number;
+        replanMs: number;
+        avoid: RvoTunables;
+    };
+    agents: {
+        id: string;
+        position: Vec3;
+        velocity: readonly [number, number];
+        goal: Vec3;
+        offsetX: number;
+        offsetZ: number;
+        speed: number;
+        radius: number;
+        waypoints: Vec3[];
+        waypoint: number;
+        arrived: boolean;
+        polys: number[];
+        waitingForPlan: boolean;
+    }[];
+}
+/** Tunables for {@link createNavCrowd}, every one retunable in play. */
+export interface NavCrowdOptions {
+    /** Default walking speed for agents that do not set their own. */
+    speed?: number;
+    radius?: number;
+    /** Distance to the goal that counts as arrived. Default 0.5. */
+    goalRadius?: number;
+    /**
+     * Radius, in world units, over which agents targeting the same goal fan out onto distinct spots
+     * (`ai/crowd`'s stable per-id `spreadOffset`). `0` walks every agent to the exact goal. Default 0.
+     */
+    spread?: number;
+    /** Distance to a waypoint that advances to the next one. Default 0.6. */
+    waypointRadius?: number;
+    /** Most path searches one `tick` may run for queued agents. Default 8. */
+    replanBudget?: number;
+    /** Milliseconds of path searching one `tick` may spend, whatever the budget. Default 1.5. */
+    replanMs?: number;
+    /** Avoidance tuning for the internal {@link RvoCrowd}. */
+    avoid?: Partial<RvoTunables>;
+    /** Register a devtools probe under this name so the perf overlay shows crowd counters. */
+    devtoolsName?: string;
+}
+/**
+ * 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.
+ */
+export interface NavCrowd {
+    /** Add an agent and plan its first route; false when the id is already present. */
+    add(id: string, spec: NavCrowdAgentSpec): boolean;
+    remove(id: string): boolean;
+    has(id: string): boolean;
+    count(): number;
+    ids(): readonly string[];
+    /** Send an agent somewhere new; it re-plans on the next tick within the re-plan budget. */
+    setGoal(id: string, goal: Vec3): boolean;
+    /** Plan one agent now, ignoring the budget. Returns false when no route exists. */
+    plan(id: string): boolean;
+    agent(id: string): NavCrowdAgentView | null;
+    /** Advance every agent by `dt` seconds. */
+    tick(dt: number): void;
+    /**
+     * Queue a re-plan for agents whose remaining route crossed polygons the last
+     * {@link NavRuntime.applyMesh} replaced or moved; routes on kept polygons are left intact.
+     */
+    revalidate(stats: NavRebuildStats, region?: NavRegion): NavCrowdRevalidate;
+    stats(): NavCrowdStats;
+    retune(patch: NavCrowdOptions): void;
+    snapshot(): NavCrowdSnapshot;
+    restore(next: NavCrowdSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * 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.
+ *
+ * @capability nav-crowd move many agents across an editor-baked nav mesh with avoidance
+ */
+export declare function createNavCrowd(options: NavCrowdOptions & {
+    nav: NavRuntime;
+}): NavCrowd;