@alife-sdk/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Rusakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# @alife-sdk/core
+
+Framework-agnostic A-Life simulation and AI decision-making system.
+
+Zero external dependencies. Works with Phaser, Unity, Node.js, or any other runtime.
+
+```
+npm install @alife-sdk/core
+```
+
+---
+
+## What this package does
+
+`@alife-sdk/core` provides the complete foundation for a living game world:
+
+- **NPC AI** — finite state machines, GOAP planners, memory and perception systems
+- **A-Life simulation** — offline NPC brains, terrain selection, spawn cooldowns, faction diplomacy
+- **Game clock** — accelerated in-game time, day/night cycle, hour events
+- **World graph** — waypoint graph with A* pathfinding for offline NPC movement
+- **Plugin system** — extend the kernel with your own domain features
+
+The package is intentionally engine-agnostic. It never imports Phaser,
+renders sprites, or touches the DOM. All engine interaction goes through
+**ports** — narrow interfaces you implement once for your engine.
+
+---
+
+## Quick start
+
+> The SDK ships **interfaces only** for engine adapters — `IEntityAdapter`,
+> `IEntityFactory`, `IDataLoader`, etc. You implement them once for your engine.
+> The example below uses placeholder names; replace them with your own implementations.
+> See [`ports/README.md`](src/ports/README.md) for full interface specs and a Phaser example.
+
+```ts
+import { ALifeKernel, Ports } from '@alife-sdk/core';
+import { fullPreset, Plugins } from '@alife-sdk/core/plugins';
+
+// 1. Create the kernel
+const kernel = new ALifeKernel();
+
+// 2. Register engine adapters (optional — kernel auto-provides no-ops if omitted)
+//    (MyEntityAdapter / MyEntityFactory — your implementations of
+//     IEntityAdapter / IEntityFactory from @alife-sdk/core/ports)
+kernel.provide(Ports.EntityAdapter,  new MyEntityAdapter(scene));
+kernel.provide(Ports.EntityFactory,  new MyEntityFactory(scene));
+kernel.provide(Ports.PlayerPosition, { getPlayerPosition: () => ({ x: player.x, y: player.y }) });
+// Ports.RuntimeClock and Ports.Random are also optional (SDK provides defaults)
+
+// 3. Install built-in plugins
+fullPreset(kernel);
+
+// 4. Register game data (before init)
+const factions = kernel.getPlugin(Plugins.FACTIONS).factions;
+factions.register('stalker', { name: 'Stalker', baseRelations: { bandit: -80 } });
+factions.register('bandit',  { name: 'Bandit',  baseRelations: { stalker: -80 } });
+
+// 5. Init — validates ports, freezes registries, returns DiagnosticsCollector
+const diag = kernel.init();
+
+// 6. Start — enables frame-based update()
+kernel.start();
+
+// 7. Game loop
+function update(deltaMs: number): void {
+  kernel.update(deltaMs);
+}
+
+// 8. Save / load
+const save = kernel.serialize();
+kernel.restoreState(save);
+
+// 9. Cleanup
+kernel.destroy();
+```
+
+---
+
+## Sub-path imports
+
+Each module has its own import path for optimal tree-shaking:
+
+| Import path | What's inside | Module docs |
+|-------------|--------------|-------------|
+| `@alife-sdk/core` | `ALifeKernel`, `Clock`, `SpatialGrid`, `Ports` | [core/](src/core/) |
+| `@alife-sdk/core/ai` | `StateMachine`, `MemoryBank`, `DangerManager`, `GOAPPlanner` | [ai/](src/ai/README.md) |
+| `@alife-sdk/core/combat` | `DamageInstance`, `MoraleTracker`, `ImmunityProfile` | [combat/](src/combat/README.md) |
+| `@alife-sdk/core/config` | `createDefaultConfig`, `IALifeConfig` | [config/](src/config/README.md) |
+| `@alife-sdk/core/entity` | `IEntity`, `IComponent` | [entity/](src/entity/README.md) |
+| `@alife-sdk/core/events` | `EventBus`, `ALifeEvents`, `ALifeEventPayloads` | [events/](src/events/README.md) |
+| `@alife-sdk/core/faction` | `Faction`, `FactionBuilder` | [faction/](src/faction/README.md) |
+| `@alife-sdk/core/logger` | `Logger`, `LogLevel`, `LogChannel` | [logger/](src/logger/README.md) |
+| `@alife-sdk/core/movement` | `PatrolRouteTracker`, `MonsterHome` | [movement/](src/movement/README.md) |
+| `@alife-sdk/core/navigation` | `LevelGraph`, `NPCGraphMover` | [navigation/](src/navigation/README.md) |
+| `@alife-sdk/core/plugins` | `IALifePlugin`, built-in plugins, `Plugins` tokens | [plugins/](src/plugins/README.md) |
+| `@alife-sdk/core/ports` | `IEntityAdapter`, `IDataLoader`, `IRandom`, … | [ports/](src/ports/README.md) |
+| `@alife-sdk/core/registry` | `Registry`, `FactionRegistry`, `AIStateRegistry`, … | [registry/](src/registry/README.md) |
+| `@alife-sdk/core/schema` | `validateMonsterDefinition`, assertion helpers | [schema/](src/schema/README.md) |
+| `@alife-sdk/core/spawn` | `SpawnRegistry` | [spawn/](src/spawn/README.md) |
+| `@alife-sdk/core/terrain` | `Zone`, `SmartTerrain`, `TerrainBuilder` | [terrain/](src/terrain/README.md) |
+| `@alife-sdk/core/time` | `TimeManager` | [time/](src/time/README.md) |
+
+---
+
+## Architecture
+
+```
+                        ┌─────────────────────────────────┐
+                        │         ALifeKernel              │
+                        │  clock · events · logger · ports │
+                        └──────────────┬──────────────────┘
+                                       │ kernel.use(plugin)
+              ┌────────────────────────┼────────────────────────┐
+              │                        │                        │
+      FactionsPlugin           NPCTypesPlugin            SpawnPlugin
+      FactionRegistry          NPCTypeRegistry            SpawnRegistry
+              │                        │                        │
+              └────────────────────────┼────────────────────────┘
+                                       │
+              ┌────────────────────────┼────────────────────────┐
+              │                        │                        │
+         StateMachine            MemoryBank              GOAPPlanner
+        (18 AI states)        (4 channels, decay)       (A* on WorldState)
+              │                        │                        │
+              └────────────────────────┼────────────────────────┘
+                                       │
+              ┌────────────────────────┼────────────────────────┐
+              │                        │                        │
+          LevelGraph             SmartTerrain              Faction
+        (A* pathfinding)     (capacity + fitness)      (two-layer relations)
+```
+
+---
+
+## Key concepts
+
+### Ports — engine adapter pattern
+
+The kernel never calls Phaser or any engine API directly. Instead, it calls
+**ports** — interfaces you implement to bridge the SDK to your engine.
+
+All ports are optional — the kernel auto-provides silent no-op defaults for
+engine ports if you don't supply real implementations. This means
+`new ALifeKernel().init()` works with zero configuration for offline
+simulation, persistence, and unit tests.
+
+| Port | Interface | Default | Purpose |
+|------|-----------|---------|---------|
+| Entity adapter | `IEntityAdapter` | no-op | Read/write entity position, visibility, components |
+| Entity factory | `IEntityFactory` | no-op | Create and destroy game objects |
+| Player position | `IPlayerPositionProvider` | `{x:0,y:0}` | Online/offline radius check each tick |
+| Runtime clock | `IRuntimeClock` | `Date.now()` | Real-time ms for cooldown timers |
+| Random | `IRandom` | `Math.random()` | PRNG for simulation randomness |
+
+See [`ports/README.md`](src/ports/README.md) for implementation examples.
+
+### Plugin system
+
+The kernel is minimal by design. All domain features live in plugins that
+you install with `kernel.use(plugin)`. Built-in plugins cover factions,
+NPC types, combat schemas, spawning, monsters, and anomalies.
+
+Write your own plugin by implementing `IALifePlugin`:
+
+```ts
+class WeatherPlugin implements IALifePlugin {
+  readonly name = 'weather';
+  install(kernel: ALifeKernel): void { ... }
+  update(deltaMs: number): void { ... }
+  destroy(): void { ... }
+}
+kernel.use(new WeatherPlugin());
+```
+
+See [`plugins/README.md`](src/plugins/README.md).
+
+### Event bus
+
+All simulation events are delivered via a deferred `EventBus`.
+`emit()` queues an event; `flush()` delivers it — called automatically by
+`kernel.update()` at the end of each frame.
+
+```ts
+kernel.events.on(ALifeEvents.NPC_DIED, ({ npcId, killedBy }) => {
+  questSystem.onNpcKilled(npcId);
+});
+```
+
+38 typed events across 9 categories: A-Life, AI, Surge, Anomaly, Squad,
+Faction, Time, Social, Monster. See [`events/README.md`](src/events/README.md).
+
+### AI — StateMachine + GOAP
+
+Every online NPC runs a `StateMachine` over states registered in `AIStateRegistry`.
+Each state has `enter / update / exit` handlers and optional auto-transition rules.
+
+Elite NPCs (rank ≥ 5) additionally run a `GOAPPlanner` — an A* planner over
+a `WorldState` bitmask that picks the optimal action sequence to achieve a goal.
+
+See [`ai/README.md`](src/ai/README.md).
+
+### Offline simulation — LevelGraph + SmartTerrain
+
+NPCs outside the player's view radius move through a `LevelGraph` (waypoint
+graph with A*) without needing a full physics update. Each offline NPC gets
+a `NPCGraphMover` cursor that interpolates world position along graph edges.
+
+NPCs choose destinations by scoring all `SmartTerrain` instances via
+`scoreFitness()` — a function of distance, capacity, shelter bonus, and
+danger-vs-rank match.
+
+---
+
+## Lifecycle
+
+```
+kernel.provide(port)   ← register port adapters
+  ↓
+kernel.use(plugin)     ← register plugins
+  ↓
+kernel.init()          ← validate ports, freeze registries, call plugin.init()
+  ↓
+kernel.start()         ← enable frame-based update()
+  ↓
+kernel.update(delta)   ← each frame: tick plugins → flush events
+  ↓
+kernel.serialize()     ← capture state for save
+kernel.restoreState()  ← restore from save
+  ↓
+kernel.destroy()       ← cleanup, call plugin.destroy() in reverse order
+```
+
+---
+
+## Testing
+
+```
+pnpm test --filter @alife-sdk/core
+```
+
+The SDK is designed to be test-friendly:
+- Engine ports (`EntityAdapter`, `PlayerPosition`, `EntityFactory`) auto-provide
+  no-ops — no boilerplate needed for offline/persistence tests
+- `IRandom` port → inject `SeededRandom` for deterministic results
+- `IRuntimeClock` port → inject a frozen clock
+
+```ts
+// Minimal test kernel — no provide() needed
+const kernel = new ALifeKernel();
+kernel.init();
+kernel.step(10);
+
+// Override only what your test actually needs
+const kernel = new ALifeKernel();
+kernel.provide(Ports.Random, new SeededRandom(42));
+kernel.init();
+```
+
+---
+
+## Module map
+
+```
+src/
+├── core/           ALifeKernel, Clock, SpatialGrid, Vec2, PortRegistry, Diagnostics
+├── ai/             StateMachine, MemorySystem, DangerManager, GOAPPlanner/Action/WorldState
+├── combat/         DamageInstance, ImmunityProfile, MoraleTracker
+├── config/         IALifeConfig, createDefaultConfig
+├── entity/         IEntity, IComponent (interfaces only)
+├── events/         EventBus, ALifeEvents, ALifeEventPayloads
+├── faction/        Faction, FactionBuilder, IFactionState
+├── logger/         Logger, LogLevel, LogChannel, ILogEntry
+├── movement/       PatrolRouteTracker, RouteType, MonsterHome
+├── navigation/     LevelGraph, NPCGraphMover
+├── plugins/        IALifePlugin, built-in plugins, PluginToken, presets
+├── ports/          IEntityAdapter, IEntityFactory, IRandom, IRuntimeClock, IDataLoader, ILogger
+├── registry/       Registry, FactionRegistry, NPCTypeRegistry, MonsterRegistry, AIStateRegistry, …
+├── schema/         validateMonsterDefinition, validateFactionDefinition, assertion helpers
+├── spawn/          SpawnRegistry
+├── terrain/        Zone, SmartTerrain, TerrainBuilder
+└── time/           TimeManager
+```

package/dist/ai/DangerManager.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Typed danger system with spatial awareness.
+ *
+ * DangerManager maintains a set of active danger zones in the world.
+ * Each danger has a type, position, radius, threat score, and time-to-live.
+ * NPCs query this manager to find nearby threats and compute safe
+ * movement directions.
+ *
+ * All spatial queries use squared-distance math for performance.
+ */
+import type { Vec2 } from '../core/Vec2';
+export declare const DangerType: {
+    readonly GRENADE: "grenade";
+    readonly GUNFIRE: "gunfire";
+    readonly EXPLOSION: "explosion";
+    readonly CORPSE: "corpse";
+    readonly ANOMALY: "anomaly";
+    readonly ATTACK_SOUND: "attack_sound";
+};
+export type DangerType = (typeof DangerType)[keyof typeof DangerType] | (string & {});
+export interface IDangerEntry {
+    readonly id: string;
+    readonly type: DangerType;
+    readonly position: Vec2;
+    readonly radius: number;
+    /** Urgency score in [0, 1]. Higher = more threatening. */
+    readonly threatScore: number;
+    /** Milliseconds remaining before this danger expires. */
+    readonly remainingMs: number;
+}
+export declare class DangerManager {
+    private readonly dangers;
+    private readonly defaultThreshold;
+    constructor(defaultThreshold?: number);
+    /** Register a danger zone. Replaces an existing danger with the same ID. */
+    addDanger(entry: IDangerEntry): void;
+    /** Remove a danger by ID. */
+    removeDanger(id: string): void;
+    /**
+     * Get total threat score at a position.
+     *
+     * Sums the threat scores of all dangers whose radius covers the position.
+     * Result is not clamped -- may exceed 1.0 when multiple dangers overlap.
+     */
+    getThreatAt(position: Vec2): number;
+    /** Get all dangers within the given radius of a position. */
+    getDangersNear(position: Vec2, radius: number): IDangerEntry[];
+    /**
+     * Find the safest direction to move (away from threats).
+     *
+     * Computes a weighted repulsion vector from all nearby dangers.
+     * Each danger contributes a repulsion force inversely proportional to
+     * its distance and proportional to its threat score.
+     *
+     * Returns ZERO if no dangers are active.
+     */
+    getSafeDirection(position: Vec2): Vec2;
+    /** Tick: decay danger durations, remove expired entries. */
+    update(deltaMs: number): void;
+    /**
+     * Check if a position is dangerous (total threat exceeds threshold).
+     *
+     * @param position  - World-space position to test.
+     * @param threshold - Minimum threat level to consider dangerous.
+     */
+    isDangerous(position: Vec2, threshold?: number): boolean;
+    get activeDangerCount(): number;
+    serialize(): IDangerEntry[];
+    restore(entries: IDangerEntry[]): void;
+}
+//# sourceMappingURL=DangerManager.d.ts.map

package/dist/ai/DangerManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DangerManager.d.ts","sourceRoot":"","sources":["../../src/ai/DangerManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAOzC,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAMtF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AA0BD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,gBAAgB,GAAE,MAAiC;IAQ/D,4EAA4E;IAC5E,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAIpC,6BAA6B;IAC7B,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM;IAcnC,6DAA6D;IAC7D,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE;IAc9D;;;;;;;;OAQG;IACH,gBAAgB,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI;IA8CtC,4DAA4D;IAC5D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAiB7B;;;;;OAKG;IACH,WAAW,CACT,QAAQ,EAAE,IAAI,EACd,SAAS,GAAE,MAA8B,GACxC,OAAO;IAeV,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAMD,SAAS,IAAI,YAAY,EAAE;IAI3B,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;CAMvC"}

package/dist/ai/DangerManager.js

@@ -0,0 +1,176 @@
+/**
+ * Typed danger system with spatial awareness.
+ *
+ * DangerManager maintains a set of active danger zones in the world.
+ * Each danger has a type, position, radius, threat score, and time-to-live.
+ * NPCs query this manager to find nearby threats and compute safe
+ * movement directions.
+ *
+ * All spatial queries use squared-distance math for performance.
+ */
+import { distanceSq, ZERO } from '../core/Vec2';
+// ---------------------------------------------------------------------------
+// Danger type
+// ---------------------------------------------------------------------------
+export const DangerType = {
+    GRENADE: 'grenade',
+    GUNFIRE: 'gunfire',
+    EXPLOSION: 'explosion',
+    CORPSE: 'corpse',
+    ANOMALY: 'anomaly',
+    ATTACK_SOUND: 'attack_sound',
+};
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_THREAT_THRESHOLD = 0.1;
+// ---------------------------------------------------------------------------
+// DangerManager
+// ---------------------------------------------------------------------------
+export class DangerManager {
+    constructor(defaultThreshold = DEFAULT_THREAT_THRESHOLD) {
+        this.dangers = new Map();
+        this.defaultThreshold = defaultThreshold;
+    }
+    // -----------------------------------------------------------------------
+    // Mutation
+    // -----------------------------------------------------------------------
+    /** Register a danger zone. Replaces an existing danger with the same ID. */
+    addDanger(entry) {
+        this.dangers.set(entry.id, { ...entry });
+    }
+    /** Remove a danger by ID. */
+    removeDanger(id) {
+        this.dangers.delete(id);
+    }
+    // -----------------------------------------------------------------------
+    // Spatial queries
+    // -----------------------------------------------------------------------
+    /**
+     * Get total threat score at a position.
+     *
+     * Sums the threat scores of all dangers whose radius covers the position.
+     * Result is not clamped -- may exceed 1.0 when multiple dangers overlap.
+     */
+    getThreatAt(position) {
+        let totalThreat = 0;
+        for (const danger of this.dangers.values()) {
+            const dsq = distanceSq(position, danger.position);
+            const rSq = danger.radius * danger.radius;
+            if (dsq <= rSq) {
+                totalThreat += danger.threatScore;
+            }
+        }
+        return totalThreat;
+    }
+    /** Get all dangers within the given radius of a position. */
+    getDangersNear(position, radius) {
+        const result = [];
+        const searchRadiusSq = radius * radius;
+        for (const danger of this.dangers.values()) {
+            const dsq = distanceSq(position, danger.position);
+            if (dsq <= searchRadiusSq) {
+                result.push(danger);
+            }
+        }
+        return result;
+    }
+    /**
+     * Find the safest direction to move (away from threats).
+     *
+     * Computes a weighted repulsion vector from all nearby dangers.
+     * Each danger contributes a repulsion force inversely proportional to
+     * its distance and proportional to its threat score.
+     *
+     * Returns ZERO if no dangers are active.
+     */
+    getSafeDirection(position) {
+        let repulsionX = 0;
+        let repulsionY = 0;
+        let hasDangers = false;
+        for (const danger of this.dangers.values()) {
+            const dsq = distanceSq(position, danger.position);
+            const rSq = danger.radius * danger.radius;
+            if (dsq > rSq)
+                continue;
+            hasDangers = true;
+            const dist = Math.sqrt(dsq);
+            if (dist < 1) {
+                // Directly on top of danger -- derive a direction from danger position
+                // to avoid a constant northeast bias.
+                const angle = ((danger.position.x * 73 + danger.position.y * 37) % 360) * (Math.PI / 180);
+                repulsionX += Math.cos(angle) * danger.threatScore;
+                repulsionY += Math.sin(angle) * danger.threatScore;
+                continue;
+            }
+            // Direction from danger to position (away from danger), inlined.
+            const dx = position.x - danger.position.x;
+            const dy = position.y - danger.position.y;
+            // Weight by threat score and inverse distance.
+            const weight = danger.threatScore / dist;
+            repulsionX += dx * weight;
+            repulsionY += dy * weight;
+        }
+        if (!hasDangers)
+            return ZERO;
+        // Inline normalize — avoid allocating intermediate {x, y}.
+        const mag = Math.sqrt(repulsionX * repulsionX + repulsionY * repulsionY);
+        if (mag === 0)
+            return ZERO;
+        return { x: repulsionX / mag, y: repulsionY / mag };
+    }
+    // -----------------------------------------------------------------------
+    // Update
+    // -----------------------------------------------------------------------
+    /** Tick: decay danger durations, remove expired entries. */
+    update(deltaMs) {
+        const toDelete = [];
+        for (const [id, danger] of this.dangers) {
+            danger.remainingMs -= deltaMs;
+            if (danger.remainingMs <= 0) {
+                toDelete.push(id);
+            }
+        }
+        for (const id of toDelete) {
+            this.dangers.delete(id);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Convenience checks
+    // -----------------------------------------------------------------------
+    /**
+     * Check if a position is dangerous (total threat exceeds threshold).
+     *
+     * @param position  - World-space position to test.
+     * @param threshold - Minimum threat level to consider dangerous.
+     */
+    isDangerous(position, threshold = this.defaultThreshold) {
+        let totalThreat = 0;
+        for (const danger of this.dangers.values()) {
+            const dsq = distanceSq(position, danger.position);
+            const rSq = danger.radius * danger.radius;
+            if (dsq <= rSq) {
+                totalThreat += danger.threatScore;
+                if (totalThreat >= threshold)
+                    return true;
+            }
+        }
+        return false;
+    }
+    get activeDangerCount() {
+        return this.dangers.size;
+    }
+    // -----------------------------------------------------------------------
+    // Serialisation
+    // -----------------------------------------------------------------------
+    serialize() {
+        return [...this.dangers.values()];
+    }
+    restore(entries) {
+        this.dangers.clear();
+        for (const entry of entries) {
+            this.dangers.set(entry.id, { ...entry });
+        }
+    }
+}
+//# sourceMappingURL=DangerManager.js.map

package/dist/ai/DangerManager.js.map

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

package/dist/ai/GOAPAction.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Abstract GOAP action base.
+ *
+ * Each concrete action encodes:
+ *   - id:            Unique string identifier for logging and plan inspection.
+ *   - cost:          Planner cost. Lower = preferred path.
+ *   - preconditions: WorldState properties that must be true before execution.
+ *   - effects:       WorldState properties this action produces on success.
+ *
+ * Execution lifecycle per action:
+ *   1. isValid()  -- real-time guard (can bail on stale conditions)
+ *   2. execute()  -- called every tick; returns RUNNING / SUCCESS / FAILURE
+ *   3. abort()    -- called when the action is interrupted (default no-op)
+ */
+import type { WorldState } from './WorldState';
+import type { IEntity } from '../entity/IEntity';
+export declare const ActionStatus: {
+    readonly RUNNING: "running";
+    readonly SUCCESS: "success";
+    readonly FAILURE: "failure";
+};
+export type ActionStatus = (typeof ActionStatus)[keyof typeof ActionStatus];
+export declare abstract class GOAPAction {
+    /** Unique action identifier for logging and plan inspection. */
+    abstract readonly id: string;
+    /** Planner cost. Lower cost = preferred path. */
+    abstract readonly cost: number;
+    /** Preconditions that must be true for this action to be valid. */
+    abstract getPreconditions(): WorldState;
+    /** Effects this action has on the world state when it completes. */
+    abstract getEffects(): WorldState;
+    /** Check if the action can currently execute (real-time guard). */
+    abstract isValid(entity: IEntity): boolean;
+    /**
+     * Execute one tick of this action.
+     *
+     * @param entity  - The entity executing this action.
+     * @param delta   - Milliseconds elapsed since the last tick.
+     * @returns Status indicating whether to continue, succeed, or fail.
+     */
+    abstract execute(entity: IEntity, delta: number): ActionStatus;
+    /** Called when the action is interrupted. Override for cleanup. */
+    abort(_entity: IEntity): void;
+}
+//# sourceMappingURL=GOAPAction.d.ts.map

package/dist/ai/GOAPAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GOAPAction.d.ts","sourceRoot":"","sources":["../../src/ai/GOAPAction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAMjD,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAM5E,8BAAsB,UAAU;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAE7B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,IAAI,UAAU;IAEvC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,IAAI,UAAU;IAEjC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY;IAE9D,mEAAmE;IACnE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAG9B"}

package/dist/ai/GOAPAction.js

@@ -0,0 +1,32 @@
+/**
+ * Abstract GOAP action base.
+ *
+ * Each concrete action encodes:
+ *   - id:            Unique string identifier for logging and plan inspection.
+ *   - cost:          Planner cost. Lower = preferred path.
+ *   - preconditions: WorldState properties that must be true before execution.
+ *   - effects:       WorldState properties this action produces on success.
+ *
+ * Execution lifecycle per action:
+ *   1. isValid()  -- real-time guard (can bail on stale conditions)
+ *   2. execute()  -- called every tick; returns RUNNING / SUCCESS / FAILURE
+ *   3. abort()    -- called when the action is interrupted (default no-op)
+ */
+// ---------------------------------------------------------------------------
+// Action status
+// ---------------------------------------------------------------------------
+export const ActionStatus = {
+    RUNNING: 'running',
+    SUCCESS: 'success',
+    FAILURE: 'failure',
+};
+// ---------------------------------------------------------------------------
+// Abstract base class
+// ---------------------------------------------------------------------------
+export class GOAPAction {
+    /** Called when the action is interrupted. Override for cleanup. */
+    abort(_entity) {
+        // Default no-op. Concrete actions override for cleanup.
+    }
+}
+//# sourceMappingURL=GOAPAction.js.map

package/dist/ai/GOAPAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GOAPAction.js","sourceRoot":"","sources":["../../src/ai/GOAPAction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;CACV,CAAC;AAIX,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,OAAgB,UAAU;IAyB9B,mEAAmE;IACnE,KAAK,CAAC,OAAgB;QACpB,wDAAwD;IAC1D,CAAC;CACF"}