@alife-sdk/ai 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,385 @@
+# @alife-sdk/ai
+
+Online frame-based NPC behavior system.
+
+Engine-agnostic. Works with Phaser, PixiJS, Node.js, or any other runtime.
+Depends on [`@alife-sdk/core`](../alife-core/README.md).
+
+```
+npm install @alife-sdk/ai
+```
+
+---
+
+## What this package does
+
+`@alife-sdk/ai` drives every online NPC — an NPC that is within the player's
+view and must behave in real-time.
+
+- **State machine driver** — `OnlineAIDriver` + `StateHandlerMap` runs a per-NPC FSM
+  over 18 built-in states (idle, patrol, combat, flee, wounded, monster abilities, …)
+- **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
+- **Squad tactics** — situational assessment, 6 commands, shared target table
+- **Animation** — 8-direction state→key mapping, layered debounced controller
+- **Suspicion** — stimulus accumulation → alert threshold crossing
+- **Conditions** — multi-channel boolean state for dialogue / event gating
+
+The package is intentionally engine-agnostic. All engine interaction goes
+through **ports** — narrow interfaces you implement once for your engine.
+
+---
+
+## Quick start
+
+> `buildNPCContext` and `liveDrivers` below are **your** code, not SDK exports.
+> `INPCContext` is an interface — you assemble it once per NPC from your engine objects.
+> See the [Key concepts → INPCContext](#inpccontext--narrow-access-interfaces) section for the full interface shape.
+
+```ts
+import { ALifeKernel }               from '@alife-sdk/core';
+import { AIPlugin }                  from '@alife-sdk/ai/plugin';
+import { buildDefaultHandlerMap,
+         OnlineAIDriver,
+         ONLINE_STATE }              from '@alife-sdk/ai/states';
+import { SeededRandom }              from '@alife-sdk/core/ports';
+
+// 1. Set up the kernel (see @alife-sdk/core quick start for full kernel setup)
+const kernel = new ALifeKernel({ /* your engine adapters */ });
+
+// 2. Install AIPlugin — owns shared cover registry and restricted zones
+const random = new SeededRandom(42);
+const aiPlugin = new AIPlugin(random);
+kernel.use(aiPlugin);
+
+await kernel.init();
+
+// 3. Build a handler map — one instance, shared across all human NPCs
+const handlers = buildDefaultHandlerMap({ combatRange: 350, meleeRange: 60 });
+
+// 4. Create an OnlineAIDriver per NPC (in your spawn / online transition)
+function spawnNPC(npcId: string): OnlineAIDriver {
+  const coverAccess = aiPlugin.createCoverAccess(npcId);
+  // buildNPCContext — your function that assembles INPCContext from engine objects
+  // (perception adapter, health adapter, cover access, danger access, etc.)
+  const ctx = buildNPCContext(npcId, coverAccess);
+  return new OnlineAIDriver(ctx, handlers, ONLINE_STATE.IDLE);
+}
+
+// 5. Game loop — call update() on each live driver
+// liveDrivers — your Map/Array of active OnlineAIDriver instances
+function update(deltaMs: number): void {
+  kernel.update(deltaMs);           // A-Life tick + events flush
+  for (const driver of liveDrivers) {
+    driver.update(deltaMs);         // per-NPC state machine
+  }
+}
+
+// 6. Read current state
+const state = driver.currentState; // e.g. 'COMBAT'
+
+// 7. Force a state transition (e.g. on NPC death)
+driver.transitionTo(ONLINE_STATE.DEAD);
+```
+
+---
+
+## Sub-path imports
+
+Each module has its own import path for optimal tree-shaking:
+
+| Import path | What's inside | Module docs |
+|-------------|--------------|-------------|
+| `@alife-sdk/ai` | Full re-export of all sub-modules | [src/](src/) |
+| `@alife-sdk/ai/plugin` | `AIPlugin`, `IAIPluginConfig` | [plugin/](src/plugin/) |
+| `@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`, `filterFreshIntel` | [perception/](src/perception/) |
+| `@alife-sdk/ai/goap` | `GOAPController`, `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` | `getAnimationKey`, `AnimationController`, `DirectionCache` | [animation/](src/animation/) |
+| `@alife-sdk/ai/sound` | `VocalizationType`, `VocalizationTracker` | [sound/](src/sound/) |
+| `@alife-sdk/ai/suspicion` | `SuspicionAccumulator`, `SuspicionStimuli` | [suspicion/](src/suspicion/) |
+| `@alife-sdk/ai/conditions` | `ConditionBank`, `ConditionChannels` | [conditions/](src/conditions/) |
+| `@alife-sdk/ai/combat` | Combat helpers for online NPC state handlers | [combat/](src/combat/) |
+| `@alife-sdk/ai/types` | Shared interfaces (`INPCContext`, `INPCOnlineState`, …) | [types/](src/types/) |
+| `@alife-sdk/ai/config` | `IStateConfig`, default config helpers | [config/](src/config/) |
+| `@alife-sdk/ai/ports` | AI-specific port interfaces | [ports/](src/ports/) |
+
+---
+
+## Architecture
+
+```
+                ┌────────────────────────────────────────┐
+                │              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                   │
+                └──────────────────────────────────────────────────────┘
+
+Shared systems (optional, compose as needed):
+  NPCSensors            filterVisibleEntities / filterHearingEntities
+  GOAPController        elite NPC A* planning (rank ≥ 5)
+  SmoothPathFollower    Catmull-Rom + Dubins arc path cursor
+  AnimationController   layered, debounced animation dispatch
+  SuspicionAccumulator  stimulus → alert threshold crossing
+  ConditionBank         multi-channel boolean state
+```
+
+---
+
+## Key concepts
+
+### OnlineAIDriver — per-NPC state machine
+
+`OnlineAIDriver` is created once per NPC when it enters the online zone
+and destroyed when it goes offline. It ticks one `IOnlineStateHandler`
+per frame: `enter → update (every frame) → exit`.
+
+```ts
+const driver = new OnlineAIDriver(ctx, handlers, ONLINE_STATE.IDLE);
+
+driver.update(deltaMs);             // call every frame
+driver.currentState;                // current state ID string
+driver.transitionTo('PATROL');      // force transition
+```
+
+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.
+
+### StateHandlerMap — three built-in presets
+
+Choose the right preset for your entity type:
+
+| Builder function | States | Use for |
+|-----------------|--------|---------|
+| `buildDefaultHandlerMap()` | 14 (core + `CombatState`) | Human NPCs — ranged weapons, cover, grenades |
+| `buildMonsterHandlerMap()` | 14 (core + `MonsterCombatController`) | Monsters — melee only, no special abilities |
+| `buildChornobylMonsterHandlerMap()` | 18 (core + controller + 4 abilities) | Stalker-style monsters: `CHARGE / STALK / LEAP / PSI_ATTACK` |
+
+All three return a fresh `StateHandlerMap` you can extend with `.register()`:
+
+```ts
+// Add a custom HUNT state to the default human map
+const handlers = buildDefaultHandlerMap({ combatRange: 300 })
+  .register('HUNT', new HuntState(cfg));
+```
+
+Monster ability states map to entity types via `CHORNOBYL_ABILITY_SELECTOR`
+(or your own `IMonsterAbilityRule[]`):
+
+| Type | Ability state |
+|------|--------------|
+| `boar` | `CHARGE` — windup → ram at 2× speed |
+| `bloodsucker` | `STALK` — go invisible (alpha 0.08) → approach |
+| `snork` | `LEAP` — windup → airborne lerp → land |
+| `controller` | `PSI_ATTACK` — channel 2 s → PSI area damage |
+
+### AIPlugin — shared world state
+
+`AIPlugin` owns the data structures that must be shared across all NPCs:
+
+- `CoverRegistry` — all cover points in the scene
+- `CoverLockRegistry` — TTL-based locking so two NPCs don't pick the same cover
+- `RestrictedZoneManager` — zones where NPCs cannot enter / must leave
+
+Install it once, then get a per-NPC adapter from `createCoverAccess(npcId)`:
+
+```ts
+const aiPlugin = new AIPlugin(random);
+kernel.use(aiPlugin);
+await kernel.init();
+
+// For each NPC going online:
+const coverAccess = aiPlugin.createCoverAccess(npcId);
+```
+
+`AIPlugin.serialize()` saves `RestrictedZoneManager` state.
+Cover locks are intentionally NOT serialized — they are ephemeral TTL data.
+
+### INPCContext — narrow access interfaces
+
+Every state handler receives `INPCContext`, which is a bag of narrow port
+interfaces. You implement each interface once and compose them per NPC:
+
+```ts
+const ctx: INPCContext = {
+  npcId:      npc.id,
+  faction:    npc.faction,
+  perception: new MyPerception(npc),  // INPCPerception
+  health:     new MyHealth(npc),      // INPCHealth
+  cover:      coverAccess,            // ICoverAccess  (from AIPlugin)
+  danger:     dangerAdapter,          // IDangerAccess
+  squad:      squadAccess,            // ISquadAccess
+  suspicion:  suspicionAccess,        // ISuspicionAccess
+  conditions: conditionAccess,        // IConditionAccess
+  shoot:      (payload) => fireWeapon(npc, payload),
+  meleeHit:   (payload) => applyMelee(npc, payload),
+};
+```
+
+### Cover system
+
+The cover module provides a full pipeline from raw cover points to per-NPC
+peek/fire cycles:
+
+1. **Register** cover points into `CoverRegistry` (world space positions + normal)
+2. **Evaluate** — choose the right evaluator for the situation:
+   - `CloseCoverEvaluator` — nearest cover
+   - `FarCoverEvaluator` — cover far from threat
+   - `BalancedCoverEvaluator` — balanced distance + angle
+   - `BestCoverEvaluator` — best angle + distance combined
+   - `AmbushCoverEvaluator` — optimal ambush position
+   - `SafeCoverEvaluator` — maximum distance from all threats
+3. **Lock** — `CoverLockRegistry.lock(npcId, coverId, ttlMs)` so no two NPCs share a point
+4. **Loopholes** — each cover point has 1–3 loophole offsets; `TakeCoverState` cycles `WAIT → PEEK → FIRE → RETURN`
+
+```ts
+import { recommendCoverType } from '@alife-sdk/ai/cover';
+
+const evaluatorType = recommendCoverType({
+  threatCount: 3,
+  npcHp:       15,
+  npcHpMax:    100,
+  isElite:     false,
+});
+// → 'SAFE' (low HP + many threats → maximize distance)
+```
+
+### GOAP — elite NPC planning
+
+For NPCs with rank ≥ 5, `GOAPController` wraps a `GOAPPlanner` (A* on a
+16-property `WorldState` bitmask) to select and execute goal-oriented action
+sequences. Replanning happens every 5 s or on a forced trigger.
+
+```ts
+const goap = new GOAPController(ctx, goapConfig);
+goap.update(deltaMs); // ticks current action or replans if needed
+
+// Custom world property builders and goal rules are opt-in:
+import { DEFAULT_WORLD_PROPERTY_BUILDERS,
+         DEFAULT_GOAL_RULES } from '@alife-sdk/ai/goap';
+```
+
+---
+
+## Lifecycle
+
+```
+kernel.use(aiPlugin)                ← register AI plugin
+  ↓
+kernel.init()                       ← freeze registries, init plugin
+  ↓
+NPC goes online:
+  coverAccess = aiPlugin.createCoverAccess(npcId)
+  driver = new OnlineAIDriver(ctx, handlers, ONLINE_STATE.IDLE)
+  ↓
+Every frame:
+  kernel.update(delta)              ← A-Life tick + events flush
+  driver.update(delta)              ← state enter/update/exit
+  ↓
+NPC goes offline:
+  driver is discarded               ← no serialization needed
+  ↓
+Save / restore:
+  aiPlugin.serialize()              ← RestrictedZoneManager state
+  aiPlugin.restore(state)           ← rebuilds zones
+  ↓
+kernel.destroy()                    ← cleanup
+```
+
+---
+
+## Testing
+
+Run only the AI package tests:
+
+```
+pnpm test --filter @alife-sdk/ai
+```
+
+Each system is designed for isolated unit tests:
+
+```ts
+import { buildDefaultHandlerMap, OnlineAIDriver, ONLINE_STATE } from '@alife-sdk/ai/states';
+
+// Minimal stub context — implement only the interfaces your test exercises
+const ctx = buildStubContext({ hp: 100, targetId: 'enemy1' });
+const driver = new OnlineAIDriver(ctx, buildDefaultHandlerMap(), ONLINE_STATE.IDLE);
+
+driver.transitionTo(ONLINE_STATE.COMBAT);
+driver.update(16);
+
+expect(driver.currentState).toBe(ONLINE_STATE.COMBAT);
+```
+
+Tips:
+- State handlers are stateless objects — instantiate once, reuse across tests
+- `INPCOnlineState` is a plain object — mutate it directly in tests to simulate phase changes
+- `CoverRegistry` / `CoverLockRegistry` have no external dependencies — construct them directly
+- `SuspicionAccumulator` and `ConditionBank` are standalone classes with no kernel dependency
+
+---
+
+## Module map
+
+```
+src/
+├── plugin/       AIPlugin, IAIPluginConfig, createDefaultAIPluginConfig
+├── states/       OnlineAIDriver, StateHandlerMap, ONLINE_STATE, builder functions
+│   ├── handlers/ DeadState, IdleState, PatrolState, AlertState, FleeState,
+│   │             SearchState, CampState, SleepState, CombatState, TakeCoverState,
+│   │             GrenadeState, EvadeGrenadeState, WoundedState, RetreatState,
+│   │             MonsterCombatController, ChargeState, StalkState, LeapState, PsiAttackState
+│   └── eat-corpse/ EatCorpseState (opt-in monster sub-state)
+├── cover/        CoverRegistry, CoverLockRegistry, CoverAccessAdapter,
+│                 6 evaluators, LoopholeGenerator, findBestLoophole, recommendCoverType
+├── perception/   NPCSensors, isInFOV, filterVisibleEntities, filterHearingEntities,
+│                 filterHostileEntities, filterFriendlyEntities, filterFreshIntel
+├── goap/         GOAPController, buildWorldState, selectGoal, EvadeHazardAction,
+│                 DEFAULT_WORLD_PROPERTY_BUILDERS, DEFAULT_GOAL_RULES
+├── navigation/   smoothPath, smoothPathWithTurning, SmoothPathFollower,
+│                 RestrictedZoneManager, RestrictionType, SteeringBehaviors
+├── squad/        evaluateSituation, SquadCommand, canApplyCommand,
+│                 SquadSharedTargetTable, PROTECTED_STATES
+├── animation/    getDirection, getAnimationKey, AnimationController,
+│                 DirectionCache, DEFAULT_STATE_ANIM_MAP, DEFAULT_WEAPON_SUFFIXES
+├── sound/        VocalizationType, VocalizationTracker, createDefaultVocalizationConfig
+├── suspicion/    SuspicionAccumulator, SuspicionStimuli, createDefaultSuspicionConfig
+├── conditions/   ConditionBank, ConditionChannels, createDefaultConditionBankConfig
+├── combat/       combat helpers used by state handlers
+├── types/        INPCContext, INPCOnlineState, IOnlineStateHandler, INPCPerception,
+│                 INPCHealth, ICoverAccess, IDangerAccess, ISquadAccess, IPackAccess,
+│                 ISuspicionAccess, IConditionAccess, IShootPayload, IMeleeHitPayload
+├── config/       IStateConfig, IStateTransitionMap, createDefaultStateConfig
+└── ports/        AI-specific port interfaces (IRestrictedZoneAccess, IHazardZoneAccess)
+```

package/dist/animation/AnimationController.d.ts

@@ -0,0 +1,60 @@
+import type { AnimLayer, IAnimationRequest } from './AnimationSelector';
+/**
+ * Port — developer injects a Phaser/Pixi/etc. implementation.
+ */
+export interface IAnimationDriver {
+    play(key: string, options: IAnimPlayOptions): void;
+    hasAnimation(key: string): boolean;
+}
+export interface IAnimPlayOptions {
+    readonly loop: boolean;
+    readonly frameRate: number;
+}
+/**
+ * Optional per-layer priority override.
+ * Default priority equals the numeric AnimLayer value (LEGS=0, TORSO=1, HEAD=2).
+ */
+export type ILayerPriorityMap = Readonly<Partial<Record<AnimLayer, number>>>;
+export interface IAnimationControllerConfig {
+    readonly driver: IAnimationDriver;
+    readonly layerPriority?: ILayerPriorityMap;
+}
+/**
+ * Stateful per-entity animation controller.
+ *
+ * - `request()` is debounced: skips play if same key+layer or lower priority layer is active.
+ * - `force()` bypasses debounce and priority (for death, hit, ability anims).
+ * - `reset()` clears state for respawn or object-pool reuse.
+ */
+export declare class AnimationController {
+    private _currentKey;
+    private _currentLayer;
+    private readonly driver;
+    private readonly layerPriority;
+    constructor(config: IAnimationControllerConfig);
+    /**
+     * Request an animation play.
+     *
+     * Plays only if:
+     * 1. priority(req.layer) >= priority(currentLayer)  [null current = any allowed]
+     * 2. req.key !== currentKey || req.layer !== currentLayer
+     * 3. driver.hasAnimation(req.key) === true
+     *
+     * Returns true if driver.play() was actually called.
+     */
+    request(req: IAnimationRequest): boolean;
+    /**
+     * Force-play an animation, bypassing debounce and priority.
+     * Useful for one-shot priority events: death, hit reaction, special ability.
+     * No-ops silently if driver.hasAnimation() returns false.
+     */
+    force(req: IAnimationRequest): void;
+    /**
+     * Reset controller state.
+     * Call on respawn or when recycling from an object pool.
+     */
+    reset(): void;
+    get currentKey(): string | null;
+    get currentLayer(): AnimLayer | null;
+}
+//# sourceMappingURL=AnimationController.d.ts.map

package/dist/animation/AnimationController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationController.d.ts","sourceRoot":"","sources":["../../src/animation/AnimationController.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAE7E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;gBAEtC,MAAM,EAAE,0BAA0B;IAK9C;;;;;;;;;OASG;IACH,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO;IAiBxC;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI;IAOnC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAKb,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAE9B;IAED,IAAI,YAAY,IAAI,SAAS,GAAG,IAAI,CAEnC;CACF"}

package/dist/animation/AnimationController.js

@@ -0,0 +1,71 @@
+// animation/AnimationController.ts
+// Stateful per-entity animation controller with debounce and layer priority.
+// Framework-agnostic via IAnimationDriver port.
+/**
+ * Stateful per-entity animation controller.
+ *
+ * - `request()` is debounced: skips play if same key+layer or lower priority layer is active.
+ * - `force()` bypasses debounce and priority (for death, hit, ability anims).
+ * - `reset()` clears state for respawn or object-pool reuse.
+ */
+export class AnimationController {
+    constructor(config) {
+        this._currentKey = null;
+        this._currentLayer = null;
+        this.driver = config.driver;
+        this.layerPriority = config.layerPriority ?? {};
+    }
+    /**
+     * Request an animation play.
+     *
+     * Plays only if:
+     * 1. priority(req.layer) >= priority(currentLayer)  [null current = any allowed]
+     * 2. req.key !== currentKey || req.layer !== currentLayer
+     * 3. driver.hasAnimation(req.key) === true
+     *
+     * Returns true if driver.play() was actually called.
+     */
+    request(req) {
+        if (this._currentLayer !== null) {
+            const newPrio = this.layerPriority[req.layer] ?? req.layer;
+            const curPrio = this.layerPriority[this._currentLayer] ?? this._currentLayer;
+            if (newPrio < curPrio)
+                return false;
+        }
+        if (req.key === this._currentKey && req.layer === this._currentLayer)
+            return false;
+        if (!this.driver.hasAnimation(req.key))
+            return false;
+        this.driver.play(req.key, { loop: req.loop, frameRate: req.frameRate });
+        this._currentKey = req.key;
+        this._currentLayer = req.layer;
+        return true;
+    }
+    /**
+     * Force-play an animation, bypassing debounce and priority.
+     * Useful for one-shot priority events: death, hit reaction, special ability.
+     * No-ops silently if driver.hasAnimation() returns false.
+     */
+    force(req) {
+        if (!this.driver.hasAnimation(req.key))
+            return;
+        this.driver.play(req.key, { loop: req.loop, frameRate: req.frameRate });
+        this._currentKey = req.key;
+        this._currentLayer = req.layer;
+    }
+    /**
+     * Reset controller state.
+     * Call on respawn or when recycling from an object pool.
+     */
+    reset() {
+        this._currentKey = null;
+        this._currentLayer = null;
+    }
+    get currentKey() {
+        return this._currentKey;
+    }
+    get currentLayer() {
+        return this._currentLayer;
+    }
+}
+//# sourceMappingURL=AnimationController.js.map

package/dist/animation/AnimationController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationController.js","sourceRoot":"","sources":["../../src/animation/AnimationController.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,6EAA6E;AAC7E,gDAAgD;AA4BhD;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IAM9B,YAAY,MAAkC;QALtC,gBAAW,GAAkB,IAAI,CAAC;QAClC,kBAAa,GAAqB,IAAI,CAAC;QAK7C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC;IAClD,CAAC;IAED;;;;;;;;;OASG;IACH,OAAO,CAAC,GAAsB;QAC5B,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;YAChC,MAAM,OAAO,GAAW,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC;YACnE,MAAM,OAAO,GAAW,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC;YACrF,IAAI,OAAO,GAAG,OAAO;gBAAE,OAAO,KAAK,CAAC;QACtC,CAAC;QAED,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QAEnF,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAErD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAsB;QAC1B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC/C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/animation/AnimationSelector.d.ts

@@ -0,0 +1,108 @@
+import type { Vec2 } from '@alife-sdk/core';
+/**
+ * 8-way directional system for animation facing.
+ * Indexed 0–7 clockwise from North.
+ */
+export declare const CompassIndex: {
+    readonly N: 0;
+    readonly NE: 1;
+    readonly E: 2;
+    readonly SE: 3;
+    readonly S: 4;
+    readonly SW: 5;
+    readonly W: 6;
+    readonly NW: 7;
+};
+export type CompassIndex = (typeof CompassIndex)[keyof typeof CompassIndex];
+/**
+ * Animation layer for multi-layer sprite rigs.
+ */
+export declare const AnimLayer: {
+    readonly LEGS: 0;
+    readonly TORSO: 1;
+    readonly HEAD: 2;
+};
+export type AnimLayer = (typeof AnimLayer)[keyof typeof AnimLayer];
+/**
+ * Descriptor for a state → animation mapping entry.
+ */
+export interface IAnimDescriptor {
+    readonly base: string;
+    readonly loop: boolean;
+    readonly frameRate: number;
+    readonly layer: AnimLayer;
+    readonly omitDirection: boolean;
+}
+/**
+ * Resolved animation request ready for the host renderer.
+ */
+export interface IAnimationRequest {
+    readonly key: string;
+    readonly loop: boolean;
+    readonly frameRate: number;
+    readonly layer: AnimLayer;
+}
+/**
+ * AI state → animation descriptor mapping.
+ * Exported as default; callers may supply a custom map to override.
+ */
+export declare const DEFAULT_STATE_ANIM_MAP: Readonly<Record<string, IAnimDescriptor>>;
+/**
+ * Weapon suffix lookup.
+ * GRENADE and MEDKIT use 'unarmed' (no held weapon visible).
+ * Keys are strings for extensibility; numeric categories are stringified at lookup time.
+ */
+export declare const DEFAULT_WEAPON_SUFFIXES: Readonly<Record<string, string>>;
+/**
+ * Per-entity direction cache.  Stores the last computed direction and the
+ * velocity that produced it.  `resolve()` only calls `getDirection()` when the
+ * velocity has changed more than a small epsilon (squared-magnitude test).
+ *
+ * Allocate one instance per NPC and pass it into `getAnimationRequest()`.
+ */
+export declare class DirectionCache {
+    private _lastVx;
+    private _lastVy;
+    private _dir;
+    /**
+     * Return the cached direction or recompute if velocity changed significantly.
+     */
+    resolve(vx: number, vy: number): CompassIndex;
+    /** Force-invalidate the cache (e.g. on teleport). */
+    invalidate(): void;
+}
+/**
+ * Convert a 2D velocity vector to an 8-way CompassIndex.
+ * Zero vector defaults to South (rest facing).
+ */
+export declare function getDirection(vx: number, vy: number): CompassIndex;
+/**
+ * Build an animation key from state, weapon type, and direction.
+ *
+ * Format: `{base}_{weapon}_{direction}` or `{base}_{weapon}` if direction omitted.
+ * Falls back to 'rifle' for unknown weapon types.
+ *
+ * @param animMap - Custom state → descriptor map. Uses DEFAULT_STATE_ANIM_MAP when omitted.
+ * @param weaponSuffixes - Custom weapon suffix map. Uses DEFAULT_WEAPON_SUFFIXES when omitted.
+ */
+export declare function getAnimationKey(state: string, weaponType: number | string, direction: CompassIndex, animMap?: Readonly<Record<string, IAnimDescriptor>>, weaponSuffixes?: Readonly<Record<string, string>>): string;
+/**
+ * Input for resolving an animation request from AI state and movement data.
+ * Groups all parameters into a single object for ergonomic callsites.
+ */
+export interface IAnimationInput {
+    readonly state: string;
+    readonly weaponCategory: number | string;
+    readonly velocity: Vec2;
+    readonly animMap?: Readonly<Record<string, IAnimDescriptor>>;
+    readonly weaponSuffixes?: Readonly<Record<string, string>>;
+    readonly directionCache?: DirectionCache;
+}
+/**
+ * Resolve a full animation request from AI state and movement data.
+ *
+ * @param input - Animation input (state, weapon, velocity, optional maps/cache).
+ * @returns Complete animation request with key, loop, frame rate, and layer.
+ */
+export declare function getAnimationRequest(input: IAnimationInput): IAnimationRequest;
+//# sourceMappingURL=AnimationSelector.d.ts.map

package/dist/animation/AnimationSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationSelector.d.ts","sourceRoot":"","sources":["../../src/animation/AnimationSelector.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;CASf,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAI5E;;GAEG;AACH,eAAO,MAAM,SAAS;;;;CAIZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAoB5E,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOpE,CAAC;AASF;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,IAAI,CAAgC;IAE5C;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY;IAc7C,qDAAqD;IACrD,UAAU,IAAI,IAAI;CAInB;AAiCD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAajE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,SAAS,EAAE,YAAY,EACvB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,EACnD,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAChD,MAAM,CAkBR;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,GACrB,iBAAiB,CAanB"}