@alife-sdk/ai 0.1.0

package/dist/sound/VocalizationTypes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * All possible NPC vocalization types.
+ * The host maps these to actual audio assets.
+ */
+export declare const VocalizationType: {
+    readonly IDLE: "idle";
+    readonly ALERT: "alert";
+    readonly COMBAT: "combat";
+    readonly WOUNDED: "wounded";
+    readonly DEATH: "death";
+    readonly FLEE: "flee";
+    readonly GRENADE_THROW: "grenade_throw";
+    readonly GRENADE_WARNING: "grenade_warning";
+    readonly RELOAD: "reload";
+    readonly SPOTTED_ENEMY: "spotted_enemy";
+    readonly LOST_TARGET: "lost_target";
+    readonly KILL_CONFIRMED: "kill_confirmed";
+    readonly FRIENDLY_FIRE: "friendly_fire";
+    readonly HELP: "help";
+    readonly ACKNOWLEDGE: "acknowledge";
+    readonly REMARK: "remark";
+    readonly KAMP_SOCIAL: "kamp_social";
+};
+export type VocalizationType = (typeof VocalizationType)[keyof typeof VocalizationType];
+/**
+ * Configuration for vocalization cooldowns per type.
+ * Prevents overlapping/spamming sounds.
+ */
+export interface IVocalizationConfig {
+    readonly cooldowns: Readonly<Record<VocalizationType, number>>;
+}
+/** Default production cooldowns (ms). */
+export declare function createDefaultVocalizationConfig(): IVocalizationConfig;
+/**
+ * Per-NPC vocalization cooldown tracker.
+ *
+ * Tracks last play time per type. The host calls `canPlay()` before
+ * triggering audio and `markPlayed()` after.
+ *
+ * @example
+ * ```ts
+ * const tracker = new VocalizationTracker(config);
+ * if (tracker.canPlay(VocalizationType.COMBAT, gameTime)) {
+ *   tracker.markPlayed(VocalizationType.COMBAT, gameTime);
+ *   audioSystem.play(npcId, VocalizationType.COMBAT);
+ * }
+ * ```
+ */
+export declare class VocalizationTracker {
+    private readonly lastPlayed;
+    private readonly config;
+    constructor(config: IVocalizationConfig);
+    canPlay(type: VocalizationType, currentTimeMs: number): boolean;
+    markPlayed(type: VocalizationType, currentTimeMs: number): void;
+    reset(): void;
+}
+//# sourceMappingURL=VocalizationTypes.d.ts.map

package/dist/sound/VocalizationTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VocalizationTypes.d.ts","sourceRoot":"","sources":["../../src/sound/VocalizationTypes.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;CAkBnB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAExF;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;CAChE;AAED,yCAAyC;AACzC,wBAAgB,+BAA+B,IAAI,mBAAmB,CAsBrE;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;gBAEjC,MAAM,EAAE,mBAAmB;IAIvC,OAAO,CAAC,IAAI,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IAU/D,UAAU,CAAC,IAAI,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAI/D,KAAK,IAAI,IAAI;CAGd"}

package/dist/sound/VocalizationTypes.js

@@ -0,0 +1,87 @@
+// sound/VocalizationTypes.ts
+// Type-safe vocalization system for NPC sounds.
+// No audio playback — the host implements the actual sound renderer.
+/**
+ * All possible NPC vocalization types.
+ * The host maps these to actual audio assets.
+ */
+export const VocalizationType = {
+    IDLE: 'idle',
+    ALERT: 'alert',
+    COMBAT: 'combat',
+    WOUNDED: 'wounded',
+    DEATH: 'death',
+    FLEE: 'flee',
+    GRENADE_THROW: 'grenade_throw',
+    GRENADE_WARNING: 'grenade_warning',
+    RELOAD: 'reload',
+    SPOTTED_ENEMY: 'spotted_enemy',
+    LOST_TARGET: 'lost_target',
+    KILL_CONFIRMED: 'kill_confirmed',
+    FRIENDLY_FIRE: 'friendly_fire',
+    HELP: 'help',
+    ACKNOWLEDGE: 'acknowledge',
+    REMARK: 'remark',
+    KAMP_SOCIAL: 'kamp_social',
+};
+/** Default production cooldowns (ms). */
+export function createDefaultVocalizationConfig() {
+    return {
+        cooldowns: {
+            [VocalizationType.IDLE]: 15000,
+            [VocalizationType.ALERT]: 5000,
+            [VocalizationType.COMBAT]: 3000,
+            [VocalizationType.WOUNDED]: 4000,
+            [VocalizationType.DEATH]: 0,
+            [VocalizationType.FLEE]: 5000,
+            [VocalizationType.GRENADE_THROW]: 1000,
+            [VocalizationType.GRENADE_WARNING]: 2000,
+            [VocalizationType.RELOAD]: 3000,
+            [VocalizationType.SPOTTED_ENEMY]: 5000,
+            [VocalizationType.LOST_TARGET]: 5000,
+            [VocalizationType.KILL_CONFIRMED]: 3000,
+            [VocalizationType.FRIENDLY_FIRE]: 5000,
+            [VocalizationType.HELP]: 4000,
+            [VocalizationType.ACKNOWLEDGE]: 2000,
+            [VocalizationType.REMARK]: 10000,
+            [VocalizationType.KAMP_SOCIAL]: 8000,
+        },
+    };
+}
+/**
+ * Per-NPC vocalization cooldown tracker.
+ *
+ * Tracks last play time per type. The host calls `canPlay()` before
+ * triggering audio and `markPlayed()` after.
+ *
+ * @example
+ * ```ts
+ * const tracker = new VocalizationTracker(config);
+ * if (tracker.canPlay(VocalizationType.COMBAT, gameTime)) {
+ *   tracker.markPlayed(VocalizationType.COMBAT, gameTime);
+ *   audioSystem.play(npcId, VocalizationType.COMBAT);
+ * }
+ * ```
+ */
+export class VocalizationTracker {
+    constructor(config) {
+        this.lastPlayed = new Map();
+        this.config = config;
+    }
+    canPlay(type, currentTimeMs) {
+        const cooldown = this.config.cooldowns[type] ?? 0;
+        if (cooldown === 0)
+            return true;
+        const last = this.lastPlayed.get(type);
+        if (last === undefined)
+            return true;
+        return currentTimeMs - last >= cooldown;
+    }
+    markPlayed(type, currentTimeMs) {
+        this.lastPlayed.set(type, currentTimeMs);
+    }
+    reset() {
+        this.lastPlayed.clear();
+    }
+}
+//# sourceMappingURL=VocalizationTypes.js.map

package/dist/sound/VocalizationTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VocalizationTypes.js","sourceRoot":"","sources":["../../src/sound/VocalizationTypes.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,gDAAgD;AAChD,qEAAqE;AAErE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,iBAAiB;IAClC,MAAM,EAAE,QAAQ;IAChB,aAAa,EAAE,eAAe;IAC9B,WAAW,EAAE,aAAa;IAC1B,cAAc,EAAE,gBAAgB;IAChC,aAAa,EAAE,eAAe;IAC9B,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,aAAa;IAC1B,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,aAAa;CAClB,CAAC;AAYX,yCAAyC;AACzC,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,SAAS,EAAE;YACT,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,KAAM;YAC/B,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,IAAK;YAC/B,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,IAAK;YAChC,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,IAAK;YACjC,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,IAAK;YAC9B,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,IAAK;YACvC,CAAC,gBAAgB,CAAC,eAAe,CAAC,EAAE,IAAK;YACzC,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,IAAK;YAChC,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,IAAK;YACvC,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,IAAK;YACrC,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,IAAK;YACxC,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,IAAK;YACvC,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,IAAK;YAC9B,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,IAAK;YACrC,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,KAAM;YACjC,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,IAAK;SACtC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,mBAAmB;IAI9B,YAAY,MAA2B;QAHtB,eAAU,GAAG,IAAI,GAAG,EAA4B,CAAC;QAIhE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,OAAO,CAAC,IAAsB,EAAE,aAAqB;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,QAAQ,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAEpC,OAAO,aAAa,GAAG,IAAI,IAAI,QAAQ,CAAC;IAC1C,CAAC;IAED,UAAU,CAAC,IAAsB,EAAE,aAAqB;QACtD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/sound/index.d.ts

@@ -0,0 +1,3 @@
+export { VocalizationType, VocalizationTracker, createDefaultVocalizationConfig, } from './VocalizationTypes';
+export type { IVocalizationConfig } from './VocalizationTypes';
+//# sourceMappingURL=index.d.ts.map

package/dist/sound/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sound/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/sound/index.js

@@ -0,0 +1,3 @@
+// sound sub-path barrel
+export { VocalizationType, VocalizationTracker, createDefaultVocalizationConfig, } from './VocalizationTypes';
+//# sourceMappingURL=index.js.map

package/dist/sound/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sound/index.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,qBAAqB,CAAC"}

package/dist/squad/SquadSharedTarget.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared enemy sighting propagated to all squad members.
+ *
+ * Produced by {@link SquadSharedTargetTable.shareTarget} and returned by
+ * {@link SquadSharedTargetTable.getSharedTarget}.
+ */
+export interface ISharedTargetInfo {
+    /** Stable entity ID of the spotted enemy. */
+    readonly targetId: string;
+    /** Enemy world X at the time of the sighting (px). */
+    readonly x: number;
+    /** Enemy world Y at the time of the sighting (px). */
+    readonly y: number;
+    /**
+     * Confidence of this indirect intel.
+     * Lower than a direct observation (1.0) — set by
+     * {@link ISquadSharedTargetConfig.sharedConfidence}.
+     */
+    readonly confidence: number;
+    /** Epoch ms when the intel was recorded (for TTL checks). */
+    readonly sharedAtMs: number;
+}
+/**
+ * Tuning parameters for the squad shared target table.
+ * All fields have defaults via {@link createDefaultSquadSharedTargetConfig}.
+ */
+export interface ISquadSharedTargetConfig {
+    /**
+     * How long (ms) before shared intel expires and is treated as stale.
+     * @default 10_000
+     */
+    readonly ttlMs: number;
+    /**
+     * Confidence value assigned to shared (indirect) sightings.
+     * Should be < 1.0 to reflect that the NPC has not seen the target directly.
+     * @default 0.8
+     */
+    readonly sharedConfidence: number;
+}
+/**
+ * Create an {@link ISquadSharedTargetConfig} with production defaults.
+ * Pass a partial override object to tune individual values.
+ *
+ * @example
+ * const cfg = createDefaultSquadSharedTargetConfig({ ttlMs: 5_000 });
+ */
+export declare function createDefaultSquadSharedTargetConfig(overrides?: Partial<ISquadSharedTargetConfig>): ISquadSharedTargetConfig;
+/**
+ * Shared enemy intel store keyed by squad ID.
+ *
+ * One instance should be created per game session and shared across all NPCs.
+ * Each NPC's {@link ISquadAccess} implementation calls into this table via its
+ * own `npcId`.
+ *
+ * ### Wiring example (host layer)
+ * ```ts
+ * const sharedTargets = new SquadSharedTargetTable(
+ *   npcId => squadManager.getSquadForNPC(npcId)?.id ?? null,
+ * );
+ *
+ * class MySquadAccess implements ISquadAccess {
+ *   constructor(private readonly npcId: string) {}
+ *   shareTarget(targetId, x, y) {
+ *     sharedTargets.shareTarget(this.npcId, targetId, x, y);
+ *   }
+ *   getSharedTarget() {
+ *     return sharedTargets.getSharedTarget(this.npcId);
+ *   }
+ *   // ...
+ * }
+ * ```
+ *
+ * ### Opt-in / opt-out
+ * - **Full feature**: implement `getSharedTarget()` on `ISquadAccess` above.
+ * - **Write only**: implement `shareTarget()` but not `getSharedTarget()`.
+ * - **Fully disabled**: don't implement either — PatrolState check is a no-op
+ *   via `ctx.squad?.getSharedTarget?.()`.
+ */
+export declare class SquadSharedTargetTable {
+    private readonly npcToSquad;
+    private readonly config;
+    private readonly nowFn;
+    /** Inner store: squadId → latest ISharedTargetInfo. */
+    private readonly store;
+    /**
+     * @param npcToSquad - Returns the squad ID for an NPC, or null if not in a
+     *                     squad. Wrap your SquadManager:
+     *                     `npcId => mgr.getSquadForNPC(npcId)?.id ?? null`
+     * @param config     - TTL and confidence overrides.
+     *                     @default createDefaultSquadSharedTargetConfig()
+     * @param nowFn      - Time source.
+     *                     @default () => Date.now()  (injectable for tests)
+     */
+    constructor(npcToSquad: (npcId: string) => string | null, config?: Partial<ISquadSharedTargetConfig>, nowFn?: () => number);
+    /**
+     * Record a target sighting for the sender's squad.
+     *
+     * All squad members can retrieve this via {@link getSharedTarget} until
+     * the TTL expires or {@link invalidate} is called.
+     *
+     * No-op if the sender is not in any squad.
+     *
+     * @param senderNpcId - NPC ID of the entity that spotted the target.
+     * @param targetId    - Stable entity ID of the enemy.
+     * @param x           - Enemy world X (px).
+     * @param y           - Enemy world Y (px).
+     */
+    shareTarget(senderNpcId: string, targetId: string, x: number, y: number): void;
+    /**
+     * Return the current shared target for the given NPC's squad.
+     *
+     * Returns `null` when:
+     * - The NPC is not in any squad.
+     * - No target has been shared yet.
+     * - The intel has expired (age > ttlMs).
+     *
+     * @param npcId - NPC querying for squad intel.
+     */
+    getSharedTarget(npcId: string): ISharedTargetInfo | null;
+    /**
+     * Explicitly clear shared intel for a squad.
+     *
+     * Call this when the target is confirmed destroyed or the engagement ends
+     * to avoid squad members chasing stale positions.
+     *
+     * @param squadId - Direct squad ID to invalidate.
+     */
+    invalidate(squadId: string): void;
+    /**
+     * Clear all shared intel for all squads.
+     *
+     * Call on save/load or scene restart to avoid stale intel from a previous
+     * session persisting into the restored game state.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=SquadSharedTarget.d.ts.map

package/dist/squad/SquadSharedTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SquadSharedTarget.d.ts","sourceRoot":"","sources":["../../src/squad/SquadSharedTarget.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAClD,SAAS,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,GAC5C,wBAAwB,CAM1B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAE9D;;;;;;;;OAQG;gBAED,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EAC5C,MAAM,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,EAC1C,KAAK,CAAC,EAAE,MAAM,MAAM;IAOtB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAc9E;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAexD;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/squad/SquadSharedTarget.js

@@ -0,0 +1,145 @@
+// squad/SquadSharedTarget.ts
+// TTL-based squad enemy intel table.
+//
+// Design goals:
+//   • Zero SDK dependency — no Phaser, no alife-core imports needed.
+//   • npcToSquad callback injection — no circular dep to SquadManager.
+//   • nowFn injectable — deterministic test control.
+//   • Opt-in at the ISquadAccess level via optional getSharedTarget?().
+//     State handlers that don't call it incur zero overhead.
+/**
+ * Create an {@link ISquadSharedTargetConfig} with production defaults.
+ * Pass a partial override object to tune individual values.
+ *
+ * @example
+ * const cfg = createDefaultSquadSharedTargetConfig({ ttlMs: 5_000 });
+ */
+export function createDefaultSquadSharedTargetConfig(overrides) {
+    return {
+        ttlMs: 10000,
+        sharedConfidence: 0.8,
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// SquadSharedTargetTable
+// ---------------------------------------------------------------------------
+/**
+ * Shared enemy intel store keyed by squad ID.
+ *
+ * One instance should be created per game session and shared across all NPCs.
+ * Each NPC's {@link ISquadAccess} implementation calls into this table via its
+ * own `npcId`.
+ *
+ * ### Wiring example (host layer)
+ * ```ts
+ * const sharedTargets = new SquadSharedTargetTable(
+ *   npcId => squadManager.getSquadForNPC(npcId)?.id ?? null,
+ * );
+ *
+ * class MySquadAccess implements ISquadAccess {
+ *   constructor(private readonly npcId: string) {}
+ *   shareTarget(targetId, x, y) {
+ *     sharedTargets.shareTarget(this.npcId, targetId, x, y);
+ *   }
+ *   getSharedTarget() {
+ *     return sharedTargets.getSharedTarget(this.npcId);
+ *   }
+ *   // ...
+ * }
+ * ```
+ *
+ * ### Opt-in / opt-out
+ * - **Full feature**: implement `getSharedTarget()` on `ISquadAccess` above.
+ * - **Write only**: implement `shareTarget()` but not `getSharedTarget()`.
+ * - **Fully disabled**: don't implement either — PatrolState check is a no-op
+ *   via `ctx.squad?.getSharedTarget?.()`.
+ */
+export class SquadSharedTargetTable {
+    /**
+     * @param npcToSquad - Returns the squad ID for an NPC, or null if not in a
+     *                     squad. Wrap your SquadManager:
+     *                     `npcId => mgr.getSquadForNPC(npcId)?.id ?? null`
+     * @param config     - TTL and confidence overrides.
+     *                     @default createDefaultSquadSharedTargetConfig()
+     * @param nowFn      - Time source.
+     *                     @default () => Date.now()  (injectable for tests)
+     */
+    constructor(npcToSquad, config, nowFn) {
+        /** Inner store: squadId → latest ISharedTargetInfo. */
+        this.store = new Map();
+        this.npcToSquad = npcToSquad;
+        this.config = createDefaultSquadSharedTargetConfig(config);
+        this.nowFn = nowFn ?? (() => Date.now());
+    }
+    /**
+     * Record a target sighting for the sender's squad.
+     *
+     * All squad members can retrieve this via {@link getSharedTarget} until
+     * the TTL expires or {@link invalidate} is called.
+     *
+     * No-op if the sender is not in any squad.
+     *
+     * @param senderNpcId - NPC ID of the entity that spotted the target.
+     * @param targetId    - Stable entity ID of the enemy.
+     * @param x           - Enemy world X (px).
+     * @param y           - Enemy world Y (px).
+     */
+    shareTarget(senderNpcId, targetId, x, y) {
+        const squadId = this.npcToSquad(senderNpcId);
+        if (squadId === null)
+            return;
+        const info = {
+            targetId,
+            x,
+            y,
+            confidence: this.config.sharedConfidence,
+            sharedAtMs: this.nowFn(),
+        };
+        this.store.set(squadId, info);
+    }
+    /**
+     * Return the current shared target for the given NPC's squad.
+     *
+     * Returns `null` when:
+     * - The NPC is not in any squad.
+     * - No target has been shared yet.
+     * - The intel has expired (age > ttlMs).
+     *
+     * @param npcId - NPC querying for squad intel.
+     */
+    getSharedTarget(npcId) {
+        const squadId = this.npcToSquad(npcId);
+        if (squadId === null)
+            return null;
+        const info = this.store.get(squadId);
+        if (info === undefined)
+            return null;
+        if (this.nowFn() - info.sharedAtMs > this.config.ttlMs) {
+            this.store.delete(squadId);
+            return null;
+        }
+        return info;
+    }
+    /**
+     * Explicitly clear shared intel for a squad.
+     *
+     * Call this when the target is confirmed destroyed or the engagement ends
+     * to avoid squad members chasing stale positions.
+     *
+     * @param squadId - Direct squad ID to invalidate.
+     */
+    invalidate(squadId) {
+        this.store.delete(squadId);
+    }
+    /**
+     * Clear all shared intel for all squads.
+     *
+     * Call on save/load or scene restart to avoid stale intel from a previous
+     * session persisting into the restored game state.
+     */
+    clear() {
+        this.store.clear();
+    }
+}
+//# sourceMappingURL=SquadSharedTarget.js.map

package/dist/squad/SquadSharedTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SquadSharedTarget.js","sourceRoot":"","sources":["../../src/squad/SquadSharedTarget.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,qCAAqC;AACrC,EAAE;AACF,gBAAgB;AAChB,qEAAqE;AACrE,uEAAuE;AACvE,qDAAqD;AACrD,wEAAwE;AACxE,6DAA6D;AAgD7D;;;;;;GAMG;AACH,MAAM,UAAU,oCAAoC,CAClD,SAA6C;IAE7C,OAAO;QACL,KAAK,EAAE,KAAM;QACb,gBAAgB,EAAE,GAAG;QACrB,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,sBAAsB;IAQjC;;;;;;;;OAQG;IACH,YACE,UAA4C,EAC5C,MAA0C,EAC1C,KAAoB;QAftB,uDAAuD;QACtC,UAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;QAgB5D,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,oCAAoC,CAAC,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,WAAmB,EAAE,QAAgB,EAAE,CAAS,EAAE,CAAS;QACrE,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QAC7C,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO;QAE7B,MAAM,IAAI,GAAsB;YAC9B,QAAQ;YACR,CAAC;YACD,CAAC;YACD,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;YACxC,UAAU,EAAE,IAAI,CAAC,KAAK,EAAE;SACzB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAa;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAElC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAEpC,IAAI,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/squad/SquadTactics.d.ts

@@ -0,0 +1,63 @@
+import type { ISquadTacticsConfig } from '../types/IOnlineAIConfig';
+/**
+ * Squad command identifiers.
+ */
+export declare const SquadCommand: {
+    readonly ATTACK: "attack";
+    readonly COVER_ME: "cover_me";
+    readonly FOLLOW: "follow";
+    readonly HOLD: "hold";
+    readonly RETREAT: "retreat";
+    readonly SPREAD_OUT: "spread_out";
+};
+export type SquadCommand = (typeof SquadCommand)[keyof typeof SquadCommand];
+/**
+ * Tactical situation snapshot for command evaluation.
+ * Aggregates squad state without entity references.
+ */
+export interface ISquadSituation {
+    /** Number of squad members (including leader). */
+    readonly squadSize: number;
+    /** Number of known enemies in the engagement. */
+    readonly enemyCount: number;
+    /** Average morale across all squad members [-1, 1]. */
+    readonly avgMorale: number;
+    /** Whether the leader is currently in cover. */
+    readonly leaderInCover: boolean;
+}
+/**
+ * A single tactical command with its evaluation logic.
+ * Each command scores a situation and returns a priority value.
+ */
+export interface ISquadCommandEvaluator {
+    readonly command: SquadCommand;
+    evaluate(situation: ISquadSituation, config: ISquadTacticsConfig): number;
+}
+/**
+ * Evaluate the best squad command for the current situation.
+ *
+ * Uses a priority-ordered decision tree (first match wins):
+ *
+ * 1. Morale collapse → RETREAT
+ * 2. No enemies → FOLLOW
+ * 3. Badly outnumbered → RETREAT
+ * 4. Even fight → HOLD
+ * 5. Numerical advantage → ATTACK
+ * 6. Leader in cover → COVER_ME
+ * 7. Default → SPREAD_OUT
+ *
+ * @param situation - Current tactical snapshot.
+ * @param config - Squad tuning configuration.
+ * @returns The recommended squad command.
+ */
+export declare function evaluateSituation(situation: ISquadSituation, config: ISquadTacticsConfig): SquadCommand;
+/**
+ * States that must never be interrupted by squad commands.
+ * The host should check this before applying any command.
+ */
+export declare const PROTECTED_STATES: Set<string>;
+/**
+ * Check if a command can be applied to an NPC in the given state.
+ */
+export declare function canApplyCommand(currentState: string): boolean;
+//# sourceMappingURL=SquadTactics.d.ts.map

package/dist/squad/SquadTactics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SquadTactics.d.ts","sourceRoot":"","sources":["../../src/squad/SquadTactics.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;CAOf,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAAC;CAC3E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,mBAAmB,GAC1B,YAAY,CAmCd;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,aAI3B,CAAC;AAEH;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/squad/SquadTactics.js

@@ -0,0 +1,76 @@
+// squad/SquadTactics.ts
+// Command pattern for squad-level tactical decisions.
+// Pure evaluation — no entity references, no framework coupling.
+/**
+ * Squad command identifiers.
+ */
+export const SquadCommand = {
+    ATTACK: 'attack',
+    COVER_ME: 'cover_me',
+    FOLLOW: 'follow',
+    HOLD: 'hold',
+    RETREAT: 'retreat',
+    SPREAD_OUT: 'spread_out',
+};
+/**
+ * Evaluate the best squad command for the current situation.
+ *
+ * Uses a priority-ordered decision tree (first match wins):
+ *
+ * 1. Morale collapse → RETREAT
+ * 2. No enemies → FOLLOW
+ * 3. Badly outnumbered → RETREAT
+ * 4. Even fight → HOLD
+ * 5. Numerical advantage → ATTACK
+ * 6. Leader in cover → COVER_ME
+ * 7. Default → SPREAD_OUT
+ *
+ * @param situation - Current tactical snapshot.
+ * @param config - Squad tuning configuration.
+ * @returns The recommended squad command.
+ */
+export function evaluateSituation(situation, config) {
+    const { squadSize, enemyCount, avgMorale, leaderInCover } = situation;
+    // Priority 1: Morale collapse.
+    if (avgMorale <= config.moralePanickedThreshold) {
+        return SquadCommand.RETREAT;
+    }
+    // Priority 2: No threats.
+    if (enemyCount === 0) {
+        return SquadCommand.FOLLOW;
+    }
+    // Priority 3: Badly outnumbered.
+    if (enemyCount > squadSize * config.outnumberRatio) {
+        return SquadCommand.RETREAT;
+    }
+    // Priority 4: Even fight.
+    if (enemyCount >= squadSize) {
+        return SquadCommand.HOLD;
+    }
+    // Priority 5: Numerical advantage.
+    if (squadSize > enemyCount * config.outnumberRatio) {
+        return SquadCommand.ATTACK;
+    }
+    // Priority 6: Leader in cover — provide suppressive fire.
+    if (leaderInCover) {
+        return SquadCommand.COVER_ME;
+    }
+    // Default: distribute tactically.
+    return SquadCommand.SPREAD_OUT;
+}
+/**
+ * States that must never be interrupted by squad commands.
+ * The host should check this before applying any command.
+ */
+export const PROTECTED_STATES = new Set([
+    'DEAD',
+    'WOUNDED',
+    'EVADE_GRENADE',
+]);
+/**
+ * Check if a command can be applied to an NPC in the given state.
+ */
+export function canApplyCommand(currentState) {
+    return !PROTECTED_STATES.has(currentState);
+}
+//# sourceMappingURL=SquadTactics.js.map

package/dist/squad/SquadTactics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SquadTactics.js","sourceRoot":"","sources":["../../src/squad/SquadTactics.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,sDAAsD;AACtD,iEAAiE;AAIjE;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,YAAY;CAChB,CAAC;AA4BX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA0B,EAC1B,MAA2B;IAE3B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;IAEtE,+BAA+B;IAC/B,IAAI,SAAS,IAAI,MAAM,CAAC,uBAAuB,EAAE,CAAC;QAChD,OAAO,YAAY,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,0BAA0B;IAC1B,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,YAAY,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,iCAAiC;IACjC,IAAI,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC,cAAc,EAAE,CAAC;QACnD,OAAO,YAAY,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,0BAA0B;IAC1B,IAAI,UAAU,IAAI,SAAS,EAAE,CAAC;QAC5B,OAAO,YAAY,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,mCAAmC;IACnC,IAAI,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC,cAAc,EAAE,CAAC;QACnD,OAAO,YAAY,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,0DAA0D;IAC1D,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,YAAY,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAED,kCAAkC;IAClC,OAAO,YAAY,CAAC,UAAU,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IACtC,MAAM;IACN,SAAS;IACT,eAAe;CAChB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC7C,CAAC"}

package/dist/squad/index.d.ts

@@ -0,0 +1,5 @@
+export { evaluateSituation, SquadCommand, canApplyCommand, PROTECTED_STATES, } from './SquadTactics';
+export type { ISquadSituation, ISquadCommandEvaluator } from './SquadTactics';
+export { SquadSharedTargetTable, createDefaultSquadSharedTargetConfig } from './SquadSharedTarget';
+export type { ISharedTargetInfo, ISquadSharedTargetConfig } from './SquadSharedTarget';
+//# sourceMappingURL=index.d.ts.map

package/dist/squad/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/squad/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE9E,OAAO,EAAE,sBAAsB,EAAE,oCAAoC,EAAE,MAAM,qBAAqB,CAAC;AACnG,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/squad/index.js

@@ -0,0 +1,4 @@
+// squad sub-path barrel
+export { evaluateSituation, SquadCommand, canApplyCommand, PROTECTED_STATES, } from './SquadTactics';
+export { SquadSharedTargetTable, createDefaultSquadSharedTargetConfig } from './SquadSharedTarget';
+//# sourceMappingURL=index.js.map

package/dist/squad/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/squad/index.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,sBAAsB,EAAE,oCAAoC,EAAE,MAAM,qBAAqB,CAAC"}