@jgengine/core 0.10.0 → 0.12.0

package/dist/ai/interestScheduler.js

@@ -0,0 +1,118 @@
+import { hashString } from "../random/rng.js";
+/**
+ * A deterministic `[0,1)` cadence phase derived from a stable id, for staggering sibling gates so a
+ * batch of agents spawned together does not fire their first active tick on the same frame. Pass the
+ * result as the `phase` argument to {@link createInterestGateState}.
+ *
+ * @capability interest-stagger deterministic per-id cadence phase that spreads sibling gate ticks across frames
+ */
+export function interestPhase(seed) {
+    const hashed = typeof seed === "number" ? hashString(String(seed)) : hashString(seed);
+    return (hashed % 100000) / 100000;
+}
+function nominalInterval(config) {
+    return config.activeInterval ?? config.tiers?.[0]?.interval ?? 0;
+}
+/**
+ * Create a dormant gate state, staggered by `phase` (`[0,1)`, typically {@link interestPhase} of the
+ * agent id) so siblings created together do not all fire their first active tick on the same frame.
+ *
+ * @capability interest-gate per-agent sleep/wake + cadence gate state so far agents skip expensive ticks
+ */
+export function createInterestGateState(config, phase = 0) {
+    const clamped = phase - Math.floor(phase);
+    return {
+        state: "dormant",
+        clock: clamped * nominalInterval(config),
+        awakeHold: 0,
+        phase: clamped,
+    };
+}
+function intervalFor(config, proximity) {
+    if (config.tiers !== undefined && proximity !== null) {
+        for (const tier of config.tiers) {
+            if (proximity <= tier.within)
+                return Math.max(0, tier.interval);
+        }
+    }
+    return Math.max(0, config.activeInterval ?? 0);
+}
+/**
+ * Advance one gate by `dt` seconds against this tick's `input`, mutating `state` in place and
+ * returning what the caller should do. Sleeping skips the expensive work (`active: false`) while the
+ * gate's timers keep advancing, so state is preserved; a `wake` signal or crossing `wakeRadius`
+ * flips it back to active and fires an immediate tick.
+ *
+ * @capability interest-scheduler advance a sleep/wake gate with hysteresis, cadence tiers, and stagger
+ */
+export function advanceInterestGate(state, config, dt, input = {}) {
+    const wakeRadius = config.wakeRadius;
+    const sleepRadius = Math.max(config.sleepRadius ?? wakeRadius, wakeRadius);
+    const proximity = input.proximity ?? null;
+    const prev = state.state;
+    if (input.wake === true) {
+        state.awakeHold = Math.max(state.awakeHold, config.stayAwakeSeconds ?? 0);
+    }
+    let want;
+    if (input.wake === true || state.awakeHold > 0) {
+        want = "active";
+    }
+    else if (proximity === null) {
+        want = prev;
+    }
+    else if (prev === "dormant") {
+        want = proximity <= wakeRadius ? "active" : "dormant";
+    }
+    else {
+        want = proximity > sleepRadius ? "dormant" : "active";
+    }
+    state.state = want;
+    const woke = prev === "dormant" && want === "active";
+    const slept = prev === "active" && want === "dormant";
+    let active = false;
+    if (want === "active") {
+        const interval = intervalFor(config, proximity);
+        if (interval <= 0 || woke || input.wake === true) {
+            active = true;
+            state.clock = 0;
+        }
+        else {
+            state.clock += dt;
+            if (state.clock >= interval) {
+                active = true;
+                state.clock -= interval;
+            }
+        }
+    }
+    else {
+        // Dormant: expensive work is skipped, but the gate keeps its timers so a later wake resumes cleanly.
+        state.clock = 0;
+    }
+    if (state.awakeHold > 0)
+        state.awakeHold = Math.max(0, state.awakeHold - dt);
+    return { state: want, active, woke, slept };
+}
+/**
+ * Create a census accumulator so the caller can tally active/dormant gates during the loop it already
+ * runs, avoiding any separate full-world scan just to report scheduler metrics.
+ *
+ * @capability interest-census running active/dormant gate tally folded into the caller's tick loop
+ */
+export function createInterestCensus() {
+    let active = 0;
+    let dormant = 0;
+    return {
+        record(state) {
+            const value = typeof state === "string" ? state : state.state;
+            if (value === "active")
+                active += 1;
+            else
+                dormant += 1;
+        },
+        snapshot: () => ({ active, dormant, total: active + dormant }),
+        reset() {
+            active = 0;
+            dormant = 0;
+        },
+    };
+}

package/dist/ai/jobBoard.d.ts

@@ -46,4 +46,5 @@ export interface JobBoard {
     active(): readonly Job[];
     list(): readonly Job[];
 }
+/** @internal */
 export declare function createJobBoard(): JobBoard;

package/dist/ai/jobBoard.js

@@ -2,6 +2,7 @@ const DEFAULT_ARRIVE_RADIUS = 0.75;
 function idleWorker() {
     return { jobId: null, phase: "idle", worked: 0, cycles: 0 };
 }
+/** @internal */
 export function createJobBoard() {
     const jobs = new Map();
     const workers = new Map();

package/dist/ai/laneSelect.d.ts

@@ -15,7 +15,10 @@ export interface PickLaneOptions<TId extends string = string> {
  * Live cost-based selection over parallel corridors (#286.7) — the racing-line / lane-merge pick
  * every AI driver hand-rolled. Evaluate each lane's cost this tick (crowding, hazards, distance)
  * and let stickiness hysteresis stop the agent flip-flopping between near-equal lanes.
- */
+  * @internal
+  */
 export declare function pickLane<TId extends string>(candidates: readonly LaneCandidate<TId>[], options?: PickLaneOptions<TId>): TId | null;
-/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`. */
+/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`.
+ * @internal
+ */
 export declare function corridorCost(points: readonly (readonly [number, number])[], costAt: (x: number, z: number) => number): number;

package/dist/ai/laneSelect.js

@@ -2,7 +2,8 @@
  * Live cost-based selection over parallel corridors (#286.7) — the racing-line / lane-merge pick
  * every AI driver hand-rolled. Evaluate each lane's cost this tick (crowding, hazards, distance)
  * and let stickiness hysteresis stop the agent flip-flopping between near-equal lanes.
- */
+  * @internal
+  */
 export function pickLane(candidates, options = {}) {
     if (candidates.length === 0)
         return null;
@@ -28,7 +29,9 @@ export function pickLane(candidates, options = {}) {
     }
     return best.id;
 }
-/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`. */
+/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`.
+ * @internal
+ */
 export function corridorCost(points, costAt) {
     let total = 0;
     for (const [x, z] of points)

package/dist/ai/mobBrain.d.ts

@@ -65,4 +65,5 @@ export interface MobBrain {
     /** Back to idle at full rest (respawn) — clears threat, evade, and wander state. */
     reset(): void;
 }
+/** @internal */
 export declare function createMobBrain(config: MobBrainConfig, deps: MobBrainDeps): MobBrain;

package/dist/ai/mobBrain.js

@@ -9,6 +9,7 @@ const HOLD = {
 function distance(a, b) {
     return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 }
+/** @internal */
 export function createMobBrain(config, deps) {
     const threat = createThreatTable(config.threat);
     const stickiness = config.stickiness ?? 1.15;

package/dist/ai/populationDirector.d.ts

@@ -0,0 +1,103 @@
+import type { NavPoint } from "../nav/navGrid.js";
+import { type RandomSeed } from "../random/rng.js";
+/** One species that ambiently populates a region: how heavily it is favoured and its alive ceiling. */
+export interface PopulationSpeciesEntry {
+    /** Opaque species/creature id the engine never interprets. */
+    species: string;
+    /** Relative pick weight among species below their cap (default 1). */
+    weight?: number;
+    /** Target/maximum number of this species alive in the region at once. */
+    cap: number;
+}
+/** Ambient population budget for a single region: its species ceilings, refill timing, and spawn geometry. */
+export interface PopulationRegionConfig {
+    /** Opaque region id the engine never interprets. */
+    region: string;
+    species: readonly PopulationSpeciesEntry[];
+    /** Seconds a freed slot waits before it becomes a spawn candidate (overrides the director default). */
+    respawnDelay?: number;
+    /** Candidate spawn locations; when present each request is tagged with one. */
+    spawnPoints?: readonly NavPoint[];
+}
+/** Full ambient-population configuration: per-region species budgets plus global refill limits and PRNG seed. */
+export interface PopulationDirectorConfig {
+    regions: readonly PopulationRegionConfig[];
+    /** Default respawn delay in game-seconds for regions without their own (default 0 — refill on the next tick). */
+    respawnDelay?: number;
+    /** Upper bound on spawn requests emitted per {@link PopulationDirector.tick} call (default 32). */
+    maxSpawnsPerTick?: number;
+    /** Seed for the persisted, serializable PRNG cursor (default 1). */
+    seed?: number;
+}
+/** A single ambient spawn the game should realise, refilling a region toward its species caps. */
+export interface PopulationSpawnRequest {
+    region: string;
+    species: string;
+    /** Chosen spawn location when the region declares `spawnPoints`. */
+    point?: NavPoint;
+}
+/** Per-call spawn-point selection hook, letting a game apply bias (distance from players, etc.) at tick time. */
+export interface PopulationTickContext {
+    /**
+     * Choose a spawn point for a request. Receives the region id, its configured candidates, and a
+     * deterministic roll in `[0, 1)` drawn from the persisted cursor. Return `null` to leave the
+     * request unplaced. When omitted, a candidate is picked uniformly from the roll.
+     */
+    pickSpawnPoint?(region: string, candidates: readonly NavPoint[], roll: number): NavPoint | null;
+}
+/** Live census of alive counts keyed `region -> species -> count`, used to reconcile the director to reality. */
+export type PopulationCensus = Record<string, Record<string, number>>;
+/**
+ * A queued refill slot awaiting its {@link PopulationDirectorState.elapsed} deadline.
+ * @internal
+ */
+export interface PopulationRespawnSlot {
+    region: string;
+    readyAt: number;
+}
+/**
+ * Opaque, JSON-serializable persistence for a {@link PopulationDirector}. Round-trip it through
+ * `snapshot`/`hydrate`; never read or mutate the fields directly.
+ */
+export interface PopulationDirectorState {
+    /** Accumulated game-seconds. */
+    elapsed: number;
+    /** Believed alive counts, `region -> species -> count`. */
+    alive: Record<string, Record<string, number>>;
+    /** Pending refill slots, each ready at its `readyAt` game-second. */
+    queue: readonly PopulationRespawnSlot[];
+    /** Opaque PRNG cursor — round-trip as part of the state, never read or set it directly. */
+    rng: RandomSeed;
+}
+/** Stateful ambient population manager for one world; drive it with `tick` and lifecycle notifications. */
+export interface PopulationDirector {
+    /**
+     * Advance by `dt` game-seconds and emit spawn requests for refill slots whose delay has elapsed,
+     * up to the per-tick cap. Only touches the bounded respawn queue — never scans the world.
+     */
+    tick(dt: number, ctx?: PopulationTickContext): PopulationSpawnRequest[];
+    /** Register that a creature left the region (killed/despawned/tamed), freeing a slot to refill after the delay. */
+    notifyRemoved(region: string, species: string, id?: string): void;
+    /** Register a creature the game introduced itself (not via a request), so caps account for it. */
+    notifySpawned(region: string, species: string, id?: string): void;
+    /** Snap believed alive counts to a live census and re-queue any deficit toward the caps. */
+    reconcile(census: PopulationCensus): void;
+    /** Believed alive count for a `(region, species)` pair. */
+    alive(region: string, species: string): number;
+    /** Serializable copy of the full director state (deep, safe to persist). */
+    snapshot(): PopulationDirectorState;
+    /** Replace the director state from a previously taken (and possibly JSON round-tripped) snapshot. */
+    hydrate(state: PopulationDirectorState): void;
+}
+/**
+ * Ambient open-world population director. Holds a target creature population per region and refills
+ * it over time, distinct from wave/horde spawning: instead of a budget draining down a wave, each
+ * region has per-species caps and a timed respawn queue. Removing a creature frees a slot; after a
+ * respawn delay `tick` emits weighted spawn requests (bounded per tick) that refill toward the caps
+ * without ever exceeding them. Species are chosen through a persisted, serializable {@link RandomSeed}
+ * cursor, so the same seed and the same lifecycle events always yield the same requests. Regions are
+ * independent, spawn points are optional, and the whole state round-trips through `snapshot`/`hydrate`.
+ *
+ * @capability population-director ambient per-region creature population manager with timed weighted respawns and caps
+ */
+export declare function createPopulationDirector(config: PopulationDirectorConfig): PopulationDirector;

package/dist/ai/populationDirector.js

@@ -0,0 +1,190 @@
+import { randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+const DEFAULT_MAX_SPAWNS_PER_TICK = 32;
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function cloneState(state) {
+    const alive = {};
+    for (const region of Object.keys(state.alive))
+        alive[region] = { ...state.alive[region] };
+    return {
+        elapsed: state.elapsed,
+        alive,
+        queue: state.queue.map((slot) => ({ region: slot.region, readyAt: slot.readyAt })),
+        rng: state.rng,
+    };
+}
+/**
+ * Ambient open-world population director. Holds a target creature population per region and refills
+ * it over time, distinct from wave/horde spawning: instead of a budget draining down a wave, each
+ * region has per-species caps and a timed respawn queue. Removing a creature frees a slot; after a
+ * respawn delay `tick` emits weighted spawn requests (bounded per tick) that refill toward the caps
+ * without ever exceeding them. Species are chosen through a persisted, serializable {@link RandomSeed}
+ * cursor, so the same seed and the same lifecycle events always yield the same requests. Regions are
+ * independent, spawn points are optional, and the whole state round-trips through `snapshot`/`hydrate`.
+ *
+ * @capability population-director ambient per-region creature population manager with timed weighted respawns and caps
+ */
+export function createPopulationDirector(config) {
+    const regions = new Map();
+    for (const region of config.regions)
+        regions.set(region.region, region);
+    const maxSpawnsPerTick = config.maxSpawnsPerTick ?? DEFAULT_MAX_SPAWNS_PER_TICK;
+    const defaultDelay = config.respawnDelay ?? 0;
+    let state = {
+        elapsed: 0,
+        alive: {},
+        queue: [],
+        rng: randomSeedFrom(config.seed ?? 1),
+    };
+    const totalCap = (region) => {
+        let sum = 0;
+        for (const entry of region.species)
+            sum += entry.cap;
+        return sum;
+    };
+    const totalAlive = (regionId) => {
+        const counts = state.alive[regionId];
+        if (counts === undefined)
+            return 0;
+        let sum = 0;
+        for (const key of Object.keys(counts))
+            sum += counts[key];
+        return sum;
+    };
+    const queuedCount = (regionId) => {
+        let sum = 0;
+        for (const slot of state.queue)
+            if (slot.region === regionId)
+                sum += 1;
+        return sum;
+    };
+    const delayFor = (region) => region.respawnDelay ?? defaultDelay;
+    const aliveFor = (regionId) => {
+        let counts = state.alive[regionId];
+        if (counts === undefined) {
+            counts = {};
+            state.alive[regionId] = counts;
+        }
+        return counts;
+    };
+    /** Top up the queue so `alive + queued` reaches the region cap, appending ready-at slots. */
+    const ensureDeficitQueued = (region, readyAt) => {
+        const deficit = totalCap(region) - totalAlive(region.region) - queuedCount(region.region);
+        if (deficit <= 0)
+            return;
+        const next = state.queue.slice();
+        for (let i = 0; i < deficit; i += 1)
+            next.push({ region: region.region, readyAt });
+        state.queue = next;
+    };
+    // Prime each region to fill toward its caps on the first ticks.
+    for (const region of config.regions) {
+        aliveFor(region.region);
+        ensureDeficitQueued(region, 0);
+    }
+    const pickSpecies = (region) => {
+        const counts = state.alive[region.region] ?? {};
+        let total = 0;
+        const eligible = [];
+        for (const entry of region.species) {
+            if ((counts[entry.species] ?? 0) >= entry.cap)
+                continue;
+            eligible.push(entry);
+            total += entry.weight ?? 1;
+        }
+        if (eligible.length === 0 || total <= 0)
+            return null;
+        const [roll, nextRng] = stepRandomSeed(state.rng);
+        state.rng = nextRng;
+        let cursor = roll * total;
+        for (const entry of eligible) {
+            cursor -= entry.weight ?? 1;
+            if (cursor <= 0)
+                return entry.species;
+        }
+        return eligible[eligible.length - 1].species;
+    };
+    const choosePoint = (region, ctx) => {
+        const points = region.spawnPoints;
+        if (points === undefined || points.length === 0)
+            return undefined;
+        const [roll, nextRng] = stepRandomSeed(state.rng);
+        state.rng = nextRng;
+        if (ctx?.pickSpawnPoint !== undefined) {
+            const chosen = ctx.pickSpawnPoint(region.region, points, roll);
+            return chosen ?? undefined;
+        }
+        return points[Math.min(points.length - 1, Math.floor(clamp01(roll) * points.length))];
+    };
+    return {
+        tick(dt, ctx) {
+            if (dt <= 0)
+                return [];
+            state.elapsed += dt;
+            const now = state.elapsed;
+            const requests = [];
+            const remaining = [];
+            for (const slot of state.queue) {
+                if (requests.length >= maxSpawnsPerTick || slot.readyAt > now) {
+                    remaining.push(slot);
+                    continue;
+                }
+                const region = regions.get(slot.region);
+                if (region === undefined)
+                    continue; // region no longer configured — drop the slot
+                const species = pickSpecies(region);
+                if (species === null)
+                    continue; // region already at cap (filled externally) — drop the slot
+                aliveFor(region.region)[species] = (state.alive[region.region][species] ?? 0) + 1;
+                const request = { region: region.region, species };
+                const point = choosePoint(region, ctx);
+                if (point !== undefined)
+                    request.point = point;
+                requests.push(request);
+            }
+            state.queue = remaining;
+            return requests;
+        },
+        notifyRemoved(region, species, _id) {
+            const counts = state.alive[region];
+            if (counts !== undefined) {
+                const current = counts[species] ?? 0;
+                if (current > 0)
+                    counts[species] = current - 1;
+            }
+            const regionConfig = regions.get(region);
+            if (regionConfig === undefined)
+                return;
+            const next = state.queue.slice();
+            next.push({ region, readyAt: state.elapsed + delayFor(regionConfig) });
+            state.queue = next;
+        },
+        notifySpawned(region, species, _id) {
+            if (!regions.has(region))
+                return;
+            const counts = aliveFor(region);
+            counts[species] = (counts[species] ?? 0) + 1;
+        },
+        reconcile(census) {
+            for (const region of config.regions) {
+                const observed = census[region.region] ?? {};
+                const counts = {};
+                for (const entry of region.species)
+                    counts[entry.species] = observed[entry.species] ?? 0;
+                state.alive[region.region] = counts;
+            }
+            for (const region of config.regions)
+                ensureDeficitQueued(region, state.elapsed);
+        },
+        alive(region, species) {
+            return state.alive[region]?.[species] ?? 0;
+        },
+        snapshot() {
+            return cloneState(state);
+        },
+        hydrate(next) {
+            state = cloneState(next);
+        },
+    };
+}

package/dist/ai/pursuit.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Composable pursuit/aggro step: the "I have a target — now chase it, stop at reach, hit it on a
+ * cooldown, and break off if led too far from home" loop that melee mobs, RTS units, and stationary
+ * turrets all re-implement by hand. This owns exactly that state machine and the per-entity attack
+ * cooldown; target *selection* stays separate (see {@link ./targetAcquisition}), and every side
+ * effect — move, attack, break off — is performed by the caller in response to the returned action.
+ *
+ * Deterministic and allocation-free: distances are measured by the caller and passed in as scalars,
+ * the only state is one serializable number ({@link PursuitState.attackCooldown}) advanced in place,
+ * and the returned {@link PursuitAction} is a string literal. No object is built per entity per step,
+ * and nothing here scans the world — feed it a target you already resolved.
+ */
+/** The action a pursuit step resolves to; the caller performs the matching side effect. */
+export type PursuitAction = 
+/** Home distance exceeded the leash — abandon the target and return home. */
+"leash"
+/** Out of range — advance toward the target. */
+ | "pursue"
+/** In range and the cooldown is ready — perform the attack, then {@link armPursuit}. */
+ | "attack"
+/** In range but the cooldown has not elapsed — hold (face the target, idle, etc.). */
+ | "wait"
+/** No engageable target this step (distance was `null`). */
+ | "idle";
+/**
+ * When the attack cooldown ticks down.
+ * - `"always"` (default): every step, like a wall-clock weapon timer that keeps counting during the
+ *   chase, so the entity can swing the instant it reaches its target.
+ * - `"inRange"`: only while within `stopDistance`, so the timer freezes during the chase and the
+ *   full interval is paid out after each contact.
+ */
+export type CooldownMode = "always" | "inRange";
+/** Per-entity cooldown state owned by the primitive. One serializable number; no methods. */
+export interface PursuitState {
+    /** Seconds remaining until the next attack may fire. Advanced toward `0` by {@link advancePursuit}. */
+    attackCooldown: number;
+}
+/** A fresh pursuit state, ready to attack immediately (`attackCooldown` at `0`). */
+export declare function createPursuitState(attackCooldown?: number): PursuitState;
+/** Set the cooldown after an attack fires (clamped at `0`). Call on the step that returned `"attack"`. */
+export declare function armPursuit(state: PursuitState, intervalSeconds: number): void;
+/**
+ * Advance one pursuit step for a single entity, mutating `state.attackCooldown`, and return the
+ * action the caller should perform. All spatial input is scalar and measured this frame:
+ *
+ * - `targetDistance` — self→target distance, or `null` when there is no engageable target (`"idle"`).
+ * - `stopDistance`   — attack once within this distance; pursue while beyond it.
+ * - `homeDistance` / `leashRange` — optional leash checked first: when `homeDistance > leashRange`
+ *   the step is `"leash"`. Leave at their defaults (`-Infinity` / `+Infinity`) to disable leashing.
+ * - `cooldownMode`   — see {@link CooldownMode}.
+ *
+ * On `"attack"` the caller applies the hit and calls {@link armPursuit} with the next interval.
+ *
+ * @capability pursuit chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+ */
+export declare function advancePursuit(state: PursuitState, dt: number, targetDistance: number | null, stopDistance: number, cooldownMode?: CooldownMode, homeDistance?: number, leashRange?: number): PursuitAction;

package/dist/ai/pursuit.js

@@ -0,0 +1,53 @@
+/**
+ * Composable pursuit/aggro step: the "I have a target — now chase it, stop at reach, hit it on a
+ * cooldown, and break off if led too far from home" loop that melee mobs, RTS units, and stationary
+ * turrets all re-implement by hand. This owns exactly that state machine and the per-entity attack
+ * cooldown; target *selection* stays separate (see {@link ./targetAcquisition}), and every side
+ * effect — move, attack, break off — is performed by the caller in response to the returned action.
+ *
+ * Deterministic and allocation-free: distances are measured by the caller and passed in as scalars,
+ * the only state is one serializable number ({@link PursuitState.attackCooldown}) advanced in place,
+ * and the returned {@link PursuitAction} is a string literal. No object is built per entity per step,
+ * and nothing here scans the world — feed it a target you already resolved.
+ */
+/** A fresh pursuit state, ready to attack immediately (`attackCooldown` at `0`). */
+export function createPursuitState(attackCooldown = 0) {
+    return { attackCooldown };
+}
+/** Set the cooldown after an attack fires (clamped at `0`). Call on the step that returned `"attack"`. */
+export function armPursuit(state, intervalSeconds) {
+    state.attackCooldown = intervalSeconds > 0 ? intervalSeconds : 0;
+}
+function tickCooldown(state, dt) {
+    if (state.attackCooldown > 0) {
+        const next = state.attackCooldown - dt;
+        state.attackCooldown = next > 0 ? next : 0;
+    }
+}
+/**
+ * Advance one pursuit step for a single entity, mutating `state.attackCooldown`, and return the
+ * action the caller should perform. All spatial input is scalar and measured this frame:
+ *
+ * - `targetDistance` — self→target distance, or `null` when there is no engageable target (`"idle"`).
+ * - `stopDistance`   — attack once within this distance; pursue while beyond it.
+ * - `homeDistance` / `leashRange` — optional leash checked first: when `homeDistance > leashRange`
+ *   the step is `"leash"`. Leave at their defaults (`-Infinity` / `+Infinity`) to disable leashing.
+ * - `cooldownMode`   — see {@link CooldownMode}.
+ *
+ * On `"attack"` the caller applies the hit and calls {@link armPursuit} with the next interval.
+ *
+ * @capability pursuit chase-to-reach cooldown-gated attack with optional leash-to-home; owns the attack cooldown
+ */
+export function advancePursuit(state, dt, targetDistance, stopDistance, cooldownMode = "always", homeDistance = Number.NEGATIVE_INFINITY, leashRange = Number.POSITIVE_INFINITY) {
+    if (cooldownMode === "always")
+        tickCooldown(state, dt);
+    if (homeDistance > leashRange)
+        return "leash";
+    if (targetDistance === null)
+        return "idle";
+    if (targetDistance > stopDistance)
+        return "pursue";
+    if (cooldownMode === "inRange")
+        tickCooldown(state, dt);
+    return state.attackCooldown <= 0 ? "attack" : "wait";
+}

package/dist/ai/spawnDirector.d.ts

@@ -1,4 +1,5 @@
 import type { NavPoint } from "../nav/navGrid.js";
+import { type RandomSeed } from "../random/rng.js";
 export interface SpawnEntry {
     id: string;
     cost: number;
@@ -32,7 +33,8 @@ export interface SpawnDirectorState {
     alert: number;
     spawnedThisWave: number;
     spawnedTotal: number;
-    rng: number;
+    /** Opaque PRNG cursor — round-trip it as part of the state, never read or set it directly. */
+    rng: RandomSeed;
     done: boolean;
 }
 export interface DirectorContext {
@@ -49,13 +51,16 @@ export interface SpawnRequest {
 }
 /** Preference for picking a spawn point relative to `avoid` positions: closer, farther, or unweighted. */
 export type SpawnPointDistanceBias = "near" | "far" | "none";
+/** How strongly `distanceBias` weights candidates by distance from `avoid` — a named intent, not a weighting exponent. */
+export type SpawnPointBiasStrength = "subtle" | "moderate" | "strong";
 /** Semantic options for selecting a spawn point without exposing weighting internals. */
 export interface SpawnPointSelectionOptions {
     candidates: readonly NavPoint[];
     avoid?: readonly NavPoint[];
     random: () => number;
     distanceBias?: SpawnPointDistanceBias;
-    biasStrength?: number;
+    /** Default `"moderate"`. */
+    biasStrength?: SpawnPointBiasStrength;
 }
 export interface DirectorStep {
     state: SpawnDirectorState;