@alife-sdk/ai 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"CoverRecommender.d.ts","sourceRoot":"","sources":["../../src/cover/CoverRecommender.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,YAAY,GACnB,SAAS,CA8BX"}

package/dist/cover/CoverRecommender.js

@@ -0,0 +1,45 @@
+// cover/CoverRecommender.ts
+// Pure decision function: tactical situation → recommended CoverType.
+// No side effects, no state — ideal for unit testing.
+import { CoverType } from '../types/ICoverPoint';
+/**
+ * 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 function recommendCoverType(situation, config) {
+    const { hpRatio, morale, enemyCount, hasAmmo } = situation;
+    // No ammo: can't fight, maximize safety.
+    if (!hasAmmo) {
+        return CoverType.SAFE;
+    }
+    // Critical HP: get behind something immediately.
+    if (hpRatio <= config.recommendHpCritical) {
+        return CoverType.CLOSE;
+    }
+    // Demoralized: prefer distance for psychological recovery.
+    if (morale <= config.recommendMoraleDemoralized) {
+        return CoverType.FAR;
+    }
+    // Outnumbered: minimize aggregate threat.
+    if (enemyCount >= config.recommendOutnumberedCount) {
+        return CoverType.SAFE;
+    }
+    // Healthy and few enemies: take the initiative.
+    if (hpRatio >= config.recommendHpHealthy && enemyCount <= 2) {
+        return CoverType.AMBUSH;
+    }
+    // Default: balanced approach.
+    return CoverType.BALANCED;
+}
+//# sourceMappingURL=CoverRecommender.js.map

package/dist/cover/CoverRecommender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoverRecommender.js","sourceRoot":"","sources":["../../src/cover/CoverRecommender.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,sEAAsE;AACtE,sDAAsD;AAEtD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAiBjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAA0B,EAC1B,MAAoB;IAEpB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;IAE3D,yCAAyC;IACzC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,SAAS,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,iDAAiD;IACjD,IAAI,OAAO,IAAI,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC1C,OAAO,SAAS,CAAC,KAAK,CAAC;IACzB,CAAC;IAED,2DAA2D;IAC3D,IAAI,MAAM,IAAI,MAAM,CAAC,0BAA0B,EAAE,CAAC;QAChD,OAAO,SAAS,CAAC,GAAG,CAAC;IACvB,CAAC;IAED,0CAA0C;IAC1C,IAAI,UAAU,IAAI,MAAM,CAAC,yBAAyB,EAAE,CAAC;QACnD,OAAO,SAAS,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,gDAAgD;IAChD,IAAI,OAAO,IAAI,MAAM,CAAC,kBAAkB,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QAC5D,OAAO,SAAS,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED,8BAA8B;IAC9B,OAAO,SAAS,CAAC,QAAQ,CAAC;AAC5B,CAAC"}

package/dist/cover/CoverRegistry.d.ts

@@ -0,0 +1,97 @@
+import type { Vec2, IRandom } from '@alife-sdk/core';
+import type { ICoverPoint, ILoophole } from '../types/ICoverPoint';
+import { CoverType } from '../types/ICoverPoint';
+import type { ICoverConfig } from '../types/IOnlineAIConfig';
+import { type ICoverSituation } from './CoverRecommender';
+import type { ICoverLockRegistry } from './ICoverLockConfig';
+/**
+ * Manages a collection of cover points in world space.
+ *
+ * Responsibilities:
+ *   - Point registration and removal.
+ *   - Occupancy tracking (one NPC per point).
+ *   - Cover search using pluggable evaluator strategies.
+ *   - Loophole generation and best-loophole queries.
+ *
+ * This is an instance-based class (not a singleton). Create one per
+ * simulation or per scene. Inject via the AI plugin system.
+ *
+ * @example
+ * ```ts
+ * const registry = new CoverRegistry(config.cover, random);
+ * registry.addPoints([{ x: 100, y: 200 }, { x: 300, y: 400 }]);
+ *
+ * const cover = registry.findCover(CoverType.BALANCED, npcPos, enemies, npcId);
+ * if (cover) registry.occupy(cover.id, npcId);
+ * ```
+ */
+export declare class CoverRegistry {
+    private readonly points;
+    private readonly evaluators;
+    private readonly loopholeGen;
+    private readonly config;
+    private readonly lockRegistry;
+    private idCounter;
+    private _allPointsCache;
+    private _allPointsDirty;
+    /**
+     * @param config       - Cover evaluator configuration.
+     * @param random       - Deterministic random source.
+     * @param lockRegistry - Optional TTL-based lock registry.
+     *                       When provided, `findCover` filters out points locked
+     *                       by other NPCs instead of relying on the mutable
+     *                       `occupiedBy` field. The legacy `occupy`/`release`
+     *                       methods remain operational for backward compatibility.
+     */
+    constructor(config: ICoverConfig, random: IRandom, lockRegistry?: ICoverLockRegistry);
+    /**
+     * Add a single cover point. Returns the created point with a generated ID.
+     */
+    addPoint(x: number, y: number, radius?: number): ICoverPoint;
+    /**
+     * Bulk-register cover points from coordinate data.
+     */
+    addPoints(data: readonly {
+        x: number;
+        y: number;
+        radius?: number;
+    }[]): void;
+    /**
+     * Remove a cover point by ID. Releases any occupancy.
+     */
+    removePoint(pointId: string): boolean;
+    /** Total number of registered cover points. */
+    getSize(): number;
+    /** Iterate all points (read-only). */
+    getAll(): readonly ICoverPoint[];
+    /**
+     * Find the best available cover point using the specified evaluator.
+     *
+     * Filters: unoccupied (or occupied by same NPC), within search radius,
+     * score above minimum threshold. Returns null if nothing qualifies.
+     */
+    findCover(type: CoverType, npcPosition: Vec2, enemies: readonly Vec2[], npcId: string, maxRadius?: number): ICoverPoint | null;
+    /**
+     * Recommend cover type then find cover in one call.
+     * Convenience method that combines CoverRecommender + findCover.
+     */
+    findRecommendedCover(situation: ICoverSituation, npcPosition: Vec2, enemies: readonly Vec2[], npcId: string): ICoverPoint | null;
+    /**
+     * Check whether a position falls inside any cover point's protection radius.
+     * Returns the closest matching point, or null.
+     */
+    isInCover(position: Vec2): ICoverPoint | null;
+    /** Mark a cover point as occupied. */
+    occupy(pointId: string, npcId: string): void;
+    /** Release a cover point. If npcId given, only release if that NPC holds it. */
+    release(pointId: string, npcId?: string): void;
+    /** Release all points held by a specific NPC (e.g. on death). */
+    releaseAll(npcId: string): void;
+    /** Get loopholes for a cover point (generated lazily). */
+    getLoopholes(cover: ICoverPoint): readonly ILoophole[];
+    /** Find the best loophole for engaging an enemy from this cover. */
+    findBestLoophole(cover: ICoverPoint, enemyX: number, enemyY: number): ILoophole | null;
+    /** Clear all points, caches, and cover locks. Call on scene teardown. */
+    clear(): void;
+}
+//# sourceMappingURL=CoverRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CoverRegistry.d.ts","sourceRoot":"","sources":["../../src/cover/CoverRegistry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAqB,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0C;IACrE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;IACzD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,eAAe,CAAQ;IAE/B;;;;;;;;OAQG;gBACS,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,kBAAkB;IAWpF;;OAEG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW;IAe5D;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,SAAS;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI;IAM3E;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAMrC,+CAA+C;IAC/C,OAAO,IAAI,MAAM;IAIjB,sCAAsC;IACtC,MAAM,IAAI,SAAS,WAAW,EAAE;IAahC;;;;;OAKG;IACH,SAAS,CACP,IAAI,EAAE,SAAS,EACf,WAAW,EAAE,IAAI,EACjB,OAAO,EAAE,SAAS,IAAI,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,GAAG,IAAI;IAsCrB;;;OAGG;IACH,oBAAoB,CAClB,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,IAAI,EACjB,OAAO,EAAE,SAAS,IAAI,EAAE,EACxB,KAAK,EAAE,MAAM,GACZ,WAAW,GAAG,IAAI;IASrB;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,IAAI,GAAG,WAAW,GAAG,IAAI;IAqB7C,sCAAsC;IACtC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK5C,gFAAgF;IAChF,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ9C,iEAAiE;IACjE,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY/B,0DAA0D;IAC1D,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,SAAS,EAAE;IAItD,oEAAoE;IACpE,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAStF,yEAAyE;IACzE,KAAK,IAAI,IAAI;CAQd"}

package/dist/cover/CoverRegistry.js

@@ -0,0 +1,223 @@
+// cover/CoverRegistry.ts
+// Instance-based cover point registry with occupancy tracking.
+// Replaces the singleton CoverSystem from the game layer.
+import { distanceSq } from '@alife-sdk/core';
+import { createCoverEvaluators } from './CoverEvaluators';
+import { recommendCoverType } from './CoverRecommender';
+import { LoopholeGenerator, findBestLoophole } from './LoopholeGenerator';
+/**
+ * Manages a collection of cover points in world space.
+ *
+ * Responsibilities:
+ *   - Point registration and removal.
+ *   - Occupancy tracking (one NPC per point).
+ *   - Cover search using pluggable evaluator strategies.
+ *   - Loophole generation and best-loophole queries.
+ *
+ * This is an instance-based class (not a singleton). Create one per
+ * simulation or per scene. Inject via the AI plugin system.
+ *
+ * @example
+ * ```ts
+ * const registry = new CoverRegistry(config.cover, random);
+ * registry.addPoints([{ x: 100, y: 200 }, { x: 300, y: 400 }]);
+ *
+ * const cover = registry.findCover(CoverType.BALANCED, npcPos, enemies, npcId);
+ * if (cover) registry.occupy(cover.id, npcId);
+ * ```
+ */
+export class CoverRegistry {
+    /**
+     * @param config       - Cover evaluator configuration.
+     * @param random       - Deterministic random source.
+     * @param lockRegistry - Optional TTL-based lock registry.
+     *                       When provided, `findCover` filters out points locked
+     *                       by other NPCs instead of relying on the mutable
+     *                       `occupiedBy` field. The legacy `occupy`/`release`
+     *                       methods remain operational for backward compatibility.
+     */
+    constructor(config, random, lockRegistry) {
+        this.points = new Map();
+        this.idCounter = 0;
+        this._allPointsCache = [];
+        this._allPointsDirty = true;
+        this.config = config;
+        this.evaluators = createCoverEvaluators(config);
+        this.loopholeGen = new LoopholeGenerator(config, random);
+        this.lockRegistry = lockRegistry ?? null;
+    }
+    // -----------------------------------------------------------------
+    // Registration
+    // -----------------------------------------------------------------
+    /**
+     * Add a single cover point. Returns the created point with a generated ID.
+     */
+    addPoint(x, y, radius) {
+        const id = `cover_${String(this.idCounter++).padStart(4, '0')}`;
+        const point = {
+            id,
+            x,
+            y,
+            radius: radius ?? this.config.pointRadius,
+            occupiedBy: null,
+            loopholes: [],
+        };
+        this.points.set(id, point);
+        this._allPointsDirty = true;
+        return point;
+    }
+    /**
+     * Bulk-register cover points from coordinate data.
+     */
+    addPoints(data) {
+        for (const p of data) {
+            this.addPoint(p.x, p.y, p.radius);
+        }
+    }
+    /**
+     * Remove a cover point by ID. Releases any occupancy.
+     */
+    removePoint(pointId) {
+        const result = this.points.delete(pointId);
+        if (result)
+            this._allPointsDirty = true;
+        return result;
+    }
+    /** Total number of registered cover points. */
+    getSize() {
+        return this.points.size;
+    }
+    /** Iterate all points (read-only). */
+    getAll() {
+        if (this._allPointsDirty) {
+            this._allPointsCache.length = 0;
+            for (const p of this.points.values())
+                this._allPointsCache.push(p);
+            this._allPointsDirty = false;
+        }
+        return this._allPointsCache;
+    }
+    // -----------------------------------------------------------------
+    // Cover Search
+    // -----------------------------------------------------------------
+    /**
+     * Find the best available cover point using the specified evaluator.
+     *
+     * Filters: unoccupied (or occupied by same NPC), within search radius,
+     * score above minimum threshold. Returns null if nothing qualifies.
+     */
+    findCover(type, npcPosition, enemies, npcId, maxRadius) {
+        const evaluator = this.evaluators.get(type);
+        if (!evaluator)
+            return null;
+        const radius = maxRadius ?? this.config.searchRadius;
+        const maxRadiusSq = radius * radius;
+        const context = {
+            npcPosition,
+            enemies,
+            maxRadiusSq,
+        };
+        let bestPoint = null;
+        let bestScore = this.config.minScoreThreshold;
+        for (const point of this.points.values()) {
+            // Skip locked / occupied points.
+            if (this.lockRegistry !== null) {
+                if (!this.lockRegistry.isAvailable(point.id, npcId))
+                    continue;
+            }
+            else if (point.occupiedBy !== null && point.occupiedBy !== npcId) {
+                continue;
+            }
+            // Squared distance pre-filter.
+            const dSq = distanceSq(npcPosition, point);
+            if (dSq > maxRadiusSq)
+                continue;
+            const score = evaluator.evaluate(point, context);
+            if (score > bestScore) {
+                bestScore = score;
+                bestPoint = point;
+            }
+        }
+        return bestPoint;
+    }
+    /**
+     * Recommend cover type then find cover in one call.
+     * Convenience method that combines CoverRecommender + findCover.
+     */
+    findRecommendedCover(situation, npcPosition, enemies, npcId) {
+        const type = recommendCoverType(situation, this.config);
+        return this.findCover(type, npcPosition, enemies, npcId);
+    }
+    // -----------------------------------------------------------------
+    // Spatial Query
+    // -----------------------------------------------------------------
+    /**
+     * Check whether a position falls inside any cover point's protection radius.
+     * Returns the closest matching point, or null.
+     */
+    isInCover(position) {
+        const thresholdSq = this.config.occupyDistance * this.config.occupyDistance;
+        let closest = null;
+        let closestDSq = Infinity;
+        for (const point of this.points.values()) {
+            const dSq = distanceSq(position, point);
+            const effectiveSq = Math.max(thresholdSq, point.radius * point.radius);
+            if (dSq <= effectiveSq && dSq < closestDSq) {
+                closestDSq = dSq;
+                closest = point;
+            }
+        }
+        return closest;
+    }
+    // -----------------------------------------------------------------
+    // Occupancy
+    // -----------------------------------------------------------------
+    /** Mark a cover point as occupied. */
+    occupy(pointId, npcId) {
+        const point = this.points.get(pointId);
+        if (point)
+            point.occupiedBy = npcId;
+    }
+    /** Release a cover point. If npcId given, only release if that NPC holds it. */
+    release(pointId, npcId) {
+        const point = this.points.get(pointId);
+        if (!point)
+            return;
+        if (npcId === undefined || point.occupiedBy === npcId) {
+            point.occupiedBy = null;
+        }
+    }
+    /** Release all points held by a specific NPC (e.g. on death). */
+    releaseAll(npcId) {
+        for (const point of this.points.values()) {
+            if (point.occupiedBy === npcId) {
+                point.occupiedBy = null;
+            }
+        }
+    }
+    // -----------------------------------------------------------------
+    // Loopholes
+    // -----------------------------------------------------------------
+    /** Get loopholes for a cover point (generated lazily). */
+    getLoopholes(cover) {
+        return this.loopholeGen.getLoopholes(cover);
+    }
+    /** Find the best loophole for engaging an enemy from this cover. */
+    findBestLoophole(cover, enemyX, enemyY) {
+        const loopholes = this.getLoopholes(cover);
+        return findBestLoophole(loopholes, cover.x, cover.y, enemyX, enemyY);
+    }
+    // -----------------------------------------------------------------
+    // Lifecycle
+    // -----------------------------------------------------------------
+    /** Clear all points, caches, and cover locks. Call on scene teardown. */
+    clear() {
+        this.points.clear();
+        this.idCounter = 0;
+        this._allPointsCache.length = 0;
+        this._allPointsDirty = true;
+        this.loopholeGen.clearCache();
+        this.lockRegistry?.clear();
+    }
+}
+//# sourceMappingURL=CoverRegistry.js.map

package/dist/cover/CoverRegistry.js.map

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

package/dist/cover/ICoverEvaluator.d.ts

@@ -0,0 +1,15 @@
+import type { ICoverPoint, ICoverEvalContext } from '../types/ICoverPoint';
+/**
+ * Strategy interface for scoring a cover point.
+ *
+ * Each evaluator optimizes for a different tactical priority (proximity,
+ * safety, flanking, etc.). Evaluators are stateless pure functions —
+ * they read the cover point and context, return a normalized score.
+ *
+ * @returns Score in range [0, 1] where 1 is the best possible cover.
+ */
+export interface ICoverEvaluator {
+    readonly type: string;
+    evaluate(point: ICoverPoint, context: ICoverEvalContext): number;
+}
+//# sourceMappingURL=ICoverEvaluator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ICoverEvaluator.d.ts","sourceRoot":"","sources":["../../src/cover/ICoverEvaluator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAAC;CAClE"}

package/dist/cover/ICoverEvaluator.js

@@ -0,0 +1,4 @@
+// cover/ICoverEvaluator.ts
+// Strategy interface for cover point evaluation.
+export {};
+//# sourceMappingURL=ICoverEvaluator.js.map

package/dist/cover/ICoverEvaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ICoverEvaluator.js","sourceRoot":"","sources":["../../src/cover/ICoverEvaluator.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,iDAAiD"}

package/dist/cover/ICoverLockConfig.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Configuration for the CoverLockRegistry.
+ *
+ * All durations are in milliseconds. Capacity values are positive integers.
+ */
+export interface ICoverLockConfig {
+    /**
+     * Default time-to-live for a lock in milliseconds.
+     * After this duration the lock expires and the point becomes available again.
+     * @default 10_000
+     */
+    readonly defaultTtlMs: number;
+    /**
+     * Default maximum number of NPCs that can lock a single cover point.
+     * Individual `tryLock` calls can override this per-point via `options.capacity`.
+     * @default 1
+     */
+    readonly defaultCapacity: number;
+    /**
+     * Auto-purge cadence: run `purgeExpired()` automatically every N `tryLock` /
+     * `isAvailable` calls. Set to 0 to disable auto-purge.
+     * @default 32
+     */
+    readonly autoPurgeInterval: number;
+}
+export declare function createDefaultCoverLockConfig(overrides?: Partial<ICoverLockConfig>): ICoverLockConfig;
+/**
+ * TTL-based reservation system for cover points.
+ *
+ * Prevents multiple NPCs from occupying the same cover point simultaneously.
+ * Locks expire automatically — no manual cleanup on NPC death is required,
+ * though `unlockAll(npcId)` is preferred for immediate availability.
+ *
+ * Cover points are identified by their string ID (`ICoverPoint.id`).
+ * Time is provided by an injected `timeFn` for determinism.
+ */
+export interface ICoverLockRegistry {
+    /**
+     * Attempt to lock a cover point for an NPC.
+     *
+     * - If the NPC already holds a lock on this point, the TTL is refreshed (idempotent).
+     * - Fails (returns false) when the point is at capacity with other NPCs.
+     *
+     * @param pointId  - Cover point ID.
+     * @param npcId    - NPC claiming the lock.
+     * @param options  - Per-call overrides for TTL and capacity.
+     */
+    tryLock(pointId: string, npcId: string, options?: {
+        ttlMs?: number;
+        capacity?: number;
+    }): boolean;
+    /**
+     * Release a specific NPC's lock on a point.
+     * No-op if the NPC does not hold a lock on this point.
+     */
+    unlock(pointId: string, npcId: string): void;
+    /**
+     * Release all locks held by an NPC. Call on NPC death or despawn.
+     * O(n) where n = total active locks across all points.
+     */
+    unlockAll(npcId: string): void;
+    /**
+     * Check whether a point can be locked by the given NPC.
+     *
+     * Returns true when:
+     *   - The NPC already holds a lock on this point, or
+     *   - The point has fewer active locks than its tracked capacity
+     *     (the highest capacity ever passed via `options.capacity` for this
+     *     point, falling back to `defaultCapacity` for unseen points).
+     */
+    isAvailable(pointId: string, npcId: string): boolean;
+    /**
+     * Expire and remove stale lock entries.
+     * Called automatically at `autoPurgeInterval` cadence.
+     * @returns number of lock entries removed.
+     */
+    purgeExpired(): number;
+    /** Remove all lock entries. Call on scene teardown. */
+    clear(): void;
+    /** Number of points that currently have at least one active lock. */
+    readonly lockedPointCount: number;
+}
+//# sourceMappingURL=ICoverLockConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ICoverLockConfig.d.ts","sourceRoot":"","sources":["../../src/cover/ICoverLockConfig.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,wBAAgB,4BAA4B,CAC1C,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACpC,gBAAgB,CAqBlB;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,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,CAAC;IAEX;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAErD;;;;OAIG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;IAEd,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC"}

package/dist/cover/ICoverLockConfig.js

@@ -0,0 +1,21 @@
+// cover/ICoverLockConfig.ts
+// Configuration and public interface for the TTL-based cover lock subsystem.
+export function createDefaultCoverLockConfig(overrides) {
+    const cfg = {
+        defaultTtlMs: 10000,
+        defaultCapacity: 1,
+        autoPurgeInterval: 32,
+        ...overrides,
+    };
+    if (cfg.defaultTtlMs <= 0) {
+        throw new RangeError(`ICoverLockConfig.defaultTtlMs must be > 0, got ${cfg.defaultTtlMs}`);
+    }
+    if (!Number.isInteger(cfg.defaultCapacity) || cfg.defaultCapacity < 1) {
+        throw new RangeError(`ICoverLockConfig.defaultCapacity must be a positive integer, got ${cfg.defaultCapacity}`);
+    }
+    if (!Number.isInteger(cfg.autoPurgeInterval) || cfg.autoPurgeInterval < 0) {
+        throw new RangeError(`ICoverLockConfig.autoPurgeInterval must be a non-negative integer, got ${cfg.autoPurgeInterval}`);
+    }
+    return cfg;
+}
+//# sourceMappingURL=ICoverLockConfig.js.map

package/dist/cover/ICoverLockConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ICoverLockConfig.js","sourceRoot":"","sources":["../../src/cover/ICoverLockConfig.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,6EAA6E;AAkC7E,MAAM,UAAU,4BAA4B,CAC1C,SAAqC;IAErC,MAAM,GAAG,GAAqB;QAC5B,YAAY,EAAE,KAAM;QACpB,eAAe,EAAE,CAAC;QAClB,iBAAiB,EAAE,EAAE;QACrB,GAAG,SAAS;KACb,CAAC;IACF,IAAI,GAAG,CAAC,YAAY,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,UAAU,CAAC,kDAAkD,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,eAAe,GAAG,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,UAAU,CAClB,oEAAoE,GAAG,CAAC,eAAe,EAAE,CAC1F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,iBAAiB,GAAG,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,UAAU,CAClB,0EAA0E,GAAG,CAAC,iBAAiB,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cover/LoopholeGenerator.d.ts

@@ -0,0 +1,44 @@
+import type { ICoverPoint, ILoophole } from '../types/ICoverPoint';
+import type { ICoverConfig } from '../types/IOnlineAIConfig';
+import type { IRandom } from '@alife-sdk/core';
+/**
+ * Generates and caches loophole positions for cover points.
+ *
+ * Loopholes are evenly distributed around the cover center at a fixed
+ * offset distance, each with a firing arc of configurable width.
+ * A seeded random source ensures deterministic generation.
+ */
+export declare class LoopholeGenerator {
+    private readonly cache;
+    private readonly offsetDistance;
+    private readonly fireArc;
+    private readonly maxPerCover;
+    private readonly random;
+    constructor(config: ICoverConfig, random: IRandom);
+    /**
+     * Get loopholes for a cover point, generating them on first access.
+     * Results are cached by cover point ID for the lifetime of this generator.
+     */
+    getLoopholes(cover: ICoverPoint): readonly ILoophole[];
+    /** Clear the generation cache. Call on scene reset. */
+    clearCache(): void;
+    /**
+     * Generate loopholes for a single cover point.
+     *
+     * Count is randomized in [1, maxPerCover]. Loopholes are distributed
+     * evenly around the cover center with angular jitter for natural feel.
+     */
+    private generate;
+}
+/**
+ * Find the loophole whose firing arc best covers the angle to an enemy.
+ *
+ * @param loopholes - Available loopholes on the cover point.
+ * @param coverX - Cover point world X.
+ * @param coverY - Cover point world Y.
+ * @param enemyX - Enemy world X.
+ * @param enemyY - Enemy world Y.
+ * @returns The best matching loophole, or null if none covers the angle.
+ */
+export declare function findBestLoophole(loopholes: readonly ILoophole[], coverX: number, coverY: number, enemyX: number, enemyY: number): ILoophole | null;
+//# sourceMappingURL=LoopholeGenerator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LoopholeGenerator.d.ts","sourceRoot":"","sources":["../../src/cover/LoopholeGenerator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2C;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAErB,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO;IAOjD;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,SAAS,EAAE;IAStD,uDAAuD;IACvD,UAAU,IAAI,IAAI;IAIlB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;CA0BjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,SAAS,EAAE,EAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,SAAS,GAAG,IAAI,CA0BlB"}