@alife-sdk/ai 0.1.0

package/dist/navigation/SteeringBehaviors.js

@@ -0,0 +1,211 @@
+// navigation/SteeringBehaviors.ts
+// Pure functions for Craig Reynolds-style flocking / pack movement.
+//
+// Design principles:
+//   • All functions are pure (no side effects, no ctx dependency).
+//   • All accept and return Vec2 — no mutable state.
+//   • combineForces() is the extensibility escape-hatch for custom force composition.
+//   • Nothing is hardcoded — every threshold lives in ISteeringConfig.
+import { ZERO, normalize, magnitude, subtract } from '@alife-sdk/core';
+/**
+ * Create an {@link ISteeringConfig} with production defaults.
+ * Pass a partial override object to tune individual values without touching the rest.
+ *
+ * @example
+ * const cfg = createDefaultSteeringConfig({ separationRadius: 60 });
+ */
+export function createDefaultSteeringConfig(overrides) {
+    return {
+        separationRadius: 40,
+        separationWeight: 1.5,
+        neighborRadius: 150,
+        cohesionWeight: 0.5,
+        alignmentWeight: 0.3,
+        maxSteeringForce: 80,
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// Primitive steering forces
+// ---------------------------------------------------------------------------
+/**
+ * Compute the separation steering force — repulsion away from any neighbor
+ * that is closer than {@link ISteeringConfig.separationRadius}.
+ *
+ * The force is inversely proportional to distance: the closer the neighbor,
+ * the stronger the push.  Neighbors outside the radius are ignored.
+ * Returns {@link ZERO} when `neighbors` is empty or none are within radius.
+ *
+ * @param self      - Position of the NPC computing the force.
+ * @param neighbors - Positions of nearby agents (e.g. from getVisibleAllies()).
+ * @param config    - Steering configuration.
+ */
+export function separation(self, neighbors, config) {
+    let fx = 0;
+    let fy = 0;
+    const rSq = config.separationRadius * config.separationRadius;
+    for (const n of neighbors) {
+        const dx = self.x - n.x;
+        const dy = self.y - n.y;
+        const distSq = dx * dx + dy * dy;
+        // Compare squared first to avoid sqrt for out-of-range neighbors.
+        if (distSq === 0 || distSq >= rSq)
+            continue;
+        const dist = Math.sqrt(distSq);
+        // Inverse-distance weighting: closer → stronger push
+        const strength = 1 - dist / config.separationRadius;
+        fx += (dx / dist) * strength;
+        fy += (dy / dist) * strength;
+    }
+    if (fx === 0 && fy === 0)
+        return ZERO;
+    return normalize({ x: fx, y: fy });
+}
+/**
+ * Compute the cohesion steering force — attraction toward the average position
+ * (center of mass) of neighbors within {@link ISteeringConfig.neighborRadius}.
+ *
+ * Returns {@link ZERO} when `neighbors` is empty or none are within the radius.
+ *
+ * @param self      - Position of the NPC computing the force.
+ * @param neighbors - Positions of nearby agents.
+ * @param config    - Steering configuration.
+ */
+export function cohesion(self, neighbors, config) {
+    let cx = 0;
+    let cy = 0;
+    let count = 0;
+    const rSq = config.neighborRadius * config.neighborRadius;
+    for (const n of neighbors) {
+        const dx = n.x - self.x;
+        const dy = n.y - self.y;
+        if (dx * dx + dy * dy > rSq)
+            continue;
+        cx += n.x;
+        cy += n.y;
+        count++;
+    }
+    if (count === 0)
+        return ZERO;
+    const center = { x: cx / count, y: cy / count };
+    const toCenter = subtract(center, self);
+    const mag = magnitude(toCenter);
+    return mag < 0.001 ? ZERO : normalize(toCenter);
+}
+/**
+ * Compute the alignment steering force — the average of all provided desired
+ * directions (normalized).
+ *
+ * **API note:** `self` is intentionally absent — alignment depends only on
+ * neighbor directions, not on the caller's own position.  The caller is
+ * responsible for computing `neighborDirections`
+ * (e.g. `normalize(target − npcPos)` for each neighbor's target vector).
+ *
+ * The `alignmentWeight` from config is applied by the caller via
+ * {@link combineForces}, consistent with how separation / cohesion weights work.
+ *
+ * Returns {@link ZERO} when `neighborDirections` is empty.
+ *
+ * @param neighborDirections - Desired movement directions of nearby agents.
+ */
+export function alignment(neighborDirections) {
+    if (neighborDirections.length === 0)
+        return ZERO;
+    let ax = 0;
+    let ay = 0;
+    for (const d of neighborDirections) {
+        ax += d.x;
+        ay += d.y;
+    }
+    const avg = { x: ax / neighborDirections.length, y: ay / neighborDirections.length };
+    const mag = magnitude(avg);
+    return mag < 0.001 ? ZERO : normalize(avg);
+}
+/**
+ * Compute a weighted sum of arbitrary steering forces, clamped to `maxMagnitude`.
+ *
+ * This is the **extensibility escape-hatch**: SDK users can compose any mix of
+ * built-in forces (separation, cohesion, alignment) with their own custom forces
+ * without modifying the SDK.
+ *
+ * @example
+ * const combined = combineForces([
+ *   { force: sep,         weight: cfg.separationWeight },
+ *   { force: coh,         weight: cfg.cohesionWeight   },
+ *   { force: myFormation, weight: 2.0                  },
+ * ], cfg.maxSteeringForce);
+ *
+ * @param forces       - Array of `{ force, weight }` entries to blend.
+ * @param maxMagnitude - Maximum allowed magnitude of the result (px/s).
+ */
+export function combineForces(forces, maxMagnitude) {
+    let fx = 0;
+    let fy = 0;
+    for (const { force, weight } of forces) {
+        fx += force.x * weight;
+        fy += force.y * weight;
+    }
+    if (fx === 0 && fy === 0)
+        return ZERO;
+    const mag = Math.sqrt(fx * fx + fy * fy);
+    if (mag <= maxMagnitude)
+        return { x: fx, y: fy };
+    const ratio = maxMagnitude / mag;
+    return { x: fx * ratio, y: fy * ratio };
+}
+// ---------------------------------------------------------------------------
+// Convenience combinations
+// ---------------------------------------------------------------------------
+/**
+ * Compute the combined separation + cohesion steering force, clamped to
+ * {@link ISteeringConfig.maxSteeringForce}.
+ *
+ * Does **not** include alignment — alignment requires caller-supplied desired
+ * directions (see {@link alignment}).  Use {@link combineForces} to add it.
+ *
+ * Returns {@link ZERO} when `neighbors` is empty.
+ *
+ * @param self      - Position of the NPC.
+ * @param neighbors - Positions of nearby agents.
+ * @param config    - Steering configuration.
+ */
+export function computePackSteering(self, neighbors, config) {
+    if (neighbors.length === 0)
+        return ZERO;
+    const sep = separation(self, neighbors, config);
+    const coh = cohesion(self, neighbors, config);
+    return combineForces([
+        { force: sep, weight: config.separationWeight },
+        { force: coh, weight: config.cohesionWeight },
+    ], config.maxSteeringForce);
+}
+/**
+ * Blend a normalised primary movement direction with a computed steering force.
+ *
+ * Returns `{ vx, vy }` ready for `ctx.setVelocity()` — consistent with the
+ * positional-tuple style used by `moveToward` / `awayFrom` in `_utils.ts`.
+ *
+ * The result is re-normalised to `speed` so the final magnitude is always
+ * consistent regardless of the blend ratio.
+ *
+ * @param primaryVx    - Normalised X component of the desired direction (toward target, etc.).
+ * @param primaryVy    - Normalised Y component of the desired direction.
+ * @param steeringForce - Steering correction force (e.g. from computePackSteering).
+ * @param speed         - Base movement speed (px/s).
+ * @param weight        - Blend weight: 0 = pure primary × speed, 1 = pure steering.
+ */
+export function blendWithPrimary(primaryVx, primaryVy, steeringForce, speed, weight) {
+    // Normalise steering to a unit direction so `weight` controls directional split
+    // independently of the force magnitude (0..maxSteeringForce).
+    const smag = Math.sqrt(steeringForce.x * steeringForce.x + steeringForce.y * steeringForce.y);
+    const sdx = smag < 0.001 ? primaryVx : steeringForce.x / smag;
+    const sdy = smag < 0.001 ? primaryVy : steeringForce.y / smag;
+    // Blend normalised directions. primaryVx/Vy are expected to be normalised by the caller.
+    const rx = primaryVx * (1 - weight) + sdx * weight;
+    const ry = primaryVy * (1 - weight) + sdy * weight;
+    const mag = Math.sqrt(rx * rx + ry * ry);
+    if (mag < 0.001)
+        return { vx: 0, vy: 0 };
+    return { vx: (rx / mag) * speed, vy: (ry / mag) * speed };
+}
+//# sourceMappingURL=SteeringBehaviors.js.map

package/dist/navigation/SteeringBehaviors.js.map

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

package/dist/navigation/index.d.ts

@@ -0,0 +1,7 @@
+export { smoothPath, smoothPathWithTurning } from './PathSmoother';
+export { SmoothPathFollower } from './SmoothPathFollower';
+export { RestrictedZoneManager, RestrictionType } from './RestrictedZoneManager';
+export type { IRestrictedZone } from './RestrictedZoneManager';
+export { createDefaultSteeringConfig, separation, cohesion, alignment, combineForces, computePackSteering, blendWithPrimary, } from './SteeringBehaviors';
+export type { ISteeringConfig } from './SteeringBehaviors';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACjF,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/navigation/index.js

@@ -0,0 +1,6 @@
+// navigation sub-path barrel
+export { smoothPath, smoothPathWithTurning } from './PathSmoother';
+export { SmoothPathFollower } from './SmoothPathFollower';
+export { RestrictedZoneManager, RestrictionType } from './RestrictedZoneManager';
+export { createDefaultSteeringConfig, separation, cohesion, alignment, combineForces, computePackSteering, blendWithPrimary, } from './SteeringBehaviors';
+//# sourceMappingURL=index.js.map

package/dist/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEjF,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}

package/dist/perception/NPCSensors.d.ts

@@ -0,0 +1,129 @@
+import type { Vec2 } from '@alife-sdk/core';
+import type { SpatialGrid } from '@alife-sdk/core';
+/**
+ * Entity that can both observe and be observed.
+ * Agnostic — callers map their game entities to this interface.
+ */
+export interface IPerceptibleEntity {
+    readonly id: string;
+    readonly position: Vec2;
+    readonly factionId: string;
+    /** Facing direction in radians (0 = right / +X axis). */
+    readonly facingAngle: number;
+    readonly isAlive: boolean;
+    /** Maximum vision distance in world units. */
+    readonly visionRange: number;
+    /** Half-angle of the FOV cone in radians (e.g. Math.PI/3 = 60° half = 120° total). */
+    readonly visionHalfAngle: number;
+    /** Maximum hearing range in world units. */
+    readonly hearingRange: number;
+}
+/** Result of a sensor detection — framework-agnostic. */
+export interface IDetectionEvent {
+    readonly observerId: string;
+    readonly targetId: string;
+    readonly targetPosition: Vec2;
+    readonly channel: 'visual' | 'sound';
+    /**
+     * Detection confidence in [0, 1].
+     * Visual detections always have confidence 1.0.
+     * Sound confidence decreases linearly with distance.
+     */
+    readonly confidence: number;
+}
+export interface INPCSensorsConfig {
+    /**
+     * Spatial hash grid for O(k) candidate lookup.
+     * Entities must be registered in the grid by the caller.
+     */
+    spatialGrid: SpatialGrid<{
+        id: string;
+        position: Vec2;
+    }>;
+    /** Returns true if observerFaction is hostile toward targetFaction. */
+    isHostile: (observerFaction: string, targetFaction: string) => boolean;
+    /**
+     * Optional LOS check — called after the FOV cone test.
+     * Return `true` if the line from `from` to `to` is unobstructed.
+     * When absent, LOS is assumed clear (backward-compatible).
+     *
+     * @example
+     * ```ts
+     * isLineOfSightClear(from, to) {
+     *   const line = new Phaser.Geom.Line(from.x, from.y, to.x, to.y);
+     *   return obstacles.every(r => !Phaser.Geom.Intersects.LineToRectangle(line, r));
+     * }
+     * ```
+     */
+    isLineOfSightClear?: (from: Vec2, to: Vec2) => boolean;
+}
+/**
+ * NPC vision and hearing sensors.
+ *
+ * Two sensors:
+ * - **Vision** (`detectVision`): FOV cone per NPC, hostile-only, O(n×k) via SpatialGrid.
+ * - **Sound** (`detectSound`): omnidirectional from a source, all factions hear it, confidence decays with distance.
+ *
+ * @example
+ * ```ts
+ * const sensors = new NPCSensors({ spatialGrid, isHostile });
+ *
+ * // Each frame — who sees who:
+ * const visionEvents = sensors.detectVision(onlineNPCs);
+ * for (const event of visionEvents) {
+ *   memoryBanks.get(event.observerId)?.add({ ... });
+ * }
+ *
+ * // On shot fired — who hears it:
+ * const soundEvents = sensors.detectSound(shootPos, 500, shooterId, shooterFaction, onlineNPCs);
+ * ```
+ */
+export declare class NPCSensors {
+    private readonly _grid;
+    private readonly _isHostile;
+    private readonly _isLOSClear;
+    constructor(config: INPCSensorsConfig);
+    /**
+     * Vision sensor — for each living NPC: query nearby candidates via SpatialGrid,
+     * apply FOV cone check, emit detection events for visible hostile targets.
+     *
+     * Builds an id→entity index once at O(n), then candidate lookup is O(1).
+     * Overall complexity: O(n * k) where n = observers, k = avg candidates per vision radius.
+     *
+     * NOTE: SpatialGrid.queryRadius() returns a scratch array that is reused between
+     * calls. Results are copied per observer to avoid aliasing issues.
+     */
+    detectVision(observers: readonly IPerceptibleEntity[]): IDetectionEvent[];
+    /**
+     * Sound sensor — detect all NPCs that hear a sound event.
+     *
+     * Sound is omnidirectional (no FOV cone). Confidence decays linearly with distance.
+     * Both hostile and friendly entities can hear the sound.
+     *
+     * O(h) where h = hearer count.
+     *
+     * @param sourcePos        - World-space origin of the sound.
+     * @param soundRange       - Maximum propagation range in world units.
+     * @param sourceId         - Entity id of the sound source (excluded from results).
+     * @param _sourceFactionId - Faction of the sound source (unused — sound is omnidirectional).
+     * @param hearers          - Candidate entities that may hear the sound.
+     */
+    detectSound(sourcePos: Vec2, soundRange: number, sourceId: string, _sourceFactionId: string, hearers: readonly IPerceptibleEntity[]): IDetectionEvent[];
+}
+/**
+ * Filter squad-shared target intel by freshness.
+ * Returns only targets seen within `freshnessMs` milliseconds.
+ *
+ * @param sharedTargets - Targets shared by squad members.
+ * @param currentTimeMs - Current game time in ms.
+ * @param freshnessMs   - Max age of intel (default: 5000ms).
+ */
+export declare function filterFreshIntel(sharedTargets: ReadonlyArray<{
+    id: string;
+    position: Vec2;
+    lastSeenMs: number;
+}>, currentTimeMs: number, freshnessMs?: number): ReadonlyArray<{
+    id: string;
+    position: Vec2;
+}>;
+//# sourceMappingURL=NPCSensors.d.ts.map

package/dist/perception/NPCSensors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NPCSensors.d.ts","sourceRoot":"","sources":["../../src/perception/NPCSensors.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAOnD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACzD,uEAAuE;IACvE,SAAS,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC;IACvE;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC;CACxD;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkD;gBAElE,MAAM,EAAE,iBAAiB;IAMrC;;;;;;;;;OASG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GAAG,eAAe,EAAE;IA4CzE;;;;;;;;;;;;;OAaG;IACH,WAAW,CACT,SAAS,EAAE,IAAI,EACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,eAAe,EAAE;CA+BrB;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,EAChF,aAAa,EAAE,MAAM,EACrB,WAAW,SAAO,GACjB,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,CAQ/C"}

package/dist/perception/NPCSensors.js

@@ -0,0 +1,147 @@
+// perception/NPCSensors.ts
+// NPC vision and hearing sensors — scene-level coordinator.
+//
+// Uses SpatialGrid for O(k) candidate lookup instead of O(n) full scan.
+// Returns IDetectionEvent[] — caller decides what to do (write to MemoryBank, emit events, etc.).
+//
+// Pure deterministic logic — no side effects, no EventBus dependency.
+import { isInFOV, distanceSq } from './PerceptionQuery';
+// ---------------------------------------------------------------------------
+// NPCSensors
+// ---------------------------------------------------------------------------
+/**
+ * NPC vision and hearing sensors.
+ *
+ * Two sensors:
+ * - **Vision** (`detectVision`): FOV cone per NPC, hostile-only, O(n×k) via SpatialGrid.
+ * - **Sound** (`detectSound`): omnidirectional from a source, all factions hear it, confidence decays with distance.
+ *
+ * @example
+ * ```ts
+ * const sensors = new NPCSensors({ spatialGrid, isHostile });
+ *
+ * // Each frame — who sees who:
+ * const visionEvents = sensors.detectVision(onlineNPCs);
+ * for (const event of visionEvents) {
+ *   memoryBanks.get(event.observerId)?.add({ ... });
+ * }
+ *
+ * // On shot fired — who hears it:
+ * const soundEvents = sensors.detectSound(shootPos, 500, shooterId, shooterFaction, onlineNPCs);
+ * ```
+ */
+export class NPCSensors {
+    constructor(config) {
+        this._grid = config.spatialGrid;
+        this._isHostile = config.isHostile;
+        this._isLOSClear = config.isLineOfSightClear;
+    }
+    /**
+     * Vision sensor — for each living NPC: query nearby candidates via SpatialGrid,
+     * apply FOV cone check, emit detection events for visible hostile targets.
+     *
+     * Builds an id→entity index once at O(n), then candidate lookup is O(1).
+     * Overall complexity: O(n * k) where n = observers, k = avg candidates per vision radius.
+     *
+     * NOTE: SpatialGrid.queryRadius() returns a scratch array that is reused between
+     * calls. Results are copied per observer to avoid aliasing issues.
+     */
+    detectVision(observers) {
+        const results = [];
+        // Build id→entity index once — O(n), gives O(1) candidate lookup
+        const entityMap = new Map();
+        for (const e of observers)
+            entityMap.set(e.id, e);
+        for (const observer of observers) {
+            if (!observer.isAlive)
+                continue;
+            // queryRadius returns a scratch array — copy immediately to avoid aliasing
+            const candidates = [...this._grid.queryRadius(observer.position, observer.visionRange)];
+            for (const cell of candidates) {
+                if (cell.id === observer.id)
+                    continue;
+                const target = entityMap.get(cell.id);
+                if (!target || !target.isAlive)
+                    continue;
+                if (!this._isHostile(observer.factionId, target.factionId))
+                    continue;
+                if (!isInFOV(observer.position, observer.facingAngle, target.position, observer.visionRange, observer.visionHalfAngle))
+                    continue;
+                // LOS obstacle check — optional, skipped when not configured
+                if (this._isLOSClear && !this._isLOSClear(observer.position, target.position))
+                    continue;
+                results.push({
+                    observerId: observer.id,
+                    targetId: target.id,
+                    targetPosition: target.position,
+                    channel: 'visual',
+                    confidence: 1.0,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Sound sensor — detect all NPCs that hear a sound event.
+     *
+     * Sound is omnidirectional (no FOV cone). Confidence decays linearly with distance.
+     * Both hostile and friendly entities can hear the sound.
+     *
+     * O(h) where h = hearer count.
+     *
+     * @param sourcePos        - World-space origin of the sound.
+     * @param soundRange       - Maximum propagation range in world units.
+     * @param sourceId         - Entity id of the sound source (excluded from results).
+     * @param _sourceFactionId - Faction of the sound source (unused — sound is omnidirectional).
+     * @param hearers          - Candidate entities that may hear the sound.
+     */
+    detectSound(sourcePos, soundRange, sourceId, _sourceFactionId, hearers) {
+        if (soundRange <= 0)
+            return [];
+        const results = [];
+        const soundRangeSq = soundRange * soundRange;
+        for (const hearer of hearers) {
+            if (!hearer.isAlive)
+                continue;
+            if (hearer.id === sourceId)
+                continue;
+            const dSq = distanceSq(hearer.position, sourcePos);
+            const hearRangeSq = hearer.hearingRange * hearer.hearingRange;
+            // Must be within both sound propagation range AND hearer's hearing range
+            if (dSq > soundRangeSq || dSq > hearRangeSq)
+                continue;
+            // Linear confidence decay: 1.0 at source, 0.0 at soundRange
+            const dist = Math.sqrt(dSq);
+            const confidence = Math.max(0, 1.0 - dist / soundRange);
+            results.push({
+                observerId: hearer.id,
+                targetId: sourceId,
+                targetPosition: sourcePos,
+                channel: 'sound',
+                confidence,
+            });
+        }
+        return results;
+    }
+}
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+/**
+ * Filter squad-shared target intel by freshness.
+ * Returns only targets seen within `freshnessMs` milliseconds.
+ *
+ * @param sharedTargets - Targets shared by squad members.
+ * @param currentTimeMs - Current game time in ms.
+ * @param freshnessMs   - Max age of intel (default: 5000ms).
+ */
+export function filterFreshIntel(sharedTargets, currentTimeMs, freshnessMs = 5000) {
+    const result = [];
+    for (const t of sharedTargets) {
+        if (currentTimeMs - t.lastSeenMs <= freshnessMs) {
+            result.push({ id: t.id, position: t.position });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=NPCSensors.js.map

package/dist/perception/NPCSensors.js.map

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

package/dist/perception/PerceptionQuery.d.ts

@@ -0,0 +1,65 @@
+import type { Vec2 } from '@alife-sdk/core';
+import type { IPerceivedEntity, IPerceptionConfig } from '../types/IPerceptionTypes';
+/**
+ * Check if a target is within a vision cone.
+ *
+ * Uses squared-distance for the range check (no sqrt).
+ * The vision cone is defined by a half-angle from the facing direction.
+ *
+ * @returns true if target is within range AND within the cone angle
+ */
+export declare function isInFOV(origin: Vec2, facingAngle: number, target: Vec2, visionRange: number, visionHalfAngle: number): boolean;
+/**
+ * Filter entities that are visible to the observer.
+ *
+ * Combines FOV cone test with alive check.
+ * O(n) where n = candidate count.
+ * Precomputes trig values once per call (same pattern as scanForEnemies).
+ * Returns a reusable scratch array — do not hold a reference across calls.
+ */
+export declare function filterVisibleEntities(origin: Vec2, facingAngle: number, candidates: readonly IPerceivedEntity[], config: IPerceptionConfig): IPerceivedEntity[];
+/**
+ * Filter entities that can hear a sound from a source.
+ *
+ * Sound is omnidirectional — no cone test, just distance.
+ * Uses squared-distance for performance.
+ * Returns a reusable scratch array — do not hold a reference across calls.
+ *
+ * @param source - Sound origin point
+ * @param soundRange - Maximum propagation range (px)
+ * @param entities - All candidate listeners
+ * @param hearingRange - Per-listener hearing range (overrides soundRange if smaller)
+ */
+export declare function filterHearingEntities(source: Vec2, soundRange: number, entities: readonly IPerceivedEntity[], hearingRange?: number): IPerceivedEntity[];
+/**
+ * Filter entities by faction hostility.
+ * Returns a reusable scratch array — do not hold a reference across calls.
+ *
+ * @param entities - Entity candidates
+ * @param observerFactionId - The observer's faction
+ * @param isHostile - Callback checking if two factions are hostile
+ */
+export declare function filterHostileEntities(entities: readonly IPerceivedEntity[], observerFactionId: string, isHostile: (factionA: string, factionB: string) => boolean): IPerceivedEntity[];
+/**
+ * Filter entities that are friendlies (same faction OR non-hostile).
+ * Returns a reusable scratch array — do not hold a reference across calls.
+ */
+export declare function filterFriendlyEntities(entities: readonly IPerceivedEntity[], observerFactionId: string, isHostile: (factionA: string, factionB: string) => boolean): IPerceivedEntity[];
+/**
+ * Calculate squared distance between two points.
+ * Avoid sqrt when only comparing relative distances.
+ */
+export declare function distanceSq(a: Vec2, b: Vec2): number;
+/**
+ * Find the closest entity to a position.
+ * Returns null if array is empty.
+ */
+export declare function findClosest(origin: Vec2, entities: readonly IPerceivedEntity[]): IPerceivedEntity | null;
+/**
+ * Full perception scan: find visible hostile entities.
+ *
+ * Combines FOV filtering + faction filtering in a single pass.
+ * This is the primary query used by GOAP world state building.
+ */
+export declare function scanForEnemies(origin: Vec2, facingAngle: number, candidates: readonly IPerceivedEntity[], observerFactionId: string, isHostile: (factionA: string, factionB: string) => boolean, config: IPerceptionConfig): IPerceivedEntity[];
+//# sourceMappingURL=PerceptionQuery.d.ts.map

package/dist/perception/PerceptionQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PerceptionQuery.d.ts","sourceRoot":"","sources":["../../src/perception/PerceptionQuery.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAWrF;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,IAAI,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,IAAI,EACZ,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,GACtB,OAAO,CAgBT;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,IAAI,EACZ,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,MAAM,EAAE,iBAAiB,GACxB,gBAAgB,EAAE,CA8BpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,IAAI,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,YAAY,CAAC,EAAE,MAAM,GACpB,gBAAgB,EAAE,CAiBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,GACzD,gBAAgB,EAAE,CASpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,GACzD,gBAAgB,EAAE,CAYpB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAInD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,IAAI,EACZ,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,gBAAgB,GAAG,IAAI,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,EACZ,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,SAAS,gBAAgB,EAAE,EACvC,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,EAC1D,MAAM,EAAE,iBAAiB,GACxB,gBAAgB,EAAE,CAgCpB"}