@alife-sdk/ai 0.1.0

package/dist/states/IStateConfig.js

@@ -0,0 +1,100 @@
+// states/IStateConfig.ts
+// All hardcoded online-AI constants as a single config object.
+// State handlers must read values exclusively from this interface —
+// no magic numbers allowed in handler files.
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a {@link IStateConfig} pre-populated with the production defaults
+ * extracted from the game-layer constants.
+ *
+ * Call with a partial override object to customise individual values:
+ * ```ts
+ * const cfg = createDefaultStateConfig({ combatRange: 250 });
+ * ```
+ */
+export function createDefaultStateConfig(overrides) {
+    return {
+        // -----------------------------------------------------------------------
+        // IMovementConfig
+        // -----------------------------------------------------------------------
+        approachSpeed: 150,
+        fleeSpeedMultiplier: 1.5,
+        panicFleeMultiplier: 1.3,
+        woundedCrawlMultiplier: 0.3,
+        evadeSpeedMultiplier: 1.5,
+        chargeSpeedMultiplier: 2.0,
+        stalkSpeedMultiplier: 0.4,
+        arriveThreshold: 12,
+        waypointArriveThreshold: 24,
+        combatRange: 200,
+        fleeDistance: 400,
+        evadeSafeDistance: 200,
+        woundedLastStandRange: 100,
+        meleeRange: 48,
+        stalkUnclockDistance: 80,
+        restrictedZoneCheckIntervalMs: 1000,
+        // -----------------------------------------------------------------------
+        // ICombatConfig
+        // -----------------------------------------------------------------------
+        woundedHpThreshold: 0.2,
+        retreatMoraleThreshold: -0.3,
+        panicMoraleThreshold: -0.7,
+        fireRateMs: 1000,
+        grenadeWindupMs: 1000,
+        bulletDamage: 10,
+        medkitHealRatio: 0.5,
+        medkitUseDurationMs: 3000,
+        killWoundedEnemyHpThreshold: 0.25,
+        killWoundedExecuteRange: 80,
+        // -----------------------------------------------------------------------
+        // IMonsterConfig
+        // -----------------------------------------------------------------------
+        meleeDamage: 15,
+        chargeDamageMultiplier: 2.0,
+        meleeCooldownMs: 1000,
+        chargeWindupMs: 600,
+        leapWindupMs: 400,
+        leapAirtimeMs: 350,
+        psiChannelMs: 2000,
+        innerLairRadius: 80,
+        patrolRadius: 180,
+        outerRadius: 350,
+        stalkAlphaInvisible: 0.08,
+        stalkAlphaShimmer: 0.3,
+        // -----------------------------------------------------------------------
+        // ITimingConfig
+        // -----------------------------------------------------------------------
+        alertDuration: 5000,
+        searchDuration: 8000,
+        woundedMaxDurationMs: 15000,
+        retreatMaxDurationMs: 8000,
+        retreatFireIntervalMs: 2000,
+        inertiaLockMs: 3000,
+        schemeReactionDelayMs: 400,
+        campSleepReactionDelayMs: 800,
+        idleConditionChannel: 'stamina',
+        idleConditionThreshold: 0.8,
+        suspicionAlertThreshold: 0.7,
+        investigateMaxDurationMs: 10000,
+        investigateLookAroundMs: 3000,
+        helpWoundedAssistMs: 5000,
+        helpWoundedMaxDurationMs: 10000,
+        corpseFoundSuspicion: 0.6,
+        killWoundedMaxApproachMs: 8000,
+        killWoundedAimMs: 800,
+        killWoundedTauntMs: 1200,
+        killWoundedBurstCount: 3,
+        killWoundedPauseMs: 1000,
+        packAlertIntervalMs: 500,
+        packAlertTtlMs: 5000,
+        loopholeWaitMinMs: 1500,
+        loopholeWaitMaxMs: 3000,
+        loopholePeekDurationMs: 600,
+        loopholeFireDurationMs: 1200,
+        loopholeReturnDurationMs: 400,
+        ...overrides,
+    };
+}
+//# sourceMappingURL=IStateConfig.js.map

package/dist/states/IStateConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStateConfig.js","sourceRoot":"","sources":["../../src/states/IStateConfig.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,+DAA+D;AAC/D,oEAAoE;AACpE,6CAA6C;AAwY7C,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAiC;IAEjC,OAAO;QACL,0EAA0E;QAC1E,kBAAkB;QAClB,0EAA0E;QAC1E,aAAa,EAAE,GAAG;QAClB,mBAAmB,EAAE,GAAG;QACxB,mBAAmB,EAAE,GAAG;QACxB,sBAAsB,EAAE,GAAG;QAC3B,oBAAoB,EAAE,GAAG;QACzB,qBAAqB,EAAE,GAAG;QAC1B,oBAAoB,EAAE,GAAG;QAEzB,eAAe,EAAE,EAAE;QACnB,uBAAuB,EAAE,EAAE;QAC3B,WAAW,EAAE,GAAG;QAChB,YAAY,EAAE,GAAG;QACjB,iBAAiB,EAAE,GAAG;QACtB,qBAAqB,EAAE,GAAG;QAC1B,UAAU,EAAE,EAAE;QACd,oBAAoB,EAAE,EAAE;QACxB,6BAA6B,EAAE,IAAK;QAEpC,0EAA0E;QAC1E,gBAAgB;QAChB,0EAA0E;QAC1E,kBAAkB,EAAE,GAAG;QACvB,sBAAsB,EAAE,CAAC,GAAG;QAC5B,oBAAoB,EAAE,CAAC,GAAG;QAE1B,UAAU,EAAE,IAAK;QACjB,eAAe,EAAE,IAAK;QAEtB,YAAY,EAAE,EAAE;QAChB,eAAe,EAAE,GAAG;QACpB,mBAAmB,EAAE,IAAK;QAC1B,2BAA2B,EAAE,IAAI;QACjC,uBAAuB,EAAE,EAAE;QAE3B,0EAA0E;QAC1E,iBAAiB;QACjB,0EAA0E;QAC1E,WAAW,EAAE,EAAE;QACf,sBAAsB,EAAE,GAAG;QAC3B,eAAe,EAAE,IAAK;QAEtB,cAAc,EAAE,GAAG;QACnB,YAAY,EAAE,GAAG;QACjB,aAAa,EAAE,GAAG;QAClB,YAAY,EAAE,IAAK;QAEnB,eAAe,EAAE,EAAE;QACnB,YAAY,EAAE,GAAG;QACjB,WAAW,EAAE,GAAG;QAEhB,mBAAmB,EAAE,IAAI;QACzB,iBAAiB,EAAE,GAAG;QAEtB,0EAA0E;QAC1E,gBAAgB;QAChB,0EAA0E;QAC1E,aAAa,EAAE,IAAK;QACpB,cAAc,EAAE,IAAK;QACrB,oBAAoB,EAAE,KAAM;QAC5B,oBAAoB,EAAE,IAAK;QAC3B,qBAAqB,EAAE,IAAK;QAC5B,aAAa,EAAE,IAAK;QACpB,qBAAqB,EAAE,GAAG;QAC1B,wBAAwB,EAAE,GAAG;QAE7B,oBAAoB,EAAE,SAAS;QAC/B,sBAAsB,EAAE,GAAG;QAC3B,uBAAuB,EAAE,GAAG;QAC5B,wBAAwB,EAAE,KAAM;QAChC,uBAAuB,EAAE,IAAK;QAC9B,mBAAmB,EAAE,IAAK;QAC1B,wBAAwB,EAAE,KAAM;QAChC,oBAAoB,EAAE,GAAG;QACzB,wBAAwB,EAAE,IAAK;QAC/B,gBAAgB,EAAE,GAAG;QACrB,kBAAkB,EAAE,IAAK;QACzB,qBAAqB,EAAE,CAAC;QACxB,kBAAkB,EAAE,IAAK;QACzB,mBAAmB,EAAE,GAAG;QACxB,cAAc,EAAE,IAAK;QAErB,iBAAiB,EAAE,IAAK;QACxB,iBAAiB,EAAE,IAAK;QACxB,sBAAsB,EAAE,GAAG;QAC3B,sBAAsB,EAAE,IAAK;QAC7B,wBAAwB,EAAE,GAAG;QAE7B,GAAG,SAAS;KACb,CAAC;AACJ,CAAC"}

package/dist/states/IStateTransitionMap.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Injectable map of logical transition names to actual state ID strings.
+ *
+ * Each handler uses `this.tr.combatOnPanicked` instead of hardcoded `'FLEE'`,
+ * allowing SDK users to rename states freely.
+ *
+ * @example
+ * ```ts
+ * // Zombie game with custom state names
+ * const handlers = buildDefaultHandlerMap(cfg, {
+ *   combatOnPanicked: 'shamble_away',
+ *   fleeOnCalmed: 'wander',
+ *   monsterOnNoEnemy: 'wander',
+ * });
+ * ```
+ */
+export interface IStateTransitionMap {
+    idleOnEnemy: string;
+    idleOnTired: string;
+    idleOnSuspicious: string;
+    patrolOnEnemy: string;
+    patrolOnSquadIntel: string;
+    patrolOnSuspicious: string;
+    patrolOnNoWaypoint: string;
+    alertOnEnemy: string;
+    alertOnTimeout: string;
+    alertOnPanic: string;
+    combatOnNoEnemy: string;
+    combatOnLastKnown: string;
+    combatOnPanicked: string;
+    combatOnShaken: string;
+    combatOnWounded: string;
+    combatOnCover: string;
+    takeCoverOnNoEnemy: string;
+    takeCoverOnPanicked: string;
+    takeCoverOnShaken: string;
+    fleeOnCalmed: string;
+    searchOnEnemy: string;
+    searchOnTimeout: string;
+    grenadeOnComplete: string;
+    grenadeOnNoAmmo: string;
+    evadeOnClear: string;
+    evadeOnTimeout: string;
+    evadeOnNoSystem: string;
+    woundedOnHealed: string;
+    woundedOnPanic: string;
+    woundedOnTimeout: string;
+    retreatOnPanicked: string;
+    retreatOnStable: string;
+    retreatOnNoEnemy: string;
+    campOnEnemy: string;
+    campOnDanger: string;
+    sleepOnEnemy: string;
+    monsterOnNoEnemy: string;
+    monsterOnLastKnown: string;
+    chargeOnComplete: string;
+    chargeOnAbort: string;
+    stalkOnAttack: string;
+    stalkOnNoEnemy: string;
+    leapOnLand: string;
+    psiOnComplete: string;
+    psiOnNoEnemy: string;
+    eatCorpseOnDone: string;
+    eatCorpseOnInterrupt: string;
+    eatCorpseOnNoCorpse: string;
+    investigateOnEnemy: string;
+    investigateOnTimeout: string;
+    investigateOnPanic: string;
+    patrolOnWoundedAlly: string;
+    idleOnWoundedAlly: string;
+    helpWoundedOnEnemy: string;
+    helpWoundedOnComplete: string;
+    helpWoundedOnPanic: string;
+    combatOnKillWounded: string;
+    alertOnKillWounded: string;
+    killWoundedOnComplete: string;
+    killWoundedOnNoTarget: string;
+    killWoundedOnPanic: string;
+    killWoundedOnTimeout: string;
+    idleOnPackAlert: string;
+    patrolOnPackAlert: string;
+    alertOnPackCombat: string;
+}
+/**
+ * Creates a transition map with Chornobyl-style defaults.
+ * Pass `overrides` to remap any transitions for your own state names.
+ */
+export declare function createDefaultTransitionMap(overrides?: Partial<IStateTransitionMap>): IStateTransitionMap;
+//# sourceMappingURL=IStateTransitionMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IStateTransitionMap.d.ts","sourceRoot":"","sources":["../../src/states/IStateTransitionMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAElC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IAGzB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAG3B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IAGrB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IAGtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAG1B,YAAY,EAAE,MAAM,CAAC;IAGrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IAGxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IAGxB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IAGxB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IAGzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IAGzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IAGrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAG3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IAGtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IAGvB,UAAU,EAAE,MAAM,CAAC;IAGnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IAGrB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAG5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAG3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAG3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAG7B,eAAe,EAAI,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACvC,mBAAmB,CAqErB"}

package/dist/states/IStateTransitionMap.js

@@ -0,0 +1,75 @@
+/**
+ * Creates a transition map with Chornobyl-style defaults.
+ * Pass `overrides` to remap any transitions for your own state names.
+ */
+export function createDefaultTransitionMap(overrides) {
+    return {
+        idleOnEnemy: 'ALERT',
+        idleOnTired: 'CAMP',
+        idleOnSuspicious: 'ALERT',
+        patrolOnEnemy: 'ALERT',
+        patrolOnSquadIntel: 'ALERT',
+        patrolOnSuspicious: 'ALERT',
+        patrolOnNoWaypoint: 'IDLE',
+        alertOnEnemy: 'COMBAT',
+        alertOnTimeout: 'PATROL',
+        alertOnPanic: 'FLEE',
+        combatOnNoEnemy: 'IDLE',
+        combatOnLastKnown: 'SEARCH',
+        combatOnPanicked: 'FLEE',
+        combatOnShaken: 'RETREAT',
+        combatOnWounded: 'WOUNDED',
+        combatOnCover: 'TAKE_COVER',
+        takeCoverOnNoEnemy: 'SEARCH',
+        takeCoverOnPanicked: 'FLEE',
+        takeCoverOnShaken: 'RETREAT',
+        fleeOnCalmed: 'ALERT',
+        searchOnEnemy: 'ALERT',
+        searchOnTimeout: 'IDLE',
+        grenadeOnComplete: 'COMBAT',
+        grenadeOnNoAmmo: 'COMBAT',
+        evadeOnClear: 'COMBAT',
+        evadeOnTimeout: 'COMBAT',
+        evadeOnNoSystem: 'COMBAT',
+        woundedOnHealed: 'COMBAT',
+        woundedOnPanic: 'FLEE',
+        woundedOnTimeout: 'FLEE',
+        retreatOnPanicked: 'FLEE',
+        retreatOnStable: 'COMBAT',
+        retreatOnNoEnemy: 'SEARCH',
+        campOnEnemy: 'COMBAT',
+        campOnDanger: 'ALERT',
+        sleepOnEnemy: 'ALERT',
+        monsterOnNoEnemy: 'IDLE',
+        monsterOnLastKnown: 'SEARCH',
+        chargeOnComplete: 'COMBAT',
+        chargeOnAbort: 'IDLE',
+        stalkOnAttack: 'COMBAT',
+        stalkOnNoEnemy: 'SEARCH',
+        leapOnLand: 'COMBAT',
+        psiOnComplete: 'COMBAT',
+        psiOnNoEnemy: 'IDLE',
+        eatCorpseOnDone: 'IDLE',
+        eatCorpseOnInterrupt: 'ALERT',
+        eatCorpseOnNoCorpse: 'IDLE',
+        investigateOnEnemy: 'ALERT',
+        investigateOnTimeout: 'PATROL',
+        investigateOnPanic: 'FLEE',
+        patrolOnWoundedAlly: 'HELP_WOUNDED',
+        idleOnWoundedAlly: 'HELP_WOUNDED',
+        helpWoundedOnEnemy: 'ALERT',
+        helpWoundedOnComplete: 'PATROL',
+        helpWoundedOnPanic: 'FLEE',
+        combatOnKillWounded: 'KILL_WOUNDED',
+        alertOnKillWounded: 'KILL_WOUNDED',
+        killWoundedOnComplete: 'COMBAT',
+        killWoundedOnNoTarget: 'SEARCH',
+        killWoundedOnPanic: 'FLEE',
+        killWoundedOnTimeout: 'COMBAT',
+        idleOnPackAlert: 'ALERT',
+        patrolOnPackAlert: 'ALERT',
+        alertOnPackCombat: 'SEARCH',
+        ...overrides,
+    };
+}
+//# sourceMappingURL=IStateTransitionMap.js.map

package/dist/states/IStateTransitionMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStateTransitionMap.js","sourceRoot":"","sources":["../../src/states/IStateTransitionMap.ts"],"names":[],"mappings":"AA+HA;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAAwC;IAExC,OAAO;QACL,WAAW,EAAE,OAAO;QACpB,WAAW,EAAE,MAAM;QACnB,gBAAgB,EAAE,OAAO;QACzB,aAAa,EAAE,OAAO;QACtB,kBAAkB,EAAE,OAAO;QAC3B,kBAAkB,EAAE,OAAO;QAC3B,kBAAkB,EAAE,MAAM;QAC1B,YAAY,EAAE,QAAQ;QACtB,cAAc,EAAE,QAAQ;QACxB,YAAY,EAAE,MAAM;QACpB,eAAe,EAAE,MAAM;QACvB,iBAAiB,EAAE,QAAQ;QAC3B,gBAAgB,EAAE,MAAM;QACxB,cAAc,EAAE,SAAS;QACzB,eAAe,EAAE,SAAS;QAC1B,aAAa,EAAE,YAAY;QAC3B,kBAAkB,EAAE,QAAQ;QAC5B,mBAAmB,EAAE,MAAM;QAC3B,iBAAiB,EAAE,SAAS;QAC5B,YAAY,EAAE,OAAO;QACrB,aAAa,EAAE,OAAO;QACtB,eAAe,EAAE,MAAM;QACvB,iBAAiB,EAAE,QAAQ;QAC3B,eAAe,EAAE,QAAQ;QACzB,YAAY,EAAE,QAAQ;QACtB,cAAc,EAAE,QAAQ;QACxB,eAAe,EAAE,QAAQ;QACzB,eAAe,EAAE,QAAQ;QACzB,cAAc,EAAE,MAAM;QACtB,gBAAgB,EAAE,MAAM;QACxB,iBAAiB,EAAE,MAAM;QACzB,eAAe,EAAE,QAAQ;QACzB,gBAAgB,EAAE,QAAQ;QAC1B,WAAW,EAAE,QAAQ;QACrB,YAAY,EAAE,OAAO;QACrB,YAAY,EAAE,OAAO;QACrB,gBAAgB,EAAE,MAAM;QACxB,kBAAkB,EAAE,QAAQ;QAC5B,gBAAgB,EAAE,QAAQ;QAC1B,aAAa,EAAE,MAAM;QACrB,aAAa,EAAE,QAAQ;QACvB,cAAc,EAAE,QAAQ;QACxB,UAAU,EAAE,QAAQ;QACpB,aAAa,EAAE,QAAQ;QACvB,YAAY,EAAE,MAAM;QACpB,eAAe,EAAE,MAAM;QACvB,oBAAoB,EAAE,OAAO;QAC7B,mBAAmB,EAAE,MAAM;QAC3B,kBAAkB,EAAE,OAAO;QAC3B,oBAAoB,EAAE,QAAQ;QAC9B,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,cAAc;QACnC,iBAAiB,EAAE,cAAc;QACjC,kBAAkB,EAAE,OAAO;QAC3B,qBAAqB,EAAE,QAAQ;QAC/B,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,cAAc;QACnC,kBAAkB,EAAE,cAAc;QAClC,qBAAqB,EAAE,QAAQ;QAC/B,qBAAqB,EAAE,QAAQ;QAC/B,kBAAkB,EAAE,MAAM;QAC1B,oBAAoB,EAAE,QAAQ;QAC9B,eAAe,EAAI,OAAO;QAC1B,iBAAiB,EAAE,OAAO;QAC1B,iBAAiB,EAAE,QAAQ;QAC3B,GAAG,SAAS;KACb,CAAC;AACJ,CAAC"}

package/dist/states/NPCOnlineState.d.ts

@@ -0,0 +1,19 @@
+import type { INPCOnlineState } from './INPCOnlineState';
+/**
+ * Create a new {@link INPCOnlineState} with all fields initialised to their
+ * zero/null/default values.
+ *
+ * Call once per NPC instance and store the result on the NPC's context object.
+ * All online state handlers share this bag (via INPCContext.state) and mutate
+ * it in-place each frame.
+ *
+ * @example
+ * ```ts
+ * class MyNPCContext implements INPCContext {
+ *   readonly state = createDefaultNPCOnlineState();
+ *   // ...
+ * }
+ * ```
+ */
+export declare function createDefaultNPCOnlineState(): INPCOnlineState;
+//# sourceMappingURL=NPCOnlineState.d.ts.map

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

@@ -0,0 +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"}

package/dist/states/NPCOnlineState.js

@@ -0,0 +1,75 @@
+// states/NPCOnlineState.ts
+// Concrete factory for creating a fresh INPCOnlineState with all defaults.
+/**
+ * Create a new {@link INPCOnlineState} with all fields initialised to their
+ * zero/null/default values.
+ *
+ * Call once per NPC instance and store the result on the NPC's context object.
+ * All online state handlers share this bag (via INPCContext.state) and mutate
+ * it in-place each frame.
+ *
+ * @example
+ * ```ts
+ * class MyNPCContext implements INPCContext {
+ *   readonly state = createDefaultNPCOnlineState();
+ *   // ...
+ * }
+ * ```
+ */
+export function createDefaultNPCOnlineState() {
+    return {
+        // Target tracking
+        targetId: null,
+        lastKnownEnemyX: 0,
+        lastKnownEnemyY: 0,
+        targetLockUntilMs: 0,
+        // Timers (all start at 0 — handlers treat 0 as "never fired")
+        alertStartMs: 0,
+        searchStartMs: 0,
+        lastIdleAnimChangeMs: 0,
+        lastMeleeMs: 0,
+        lastShootMs: 0,
+        lastVocalizationMs: 0,
+        lastGrenadeMs: 0,
+        lastSupressiveFireMs: 0,
+        grenadeThrowStartMs: 0,
+        evadeStartMs: 0,
+        woundedStartMs: 0,
+        psiPhaseStartMs: 0,
+        investigateStartMs: 0,
+        investigateLookAroundStartMs: -1,
+        helpWoundedTargetId: null,
+        helpWoundedStartMs: 0,
+        helpWoundedAssistStartMs: -1,
+        helpWoundedX: 0,
+        helpWoundedY: 0,
+        killWoundedTargetId: null,
+        killWoundedStartMs: 0,
+        killWoundedAimStartMs: -1,
+        killWoundedTauntStartMs: -1,
+        killWoundedExecuteStartMs: -1,
+        killWoundedShotsFired: 0,
+        killWoundedPauseStartMs: -1,
+        killWoundedTargetX: 0,
+        killWoundedTargetY: 0,
+        packLastBroadcastMs: 0,
+        // Navigation
+        patrolWaypointIndex: 0,
+        searchWaypointIndex: 0,
+        // Loadout
+        primaryWeapon: null,
+        secondaryWeapon: null,
+        grenadeCount: 0,
+        medkitCount: 0,
+        // State flags
+        isAlert: false,
+        hasTakenCover: false,
+        coverPointX: 0,
+        coverPointY: 0,
+        loophole: null,
+        // Morale
+        morale: 0,
+        moraleState: 'STABLE',
+    };
+}
+//# sourceMappingURL=NPCOnlineState.js.map

package/dist/states/NPCOnlineState.js.map

@@ -0,0 +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,oBAAoB,EAAE,CAAC;QACvB,mBAAmB,EAAE,CAAC;QACtB,YAAY,EAAE,CAAC;QACf,cAAc,EAAE,CAAC;QACjB,eAAe,EAAE,CAAC;QAClB,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,aAAa;QACb,mBAAmB,EAAE,CAAC;QACtB,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,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,QAAQ,EAAE,IAAI;QAEd,SAAS;QACT,MAAM,EAAE,CAAC;QACT,WAAW,EAAE,QAAQ;KACtB,CAAC;AACJ,CAAC"}

package/dist/states/NPCPerception.d.ts

@@ -0,0 +1,108 @@
+import type { INPCPerception } from './INPCContext';
+/**
+ * A single visible entity as stored and returned by NPCPerception.
+ * Used for both enemies and allies.
+ */
+export interface IVisibleEntity {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly factionId: string;
+}
+/**
+ * A single item visible or in the NPC's vicinity.
+ */
+export interface INearbyItem {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly type: string;
+}
+/**
+ * Concrete implementation of {@link INPCPerception}.
+ *
+ * Stores a per-frame snapshot of the NPC's world awareness.
+ * The host calls {@link sync} to update the snapshot each frame before
+ * state handlers run.
+ *
+ * @example
+ * ```ts
+ * const perception = new NPCPerception();
+ *
+ * // Called by the host after ScenePerceptionSystem.update():
+ * perception.sync(visibleEnemies, visibleAllies, nearbyItems);
+ *
+ * // Called by state handlers:
+ * if (perception.hasVisibleEnemy()) {
+ *   ctx.transition('COMBAT');
+ * }
+ * ```
+ */
+export declare class NPCPerception implements INPCPerception {
+    private _visibleEnemies;
+    private _visibleAllies;
+    private _nearbyItems;
+    /**
+     * Push a fresh perception snapshot.
+     *
+     * Called by the host (e.g. PhaserNPCContext) each frame after the
+     * scene-level perception system has run. Creates internal shallow copies of
+     * all three arrays so neither the caller nor the state handlers can alias
+     * the stored data.
+     *
+     * @param enemies - All visible hostile entities this frame.
+     * @param allies  - All visible friendly entities this frame.
+     * @param items   - All nearby items this frame.
+     */
+    sync(enemies: ReadonlyArray<IVisibleEntity>, allies: ReadonlyArray<IVisibleEntity>, items: ReadonlyArray<INearbyItem>): void;
+    /**
+     * Clear all perception data.
+     * Equivalent to calling sync([], [], []).
+     */
+    clear(): void;
+    /**
+     * All visible enemies this frame.
+     *
+     * Returns the internal array cast as ReadonlyArray — no additional copy is
+     * made, so this is O(1). The contents are stable for the current frame.
+     */
+    getVisibleEnemies(): ReadonlyArray<{
+        id: string;
+        x: number;
+        y: number;
+        factionId: string;
+    }>;
+    /**
+     * All visible allied NPCs this frame.
+     *
+     * Returns the internal array cast as ReadonlyArray — O(1).
+     */
+    getVisibleAllies(): ReadonlyArray<{
+        id: string;
+        x: number;
+        y: number;
+    }>;
+    /**
+     * All nearby items this frame.
+     *
+     * Returns the internal array cast as ReadonlyArray — O(1).
+     */
+    getNearbyItems(): ReadonlyArray<{
+        id: string;
+        x: number;
+        y: number;
+        type: string;
+    }>;
+    /**
+     * Returns true if at least one visible enemy is in the snapshot.
+     * O(1) — length check only.
+     */
+    hasVisibleEnemy(): boolean;
+    /** Total number of visible enemies. */
+    get enemyCount(): number;
+    /** Total number of visible allies. */
+    get allyCount(): number;
+    /** Total number of nearby items. */
+    get itemCount(): number;
+}
+//# sourceMappingURL=NPCPerception.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NPCPerception.d.ts","sourceRoot":"","sources":["../../src/states/NPCPerception.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMpD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAAqB;IAMzC;;;;;;;;;;;OAWG;IACH,IAAI,CACF,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,EACtC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAChC,IAAI;IAMP;;;OAGG;IACH,KAAK,IAAI,IAAI;IAUb;;;;;OAKG;IACH,iBAAiB,IAAI,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3F;;;;OAIG;IACH,gBAAgB,IAAI,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAIvE;;;;OAIG;IACH,cAAc,IAAI,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAInF;;;OAGG;IACH,eAAe,IAAI,OAAO;IAQ1B,uCAAuC;IACvC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,sCAAsC;IACtC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,oCAAoC;IACpC,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}

package/dist/states/NPCPerception.js

@@ -0,0 +1,122 @@
+// states/NPCPerception.ts
+// Concrete implementation of INPCPerception that wraps a simple data store.
+//
+// The host (e.g. PhaserNPCContext) calls sync() each frame after running the
+// scene-level perception system to push fresh enemy/ally/item snapshots.
+// State handlers then call the standard INPCPerception query methods — they
+// never see the internal arrays directly.
+//
+// Defensive copying: sync() takes read-only arrays but stores shallow copies
+// internally. Mutations of the input arrays after sync() do not affect the
+// stored snapshots; mutations of the returned ReadonlyArray views do not affect
+// internal storage either.
+// ---------------------------------------------------------------------------
+// NPCPerception
+// ---------------------------------------------------------------------------
+/**
+ * Concrete implementation of {@link INPCPerception}.
+ *
+ * Stores a per-frame snapshot of the NPC's world awareness.
+ * The host calls {@link sync} to update the snapshot each frame before
+ * state handlers run.
+ *
+ * @example
+ * ```ts
+ * const perception = new NPCPerception();
+ *
+ * // Called by the host after ScenePerceptionSystem.update():
+ * perception.sync(visibleEnemies, visibleAllies, nearbyItems);
+ *
+ * // Called by state handlers:
+ * if (perception.hasVisibleEnemy()) {
+ *   ctx.transition('COMBAT');
+ * }
+ * ```
+ */
+export class NPCPerception {
+    constructor() {
+        this._visibleEnemies = [];
+        this._visibleAllies = [];
+        this._nearbyItems = [];
+    }
+    // -------------------------------------------------------------------------
+    // Host API
+    // -------------------------------------------------------------------------
+    /**
+     * Push a fresh perception snapshot.
+     *
+     * Called by the host (e.g. PhaserNPCContext) each frame after the
+     * scene-level perception system has run. Creates internal shallow copies of
+     * all three arrays so neither the caller nor the state handlers can alias
+     * the stored data.
+     *
+     * @param enemies - All visible hostile entities this frame.
+     * @param allies  - All visible friendly entities this frame.
+     * @param items   - All nearby items this frame.
+     */
+    sync(enemies, allies, items) {
+        this._visibleEnemies = [...enemies];
+        this._visibleAllies = [...allies];
+        this._nearbyItems = [...items];
+    }
+    /**
+     * Clear all perception data.
+     * Equivalent to calling sync([], [], []).
+     */
+    clear() {
+        this._visibleEnemies = [];
+        this._visibleAllies = [];
+        this._nearbyItems = [];
+    }
+    // -------------------------------------------------------------------------
+    // INPCPerception implementation
+    // -------------------------------------------------------------------------
+    /**
+     * All visible enemies this frame.
+     *
+     * Returns the internal array cast as ReadonlyArray — no additional copy is
+     * made, so this is O(1). The contents are stable for the current frame.
+     */
+    getVisibleEnemies() {
+        return this._visibleEnemies;
+    }
+    /**
+     * All visible allied NPCs this frame.
+     *
+     * Returns the internal array cast as ReadonlyArray — O(1).
+     */
+    getVisibleAllies() {
+        return this._visibleAllies;
+    }
+    /**
+     * All nearby items this frame.
+     *
+     * Returns the internal array cast as ReadonlyArray — O(1).
+     */
+    getNearbyItems() {
+        return this._nearbyItems;
+    }
+    /**
+     * Returns true if at least one visible enemy is in the snapshot.
+     * O(1) — length check only.
+     */
+    hasVisibleEnemy() {
+        return this._visibleEnemies.length > 0;
+    }
+    // -------------------------------------------------------------------------
+    // Convenience queries (not part of INPCPerception but useful for tests)
+    // -------------------------------------------------------------------------
+    /** Total number of visible enemies. */
+    get enemyCount() {
+        return this._visibleEnemies.length;
+    }
+    /** Total number of visible allies. */
+    get allyCount() {
+        return this._visibleAllies.length;
+    }
+    /** Total number of nearby items. */
+    get itemCount() {
+        return this._nearbyItems.length;
+    }
+}
+//# sourceMappingURL=NPCPerception.js.map

package/dist/states/NPCPerception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NPCPerception.js","sourceRoot":"","sources":["../../src/states/NPCPerception.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,4EAA4E;AAC5E,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,4EAA4E;AAC5E,0CAA0C;AAC1C,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAChF,2BAA2B;AA6B3B,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,aAAa;IAA1B;QACU,oBAAe,GAAqB,EAAE,CAAC;QACvC,mBAAc,GAAqB,EAAE,CAAC;QACtC,iBAAY,GAAkB,EAAE,CAAC;IAgG3C,CAAC;IA9FC,4EAA4E;IAC5E,WAAW;IACX,4EAA4E;IAE5E;;;;;;;;;;;OAWG;IACH,IAAI,CACF,OAAsC,EACtC,MAAqC,EACrC,KAAiC;QAEjC,IAAI,CAAC,eAAe,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,cAAc,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,YAAY,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;IACzB,CAAC;IAED,4EAA4E;IAC5E,gCAAgC;IAChC,4EAA4E;IAE5E;;;;;OAKG;IACH,iBAAiB;QACf,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,CAAC;IAED,4EAA4E;IAC5E,wEAAwE;IACxE,4EAA4E;IAE5E,uCAAuC;IACvC,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;IACrC,CAAC;IAED,sCAAsC;IACtC,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;IACpC,CAAC;IAED,oCAAoC;IACpC,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC;IAClC,CAAC;CACF"}