@jgengine/core 0.28.0 → 0.30.0

package/dist/ai/director/encounter.js

@@ -0,0 +1,195 @@
+import { seededRng } from "../../random/rng.js";
+function clampInt(value, min, max) {
+    if (value === undefined || !Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+/**
+ * Expand one authored wave into the units it sends, at the times it sends them.
+ *
+ * Authoring stays data: composition (`unit`, `count`), entry (`entry`), timing (`at`, `jitterSeconds`,
+ * `durationSeconds`) and escalation (`escalates`, `elite`) all live in the
+ * definition. Pressure only *adds*: extra copies for `escalates` groups (capped at
+ * `maxExtraPerGroup`) and elite slots, and it shortens delays through `cadenceScale` — it never
+ * rewrites an authored unit or entry. Same definition, seed and pressure always produce the same
+ * schedule.
+ *
+ * @capability encounter-expand turn an authored wave into a deterministic, pressure-adjusted list of timed spawn orders
+ */
+export function expandWave(config, waveIndex, pressure = {}) {
+    const waves = config.definition.waves;
+    if (waveIndex < 0 || waveIndex >= waves.length)
+        return [];
+    const wave = waves[waveIndex];
+    const seed = config.seed ?? 1;
+    const defaultIntent = config.defaultIntent ?? "assault";
+    const maxExtra = Math.max(0, Math.floor(config.maxExtraPerGroup ?? 4));
+    const countBonus = clampInt(pressure.countBonus, 0, maxExtra);
+    const eliteSlots = clampInt(pressure.eliteSlots, 0, Number.MAX_SAFE_INTEGER);
+    const cadenceScale = pressure.cadenceScale === undefined || !Number.isFinite(pressure.cadenceScale) || pressure.cadenceScale <= 0
+        ? 1
+        : Math.min(1, pressure.cadenceScale);
+    const rng = seededRng(`${seed}:${waveIndex}`);
+    const schedule = [];
+    let eliteUsed = 0;
+    for (let groupIndex = 0; groupIndex < wave.groups.length; groupIndex += 1) {
+        const group = wave.groups[groupIndex];
+        if (group.elite === true) {
+            if (eliteUsed >= eliteSlots)
+                continue;
+            eliteUsed += 1;
+        }
+        const authored = Math.max(0, Math.floor(group.count ?? 1));
+        const extra = group.escalates === true ? countBonus : 0;
+        const at = Math.max(0, group.at ?? 0) * cadenceScale;
+        for (let itemIndex = 0; itemIndex < authored + extra; itemIndex += 1) {
+            const jitter = group.jitterSeconds === undefined || group.jitterSeconds <= 0
+                ? 0
+                : (rng() * 2 - 1) * group.jitterSeconds;
+            schedule.push({
+                groupIndex,
+                itemIndex,
+                order: {
+                    wave: waveIndex,
+                    waveId: wave.id,
+                    unit: group.unit,
+                    entry: group.entry,
+                    intent: group.intent ?? defaultIntent,
+                    atSeconds: Math.max(0, at + jitter),
+                    group: groupIndex,
+                    pressureAdded: itemIndex >= authored,
+                },
+            });
+        }
+    }
+    schedule.sort((a, b) => a.order.atSeconds - b.order.atSeconds || a.groupIndex - b.groupIndex || a.itemIndex - b.itemIndex);
+    return schedule.map((entry) => entry.order);
+}
+/**
+ * Create a live encounter over an authored definition: open a wave, step its clock, take the orders
+ * whose time has come, and close the wave when the game says it is cleared.
+ *
+ * This is the composition layer, not a second spawn system: every order names a game-owned `unit`
+ * and `entry`, exactly like a `SpawnRequest` names an `entryId`, and the game builds the entity.
+ * Pair it with `combat/encounterSequence` when a fight needs scripted phase gates, and with
+ * `ai/waveRunner` when a wave should be drawn from a budget instead of authored.
+ *
+ * Pressure is captured when a wave opens, so a wave's composition cannot change mid-arrival; read
+ * `evaluatePressure` when the wave opens and pass the plan in.
+ *
+ * @capability encounter-runner open authored waves, emit their timed orders, and track wave progress through a save
+ */
+export function createEncounter(config) {
+    const waves = config.definition.waves;
+    let state = {
+        wave: 0,
+        opened: false,
+        elapsed: 0,
+        emitted: 0,
+        completedWaves: 0,
+        done: waves.length === 0,
+        countBonus: 0,
+        eliteSlots: 0,
+        cadenceScale: 1,
+    };
+    const readout = {
+        wave: 1,
+        totalWaves: waves.length,
+        waveId: null,
+        label: null,
+        total: 0,
+        emitted: 0,
+        progress: 0,
+        ready: false,
+        done: false,
+    };
+    function pressureOf() {
+        return { countBonus: state.countBonus, eliteSlots: state.eliteSlots, cadenceScale: state.cadenceScale };
+    }
+    function schedule() {
+        return state.opened ? expandWave(config, state.wave, pressureOf()) : [];
+    }
+    function durationSeconds() {
+        const wave = waves[state.wave];
+        if (wave?.durationSeconds === undefined)
+            return 0;
+        return Math.max(0, wave.durationSeconds) * state.cadenceScale;
+    }
+    return {
+        openWave(index, pressure = {}) {
+            const target = index ?? state.completedWaves;
+            if (target < 0 || target >= waves.length) {
+                state = { ...state, done: true };
+                return [];
+            }
+            state = {
+                ...state,
+                wave: target,
+                opened: true,
+                elapsed: 0,
+                emitted: 0,
+                done: false,
+                countBonus: clampInt(pressure.countBonus, 0, Math.max(0, Math.floor(config.maxExtraPerGroup ?? 4))),
+                eliteSlots: clampInt(pressure.eliteSlots, 0, Number.MAX_SAFE_INTEGER),
+                cadenceScale: pressure.cadenceScale === undefined || !Number.isFinite(pressure.cadenceScale) || pressure.cadenceScale <= 0
+                    ? 1
+                    : Math.min(1, pressure.cadenceScale),
+            };
+            return schedule();
+        },
+        update(dt) {
+            if (!state.opened || state.done || !(dt > 0))
+                return [];
+            state = { ...state, elapsed: state.elapsed + dt };
+            const all = schedule();
+            const orders = [];
+            while (state.emitted < all.length && all[state.emitted].atSeconds <= state.elapsed + 1e-9) {
+                orders.push(all[state.emitted]);
+                state = { ...state, emitted: state.emitted + 1 };
+            }
+            return orders;
+        },
+        completeWave() {
+            if (!state.opened)
+                return;
+            const completedWaves = state.wave + 1;
+            state = {
+                ...state,
+                opened: false,
+                elapsed: 0,
+                emitted: 0,
+                completedWaves,
+                wave: Math.min(completedWaves, waves.length),
+                done: completedWaves >= waves.length,
+            };
+        },
+        waveAt(index) {
+            return waves[index] ?? null;
+        },
+        view() {
+            const wave = waves[state.wave] ?? null;
+            const all = schedule();
+            const duration = durationSeconds();
+            readout.wave = Math.min(state.wave + 1, waves.length);
+            readout.waveId = wave?.id ?? null;
+            readout.label = wave?.label ?? null;
+            readout.total = all.length;
+            readout.emitted = state.emitted;
+            readout.progress =
+                all.length === 0
+                    ? state.opened && state.elapsed >= duration
+                        ? 1
+                        : 0
+                    : Math.min(1, state.emitted / all.length);
+            readout.ready = state.opened && state.emitted >= all.length && state.elapsed >= duration;
+            readout.done = state.done;
+            return readout;
+        },
+        snapshot() {
+            return { ...state };
+        },
+        restore(next) {
+            state = { ...next };
+        },
+    };
+}

package/dist/ai/director/pressure.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Encounter pressure: how hard a director leans on a player who is struggling, read from the
+ * player's own state, quantized to a tier, and bounded by the rule's cap. The plan is a value, not
+ * a callback, so a test can sweep it and a probe can print it.
+ */
+/** What the director reads about the player before it chooses a tier. */
+export interface PressureReading {
+    /** Player health fraction `0..1`. Lower leans harder. */
+    health: number;
+    /** Encounter progress `0..1` — waves cleared over waves authored. Lower leans harder. */
+    progress: number;
+    /** Seconds the encounter has run. Longer leans harder, up to the window. */
+    elapsed: number;
+}
+/** The weights and window that turn a reading into an index, plus the hard cap. */
+export interface PressureRule {
+    /** Weight of low player health. Default `1`. */
+    healthWeight?: number;
+    /** Weight of the encounter not being finished. Default `1`. */
+    progressWeight?: number;
+    /** Weight of time spent past `timeFloorSeconds`. Default `0.5`. */
+    timeWeight?: number;
+    /** Seconds of encounter time before the clock term starts. Default `90`. */
+    timeFloorSeconds?: number;
+    /** Seconds at which the clock term is full. Default `300`. */
+    timeWindowSeconds?: number;
+    /** Highest tier this rule can reach. Default `2`. Every plan bound derives from it. */
+    maxTier?: number;
+}
+/** One bounded answer to "how hard now", plus the effects the encounter layer applies. */
+export interface PressurePlan {
+    /** `0..maxTier`. */
+    tier: number;
+    /** The weighted reading in `0..1` before quantization. */
+    index: number;
+    /** Extra units each pressure-scaled group gains: `0..maxTier`. */
+    countBonus: number;
+    /** Extra elite slots unlocked: `0..maxTier`. */
+    eliteSlots: number;
+    /** Multiplier on authored entry delays, `>= 1 / (1 + maxTier / 2)`. */
+    cadenceScale: number;
+    /** True when the tier sits on the rule's cap. */
+    atCap: boolean;
+    /** One line naming the terms, for a probe or a test failure. */
+    reason: string;
+}
+/**
+ * Turn one reading into a bounded pressure plan.
+ *
+ * The index is the weighted mean of three terms — how hurt the player is (`1 - health`), how far
+ * from finished the encounter is (`1 - progress`), and how long it has run — each clamped to
+ * `0..1`, then split into `maxTier + 1` bands. Because every term and every derived effect is a
+ * clamp of an authored cap, the rule cannot climb: a dead player on a stalled timer for an hour
+ * lands on `tier === maxTier` with `countBonus === maxTier`, never above it.
+ *
+ * @capability encounter-pressure bounded difficulty tier read from player health, encounter progress and time
+ */
+export declare function evaluatePressure(reading: PressureReading, rule?: PressureRule): PressurePlan;

package/dist/ai/director/pressure.js

@@ -0,0 +1,70 @@
+/**
+ * Encounter pressure: how hard a director leans on a player who is struggling, read from the
+ * player's own state, quantized to a tier, and bounded by the rule's cap. The plan is a value, not
+ * a callback, so a test can sweep it and a probe can print it.
+ */
+const RULE_DEFAULTS = {
+    healthWeight: 1,
+    progressWeight: 1,
+    timeWeight: 0.5,
+    timeFloorSeconds: 90,
+    timeWindowSeconds: 300,
+    maxTier: 2,
+};
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function resolveRule(rule) {
+    const maxTier = Math.max(0, Math.floor(rule.maxTier ?? RULE_DEFAULTS.maxTier));
+    return {
+        healthWeight: Math.max(0, rule.healthWeight ?? RULE_DEFAULTS.healthWeight),
+        progressWeight: Math.max(0, rule.progressWeight ?? RULE_DEFAULTS.progressWeight),
+        timeWeight: Math.max(0, rule.timeWeight ?? RULE_DEFAULTS.timeWeight),
+        timeFloorSeconds: Math.max(0, rule.timeFloorSeconds ?? RULE_DEFAULTS.timeFloorSeconds),
+        timeWindowSeconds: Math.max(1, rule.timeWindowSeconds ?? RULE_DEFAULTS.timeWindowSeconds),
+        maxTier,
+    };
+}
+/** The clock term in `0..1`: zero inside the floor, full at the end of the window. */
+function timeTerm(elapsed, rule) {
+    const span = rule.timeWindowSeconds - rule.timeFloorSeconds;
+    if (!(span > 0))
+        return elapsed >= rule.timeWindowSeconds ? 1 : 0;
+    return clamp01((elapsed - rule.timeFloorSeconds) / span);
+}
+/**
+ * Turn one reading into a bounded pressure plan.
+ *
+ * The index is the weighted mean of three terms — how hurt the player is (`1 - health`), how far
+ * from finished the encounter is (`1 - progress`), and how long it has run — each clamped to
+ * `0..1`, then split into `maxTier + 1` bands. Because every term and every derived effect is a
+ * clamp of an authored cap, the rule cannot climb: a dead player on a stalled timer for an hour
+ * lands on `tier === maxTier` with `countBonus === maxTier`, never above it.
+ *
+ * @capability encounter-pressure bounded difficulty tier read from player health, encounter progress and time
+ */
+export function evaluatePressure(reading, rule = {}) {
+    const resolved = resolveRule(rule);
+    const health = clamp01(Number.isFinite(reading.health) ? reading.health : 1);
+    const progress = clamp01(Number.isFinite(reading.progress) ? reading.progress : 1);
+    const elapsed = Number.isFinite(reading.elapsed) ? Math.max(0, reading.elapsed) : 0;
+    const time = timeTerm(elapsed, resolved);
+    const totalWeight = resolved.healthWeight + resolved.progressWeight + resolved.timeWeight;
+    const index = totalWeight <= 0
+        ? 0
+        : clamp01((resolved.healthWeight * (1 - health) +
+            resolved.progressWeight * (1 - progress) +
+            resolved.timeWeight * time) /
+            totalWeight);
+    const tier = Math.min(resolved.maxTier, Math.max(0, Math.floor(index * (resolved.maxTier + 1))));
+    return {
+        tier,
+        index,
+        countBonus: tier,
+        eliteSlots: Math.max(0, tier - 1),
+        cadenceScale: 1 / (1 + tier / 2),
+        atCap: tier >= resolved.maxTier,
+        reason: `tier ${tier}/${resolved.maxTier}: health ${health.toFixed(2)}, progress ${progress.toFixed(2)}, ` +
+            `time ${time.toFixed(2)} (${elapsed.toFixed(0)}s), index ${index.toFixed(2)}`,
+    };
+}

package/dist/ai/director/roles.d.ts

@@ -0,0 +1,61 @@
+import type { SquadComposition, SquadRole } from "../../combat/squadTactics.js";
+import type { Vec3 } from "../../world/geometry.js";
+/**
+ * The five duties a fighter can be given in a fight. A duty is *who does what*; the squad role a
+ * game dials (range, angles, fire discipline) is *how that duty fights* and stays content.
+ */
+export type FightIntent = "retreat" | "hold" | "flank" | "cover" | "assault";
+/** One fighter the director can order, with the state the decision reads. */
+export interface FighterState {
+    id: string;
+    /** Position on the ground plane; only `x` and `z` are read. */
+    position: Vec3;
+    /** Health fraction `0..1`. */
+    health: number;
+    /** True while the fighter is taking fire this tick. */
+    underFire?: boolean;
+}
+/** The squad as it stands and the enemy it is facing, or no enemy at all. */
+export interface FightSituation {
+    fighters: readonly FighterState[];
+    /** Where the squad last knew the enemy to be, or null when it has no contact. */
+    threat: Vec3 | null;
+    /** Health fraction at or below which a fighter falls back. Default `0.25`. */
+    retreatBelow?: number;
+}
+/** What the director decided, per fighter, and why. */
+export interface FightOrders {
+    /** Duty per fighter id. Every fighter in the situation appears exactly once. */
+    intents: Map<string, FightIntent>;
+    /** How many fighters took each duty, for a HUD or a test. */
+    counts: Record<FightIntent, number>;
+    /** One line naming the terms that drove the split. */
+    reason: string;
+}
+/**
+ * Assign each fighter a duty from the squad's own state — who is hurt, who is under fire, and who
+ * already stands on the outside of the formation — never from an authored order or a spawn index.
+ *
+ * Rules, applied in this order:
+ * 1. A fighter at or below `retreatBelow` health falls back (`retreat`).
+ * 2. With no known enemy the rest advance (`assault`); there is nothing to hold, flank or hide from.
+ * 3. Against a known enemy one fighter holds the line: the healthiest fighter closest to the
+ *    squad's centre, ties broken by id, so the anchor is the one already standing there.
+ * 4. A third of what is left flanks, taken from the outside of the formation, alternating sides so
+ *    a squad never stacks its flankers on one shoulder. Under fire disqualifies a flanker.
+ * 5. Everyone else fights from cover, which is where `createSquadCombat` puts them anyway.
+ *
+ * Deterministic: same situation, same orders, and input order does not change a duty.
+ *
+ * @capability fight-intents assign hold, flank, cover, assault and retreat duties from live squad state
+ */
+export declare function assignFightIntents(situation: FightSituation): FightOrders;
+/**
+ * Turn duties into a squad composition `createSquadCombat` accepts: one slot per fighter, in the
+ * order the game gives its members, each mapped to the role that game dials for the duty. Build it
+ * through `composition` so squad combat executes the director's assignment instead of its own
+ * static list.
+ *
+ * @capability fight-intent-composition map assigned duties onto a squad combat composition in member order
+ */
+export declare function compositionForIntents(order: readonly string[], intents: ReadonlyMap<string, FightIntent>, roleFor: (intent: FightIntent) => SquadRole): SquadComposition;

package/dist/ai/director/roles.js

@@ -0,0 +1,118 @@
+const DEFAULT_RETREAT_BELOW = 0.25;
+function flatDistance(a, b) {
+    return Math.hypot(a[0] - b[0], a[2] - b[2]);
+}
+/**
+ * Assign each fighter a duty from the squad's own state — who is hurt, who is under fire, and who
+ * already stands on the outside of the formation — never from an authored order or a spawn index.
+ *
+ * Rules, applied in this order:
+ * 1. A fighter at or below `retreatBelow` health falls back (`retreat`).
+ * 2. With no known enemy the rest advance (`assault`); there is nothing to hold, flank or hide from.
+ * 3. Against a known enemy one fighter holds the line: the healthiest fighter closest to the
+ *    squad's centre, ties broken by id, so the anchor is the one already standing there.
+ * 4. A third of what is left flanks, taken from the outside of the formation, alternating sides so
+ *    a squad never stacks its flankers on one shoulder. Under fire disqualifies a flanker.
+ * 5. Everyone else fights from cover, which is where `createSquadCombat` puts them anyway.
+ *
+ * Deterministic: same situation, same orders, and input order does not change a duty.
+ *
+ * @capability fight-intents assign hold, flank, cover, assault and retreat duties from live squad state
+ */
+export function assignFightIntents(situation) {
+    const retreatBelow = situation.retreatBelow ?? DEFAULT_RETREAT_BELOW;
+    const intents = new Map();
+    const counts = { retreat: 0, hold: 0, flank: 0, cover: 0, assault: 0 };
+    const fighters = [...situation.fighters].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const assign = (fighter, intent) => {
+        intents.set(fighter.id, intent);
+        counts[intent] += 1;
+    };
+    let x = 0;
+    let z = 0;
+    for (const fighter of fighters) {
+        x += fighter.position[0];
+        z += fighter.position[2];
+    }
+    const centre = fighters.length === 0 ? [0, 0, 0] : [x / fighters.length, 0, z / fighters.length];
+    const remaining = [];
+    for (const fighter of fighters) {
+        if (fighter.health <= retreatBelow)
+            assign(fighter, "retreat");
+        else
+            remaining.push(fighter);
+    }
+    const threat = situation.threat;
+    if (threat === null) {
+        for (const fighter of remaining)
+            assign(fighter, "assault");
+        return {
+            intents,
+            counts,
+            reason: `no contact: ${counts.assault} assault, ${counts.retreat} retreat below ${retreatBelow}`,
+        };
+    }
+    const forwardLength = Math.max(0.0001, flatDistance(centre, threat));
+    const forwardX = (threat[0] - centre[0]) / forwardLength;
+    const forwardZ = (threat[2] - centre[2]) / forwardLength;
+    const sideOf = (fighter) => forwardX * (fighter.position[2] - centre[2]) - forwardZ * (fighter.position[0] - centre[0]);
+    if (remaining.length > 0) {
+        let anchor = remaining[0];
+        for (const fighter of remaining) {
+            const candidate = Math.abs(sideOf(fighter));
+            const held = Math.abs(sideOf(anchor));
+            if (candidate < held - 0.0001 || (Math.abs(candidate - held) <= 0.0001 && fighter.health > anchor.health)) {
+                anchor = fighter;
+            }
+        }
+        assign(anchor, "hold");
+    }
+    const candidates = remaining
+        .filter((fighter) => intents.get(fighter.id) !== "hold" && fighter.underFire !== true)
+        .sort((a, b) => {
+        const lateral = Math.abs(sideOf(b)) - Math.abs(sideOf(a));
+        if (Math.abs(lateral) > 0.0001)
+            return lateral;
+        const health = b.health - a.health;
+        if (Math.abs(health) > 0.0001)
+            return health;
+        return a.id < b.id ? -1 : 1;
+    });
+    let flankers = Math.min(candidates.length, Math.floor(remaining.length / 3));
+    let side = 0;
+    while (flankers > 0) {
+        const pick = side === 0
+            ? candidates.find((fighter) => intents.get(fighter.id) === undefined)
+            : candidates.find((fighter) => intents.get(fighter.id) === undefined && Math.sign(sideOf(fighter)) === side) ?? candidates.find((fighter) => intents.get(fighter.id) === undefined);
+        if (pick === undefined)
+            break;
+        assign(pick, "flank");
+        side = side === 0 ? -Math.sign(sideOf(pick)) : -side;
+        flankers -= 1;
+    }
+    for (const fighter of remaining)
+        if (intents.get(fighter.id) === undefined)
+            assign(fighter, "cover");
+    return {
+        intents,
+        counts,
+        reason: `${counts.hold} hold, ${counts.flank} flank, ${counts.cover} cover, ${counts.assault} assault, ` +
+            `${counts.retreat} retreat below ${retreatBelow}`,
+    };
+}
+/**
+ * Turn duties into a squad composition `createSquadCombat` accepts: one slot per fighter, in the
+ * order the game gives its members, each mapped to the role that game dials for the duty. Build it
+ * through `composition` so squad combat executes the director's assignment instead of its own
+ * static list.
+ *
+ * @capability fight-intent-composition map assigned duties onto a squad combat composition in member order
+ */
+export function compositionForIntents(order, intents, roleFor) {
+    const roles = [];
+    for (const id of order) {
+        const intent = intents.get(id);
+        roles.push({ ...roleFor(intent ?? "cover"), count: 1 });
+    }
+    return { roles };
+}

package/dist/ai/director/sound.d.ts

@@ -0,0 +1,79 @@
+import type { PerceptionService } from "../../sensor/perception.js";
+import type { Vec3 } from "../../world/geometry.js";
+/** A unit that could hear a noise: its id and where it stands when the noise lands. */
+export interface SoundHunter {
+    id: string;
+    position: Vec3;
+}
+/** One noise in the world, as the game produces it. */
+export interface NoiseEvent {
+    /** Who made the noise — the hearing owner records the memory against this id. */
+    sourceId: string;
+    position: Vec3;
+    /** Seconds on the game clock, the same clock the perception service is given. */
+    at: number;
+    /** Multiplies `hearingRange` exactly as `PerceptionStimulus.loudness` does. Default `1`. */
+    loudness?: number;
+}
+/** A hunter still working a noise, as the squad layer reads it this tick. */
+export interface Investigation {
+    hunterId: string;
+    sourceId: string;
+    /** Where the noise came from: the hearing owner's remembered position. */
+    position: Vec3;
+    /** Confidence left in the memory, `0..1`; it falls as the memory decays and ends the hunt at 0. */
+    confidence: number;
+    /** Seconds since the noise landed. */
+    ageSeconds: number;
+}
+/** One noise and the hunters sent to it. Serializable, so a hunt survives a save. */
+export interface SoundHuntEntry {
+    noise: NoiseEvent;
+    hunters: string[];
+}
+/** Serializable book-keeping: which noises are still being worked, and by whom. */
+export interface SoundHuntSnapshot {
+    entries: SoundHuntEntry[];
+}
+/** Everything the hunt reads and its bounds. */
+export interface SoundHuntConfig {
+    perception: PerceptionService;
+    /** Candidates near a noise, bounded by the caller's roster. Called once per noise, not per tick. */
+    hunters: (position: Vec3, hearingRange: number) => readonly SoundHunter[];
+    /** The same hearing range given to `createPerception`. */
+    hearingRange: number;
+    /** Most hunters one noise sends. Default `3`. */
+    maxInvestigators?: number;
+    /** Confidence at or below which a hunter gives up and returns to its post. Default `0.15`. */
+    giveUpConfidence?: number;
+    /** Longest one hunt survives, seconds. Default `20`. */
+    maxSeconds?: number;
+    /** Most noises remembered at once; the oldest is dropped first. Default `16`. */
+    maxNoises?: number;
+}
+/** Sound hunting: raise a noise, get the bounded set of enemies that go and look. */
+export interface SoundHunt {
+    /**
+     * Record one noise in the hearing owner's stimulus stream and admit the nearest hunters to it.
+     * Returns the admitted hunter ids so the caller can issue its own move order now; the decay and
+     * the give-up are read back through {@link SoundHunt.investigations}.
+     */
+    noise(event: NoiseEvent): readonly string[];
+    /** Hunters still working their noise at `nowMs`, with the memory's remaining confidence. */
+    investigations(nowMs: number): Investigation[];
+    snapshot(): SoundHuntSnapshot;
+    restore(snapshot: SoundHuntSnapshot): void;
+}
+/**
+ * Make enemies investigate a noise, reusing the hearing owner.
+ *
+ * The noise goes into `PerceptionService.pushStimulus` as a `sound` stimulus, so the same range,
+ * loudness and linear memory decay that every other hearing consumer gets apply here; this layer
+ * adds only the two things a squad needs: a *bound* on how many enemies chase one noise, and a
+ * *give-up* rule, both read back from that memory instead of a second copy of it. A sighting of the
+ * source during the hunt raises the same memory's confidence, so an investigation escalates into a
+ * pursuit without any bookkeeping here.
+ *
+ * @capability sound-hunting send a bounded set of nearby enemies to investigate a noise with decaying memory
+ */
+export declare function createSoundHunt(config: SoundHuntConfig): SoundHunt;