@alife-sdk/ai 0.1.0

package/dist/cover/CoverAccessAdapter.d.ts

@@ -0,0 +1,61 @@
+import type { ICoverAccess } from '../states/INPCContext';
+import { CoverRegistry } from './CoverRegistry';
+import type { ICoverLockRegistry } from './ICoverLockConfig';
+/**
+ * Per-NPC cover access adapter.
+ *
+ * Bridges the generic `ICoverAccess` contract used by state handlers with
+ * the concrete `CoverRegistry` + `CoverLockRegistry` SDK classes.
+ *
+ * Responsibilities:
+ *  - Translates the flat `(x, y, enemyX, enemyY)` API to the typed
+ *    `CoverRegistry.findCover(type, pos, enemies, npcId)` call.
+ *  - Stores the `ICoverPoint.id` of the last successful `findCover` result
+ *    so that `lockLastFound()` can acquire the TTL lock without requiring
+ *    the caller to manage point IDs.
+ *
+ * **Create one adapter per NPC** via `AIPlugin.createCoverAccess(npcId)`.
+ * The adapter is stateful (tracks `_lastFoundId`) and must not be shared
+ * across different NPC entities.
+ *
+ * @example
+ * ```ts
+ * // Phaser bridge setup (PhaserNPCContext):
+ * const coverAccess = aiPlugin.createCoverAccess(npcId);
+ * // Then expose via INPCContext.cover = coverAccess
+ * ```
+ */
+export declare class CoverAccessAdapter implements ICoverAccess {
+    private readonly _registry;
+    private readonly _lockRegistry;
+    private readonly _npcId;
+    private _lastFoundId;
+    /**
+     * @param _registry   - Shared cover registry (scene-level singleton).
+     * @param _lockRegistry - Optional TTL lock registry. When null, locking
+     *                        is skipped and `lockLastFound` returns true.
+     * @param _npcId      - The NPC this adapter serves. Used as the requester
+     *                      ID in `findCover` occupancy filtering.
+     */
+    constructor(_registry: CoverRegistry, _lockRegistry: ICoverLockRegistry | null, _npcId: string);
+    findCover(x: number, y: number, enemyX: number, enemyY: number, type?: string): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Acquire a TTL lock on the most recently returned cover point.
+     *
+     * Returns `true` (vacuous success) if:
+     *  - No cover point has been found yet (`findCover` was not called or returned null).
+     *  - No lock registry was provided at construction time.
+     *
+     * Returns `false` if the point is already locked at capacity by other NPCs.
+     */
+    lockLastFound(npcId: string, ttlMs?: number): boolean;
+    /**
+     * Release all TTL locks held by the given NPC in the lock registry.
+     * No-op if no lock registry was provided at construction time.
+     */
+    unlockAll(npcId: string): void;
+}
+//# sourceMappingURL=CoverAccessAdapter.d.ts.map

package/dist/cover/CoverAccessAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoverAccessAdapter.d.ts","sourceRoot":"","sources":["../../src/cover/CoverAccessAdapter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IAWnD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB,OAAO,CAAC,YAAY,CAAuB;IAE3C;;;;;;OAMG;gBAEgB,SAAS,EAAE,aAAa,EACxB,aAAa,EAAE,kBAAkB,GAAG,IAAI,EACxC,MAAM,EAAE,MAAM;IAOjC,SAAS,CACP,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GACZ;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAelC;;;;;;;;OAQG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO;IASrD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAG/B"}

package/dist/cover/CoverAccessAdapter.js

@@ -0,0 +1,74 @@
+// cover/CoverAccessAdapter.ts
+// SDK-provided implementation of ICoverAccess that bridges CoverRegistry
+// with an optional CoverLockRegistry.
+import { CoverType as CoverTypeConst } from '../types/ICoverPoint';
+/**
+ * Per-NPC cover access adapter.
+ *
+ * Bridges the generic `ICoverAccess` contract used by state handlers with
+ * the concrete `CoverRegistry` + `CoverLockRegistry` SDK classes.
+ *
+ * Responsibilities:
+ *  - Translates the flat `(x, y, enemyX, enemyY)` API to the typed
+ *    `CoverRegistry.findCover(type, pos, enemies, npcId)` call.
+ *  - Stores the `ICoverPoint.id` of the last successful `findCover` result
+ *    so that `lockLastFound()` can acquire the TTL lock without requiring
+ *    the caller to manage point IDs.
+ *
+ * **Create one adapter per NPC** via `AIPlugin.createCoverAccess(npcId)`.
+ * The adapter is stateful (tracks `_lastFoundId`) and must not be shared
+ * across different NPC entities.
+ *
+ * @example
+ * ```ts
+ * // Phaser bridge setup (PhaserNPCContext):
+ * const coverAccess = aiPlugin.createCoverAccess(npcId);
+ * // Then expose via INPCContext.cover = coverAccess
+ * ```
+ */
+export class CoverAccessAdapter {
+    /**
+     * @param _registry   - Shared cover registry (scene-level singleton).
+     * @param _lockRegistry - Optional TTL lock registry. When null, locking
+     *                        is skipped and `lockLastFound` returns true.
+     * @param _npcId      - The NPC this adapter serves. Used as the requester
+     *                      ID in `findCover` occupancy filtering.
+     */
+    constructor(_registry, _lockRegistry, _npcId) {
+        this._registry = _registry;
+        this._lockRegistry = _lockRegistry;
+        this._npcId = _npcId;
+        this._lastFoundId = null;
+    }
+    // -------------------------------------------------------------------------
+    // ICoverAccess
+    // -------------------------------------------------------------------------
+    findCover(x, y, enemyX, enemyY, type) {
+        const coverType = type ?? CoverTypeConst.BALANCED;
+        const point = this._registry.findCover(coverType, { x, y }, [{ x: enemyX, y: enemyY }], this._npcId);
+        this._lastFoundId = point?.id ?? null;
+        return point !== null ? { x: point.x, y: point.y } : null;
+    }
+    /**
+     * Acquire a TTL lock on the most recently returned cover point.
+     *
+     * Returns `true` (vacuous success) if:
+     *  - No cover point has been found yet (`findCover` was not called or returned null).
+     *  - No lock registry was provided at construction time.
+     *
+     * Returns `false` if the point is already locked at capacity by other NPCs.
+     */
+    lockLastFound(npcId, ttlMs) {
+        if (this._lockRegistry === null || this._lastFoundId === null)
+            return true;
+        return this._lockRegistry.tryLock(this._lastFoundId, npcId, ttlMs !== undefined ? { ttlMs } : undefined);
+    }
+    /**
+     * Release all TTL locks held by the given NPC in the lock registry.
+     * No-op if no lock registry was provided at construction time.
+     */
+    unlockAll(npcId) {
+        this._lockRegistry?.unlockAll(npcId);
+    }
+}
+//# sourceMappingURL=CoverAccessAdapter.js.map

package/dist/cover/CoverAccessAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoverAccessAdapter.js","sourceRoot":"","sources":["../../src/cover/CoverAccessAdapter.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,yEAAyE;AACzE,sCAAsC;AAItC,OAAO,EAAE,SAAS,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,kBAAkB;IAG7B;;;;;;OAMG;IACH,YACmB,SAAwB,EACxB,aAAwC,EACxC,MAAc;QAFd,cAAS,GAAT,SAAS,CAAe;QACxB,kBAAa,GAAb,aAAa,CAA2B;QACxC,WAAM,GAAN,MAAM,CAAQ;QAZzB,iBAAY,GAAkB,IAAI,CAAC;IAaxC,CAAC;IAEJ,4EAA4E;IAC5E,eAAe;IACf,4EAA4E;IAE5E,SAAS,CACP,CAAS,EACT,CAAS,EACT,MAAc,EACd,MAAc,EACd,IAAa;QAEb,MAAM,SAAS,GAAe,IAAkB,IAAI,cAAc,CAAC,QAAQ,CAAC;QAE5E,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CACpC,SAAS,EACT,EAAE,CAAC,EAAE,CAAC,EAAE,EACR,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAC1B,IAAI,CAAC,MAAM,CACZ,CAAC;QAEF,IAAI,CAAC,YAAY,GAAG,KAAK,EAAE,EAAE,IAAI,IAAI,CAAC;QAEtC,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,CAAC;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,KAAa,EAAE,KAAc;QACzC,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC3E,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAC/B,IAAI,CAAC,YAAY,EACjB,KAAK,EACL,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAC5C,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,KAAa;QACrB,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/cover/CoverEvaluators.d.ts

@@ -0,0 +1,43 @@
+import type { ICoverPoint, ICoverEvalContext } from '../types/ICoverPoint';
+import { CoverType } from '../types/ICoverPoint';
+import type { ICoverEvaluator } from './ICoverEvaluator';
+import type { ICoverConfig } from '../types/IOnlineAIConfig';
+export declare class CloseCoverEvaluator implements ICoverEvaluator {
+    readonly type: "close";
+    private readonly maxRange;
+    constructor(config: ICoverConfig);
+    evaluate(point: ICoverPoint, context: ICoverEvalContext): number;
+}
+export declare class FarCoverEvaluator implements ICoverEvaluator {
+    readonly type: "far";
+    private readonly maxRange;
+    constructor(config: ICoverConfig);
+    evaluate(point: ICoverPoint, context: ICoverEvalContext): number;
+}
+export declare class BalancedCoverEvaluator implements ICoverEvaluator {
+    readonly type: "balanced";
+    evaluate(point: ICoverPoint, context: ICoverEvalContext): number;
+}
+export declare class AmbushCoverEvaluator implements ICoverEvaluator {
+    readonly type: "ambush";
+    private readonly minAngle;
+    private readonly maxAngle;
+    private readonly minDist;
+    private readonly maxDist;
+    constructor(config: ICoverConfig);
+    evaluate(point: ICoverPoint, context: ICoverEvalContext): number;
+}
+export declare class SafeCoverEvaluator implements ICoverEvaluator {
+    readonly type: "safe";
+    evaluate(point: ICoverPoint, context: ICoverEvalContext): number;
+}
+/**
+ * Create a complete set of cover evaluators keyed by CoverType.
+ *
+ * @param config - Cover subsystem configuration.
+ * @returns Map of CoverType → ICoverEvaluator.
+ */
+export declare function createCoverEvaluators(config: ICoverConfig): ReadonlyMap<CoverType, ICoverEvaluator>;
+/** @deprecated Use BalancedCoverEvaluator */
+export declare const BestCoverEvaluator: typeof BalancedCoverEvaluator;
+//# sourceMappingURL=CoverEvaluators.d.ts.map

package/dist/cover/CoverEvaluators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoverEvaluators.d.ts","sourceRoot":"","sources":["../../src/cover/CoverEvaluators.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAkB,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AA6B7D,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,IAAI,UAAmB;IAEhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,MAAM,EAAE,YAAY;IAIhC,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM;CAajE;AAMD,qBAAa,iBAAkB,YAAW,eAAe;IACvD,QAAQ,CAAC,IAAI,QAAiB;IAE9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,MAAM,EAAE,YAAY;IAIhC,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM;CAajE;AAMD,qBAAa,sBAAuB,YAAW,eAAe;IAC5D,QAAQ,CAAC,IAAI,aAAsB;IAEnC,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM;CAwBjE;AAMD,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,QAAQ,CAAC,IAAI,WAAoB;IAEjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,YAAY;IAOhC,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM;CAsCjE;AAMD,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,SAAkB;IAE/B,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM;CAkBjE;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,GACnB,WAAW,CAAC,SAAS,EAAE,eAAe,CAAC,CAQzC;AAED,6CAA6C;AAC7C,eAAO,MAAM,kBAAkB,+BAAyB,CAAC"}

package/dist/cover/CoverEvaluators.js

@@ -0,0 +1,193 @@
+// cover/CoverEvaluators.ts
+// Five tactical cover evaluators implementing the Strategy pattern.
+//
+// Each evaluator scores a cover point on [0, 1] for a specific tactical
+// priority. They are pure functions — no side effects, no state,
+// fully deterministic given the same inputs.
+import { distanceSq } from '@alife-sdk/core';
+import { CoverType } from '../types/ICoverPoint';
+// ---------------------------------------------------------------------------
+// Shared geometry helpers
+// ---------------------------------------------------------------------------
+function averageEnemyPosition(enemies) {
+    if (enemies.length === 0)
+        return { x: 0, y: 0 };
+    let sx = 0;
+    let sy = 0;
+    for (const e of enemies) {
+        sx += e.x;
+        sy += e.y;
+    }
+    return { x: sx / enemies.length, y: sy / enemies.length };
+}
+function angleBetween(from, to) {
+    return Math.atan2(to.y - from.y, to.x - from.x);
+}
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+// ---------------------------------------------------------------------------
+// CLOSE — nearest cover, quick retreat under fire
+// ---------------------------------------------------------------------------
+export class CloseCoverEvaluator {
+    constructor(config) {
+        this.type = CoverType.CLOSE;
+        this.maxRange = config.closeMaxRange;
+    }
+    evaluate(point, context) {
+        const dSq = distanceSq(context.npcPosition, point);
+        const dist = Math.sqrt(dSq);
+        const ratio = dist / this.maxRange;
+        // Beyond max range: score drops linearly to 0 at 2x max range.
+        if (ratio > 1.0) {
+            return clamp01(1.0 - (ratio - 1.0));
+        }
+        // Within range: closer is better. Score 1.0 at distance 0.
+        return 1.0 - ratio;
+    }
+}
+// ---------------------------------------------------------------------------
+// FAR — maximize distance from enemies, strategic retreat
+// ---------------------------------------------------------------------------
+export class FarCoverEvaluator {
+    constructor(config) {
+        this.type = CoverType.FAR;
+        this.maxRange = config.farMaxRange;
+    }
+    evaluate(point, context) {
+        if (context.enemies.length === 0)
+            return 0.5;
+        // Score based on average distance to all enemies.
+        let totalDist = 0;
+        for (const enemy of context.enemies) {
+            totalDist += Math.sqrt(distanceSq(point, enemy));
+        }
+        const avgDist = totalDist / context.enemies.length;
+        // Normalize: 1.0 at maxRange or beyond, 0 at distance 0.
+        return clamp01(avgDist / this.maxRange);
+    }
+}
+// ---------------------------------------------------------------------------
+// BALANCED — balanced three-factor weighted score
+// ---------------------------------------------------------------------------
+export class BalancedCoverEvaluator {
+    constructor() {
+        this.type = CoverType.BALANCED;
+    }
+    evaluate(point, context) {
+        if (context.enemies.length === 0)
+            return 0.5;
+        const centroid = averageEnemyPosition(context.enemies);
+        const coverDist = Math.sqrt(distanceSq(context.npcPosition, point));
+        const enemyDist = Math.sqrt(distanceSq(point, centroid));
+        // Factor 1: proximity to NPC (closer = better, max 30 points).
+        const proximityScore = clamp01(1.0 - coverDist / 400) * 30;
+        // Factor 2: distance from enemies (farther = safer, max 30 points).
+        const safetyScore = clamp01(enemyDist / 600) * 30;
+        // Factor 3: angle quality — cover between NPC and enemy is ideal (max 30 points).
+        const npcToEnemy = angleBetween(context.npcPosition, centroid);
+        const npcToCover = angleBetween(context.npcPosition, point);
+        let angleDelta = Math.abs(npcToEnemy - npcToCover);
+        if (angleDelta > Math.PI)
+            angleDelta = 2 * Math.PI - angleDelta;
+        // Small angle difference means cover is roughly toward/away from enemy.
+        const angleScore = clamp01(1.0 - angleDelta / Math.PI) * 30;
+        // Normalize to [0, 1] (max raw = 90).
+        return (proximityScore + safetyScore + angleScore) / 90;
+    }
+}
+// ---------------------------------------------------------------------------
+// AMBUSH — flanking position, offensive posture
+// ---------------------------------------------------------------------------
+export class AmbushCoverEvaluator {
+    constructor(config) {
+        this.type = CoverType.AMBUSH;
+        this.minAngle = config.ambushMinAngle;
+        this.maxAngle = config.ambushMaxAngle;
+        this.minDist = config.ambushMinDist;
+        this.maxDist = config.ambushMaxDist;
+    }
+    evaluate(point, context) {
+        if (context.enemies.length === 0)
+            return 0;
+        const centroid = averageEnemyPosition(context.enemies);
+        // Distance from cover to enemy centroid.
+        const dist = Math.sqrt(distanceSq(point, centroid));
+        if (dist < this.minDist || dist > this.maxDist) {
+            // Outside ambush distance band — poor score.
+            return clamp01(0.2 - Math.abs(dist - (this.minDist + this.maxDist) / 2) / this.maxDist);
+        }
+        // Flanking angle: angle between (enemy→NPC) and (enemy→cover).
+        const enemyToNpc = angleBetween(centroid, context.npcPosition);
+        const enemyToCover = angleBetween(centroid, point);
+        let flankAngle = Math.abs(enemyToNpc - enemyToCover);
+        if (flankAngle > Math.PI)
+            flankAngle = 2 * Math.PI - flankAngle;
+        // Best flanking is between minAngle and maxAngle (roughly 60°-120°).
+        if (flankAngle >= this.minAngle && flankAngle <= this.maxAngle) {
+            // Perfect flanking band — high score.
+            if (this.maxDist === this.minDist)
+                return 0.85;
+            const distScore = 1.0 - Math.abs(dist - (this.minDist + this.maxDist) / 2) / (this.maxDist - this.minDist);
+            return clamp01(0.7 + distScore * 0.3);
+        }
+        // Outside flanking band — reduced score based on deviation.
+        let deviation;
+        if (flankAngle < this.minAngle) {
+            if (this.minAngle <= 0)
+                return 0;
+            deviation = (this.minAngle - flankAngle) / this.minAngle;
+        }
+        else {
+            if (Math.PI - this.maxAngle <= 0)
+                return 0;
+            deviation = (flankAngle - this.maxAngle) / (Math.PI - this.maxAngle);
+        }
+        return clamp01(0.5 * (1.0 - deviation));
+    }
+}
+// ---------------------------------------------------------------------------
+// SAFE — minimize aggregate threat exposure
+// ---------------------------------------------------------------------------
+export class SafeCoverEvaluator {
+    constructor() {
+        this.type = CoverType.SAFE;
+    }
+    evaluate(point, context) {
+        if (context.enemies.length === 0)
+            return 1.0;
+        // Aggregate threat: sum of inverse squared distances to each enemy.
+        // Lower threat = safer = higher score.
+        let threatSum = 0;
+        for (const enemy of context.enemies) {
+            const dSq = distanceSq(point, enemy);
+            // Avoid division by zero; minimum distance of 1px.
+            threatSum += 1.0 / Math.max(1, dSq);
+        }
+        // Normalize threat to [0, 1]. Empirically, threat rarely exceeds 0.01
+        // for reasonable distances (>10px per enemy).
+        const normalizedThreat = clamp01(threatSum * 5000);
+        return 1.0 - normalizedThreat;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory — create all evaluators from config
+// ---------------------------------------------------------------------------
+/**
+ * Create a complete set of cover evaluators keyed by CoverType.
+ *
+ * @param config - Cover subsystem configuration.
+ * @returns Map of CoverType → ICoverEvaluator.
+ */
+export function createCoverEvaluators(config) {
+    const map = new Map();
+    map.set(CoverType.CLOSE, new CloseCoverEvaluator(config));
+    map.set(CoverType.FAR, new FarCoverEvaluator(config));
+    map.set(CoverType.BALANCED, new BalancedCoverEvaluator());
+    map.set(CoverType.AMBUSH, new AmbushCoverEvaluator(config));
+    map.set(CoverType.SAFE, new SafeCoverEvaluator());
+    return map;
+}
+/** @deprecated Use BalancedCoverEvaluator */
+export const BestCoverEvaluator = BalancedCoverEvaluator;
+//# sourceMappingURL=CoverEvaluators.js.map

package/dist/cover/CoverEvaluators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoverEvaluators.js","sourceRoot":"","sources":["../../src/cover/CoverEvaluators.ts"],"names":[],"mappings":"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"}

package/dist/cover/CoverLockRegistry.d.ts

@@ -0,0 +1,50 @@
+import type { ICoverLockConfig, ICoverLockRegistry } from './ICoverLockConfig';
+/**
+ * TTL-based reservation system for cover points.
+ *
+ * Locks are stored per point-ID in `Map<string, PointEntry>`.
+ * Expired entries are pruned lazily (inline on tryLock/isAvailable) and
+ * periodically via auto-purge at `autoPurgeInterval` cadence.
+ *
+ * Memory at scale: 200 NPCs × 1 lock each ≈ 200 Map entries, ~20KB.
+ *
+ * @example
+ * ```ts
+ * const locks = new CoverLockRegistry(() => Date.now());
+ *
+ * // In TakeCoverState.enter():
+ * const ok = locks.tryLock('cover_0012', npcId);
+ *
+ * // In TakeCoverState.exit():
+ * locks.unlockAll(npcId);
+ * ```
+ */
+export declare class CoverLockRegistry implements ICoverLockRegistry {
+    private readonly _points;
+    private readonly config;
+    private readonly timeFn;
+    private _checkCounter;
+    /**
+     * @param timeFn - Monotonically non-decreasing time source (returns ms).
+     *                 Must not return negative or wildly non-monotonic values.
+     * @param config - Optional config overrides (TTL, capacity, auto-purge rate).
+     */
+    constructor(timeFn: () => number, config?: Partial<ICoverLockConfig>);
+    tryLock(pointId: string, npcId: string, options?: {
+        ttlMs?: number;
+        capacity?: number;
+    }): boolean;
+    unlock(pointId: string, npcId: string): void;
+    unlockAll(npcId: string): void;
+    isAvailable(pointId: string, npcId: string): boolean;
+    purgeExpired(): number;
+    clear(): void;
+    /**
+     * Approximate count of points with at least one lock entry.
+     * May include points whose locks have all expired but not yet been purged.
+     * Call `purgeExpired()` first for an exact count.
+     */
+    get lockedPointCount(): number;
+    private _maybeAutoPurge;
+}
+//# sourceMappingURL=CoverLockRegistry.d.ts.map

package/dist/cover/CoverLockRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoverLockRegistry.d.ts","sourceRoot":"","sources":["../../src/cover/CoverLockRegistry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AA4B/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,aAAa,CAAK;IAE1B;;;;OAIG;gBACS,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IASpE,OAAO,CACL,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9C,OAAO;IAkDV,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAU5C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAc9B,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAkBpD,YAAY,IAAI,MAAM;IAoBtB,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAMD,OAAO,CAAC,eAAe;CAOxB"}

package/dist/cover/CoverLockRegistry.js

@@ -0,0 +1,164 @@
+// cover/CoverLockRegistry.ts
+// TTL-based cover point reservation system.
+import { createDefaultCoverLockConfig } from './ICoverLockConfig';
+// ---------------------------------------------------------------------------
+// CoverLockRegistry
+// ---------------------------------------------------------------------------
+/**
+ * TTL-based reservation system for cover points.
+ *
+ * Locks are stored per point-ID in `Map<string, PointEntry>`.
+ * Expired entries are pruned lazily (inline on tryLock/isAvailable) and
+ * periodically via auto-purge at `autoPurgeInterval` cadence.
+ *
+ * Memory at scale: 200 NPCs × 1 lock each ≈ 200 Map entries, ~20KB.
+ *
+ * @example
+ * ```ts
+ * const locks = new CoverLockRegistry(() => Date.now());
+ *
+ * // In TakeCoverState.enter():
+ * const ok = locks.tryLock('cover_0012', npcId);
+ *
+ * // In TakeCoverState.exit():
+ * locks.unlockAll(npcId);
+ * ```
+ */
+export class CoverLockRegistry {
+    /**
+     * @param timeFn - Monotonically non-decreasing time source (returns ms).
+     *                 Must not return negative or wildly non-monotonic values.
+     * @param config - Optional config overrides (TTL, capacity, auto-purge rate).
+     */
+    constructor(timeFn, config) {
+        this._points = new Map();
+        this._checkCounter = 0;
+        this.timeFn = timeFn;
+        this.config = createDefaultCoverLockConfig(config);
+    }
+    // -------------------------------------------------------------------------
+    // ICoverLockRegistry
+    // -------------------------------------------------------------------------
+    tryLock(pointId, npcId, options) {
+        this._maybeAutoPurge();
+        const now = this.timeFn();
+        const ttl = options?.ttlMs ?? this.config.defaultTtlMs;
+        const capacity = options?.capacity ?? this.config.defaultCapacity;
+        const expiresAt = now + ttl;
+        const entry = this._points.get(pointId);
+        if (entry === undefined) {
+            this._points.set(pointId, { capacity, locks: [{ npcId, expiresAt }] });
+            return true;
+        }
+        // Promote capacity if this call requests higher capacity for this point.
+        if (capacity > entry.capacity) {
+            entry.capacity = capacity;
+        }
+        // Prune expired entries inline (arrays are typically size 1-3).
+        let activeCount = 0;
+        let ownIdx = -1;
+        for (let i = 0; i < entry.locks.length; i++) {
+            const lock = entry.locks[i];
+            if (lock.expiresAt <= now)
+                continue; // expired
+            if (lock.npcId === npcId) {
+                ownIdx = i;
+            }
+            else {
+                activeCount++;
+            }
+        }
+        if (ownIdx !== -1) {
+            // Refresh TTL for the NPC's existing lock.
+            entry.locks[ownIdx].expiresAt = expiresAt;
+            // Compact out expired entries.
+            entry.locks = entry.locks.filter((l) => l.expiresAt > now);
+            return true;
+        }
+        if (activeCount >= entry.capacity) {
+            entry.locks = entry.locks.filter((l) => l.expiresAt > now);
+            return false;
+        }
+        // Compact + add new lock.
+        entry.locks = entry.locks.filter((l) => l.expiresAt > now);
+        entry.locks.push({ npcId, expiresAt });
+        return true;
+    }
+    unlock(pointId, npcId) {
+        const entry = this._points.get(pointId);
+        if (entry === undefined)
+            return;
+        entry.locks = entry.locks.filter((l) => l.npcId !== npcId);
+        if (entry.locks.length === 0) {
+            this._points.delete(pointId);
+        }
+    }
+    unlockAll(npcId) {
+        // Collect points to delete after iteration to avoid mutation-during-iteration.
+        const toDelete = [];
+        for (const [pointId, entry] of this._points) {
+            entry.locks = entry.locks.filter((l) => l.npcId !== npcId);
+            if (entry.locks.length === 0) {
+                toDelete.push(pointId);
+            }
+        }
+        for (const id of toDelete)
+            this._points.delete(id);
+    }
+    isAvailable(pointId, npcId) {
+        this._maybeAutoPurge();
+        const entry = this._points.get(pointId);
+        if (entry === undefined)
+            return true;
+        const now = this.timeFn();
+        let activeCount = 0;
+        for (const lock of entry.locks) {
+            if (lock.expiresAt <= now)
+                continue;
+            if (lock.npcId === npcId)
+                return true; // own lock — always available
+            activeCount++;
+        }
+        return activeCount < entry.capacity;
+    }
+    purgeExpired() {
+        const now = this.timeFn();
+        let purged = 0;
+        const toDelete = [];
+        for (const [pointId, entry] of this._points) {
+            const before = entry.locks.length;
+            entry.locks = entry.locks.filter((l) => l.expiresAt > now);
+            purged += before - entry.locks.length;
+            if (entry.locks.length === 0) {
+                toDelete.push(pointId);
+            }
+        }
+        for (const id of toDelete)
+            this._points.delete(id);
+        return purged;
+    }
+    clear() {
+        this._points.clear();
+        this._checkCounter = 0;
+    }
+    /**
+     * Approximate count of points with at least one lock entry.
+     * May include points whose locks have all expired but not yet been purged.
+     * Call `purgeExpired()` first for an exact count.
+     */
+    get lockedPointCount() {
+        return this._points.size;
+    }
+    // -------------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------------
+    _maybeAutoPurge() {
+        if (this.config.autoPurgeInterval <= 0)
+            return;
+        if (++this._checkCounter >= this.config.autoPurgeInterval) {
+            this._checkCounter = 0;
+            this.purgeExpired();
+        }
+    }
+}
+//# sourceMappingURL=CoverLockRegistry.js.map

package/dist/cover/CoverLockRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoverLockRegistry.js","sourceRoot":"","sources":["../../src/cover/CoverLockRegistry.ts"],"names":[],"mappings":"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"}

package/dist/cover/CoverRecommender.d.ts

@@ -0,0 +1,32 @@
+import { CoverType } from '../types/ICoverPoint';
+import type { ICoverConfig } from '../types/IOnlineAIConfig';
+/**
+ * Tactical context for cover type recommendation.
+ */
+export interface ICoverSituation {
+    /** Current HP / max HP in range [0, 1]. */
+    readonly hpRatio: number;
+    /** Current morale in range [-1, 1]. */
+    readonly morale: number;
+    /** Number of known active enemies. */
+    readonly enemyCount: number;
+    /** Whether the NPC has usable ammunition. */
+    readonly hasAmmo: boolean;
+}
+/**
+ * Recommend the best CoverType for a given tactical situation.
+ *
+ * Decision tree (priority order):
+ *   1. No ammo → SAFE (no point being offensive).
+ *   2. Critical HP → CLOSE (need cover NOW, closest available).
+ *   3. Demoralized → FAR (distance = psychological safety).
+ *   4. Outnumbered → SAFE (minimize exposure to multiple threats).
+ *   5. Healthy + few enemies → AMBUSH (take offensive position).
+ *   6. Default → BALANCED (balanced approach).
+ *
+ * @param situation - Tactical context describing the NPC's state.
+ * @param config - Cover configuration for threshold values.
+ * @returns The recommended CoverType.
+ */
+export declare function recommendCoverType(situation: ICoverSituation, config: ICoverConfig): CoverType;
+//# sourceMappingURL=CoverRecommender.d.ts.map