@alife-sdk/ai 0.4.1 → 0.5.0

package/README.md

@@ -22,7 +22,8 @@ view and must behave in real-time.
 - **Cover system** — 6 evaluators, loophole peek/fire cycles, TTL-based cover locking
 - **Perception** — FOV queries, hearing radius, intel freshness filters
 - **GOAP** — elite NPC goal-oriented planning over a 16-property world state bitmask
-- **Navigation** — Catmull-Rom + Dubins arc path smoothing, restricted zones, pack steering
+- **GOAPDirector** — built-in bridge between GOAP planner and FSM; replans on entry, dispatches actions as sub-states, handles interrupts and plan lifecycle
+- **Navigation** — Catmull-Rom + Dubins arc path smoothing, restricted zones, pack steering, pluggable `IPathfindingAccess` for grid/navmesh A*
 - **Squad tactics** — situational assessment, 6 commands, shared target table
 - **Animation** — 8-direction state→key mapping, layered debounced controller
 - **Suspicion** — stimulus accumulation → alert threshold crossing
@@ -81,10 +82,19 @@ function update(deltaMs: number): void {
 // 6. Read current state
 const state = driver.currentStateId; // e.g. 'COMBAT'
 
-// 7. Force a state transition from within a state handler (e.g. on NPC death)
-// Transitions happen via ctx.transition(), called from inside a state handler:
-//   ctx.transition(ONLINE_STATE.DEAD);
-// To force a transition externally, call driver.update() after mutating ctx.state.
+// 7. Force a state transition from OUTSIDE a handler (new!)
+driver.forceTransition(ONLINE_STATE.DEAD);
+
+// 8. Listen to state transitions (new!)
+const unsub = driver.onTransition((from, to) => {
+  console.log(`NPC ${npcId}: ${from} → ${to}`);
+});
+// unsub() to remove the listener
+
+// 9. Store game-specific data in the extensible state bag (new!)
+ctx.state.custom ??= {};
+ctx.state.custom.ammo = 30;
+ctx.state.custom.goapPlan = planner.plan(worldState, goal);
 ```
 
 ---
@@ -100,7 +110,7 @@ Each module has its own import path for optimal tree-shaking:
 | `@alife-sdk/ai/states` | `OnlineAIDriver`, `StateHandlerMap`, `ONLINE_STATE`, all handlers, builder functions | [states/](src/states/) |
 | `@alife-sdk/ai/cover` | `CoverRegistry`, `CoverLockRegistry`, 6 evaluators, `LoopholeGenerator` | [cover/](src/cover/) |
 | `@alife-sdk/ai/perception` | `NPCSensors`, `isInFOV`, `filterVisibleEntities`, `filterHearingEntities`, `filterHostileEntities`, `filterFriendlyEntities`, `filterFreshIntel`, `distanceSq`, `findClosest`, `scanForEnemies` | [perception/](src/perception/) |
-| `@alife-sdk/ai/goap` | `GOAPController`, `buildWorldState`, `selectGoal`, `EvadeHazardAction` | [goap/](src/goap/) |
+| `@alife-sdk/ai/goap` | `GOAPController`, `GOAPDirector`, `buildWorldState`, `selectGoal`, `EvadeHazardAction` | [goap/](src/goap/) |
 | `@alife-sdk/ai/navigation` | `smoothPath`, `smoothPathWithTurning`, `SmoothPathFollower`, `RestrictedZoneManager`, `SteeringBehaviors` | [navigation/](src/navigation/) |
 | `@alife-sdk/ai/squad` | `evaluateSituation`, `SquadCommand`, `SquadSharedTargetTable` | [squad/](src/squad/) |
 | `@alife-sdk/ai/animation` | `getDirection`, `getAnimationKey`, `getAnimationRequest`, `AnimationController`, `DirectionCache`, `CompassIndex`, `AnimLayer`, `DEFAULT_STATE_ANIM_MAP`, `DEFAULT_WEAPON_SUFFIXES` | [animation/](src/animation/) |
@@ -117,43 +127,47 @@ Each module has its own import path for optimal tree-shaking:
 ## Architecture
 
 ```
-                ┌────────────────────────────────────────┐
-                │              ALifeKernel               │
-                │   (from @alife-sdk/core)               │
-                └──────────────┬─────────────────────────┘
-                               │ kernel.use(aiPlugin)
-                ┌──────────────▼─────────────────────────┐
-                │              AIPlugin                  │
-                │  CoverRegistry · CoverLockRegistry     │
-                │  RestrictedZoneManager                 │
-                │  createCoverAccess(npcId) ─────────────┼──► ICoverAccess (per NPC)
-                └────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────┐
+│                       ALifeKernel                         │
+│                  (from @alife-sdk/core)                    │
+└──────────────────────────┬────────────────────────────────┘
+                           │ kernel.use(aiPlugin)
+┌──────────────────────────▼────────────────────────────────┐
+│                       AIPlugin                            │
+│  CoverRegistry · CoverLockRegistry                        │
+│  RestrictedZoneManager                                    │
+│  createCoverAccess(npcId) ──► ICoverAccess (per NPC)      │
+└───────────────────────────────────────────────────────────┘
 
 Per-NPC (created on online transition):
-                ┌──────────────────────────────────────────────────────┐
-                │  OnlineAIDriver                                      │
-                │                                                      │
-                │  StateHandlerMap ──► IOnlineStateHandler             │
-                │   DEAD · IDLE · PATROL · ALERT · FLEE · SEARCH      │
-                │   CAMP · SLEEP · COMBAT · TAKE_COVER · GRENADE      │
-                │   EVADE_GRENADE · WOUNDED · RETREAT                  │
-                │   CHARGE · STALK · LEAP · PSI_ATTACK                 │
-                │                                                      │
-                │  INPCContext ─┬─ INPCPerception (FOV / hearing)     │
-                │               ├─ INPCHealth    (hp / morale)        │
-                │               ├─ ICoverAccess  (find / lock cover)  │
-                │               ├─ IDangerAccess (DangerManager port) │
-                │               ├─ ISquadAccess  (commands / target)  │
-                │               ├─ ISuspicionAccess                   │
-                │               └─ IConditionAccess                   │
-                └──────────────────────────────────────────────────────┘
+┌───────────────────────────────────────────────────────────┐
+│  OnlineAIDriver                                           │
+│                                                           │
+│  StateHandlerMap ──► IOnlineStateHandler                  │
+│    DEAD · IDLE · PATROL · ALERT · FLEE · SEARCH           │
+│    CAMP · SLEEP · COMBAT · TAKE_COVER · GRENADE           │
+│    EVADE_GRENADE · WOUNDED · RETREAT                       │
+│    CHARGE · STALK · LEAP · PSI_ATTACK                     │
+│                                                           │
+│  INPCContext ─┬─ INPCPerception     (FOV / hearing)       │
+│               ├─ INPCHealth         (hp / morale)         │
+│               ├─ ICoverAccess       (find / lock cover)   │
+│               ├─ IDangerAccess      (DangerManager port)  │
+│               ├─ IPathfindingAccess (A* / NavMesh port)   │
+│               ├─ ISquadAccess       (commands / target)   │
+│               ├─ ISuspicionAccess                         │
+│               └─ IConditionAccess                         │
+│                                                           │
+│  state.custom ── extensible Record<string, unknown> bag   │
+└───────────────────────────────────────────────────────────┘
 
 Shared systems (optional, compose as needed):
   NPCSensors            filterVisibleEntities / filterHearingEntities
-  GOAPController        elite NPC A* planning (rank ≥ 5)
+  GOAPController        elite NPC A* planning (rank >= 5)
+  GOAPDirector          GOAP -> FSM bridge (register as COMBAT handler)
   SmoothPathFollower    Catmull-Rom + Dubins arc path cursor
   AnimationController   layered, debounced animation dispatch
-  SuspicionAccumulator  stimulus → alert threshold crossing
+  SuspicionAccumulator  stimulus -> alert threshold crossing
   ConditionBank         multi-channel boolean state
 ```
 
@@ -172,13 +186,21 @@ const driver = new OnlineAIDriver(ctx, handlers, ONLINE_STATE.IDLE);
 
 driver.update(deltaMs);             // call every frame
 driver.currentStateId;              // current state ID string
-// Transitions happen via ctx.transition() from inside a state handler:
-//   ctx.transition('PATROL');
+
+// Transitions from inside a handler:
+ctx.transition('PATROL');
+
+// Transitions from OUTSIDE a handler (e.g. GOAP director, scripted events):
+driver.forceTransition('DEAD');
+
+// Listen to transitions:
+driver.onTransition((from, to) => console.log(`${from} → ${to}`));
 ```
 
 Each state handler is a stateless object — all per-NPC runtime data lives in
 `INPCOnlineState` (position, target, phase flags, timer, etc.), not in the handler.
 The handler map can be shared across all NPCs of the same type.
+Game-specific data (GOAP plans, ammo, personality) goes in `ctx.state.custom`.
 
 ### StateHandlerMap — three built-in presets
 
@@ -241,11 +263,12 @@ const ctx: INPCContext = {
   faction:    npc.faction,
   perception: new MyPerception(npc),  // INPCPerception  | null
   health:     new MyHealth(npc),      // INPCHealth      | null
-  cover:      coverAccess,            // ICoverAccess    | null  (from AIPlugin)
-  danger:     dangerAdapter,          // IDangerAccess   | null
-  squad:      squadAccess,            // ISquadAccess    | null
-  suspicion:  suspicionAccess,        // ISuspicionAccess | null
-  conditions: conditionAccess,        // IConditionAccess | null
+  cover:        coverAccess,            // ICoverAccess        | null  (from AIPlugin)
+  danger:       dangerAdapter,          // IDangerAccess       | null
+  pathfinding:  gridPathfinding,        // IPathfindingAccess  | null  (A* / NavMesh)
+  squad:        squadAccess,            // ISquadAccess        | null
+  suspicion:    suspicionAccess,        // ISuspicionAccess    | null
+  conditions:   conditionAccess,        // IConditionAccess    | null
   // pack, restrictedZones also nullable — omit if not used
   emitShoot:   (payload) => fireWeapon(npc, payload),
   emitMeleeHit:(payload) => applyMelee(npc, payload),
@@ -258,6 +281,85 @@ const ctx: INPCContext = {
 > Omitting a subsystem (setting it to `null`) silently disables the
 > features that depend on it, with no code changes required in the handlers.
 
+### GOAPDirector — GOAP-to-FSM bridge
+
+`GOAPDirector` bridges `GOAPPlanner` with the FSM. Register it as the `COMBAT`
+handler — when NPCs enter combat, the director replans and dispatches each
+action as a sub-state with full lifecycle management.
+
+```ts
+import { GOAPDirector } from '@alife-sdk/ai/goap';
+import type { IGOAPActionHandler } from '@alife-sdk/ai/goap';
+
+const director = new GOAPDirector(planner, {
+  buildWorldState: (ctx) => WorldState.from({
+    isHealthy: ctx.health!.hpPercent >= 0.5,
+    inCover:   ctx.state.hasTakenCover,
+    seeEnemy:  ctx.perception?.hasVisibleEnemy() ?? false,
+  }),
+  goal: WorldState.from({ targetEliminated: true }),
+  actionHandlers: {
+    TakeCover: {
+      enter(ctx) { ctx.pathfinding?.findPath(coverX, coverY); },
+      update(ctx, dt) { return ctx.pathfinding?.isNavigating() ? 'running' : 'success'; },
+      exit(ctx) {},
+    },
+    Suppress: {
+      enter(ctx) { /* start firing */ },
+      update(ctx, dt) { return shotsFired >= 4 ? 'success' : 'running'; },
+      exit(ctx) {},
+    },
+    Attack: {
+      enter(ctx) { /* engage */ },
+      update(ctx, dt) { return 'running'; }, // terminal — stays until interrupted
+      exit(ctx) {},
+    },
+  },
+  interrupts: [
+    { condition: ctx => ctx.state.moraleState === 'PANICKED', targetState: 'FLEE' },
+    { condition: ctx => ctx.health!.hpPercent < 0.2, targetState: 'WOUNDED' },
+  ],
+  onNoPlan: (ctx, dt) => { /* fallback when plan is empty */ },
+});
+
+handlers.register(ONLINE_STATE.COMBAT, director);
+```
+
+The director:
+- **Replans** on every entry (including after interrupts like WOUNDED → COMBAT)
+- **Dispatches** actions: calls `enter()` → `update()` each tick → `exit()` on success/failure
+- **Advances** to the next action on `'success'`, replans on `'failure'`
+- **Checks interrupts** every tick before the action handler runs
+- **Prevents infinite replans** — stops after 3 consecutive empty plans
+- Stores plan state in `ctx.state.custom` (keys prefixed with `__goap`)
+
+### IPathfindingAccess — pluggable pathfinding
+
+State handlers can use obstacle-aware navigation via the optional `IPathfindingAccess`
+subsystem. When provided, `moveAlongPath()` follows waypoints from the pathfinder
+instead of moving in a straight line.
+
+```ts
+// Host implements IPathfindingAccess (e.g. wrapping PathFinding.js, EasyStar, or NavMesh)
+class GridPathfinding implements IPathfindingAccess {
+  findPath(targetX, targetY) { /* A* search on grid */ }
+  getNextWaypoint()          { /* return next waypoint, advance cursor */ }
+  setPath(waypoints)         { /* replace current path */ }
+  isNavigating()             { /* true if cursor < path.length */ }
+  clearPath()                { /* stop following path */ }
+}
+
+// Wire to NPC context:
+const ctx = { ..., pathfinding: new GridPathfinding(npc) };
+
+// In action handlers:
+ctx.pathfinding?.findPath(target.x, target.y);  // compute path
+ctx.pathfinding?.isNavigating();                 // check if walking
+ctx.pathfinding?.clearPath();                    // stop
+```
+
+When `ctx.pathfinding` is null, all handlers fall back to direct straight-line movement.
+
 ### Cover system
 
 The cover module provides a full pipeline from raw cover points to per-NPC
@@ -417,10 +519,11 @@ number wins):
 | Priority | Goal | Trigger |
 |---|---|---|
 | 0 `CRITICALLY_WOUNDED` | Heal + disengage | `hpRatio <= healHpThreshold` |
-| 1 `ENEMY_PRESENT` | Eliminate enemy | `snapshot.enemyPresent` |
-| 2 `DANGER` | Evade danger | `snapshot.hasDanger` |
-| 3 `ANOMALY_AVOID` | Exit anomaly zone | `snapshot.nearAnomalyZone` |
-| 4 `DEFAULT` | Patrol / idle | always (fallback) |
+| 1 `PANIC_FLEE` | Flee (morale collapsed) | `isPanicked && hasDanger` |
+| 2 `ENEMY_PRESENT` | Eliminate enemy | `snapshot.enemyPresent` |
+| 3 `DANGER` | Evade danger | `snapshot.hasDanger` |
+| 4 `ANOMALY_AVOID` | Exit anomaly zone | `snapshot.nearAnomalyZone` |
+| 5 `DEFAULT` | Patrol / idle | always (fallback) |
 
 #### Integration example
 

package/dist/cover/CoverAccessAdapter.js

@@ -44,7 +44,7 @@ export class CoverAccessAdapter {
     // ICoverAccess
     // -------------------------------------------------------------------------
     findCover(x, y, enemyX, enemyY, type) {
-        const coverType = type ?? CoverTypeConst.BALANCED;
+        const coverType = type?.toLowerCase() ?? 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;

package/dist/cover/CoverAccessAdapter.js.map

@@ -1 +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"}
+{"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,IAAI,EAAE,WAAW,EAAgB,IAAI,cAAc,CAAC,QAAQ,CAAC;QAE3F,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/goap/GOAPDirector.d.ts

@@ -0,0 +1,89 @@
+import type { IOnlineStateHandler } from '../states/IOnlineStateHandler';
+import type { INPCContext } from '../states/INPCContext';
+import type { WorldState } from '@alife-sdk/core';
+/**
+ * Minimal planner interface — accepts any object with a `plan()` method.
+ * This allows passing a GOAPPlanner instance, a dynamic wrapper, or a mock.
+ */
+export interface IGOAPPlannerLike {
+    plan(worldState: WorldState, goal: WorldState): Array<{
+        id: string;
+    }> | null;
+}
+/**
+ * Handler for a single GOAP action execution.
+ *
+ * Stateless — per-NPC data should be stored in `ctx.state.custom`.
+ * Return 'running' to continue, 'success' to advance, 'failure' to replan.
+ */
+export interface IGOAPActionHandler {
+    /** Called when this action starts executing. */
+    enter(ctx: INPCContext): void;
+    /** Called each frame. */
+    update(ctx: INPCContext, deltaMs: number): 'running' | 'success' | 'failure';
+    /** Called when action completes or is interrupted. */
+    exit(ctx: INPCContext): void;
+}
+/**
+ * Interrupt condition — checked every tick before action execution.
+ * If condition returns true, the director transitions to targetState.
+ */
+export interface IGOAPInterrupt {
+    readonly condition: (ctx: INPCContext) => boolean;
+    readonly targetState: string;
+}
+/**
+ * Configuration for the GOAP Director.
+ */
+export interface IGOAPDirectorConfig {
+    /** Build a WorldState snapshot from the current NPC context. */
+    buildWorldState: (ctx: INPCContext) => WorldState;
+    /** The goal to achieve. */
+    goal: WorldState;
+    /** Map GOAP action ID to handler. Unmatched actions are skipped. */
+    actionHandlers: Record<string, IGOAPActionHandler>;
+    /** Interrupt conditions checked every tick (evaluated in order). */
+    interrupts?: IGOAPInterrupt[];
+    /** Called when the plan is empty or exhausted (optional fallback). */
+    onNoPlan?: (ctx: INPCContext, deltaMs: number) => void;
+}
+/**
+ * Built-in GOAP Director — register as the COMBAT handler.
+ *
+ * On enter: replans via the provided planner + buildWorldState.
+ * Each tick: checks interrupts, then ticks the active action handler.
+ * On action success: advances to next action.
+ * On action failure or plan exhaustion: replans.
+ *
+ * @example
+ * ```ts
+ * const director = new GOAPDirector(planner, {
+ *   buildWorldState: (ctx) => WorldState.from({ ... }),
+ *   goal: WorldState.from({ targetEliminated: true }),
+ *   actionHandlers: {
+ *     TakeCover: { enter(ctx) { ... }, update(ctx, dt) { return 'running'; }, exit(ctx) {} },
+ *     Attack:    { enter(ctx) { ... }, update(ctx, dt) { return 'success'; }, exit(ctx) {} },
+ *   },
+ *   interrupts: [
+ *     { condition: ctx => ctx.state.moraleState === 'PANICKED', targetState: 'FLEE' },
+ *   ],
+ * });
+ * handlers.register('COMBAT', director);
+ * ```
+ */
+export declare class GOAPDirector implements IOnlineStateHandler {
+    private readonly planner;
+    private readonly config;
+    constructor(planner: IGOAPPlannerLike, config: IGOAPDirectorConfig);
+    enter(ctx: INPCContext): void;
+    update(ctx: INPCContext, deltaMs: number): void;
+    exit(ctx: INPCContext): void;
+    /** Read a GOAP key from ctx.state.custom (always fresh, never cached). */
+    private _read;
+    /** Write a single GOAP key to ctx.state.custom (always fresh, never cached). */
+    private _write;
+    private _replan;
+    private _advanceAction;
+    private _exitCurrentAction;
+}
+//# sourceMappingURL=GOAPDirector.d.ts.map

package/dist/goap/GOAPDirector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GOAPDirector.d.ts","sourceRoot":"","sources":["../../src/goap/GOAPDirector.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;CAC9E;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B,yBAAyB;IACzB,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC7E,sDAAsD;IACtD,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,eAAe,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,UAAU,CAAC;IAClD,2BAA2B;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACnD,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACxD;AAQD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,YAAa,YAAW,mBAAmB;IAEpD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,mBAAmB;IAG9C,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAI7B,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAuD/C,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAQ5B,0EAA0E;IAC1E,OAAO,CAAC,KAAK;IAIb,gFAAgF;IAChF,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,kBAAkB;CAO3B"}

package/dist/goap/GOAPDirector.js

@@ -0,0 +1,142 @@
+// goap/GOAPDirector.ts
+// Built-in GOAP Director — bridges GOAPPlanner with the FSM.
+//
+// Register as the COMBAT state handler. On every entry the director
+// replans and dispatches actions as sub-states. Each action handler
+// reports running/success/failure; on success the director advances
+// to the next action. On failure or plan exhaustion the director
+// replans from scratch.
+//
+// Interrupts (morale panic, low HP, grenade) are checked every tick
+// and can abort the current action to transition to a built-in FSM state.
+// Custom state keys used by the director (stored in ctx.state.custom).
+const GOAP_PLAN_KEY = '__goapPlan';
+const GOAP_INDEX_KEY = '__goapIndex';
+const GOAP_HANDLER_KEY = '__goapActiveHandler';
+const GOAP_EMPTY_COUNT_KEY = '__goapEmptyCount';
+/**
+ * Built-in GOAP Director — register as the COMBAT handler.
+ *
+ * On enter: replans via the provided planner + buildWorldState.
+ * Each tick: checks interrupts, then ticks the active action handler.
+ * On action success: advances to next action.
+ * On action failure or plan exhaustion: replans.
+ *
+ * @example
+ * ```ts
+ * const director = new GOAPDirector(planner, {
+ *   buildWorldState: (ctx) => WorldState.from({ ... }),
+ *   goal: WorldState.from({ targetEliminated: true }),
+ *   actionHandlers: {
+ *     TakeCover: { enter(ctx) { ... }, update(ctx, dt) { return 'running'; }, exit(ctx) {} },
+ *     Attack:    { enter(ctx) { ... }, update(ctx, dt) { return 'success'; }, exit(ctx) {} },
+ *   },
+ *   interrupts: [
+ *     { condition: ctx => ctx.state.moraleState === 'PANICKED', targetState: 'FLEE' },
+ *   ],
+ * });
+ * handlers.register('COMBAT', director);
+ * ```
+ */
+export class GOAPDirector {
+    constructor(planner, config) {
+        this.planner = planner;
+        this.config = config;
+    }
+    enter(ctx) {
+        this._replan(ctx);
+    }
+    update(ctx, deltaMs) {
+        // 1. Check interrupts (highest priority).
+        if (this.config.interrupts) {
+            for (const interrupt of this.config.interrupts) {
+                if (interrupt.condition(ctx)) {
+                    this._exitCurrentAction(ctx);
+                    ctx.transition(interrupt.targetState);
+                    return;
+                }
+            }
+        }
+        // 2. Get current plan and action.
+        const plan = this._read(ctx, GOAP_PLAN_KEY);
+        const index = this._read(ctx, GOAP_INDEX_KEY) ?? 0;
+        if (!plan || index >= plan.length) {
+            if (this.config.onNoPlan) {
+                this.config.onNoPlan(ctx, deltaMs);
+            }
+            return;
+        }
+        // 3. Get or enter the action handler.
+        const action = plan[index];
+        const handler = this.config.actionHandlers[action.id];
+        if (!handler) {
+            this._advanceAction(ctx);
+            return;
+        }
+        const activeHandlerId = this._read(ctx, GOAP_HANDLER_KEY);
+        if (activeHandlerId !== action.id) {
+            if (activeHandlerId) {
+                const prevHandler = this.config.actionHandlers[activeHandlerId];
+                prevHandler?.exit(ctx);
+            }
+            handler.enter(ctx);
+            this._write(ctx, GOAP_HANDLER_KEY, action.id);
+        }
+        // 4. Tick the action handler.
+        const result = handler.update(ctx, deltaMs);
+        if (result === 'success') {
+            handler.exit(ctx);
+            this._write(ctx, GOAP_HANDLER_KEY, undefined);
+            this._advanceAction(ctx);
+        }
+        else if (result === 'failure') {
+            handler.exit(ctx);
+            this._write(ctx, GOAP_HANDLER_KEY, undefined);
+            this._replan(ctx);
+        }
+    }
+    exit(ctx) {
+        this._exitCurrentAction(ctx);
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    /** Read a GOAP key from ctx.state.custom (always fresh, never cached). */
+    _read(ctx, key) {
+        return (ctx.state.custom ?? {})[key];
+    }
+    /** Write a single GOAP key to ctx.state.custom (always fresh, never cached). */
+    _write(ctx, key, value) {
+        ctx.state.custom = { ...(ctx.state.custom ?? {}), [key]: value };
+    }
+    _replan(ctx) {
+        const ws = this.config.buildWorldState(ctx);
+        const plan = this.planner.plan(ws, this.config.goal);
+        const resultPlan = plan ?? [];
+        let emptyCount = this._read(ctx, GOAP_EMPTY_COUNT_KEY) ?? 0;
+        emptyCount = resultPlan.length === 0 ? emptyCount + 1 : 0;
+        this._write(ctx, GOAP_PLAN_KEY, resultPlan);
+        this._write(ctx, GOAP_INDEX_KEY, 0);
+        this._write(ctx, GOAP_HANDLER_KEY, undefined);
+        this._write(ctx, GOAP_EMPTY_COUNT_KEY, emptyCount);
+    }
+    _advanceAction(ctx) {
+        const index = (this._read(ctx, GOAP_INDEX_KEY) ?? 0) + 1;
+        const plan = this._read(ctx, GOAP_PLAN_KEY);
+        this._write(ctx, GOAP_INDEX_KEY, index);
+        if (!plan || index >= plan.length) {
+            const emptyCount = this._read(ctx, GOAP_EMPTY_COUNT_KEY) ?? 0;
+            if (emptyCount < 3) {
+                this._replan(ctx);
+            }
+        }
+    }
+    _exitCurrentAction(ctx) {
+        const activeId = this._read(ctx, GOAP_HANDLER_KEY);
+        if (activeId) {
+            this.config.actionHandlers[activeId]?.exit(ctx);
+            this._write(ctx, GOAP_HANDLER_KEY, undefined);
+        }
+    }
+}
+//# sourceMappingURL=GOAPDirector.js.map

package/dist/goap/GOAPDirector.js.map

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

package/dist/goap/index.d.ts

@@ -6,4 +6,6 @@ export { GOAPController } from './GOAPController';
 export type { IGOAPUpdateResult, IGOAPControllerState } from './GOAPController';
 export type { IHazardZoneAccess } from './IHazardZoneAccess';
 export { EvadeHazardAction } from './EvadeHazardAction';
+export { GOAPDirector } from './GOAPDirector';
+export type { IGOAPDirectorConfig, IGOAPActionHandler, IGOAPInterrupt, IGOAPPlannerLike } from './GOAPDirector';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/goap/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/goap/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/goap/index.js

@@ -3,4 +3,5 @@ export { buildWorldState, DEFAULT_WORLD_PROPERTY_BUILDERS } from './WorldStateBu
 export { selectGoal, DEFAULT_GOAL_RULES } from './GoalSelector';
 export { GOAPController } from './GOAPController';
 export { EvadeHazardAction } from './EvadeHazardAction';
+export { GOAPDirector } from './GOAPDirector';
 //# sourceMappingURL=index.js.map

package/dist/goap/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/goap/index.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,OAAO,EAAE,eAAe,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/goap/index.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,OAAO,EAAE,eAAe,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/states/INPCContext.d.ts

@@ -305,6 +305,62 @@ export interface ISuspicionAccess {
      */
     clear(): void;
 }
+/**
+ * Pathfinding query interface.
+ *
+ * Wraps the engine-specific pathfinding system (A*, NavMesh, etc.) so
+ * state handlers can request paths without importing game-layer classes.
+ *
+ * The host implements this interface by delegating to its pathfinding
+ * engine (e.g. PathFinding.js, EasyStar, or a NavMesh adapter).
+ *
+ * If not provided (`ctx.pathfinding === null`), state handlers fall back
+ * to direct straight-line movement via `moveToward()`.
+ */
+export interface IPathfindingAccess {
+    /**
+     * Compute a path from the NPC's current position to the target.
+     * The implementation should cache the result until `setPath()` or
+     * a new `findPath()` call replaces it.
+     *
+     * @param targetX - Destination world X (px).
+     * @param targetY - Destination world Y (px).
+     * @returns Array of world-space waypoints, or null if no path exists.
+     */
+    findPath(targetX: number, targetY: number): ReadonlyArray<{
+        x: number;
+        y: number;
+    }> | null;
+    /**
+     * Get the next waypoint the NPC should move toward.
+     * Manages an internal cursor — advances when the NPC reaches each waypoint.
+     *
+     * @returns Next waypoint, or null if path is complete or no path is set.
+     */
+    getNextWaypoint(): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Replace the current path with new waypoints.
+     * Resets the internal cursor to the first waypoint.
+     *
+     * @param waypoints - World-space path waypoints.
+     */
+    setPath(waypoints: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>): void;
+    /**
+     * True if the NPC is actively following a path (cursor not at end).
+     */
+    isNavigating(): boolean;
+    /**
+     * Stop following the current path and clear waypoints.
+     * After this call, `isNavigating()` returns false.
+     */
+    clearPath(): void;
+}
 /**
  * Squad communication interface.
  *
@@ -531,6 +587,14 @@ export interface INPCContext {
      * PatrolState and IdleState use this to detect accumulated threat and trigger ALERT.
      */
     readonly suspicion: ISuspicionAccess | null;
+    /**
+     * Pathfinding system accessor, or null if no pathfinding is registered.
+     *
+     * When provided, state handlers can use `moveAlongPath()` instead of
+     * `moveToward()` for obstacle-aware navigation. When null, handlers
+     * fall back to direct straight-line movement.
+     */
+    readonly pathfinding: IPathfindingAccess | null;
     /**
      * Return the current elapsed time in milliseconds.
      *

package/dist/states/INPCContext.d.ts.map

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

package/dist/states/INPCOnlineState.d.ts

@@ -228,5 +228,27 @@ export interface INPCOnlineState {
      * - PANICKED : morale <= panicMoraleThreshold
      */
     moraleState: 'STABLE' | 'SHAKEN' | 'PANICKED';
+    /**
+     * Extensible key-value bag for game-specific data.
+     *
+     * Use this for data that doesn't fit the built-in fields: GOAP plans,
+     * ammo counts, personality tags, enemy velocity tracking, etc.
+     *
+     * Handlers access it via `ctx.state.custom?.myKey`. The SDK never
+     * reads or writes this field — it's entirely owned by the game layer.
+     *
+     * **Key namespacing:** To avoid collisions between different systems
+     * writing to `custom`, prefix your keys. The SDK reserves the `__goap`
+     * prefix for the built-in GOAPDirector. Example: `custom.__goapPlan`.
+     * Game code should use its own prefix: `custom.myGame_ammo`.
+     *
+     * @example
+     * ```ts
+     * ctx.state.custom ??= {};
+     * ctx.state.custom.goapPlan = planner.plan(ws, goal);
+     * ctx.state.custom.ammo = 30;
+     * ```
+     */
+    custom?: Record<string, unknown>;
 }
 //# sourceMappingURL=INPCOnlineState.d.ts.map

package/dist/states/INPCOnlineState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"INPCOnlineState.d.ts","sourceRoot":"","sources":["../../src/states/INPCOnlineState.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"INPCOnlineState.d.ts","sourceRoot":"","sources":["../../src/states/INPCOnlineState.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAMpE;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3C,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,MAAM,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB,kFAAkF;IAClF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC;IAChB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAK9B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IAExB,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAM1B,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IAErB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IAEtB,+FAA+F;IAC/F,oBAAoB,EAAE,MAAM,CAAC;IAE7B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IAEpB,kDAAkD;IAClD,kBAAkB,EAAE,MAAM,CAAC;IAE3B,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IAEtB,kEAAkE;IAClE,qBAAqB,EAAE,MAAM,CAAC;IAE9B,8DAA8D;IAC9D,mBAAmB,EAAE,MAAM,CAAC;IAE5B,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IAErB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B,gHAAgH;IAChH,cAAc,EAAE,MAAM,CAAC;IAEvB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IAErB,oDAAoD;IACpD,kBAAkB,EAAE,MAAM,CAAC;IAE3B,+GAA+G;IAC/G,4BAA4B,EAAE,MAAM,CAAC;IAMrC,0EAA0E;IAC1E,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAC;IAE3B,yGAAyG;IACzG,wBAAwB,EAAE,MAAM,CAAC;IAEjC,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;IAErB,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;IAMrB,2EAA2E;IAC3E,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAC;IAE3B,qEAAqE;IACrE,qBAAqB,EAAE,MAAM,CAAC;IAE9B,yEAAyE;IACzE,uBAAuB,EAAE,MAAM,CAAC;IAEhC,kFAAkF;IAClF,yBAAyB,EAAE,MAAM,CAAC;IAElC,iEAAiE;IACjE,qBAAqB,EAAE,MAAM,CAAC;IAE9B,4EAA4E;IAC5E,uBAAuB,EAAE,MAAM,CAAC;IAEhC,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAC;IAE3B,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAC;IAM3B,2GAA2G;IAC3G,mBAAmB,EAAE,MAAM,CAAC;IAM5B,mEAAmE;IACnE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,+EAA+E;IAC/E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IAMpB,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IAEjB,wDAAwD;IACxD,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB,8FAA8F;IAC9F,WAAW,EAAE,MAAM,CAAC;IAEpB,8FAA8F;IAC9F,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAEhC;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAM1B,+BAA+B;IAC/B,WAAW,CAAC,EAAE,YAAY,CAAC;IAE3B,uCAAuC;IACvC,UAAU,CAAC,EAAE,WAAW,CAAC;IAEzB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,UAAU,CAAC;IAEvB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;OAIG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;IAEjC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAM5B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,WAAW,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IAM9C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC"}

package/dist/states/NPCOnlineState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NPCOnlineState.d.ts","sourceRoot":"","sources":["../../src/states/NPCOnlineState.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,IAAI,eAAe,CA+D7D"}
+{"version":3,"file":"NPCOnlineState.d.ts","sourceRoot":"","sources":["../../src/states/NPCOnlineState.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,IAAI,eAAe,CAkE7D"}

package/dist/states/NPCOnlineState.js

@@ -71,6 +71,8 @@ export function createDefaultNPCOnlineState() {
         // Morale
         morale: 0,
         moraleState: 'STABLE',
+        // Extensible game-specific state
+        custom: {},
     };
 }
 //# sourceMappingURL=NPCOnlineState.js.map

package/dist/states/NPCOnlineState.js.map

@@ -1 +1 @@
-{"version":3,"file":"NPCOnlineState.js","sourceRoot":"","sources":["../../src/states/NPCOnlineState.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,2EAA2E;AAI3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,kBAAkB;QAClB,QAAQ,EAAE,IAAI;QACd,eAAe,EAAE,CAAC;QAClB,eAAe,EAAE,CAAC;QAClB,iBAAiB,EAAE,CAAC;QAEpB,8DAA8D;QAC9D,YAAY,EAAE,CAAC;QACf,aAAa,EAAE,CAAC;QAChB,oBAAoB,EAAE,CAAC;QACvB,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,kBAAkB,EAAE,CAAC;QACrB,aAAa,EAAE,CAAC;QAChB,qBAAqB,EAAE,CAAC;QACxB,mBAAmB,EAAE,CAAC;QACtB,YAAY,EAAE,CAAC;QACf,cAAc,EAAE,CAAC;QACjB,oBAAoB,EAAE,CAAC;QACvB,cAAc,EAAE,CAAC;QACjB,YAAY,EAAE,CAAC;QACf,kBAAkB,EAAE,CAAC;QACrB,4BAA4B,EAAE,CAAC,CAAC;QAEhC,mBAAmB,EAAE,IAAI;QACzB,kBAAkB,EAAE,CAAC;QACrB,wBAAwB,EAAE,CAAC,CAAC;QAC5B,YAAY,EAAE,CAAC;QACf,YAAY,EAAE,CAAC;QAEf,mBAAmB,EAAE,IAAI;QACzB,kBAAkB,EAAE,CAAC;QACrB,qBAAqB,EAAE,CAAC,CAAC;QACzB,uBAAuB,EAAE,CAAC,CAAC;QAC3B,yBAAyB,EAAE,CAAC,CAAC;QAC7B,qBAAqB,EAAE,CAAC;QACxB,uBAAuB,EAAE,CAAC,CAAC;QAC3B,kBAAkB,EAAE,CAAC;QACrB,kBAAkB,EAAE,CAAC;QAErB,mBAAmB,EAAE,CAAC;QAEtB,UAAU;QACV,aAAa,EAAE,IAAI;QACnB,eAAe,EAAE,IAAI;QACrB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,CAAC;QAEd,cAAc;QACd,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,KAAK;QACpB,eAAe,EAAE,CAAC;QAClB,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,QAAQ,EAAE,IAAI;QACd,iBAAiB,EAAE,CAAC;QAEpB,SAAS;QACT,MAAM,EAAE,CAAC;QACT,WAAW,EAAE,QAAQ;KACtB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"NPCOnlineState.js","sourceRoot":"","sources":["../../src/states/NPCOnlineState.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,2EAA2E;AAI3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,kBAAkB;QAClB,QAAQ,EAAE,IAAI;QACd,eAAe,EAAE,CAAC;QAClB,eAAe,EAAE,CAAC;QAClB,iBAAiB,EAAE,CAAC;QAEpB,8DAA8D;QAC9D,YAAY,EAAE,CAAC;QACf,aAAa,EAAE,CAAC;QAChB,oBAAoB,EAAE,CAAC;QACvB,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,kBAAkB,EAAE,CAAC;QACrB,aAAa,EAAE,CAAC;QAChB,qBAAqB,EAAE,CAAC;QACxB,mBAAmB,EAAE,CAAC;QACtB,YAAY,EAAE,CAAC;QACf,cAAc,EAAE,CAAC;QACjB,oBAAoB,EAAE,CAAC;QACvB,cAAc,EAAE,CAAC;QACjB,YAAY,EAAE,CAAC;QACf,kBAAkB,EAAE,CAAC;QACrB,4BAA4B,EAAE,CAAC,CAAC;QAEhC,mBAAmB,EAAE,IAAI;QACzB,kBAAkB,EAAE,CAAC;QACrB,wBAAwB,EAAE,CAAC,CAAC;QAC5B,YAAY,EAAE,CAAC;QACf,YAAY,EAAE,CAAC;QAEf,mBAAmB,EAAE,IAAI;QACzB,kBAAkB,EAAE,CAAC;QACrB,qBAAqB,EAAE,CAAC,CAAC;QACzB,uBAAuB,EAAE,CAAC,CAAC;QAC3B,yBAAyB,EAAE,CAAC,CAAC;QAC7B,qBAAqB,EAAE,CAAC;QACxB,uBAAuB,EAAE,CAAC,CAAC;QAC3B,kBAAkB,EAAE,CAAC;QACrB,kBAAkB,EAAE,CAAC;QAErB,mBAAmB,EAAE,CAAC;QAEtB,UAAU;QACV,aAAa,EAAE,IAAI;QACnB,eAAe,EAAE,IAAI;QACrB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,CAAC;QAEd,cAAc;QACd,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,KAAK;QACpB,eAAe,EAAE,CAAC;QAClB,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,QAAQ,EAAE,IAAI;QACd,iBAAiB,EAAE,CAAC;QAEpB,SAAS;QACT,MAAM,EAAE,CAAC;QACT,WAAW,EAAE,QAAQ;QAErB,iCAAiC;QACjC,MAAM,EAAE,EAAE;KACX,CAAC;AACJ,CAAC"}

package/dist/states/OnlineAIDriver.d.ts

@@ -36,6 +36,8 @@ export declare class OnlineAIDriver {
     private readonly ctx;
     /** True while a transition is in progress (guards against re-entrant transitions). */
     private _transitioning;
+    /** Transition event listeners. */
+    private _transitionListeners;
     /** True after destroy() has been called. Guards against use-after-destroy. */
     private _destroyed;
     constructor(host: IOnlineDriverHost, handlers: StateHandlerMap | ReadonlyMap<string, IOnlineStateHandler>, initialState: string);
@@ -57,6 +59,38 @@ export declare class OnlineAIDriver {
      * Call when the NPC entity is destroyed or the scene shuts down.
      */
     destroy(): void;
+    /**
+     * Force an FSM state transition from outside the handler.
+     *
+     * Calls exit() on the current state and enter() on the new one,
+     * exactly like an internal ctx.transition() call. Useful for
+     * GOAP directors, scripted events, or any external system that
+     * needs to steer the FSM.
+     *
+     * No-op if the driver has been destroyed.
+     * Re-entrant calls are silently ignored (same as internal transitions).
+     *
+     * @param newStateId - Target state identifier.
+     */
+    forceTransition(newStateId: string): void;
+    /**
+     * Register a callback that fires after every state transition.
+     *
+     * Returns an unsubscribe function. Listeners fire synchronously
+     * after enter() completes on the new state, in registration order.
+     *
+     * @param cb - Callback receiving the previous and new state IDs.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsub = driver.onTransition((from, to) => {
+     *   console.log(`${npcId}: ${from} → ${to}`);
+     * });
+     * // Later: unsub();
+     * ```
+     */
+    onTransition(cb: (from: string, to: string) => void): () => void;
     /** @internal Called by {@link DriverContext.transition}. */
     _doTransition(newStateId: string): void;
     private getHandler;

package/dist/states/OnlineAIDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OnlineAIDriver.d.ts","sourceRoot":"","sources":["../../src/states/OnlineAIDriver.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMpD;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,gBAAgB,CAAC,CAAC;AAMnF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAElC,sFAAsF;IACtF,OAAO,CAAC,cAAc,CAAS;IAE/B,8EAA8E;IAC9E,OAAO,CAAC,UAAU,CAAS;gBAGzB,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACpE,YAAY,EAAE,MAAM;IAkBtB,gDAAgD;IAChD,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7B;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAUf,4DAA4D;IAC5D,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAqBvC,OAAO,CAAC,UAAU;CAOnB"}
+{"version":3,"file":"OnlineAIDriver.d.ts","sourceRoot":"","sources":["../../src/states/OnlineAIDriver.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMpD;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,gBAAgB,CAAC,CAAC;AAMnF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAElC,sFAAsF;IACtF,OAAO,CAAC,cAAc,CAAS;IAE/B,kCAAkC;IAClC,OAAO,CAAC,oBAAoB,CAAiD;IAE7E,8EAA8E;IAC9E,OAAO,CAAC,UAAU,CAAS;gBAGzB,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACpE,YAAY,EAAE,MAAM;IAkBtB,gDAAgD;IAChD,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7B;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAMf;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKzC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAWhE,4DAA4D;IAC5D,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAyBvC,OAAO,CAAC,UAAU;CAOnB"}

package/dist/states/OnlineAIDriver.js

@@ -39,6 +39,8 @@ export class OnlineAIDriver {
     constructor(host, handlers, initialState) {
         /** True while a transition is in progress (guards against re-entrant transitions). */
         this._transitioning = false;
+        /** Transition event listeners. */
+        this._transitionListeners = [];
         /** True after destroy() has been called. Guards against use-after-destroy. */
         this._destroyed = false;
         this.handlers = handlers instanceof StateHandlerMap ? handlers.toMap() : handlers;
@@ -82,6 +84,47 @@ export class OnlineAIDriver {
         this._destroyed = true;
         this.getHandler(this._currentStateId).exit(this.ctx);
     }
+    /**
+     * Force an FSM state transition from outside the handler.
+     *
+     * Calls exit() on the current state and enter() on the new one,
+     * exactly like an internal ctx.transition() call. Useful for
+     * GOAP directors, scripted events, or any external system that
+     * needs to steer the FSM.
+     *
+     * No-op if the driver has been destroyed.
+     * Re-entrant calls are silently ignored (same as internal transitions).
+     *
+     * @param newStateId - Target state identifier.
+     */
+    forceTransition(newStateId) {
+        if (this._destroyed)
+            return;
+        this._doTransition(newStateId);
+    }
+    /**
+     * Register a callback that fires after every state transition.
+     *
+     * Returns an unsubscribe function. Listeners fire synchronously
+     * after enter() completes on the new state, in registration order.
+     *
+     * @param cb - Callback receiving the previous and new state IDs.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsub = driver.onTransition((from, to) => {
+     *   console.log(`${npcId}: ${from} → ${to}`);
+     * });
+     * // Later: unsub();
+     * ```
+     */
+    onTransition(cb) {
+        this._transitionListeners.push(cb);
+        return () => {
+            this._transitionListeners = this._transitionListeners.filter(l => l !== cb);
+        };
+    }
     // -------------------------------------------------------------------------
     // Internal — called by DriverContext
     // -------------------------------------------------------------------------
@@ -93,10 +136,15 @@ export class OnlineAIDriver {
             return;
         }
         this._transitioning = true;
+        const previousStateId = this._currentStateId;
         try {
             this.getHandler(this._currentStateId).exit(this.ctx);
             this._currentStateId = newStateId;
             this.getHandler(newStateId).enter(this.ctx);
+            // Copy to avoid issues if a listener unsubscribes during iteration.
+            const listeners = [...this._transitionListeners];
+            for (const cb of listeners)
+                cb(previousStateId, newStateId);
         }
         finally {
             this._transitioning = false;
@@ -149,6 +197,7 @@ class DriverContext {
     get pack() { return this.host.pack; }
     get conditions() { return this.host.conditions; }
     get suspicion() { return this.host.suspicion; }
+    get pathfinding() { return this.host.pathfinding; }
     // Movement & rendering — delegate to host
     setVelocity(vx, vy) { this.host.setVelocity(vx, vy); }
     halt() { this.host.halt(); }

package/dist/states/OnlineAIDriver.js.map

@@ -1 +1 @@
-{"version":3,"file":"OnlineAIDriver.js","sourceRoot":"","sources":["../../src/states/OnlineAIDriver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"OnlineAIDriver.js","sourceRoot":"","sources":["../../src/states/OnlineAIDriver.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,8CAA8C;AAC9C,EAAE;AACF,QAAQ;AACR,kEAAkE;AAClE,2DAA2D;AAC3D,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,mCAAmC;AACnC,EAAE;AACF,sCAAsC;AACtC,qCAAqC;AACrC,qDAAqD;AAIrD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAkBpD,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,cAAc;IAczB,YACE,IAAuB,EACvB,QAAoE,EACpE,YAAoB;QAZtB,sFAAsF;QAC9E,mBAAc,GAAG,KAAK,CAAC;QAE/B,kCAAkC;QAC1B,yBAAoB,GAA8C,EAAE,CAAC;QAE7E,8EAA8E;QACtE,eAAU,GAAG,KAAK,CAAC;QAOzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,YAAY,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAClF,IAAI,CAAC,eAAe,GAAG,YAAY,CAAC;QAEpC,6EAA6E;QAC7E,4DAA4D;QAC5D,MAAM,MAAM,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,GAAG,GAAG,IAAI,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAE3C,qCAAqC;QACrC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAED,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E,gDAAgD;IAChD,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAe;QACpB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,UAAkB;QAChC,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAsC;QACjD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9E,CAAC,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,qCAAqC;IACrC,4EAA4E;IAE5E,4DAA4D;IAC5D,aAAa,CAAC,UAAkB;QAC9B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,wEAAwE;YACxE,0EAA0E;YAC1E,OAAO;QACT,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;QAC7C,IAAI,CAAC;YACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACrD,IAAI,CAAC,eAAe,GAAG,UAAU,CAAC;YAClC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5C,oEAAoE;YACpE,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACjD,KAAK,MAAM,EAAE,IAAI,SAAS;gBAAE,EAAE,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC9D,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,kBAAkB;IAClB,4EAA4E;IAEpE,UAAU,CAAC,OAAe;QAChC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,oDAAoD,OAAO,GAAG,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;CACF;AAED,8EAA8E;AAC9E,+CAA+C;AAC/C,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,aAAa;IACjB,YACmB,IAAuB,EACvB,MAAsB;QADtB,SAAI,GAAJ,IAAI,CAAmB;QACvB,WAAM,GAAN,MAAM,CAAgB;IACtC,CAAC;IAEJ,WAAW;IACX,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvC,IAAI,SAAS,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/C,IAAI,UAAU,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjD,WAAW;IACX,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/B,uBAAuB;IACvB,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAEvC,sBAAsB;IACtB,IAAI,UAAU,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IACjD,IAAI,MAAM,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACzC,IAAI,eAAe,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;IAC3D,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,IAAI,UAAU,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IACjD,IAAI,SAAS,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/C,IAAI,WAAW,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAEnD,0CAA0C;IAC1C,WAAW,CAAC,EAAU,EAAE,EAAU,IAAU,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,KAAW,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClC,WAAW,CAAC,CAAS,IAAU,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,CAAS,IAAU,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,CAAS,EAAE,CAAS,IAAU,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClE,cAAc,KAAW,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;IAEtD,gCAAgC;IAChC,IAAI,cAAc,KAAa,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;IACnE,UAAU,CAAC,UAAkB,IAAU,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAE/E,oCAAoC;IACpC,SAAS,CAAC,CAA0C,IAAU,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,YAAY,CAAC,CAA6C,IAAU,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChG,gBAAgB,CAAC,CAAS,IAAU,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,kBAAkB,CAAC,CAAS,EAAE,CAAS,IAAU,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtF,+BAA+B;IAC/B,GAAG,KAAa,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACzC,MAAM,KAAa,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;CAChD"}

package/dist/states/handlers/_utils.d.ts

@@ -20,6 +20,27 @@ export declare function angleToward(ax: number, ay: number, bx: number, by: numb
  * avoid jitter; no rotation change is applied.
  */
 export declare function moveToward(ctx: INPCContext, targetX: number, targetY: number, speed: number): void;
+/**
+ * Move an NPC along a pathfinding-computed route, falling back to direct
+ * movement if no pathfinding system is available.
+ *
+ * When `ctx.pathfinding` is present:
+ *   1. If not currently navigating, computes a new path to (targetX, targetY).
+ *   2. Reads the next waypoint from the path cursor.
+ *   3. Moves toward that waypoint using `moveToward()` (which applies steering).
+ *
+ * When `ctx.pathfinding` is null:
+ *   Falls back to `moveToward(ctx, targetX, targetY, speed)` — direct movement.
+ *
+ * **Path lifecycle:** `findPath()` is called only when `isNavigating()` returns
+ * false (path complete or not started). The host's `IPathfindingAccess` implementation
+ * is responsible for detecting when the target has moved significantly and invalidating
+ * the current path by returning `isNavigating() === false`.
+ *
+ * Handlers can use this as a drop-in replacement for `moveToward()` to gain
+ * obstacle avoidance without changing their logic.
+ */
+export declare function moveAlongPath(ctx: INPCContext, targetX: number, targetY: number, speed: number): void;
 /**
  * Set the NPC's velocity so it moves directly away from (fromX, fromY) at the
  * given speed (px/s). Also updates the NPC's rotation to face away.

package/dist/states/handlers/_utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_utils.d.ts","sourceRoot":"","sources":["../../../src/states/handlers/_utils.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAyC,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACxH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAElF;AAKD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,IAAI,CAqBN;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,IAAI,CAcN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,aAAa,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,SAAO,GACZ,IAAI,CAMN;AAID,OAAO,EAAE,2BAA2B,EAAE,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"_utils.d.ts","sourceRoot":"","sources":["../../../src/states/handlers/_utils.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAyC,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACxH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAElF;AAKD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,IAAI,CAqBN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,IAAI,CAiBN;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,IAAI,CAcN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,aAAa,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,SAAO,GACZ,IAAI,CAMN;AAID,OAAO,EAAE,2BAA2B,EAAE,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/states/handlers/_utils.js

@@ -48,6 +48,42 @@ export function moveToward(ctx, targetX, targetY, speed) {
         ctx.setRotation(Math.atan2(dy, dx));
     }
 }
+/**
+ * Move an NPC along a pathfinding-computed route, falling back to direct
+ * movement if no pathfinding system is available.
+ *
+ * When `ctx.pathfinding` is present:
+ *   1. If not currently navigating, computes a new path to (targetX, targetY).
+ *   2. Reads the next waypoint from the path cursor.
+ *   3. Moves toward that waypoint using `moveToward()` (which applies steering).
+ *
+ * When `ctx.pathfinding` is null:
+ *   Falls back to `moveToward(ctx, targetX, targetY, speed)` — direct movement.
+ *
+ * **Path lifecycle:** `findPath()` is called only when `isNavigating()` returns
+ * false (path complete or not started). The host's `IPathfindingAccess` implementation
+ * is responsible for detecting when the target has moved significantly and invalidating
+ * the current path by returning `isNavigating() === false`.
+ *
+ * Handlers can use this as a drop-in replacement for `moveToward()` to gain
+ * obstacle avoidance without changing their logic.
+ */
+export function moveAlongPath(ctx, targetX, targetY, speed) {
+    if (ctx.pathfinding) {
+        // Start a new path if not currently navigating.
+        if (!ctx.pathfinding.isNavigating()) {
+            ctx.pathfinding.findPath(targetX, targetY);
+        }
+        // Follow the next waypoint.
+        const wp = ctx.pathfinding.getNextWaypoint();
+        if (wp) {
+            moveToward(ctx, wp.x, wp.y, speed);
+            return;
+        }
+    }
+    // Fallback: direct straight-line movement (existing behavior).
+    moveToward(ctx, targetX, targetY, speed);
+}
 /**
  * Set the NPC's velocity so it moves directly away from (fromX, fromY) at the
  * given speed (px/s). Also updates the NPC's rotation to face away.

package/dist/states/handlers/_utils.js.map

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

package/dist/states/index.d.ts

@@ -3,7 +3,7 @@ export { createDefaultStateConfig } from './IStateConfig';
 export * from './IStateTransitionMap';
 export type { ILoopholeState, IChargePhase, IStalkPhase, ILeapPhase, IPsiPhase, INPCOnlineState, } from './INPCOnlineState';
 export { createDefaultNPCOnlineState } from './NPCOnlineState';
-export type { INPCPerception, INPCHealth, ICoverAccess, IDangerAccess, IRestrictedZoneAccess, ISquadAccess, IConditionAccess, ISuspicionAccess, IShootPayload, IMeleeHitPayload, INPCContext, } from './INPCContext';
+export type { INPCPerception, INPCHealth, ICoverAccess, IDangerAccess, IRestrictedZoneAccess, ISquadAccess, IConditionAccess, ISuspicionAccess, IPathfindingAccess, IShootPayload, IMeleeHitPayload, INPCContext, } from './INPCContext';
 export type { IPackAccess, IPackTarget, PackAlertLevel } from './pack/IPackAccess';
 export { PACK_ALERT_ORDER } from './pack/IPackAccess';
 export type { IOnlineStateHandler } from './IOnlineStateHandler';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/states/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAClH,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,cAAc,uBAAuB,CAAC;AAEtC,YAAY,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAE/D,YAAY,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,cAAc,kBAAkB,CAAC;AAEjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/states/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAClH,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,cAAc,uBAAuB,CAAC;AAEtC,YAAY,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAE/D,YAAY,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,cAAc,kBAAkB,CAAC;AAEjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/states/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/states/index.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,8DAA8D;AAG9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,cAAc,uBAAuB,CAAC;AAWtC,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAiB/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/states/index.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,8DAA8D;AAG9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,cAAc,uBAAuB,CAAC;AAWtC,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAkB/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alife-sdk/ai",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Online frame-based NPC behavior system",
   "type": "module",
   "sideEffects": false,