@alife-sdk/ai 0.1.0

package/dist/states/INPCOnlineState.d.ts

@@ -0,0 +1,202 @@
+import type { IEatCorpsePhase } from './eat-corpse/IEatCorpsePhase';
+/**
+ * TakeCoverState loophole peek-fire-return-wait cycle phase data.
+ * Mirrors the game-layer LoopholeData class as a plain data interface.
+ */
+export interface ILoopholeState {
+    /** Current phase within the peek-fire cycle. */
+    phase: 'WAIT' | 'PEEK' | 'FIRE' | 'RETURN';
+    /** scene.time.now (or equivalent) at the start of the current phase (ms). */
+    phaseStartMs: number;
+}
+/**
+ * Boar charge attack phase data.
+ * Mirrors ChargeData from the game layer.
+ */
+export interface IChargePhase {
+    /** Whether the charge sequence has been activated this combat cycle. */
+    active: boolean;
+    /** scene.time.now at the start of the charge wind-up (ms). */
+    windupStartMs: number;
+    /** Whether the NPC is currently in the full-speed charge phase. */
+    charging: boolean;
+    /** World X of the charge target when the charge was initiated. */
+    targetX: number;
+    /** World Y of the charge target when the charge was initiated. */
+    targetY: number;
+}
+/**
+ * Bloodsucker stalk approach phase data.
+ * Mirrors StalkData from the game layer.
+ */
+export interface IStalkPhase {
+    /** Whether the stalk sequence has been activated this combat cycle. */
+    active: boolean;
+    /** Whether the bloodsucker is currently closing distance for the melee strike. */
+    approaching: boolean;
+}
+/**
+ * Snork leap attack phase data.
+ * Mirrors LeapData from the game layer.
+ */
+export interface ILeapPhase {
+    /** Whether the leap sequence has been activated this combat cycle. */
+    active: boolean;
+    /** scene.time.now at the start of the leap wind-up (ms). */
+    windupStartMs: number;
+    /** Whether the snork is currently in the airborne phase. */
+    airborne: boolean;
+    /** World X when the leap was initiated (interpolation start). */
+    startX: number;
+    /** World Y when the leap was initiated (interpolation start). */
+    startY: number;
+    /** World X of the leap landing target. */
+    targetX: number;
+    /** World Y of the leap landing target. */
+    targetY: number;
+    /** scene.time.now when the airborne phase began (ms). */
+    airStartMs: number;
+}
+/**
+ * Controller PSI attack phase data.
+ * Mirrors PsiData from the game layer.
+ */
+export interface IPsiPhase {
+    /** Whether the PSI channel is active. */
+    active: boolean;
+    /** scene.time.now when channelling began (ms). */
+    channelStartMs: number;
+}
+/**
+ * Mutable per-NPC AI data bag.
+ *
+ * Stored on each NPC instance (e.g. inside PhaserNPCContext or a plain object
+ * in tests). All online state handlers are stateless — they read and write
+ * this bag each frame via {@link INPCContext.state}.
+ *
+ * Fields match those in the game-layer AIComponent but use ms-based timers
+ * (not scene.time.now subtraction) where possible for portability.
+ */
+export interface INPCOnlineState {
+    /** Stable entity ID of the current combat target, or null when no target. */
+    targetId: string | null;
+    /** World X of the last confirmed enemy position (px). */
+    lastKnownEnemyX: number;
+    /** World Y of the last confirmed enemy position (px). */
+    lastKnownEnemyY: number;
+    /**
+     * Timestamp (ms) until which the target lock is held.
+     * Prevents rapid target switching — compare with ctx.now().
+     */
+    targetLockUntilMs: number;
+    /** ctx.now() when ALERT state was entered. */
+    alertStartMs: number;
+    /** ctx.now() when SEARCH state was entered. */
+    searchStartMs: number;
+    /** ctx.now() of the last idle animation change (for random anim cycling). */
+    lastIdleAnimChangeMs: number;
+    /** ctx.now() of the last melee attack performed. */
+    lastMeleeMs: number;
+    /** ctx.now() of the last ranged shot fired. */
+    lastShootMs: number;
+    /** ctx.now() of the last vocalization emitted. */
+    lastVocalizationMs: number;
+    /** ctx.now() of the last grenade throw. */
+    lastGrenadeMs: number;
+    /** ctx.now() of the last suppressive fire shot during RETREAT. */
+    lastSupressiveFireMs: number;
+    /** ctx.now() when the current grenade throw wind-up began. */
+    grenadeThrowStartMs: number;
+    /** ctx.now() when EVADE_GRENADE state was entered. */
+    evadeStartMs: number;
+    /** ctx.now() when WOUNDED state was entered. */
+    woundedStartMs: number;
+    /** ctx.now() when the current PSI channel began (legacy — use psiPhase). */
+    psiPhaseStartMs: number;
+    /** ctx.now() when INVESTIGATE state was entered. */
+    investigateStartMs: number;
+    /** ctx.now() when the NPC arrived at the investigate target and began looking around. -1 = not yet arrived. */
+    investigateLookAroundStartMs: number;
+    /** ID of the wounded ally being helped. Null when not in HELP_WOUNDED. */
+    helpWoundedTargetId: string | null;
+    /** ctx.now() when HELP_WOUNDED state was entered (overall approach timeout). */
+    helpWoundedStartMs: number;
+    /** ctx.now() when the NPC arrived next to the wounded ally and began assisting. -1 = not yet arrived. */
+    helpWoundedAssistStartMs: number;
+    /** World X of the wounded ally target (populated by calling state before enter()). */
+    helpWoundedX: number;
+    /** World Y of the wounded ally target (populated by calling state before enter()). */
+    helpWoundedY: number;
+    /** ID of the wounded enemy being hunted. Null when not in KILL_WOUNDED. */
+    killWoundedTargetId: string | null;
+    /** ctx.now() when KILL_WOUNDED state was entered (overall approach timeout). */
+    killWoundedStartMs: number;
+    /** ctx.now() when the AIM phase began. -1 = not yet in aim phase. */
+    killWoundedAimStartMs: number;
+    /** ctx.now() when the TAUNT phase began. -1 = not yet in taunt phase. */
+    killWoundedTauntStartMs: number;
+    /** ctx.now() when the EXECUTE phase began (first shot in burst). -1 = not yet. */
+    killWoundedExecuteStartMs: number;
+    /** Number of shots fired so far in the current EXECUTE burst. */
+    killWoundedShotsFired: number;
+    /** ctx.now() when the PAUSE phase began (post-kill stand). -1 = not yet. */
+    killWoundedPauseStartMs: number;
+    /** World X of the wounded enemy target (updated each frame from perception). */
+    killWoundedTargetX: number;
+    /** World Y of the wounded enemy target (updated each frame from perception). */
+    killWoundedTargetY: number;
+    /** Timestamp of last outgoing pack broadcast (ms). Used to throttle MonsterCombatController broadcasts. */
+    packLastBroadcastMs: number;
+    /** Current patrol waypoint index (wraps by handler). */
+    patrolWaypointIndex: number;
+    /** Current search waypoint index. */
+    searchWaypointIndex: number;
+    /** ID of the primary weapon (e.g. 'rifle'), or null if unarmed. */
+    primaryWeapon: string | null;
+    /** ID of the secondary weapon (e.g. 'pistol'), or null if not carrying one. */
+    secondaryWeapon: string | null;
+    /** Remaining grenade count. */
+    grenadeCount: number;
+    /** Remaining medkit count. */
+    medkitCount: number;
+    /** True while the NPC is in ALERT (aware of potential threat). */
+    isAlert: boolean;
+    /** True while the NPC is occupying a cover position. */
+    hasTakenCover: boolean;
+    /** World X of the current cover point (valid when hasTakenCover is true). */
+    coverPointX: number;
+    /** World Y of the current cover point (valid when hasTakenCover is true). */
+    coverPointY: number;
+    /**
+     * TakeCoverState loophole peek-fire-return-wait cycle data.
+     * Null when not in TAKE_COVER state.
+     */
+    loophole: ILoopholeState | null;
+    /** Boar charge attack data. */
+    chargePhase?: IChargePhase;
+    /** Bloodsucker stalk approach data. */
+    stalkPhase?: IStalkPhase;
+    /** Snork leap attack data. */
+    leapPhase?: ILeapPhase;
+    /** Controller PSI attack data. */
+    psiPhase?: IPsiPhase;
+    /**
+     * EAT_CORPSE state phase data.
+     * Opt-in — only populated by the `eat-corpse` module.
+     * Undefined for NPCs that never enter EAT_CORPSE.
+     */
+    eatCorpsePhase?: IEatCorpsePhase;
+    /**
+     * Morale value in the range [-1, 1].
+     * 0 = neutral, +1 = fully confident, -1 = fully panicked.
+     */
+    morale: number;
+    /**
+     * Discrete morale state derived from `morale`.
+     * - STABLE   : morale > retreatMoraleThreshold
+     * - SHAKEN   : retreatMoraleThreshold >= morale > panicMoraleThreshold
+     * - PANICKED : morale <= panicMoraleThreshold
+     */
+    moraleState: 'STABLE' | 'SHAKEN' | 'PANICKED';
+}
+//# sourceMappingURL=INPCOnlineState.d.ts.map

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

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

package/dist/states/INPCOnlineState.js

@@ -0,0 +1,9 @@
+// states/INPCOnlineState.ts
+// Mutable per-NPC AI data bag.
+//
+// All online state handlers are stateless singletons — per-NPC runtime state
+// lives here rather than in the handlers themselves. This mirrors the
+// AIComponent design in the game layer but strips all Phaser references,
+// making it usable in framework-agnostic environments (tests, server-side, etc.)
+export {};
+//# sourceMappingURL=INPCOnlineState.js.map

package/dist/states/INPCOnlineState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"INPCOnlineState.js","sourceRoot":"","sources":["../../src/states/INPCOnlineState.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,+BAA+B;AAC/B,EAAE;AACF,6EAA6E;AAC7E,sEAAsE;AACtE,yEAAyE;AACzE,iFAAiF"}

package/dist/states/IOnlineStateHandler.d.ts

@@ -0,0 +1,58 @@
+import type { INPCContext } from './INPCContext';
+/**
+ * Contract for all online NPC AI state handlers.
+ *
+ * Handlers are stateless — all mutable per-NPC data must be read from and
+ * written to {@link INPCContext.state}. This ensures a single handler
+ * instance can safely drive any number of simultaneous NPC entities.
+ *
+ * @example
+ * ```ts
+ * export class IdleStateHandler implements IOnlineStateHandler {
+ *   enter(ctx: INPCContext): void {
+ *     ctx.halt();
+ *   }
+ *
+ *   update(ctx: INPCContext, deltaMs: number): void {
+ *     if (ctx.perception?.hasVisibleEnemy()) {
+ *       ctx.transition('COMBAT');
+ *     }
+ *   }
+ *
+ *   exit(_ctx: INPCContext): void {
+ *     // nothing
+ *   }
+ * }
+ * ```
+ */
+export interface IOnlineStateHandler {
+    /**
+     * Called once when the FSM transitions into this state.
+     *
+     * Use to reset per-NPC timers, set initial velocities, emit entry
+     * vocalizations, etc.
+     *
+     * @param ctx - The NPC context for the entering entity.
+     */
+    enter(ctx: INPCContext): void;
+    /**
+     * Called every frame while this state is active.
+     *
+     * Contains the main per-frame logic: perception checks, movement commands,
+     * combat calculations, and transition triggers.
+     *
+     * @param ctx     - The NPC context for the updating entity.
+     * @param deltaMs - Elapsed time since the last frame (milliseconds).
+     */
+    update(ctx: INPCContext, deltaMs: number): void;
+    /**
+     * Called once when the FSM transitions out of this state.
+     *
+     * Use to clean up any per-NPC flags or release resources (e.g. halt movement,
+     * clear loophole state, reset animation overrides).
+     *
+     * @param ctx - The NPC context for the exiting entity.
+     */
+    exit(ctx: INPCContext): void;
+}
+//# sourceMappingURL=IOnlineStateHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IOnlineStateHandler.d.ts","sourceRoot":"","sources":["../../src/states/IOnlineStateHandler.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAE9B;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhD;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B"}

package/dist/states/IOnlineStateHandler.js

@@ -0,0 +1,13 @@
+// states/IOnlineStateHandler.ts
+// Contract for all online NPC state handlers.
+//
+// All state handlers must be stateless singletons — per-NPC runtime state
+// lives in INPCContext.state (INPCOnlineState), NOT in the handler itself.
+// This allows a single handler instance to be shared across all NPC instances.
+//
+// Lifecycle per active state:
+//   1. enter(ctx)          — called once when the FSM transitions into this state.
+//   2. update(ctx, deltaMs) — called every frame while this state is active.
+//   3. exit(ctx)           — called once when the FSM transitions out of this state.
+export {};
+//# sourceMappingURL=IOnlineStateHandler.js.map

package/dist/states/IOnlineStateHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOnlineStateHandler.js","sourceRoot":"","sources":["../../src/states/IOnlineStateHandler.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,8CAA8C;AAC9C,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,8BAA8B;AAC9B,mFAAmF;AACnF,6EAA6E;AAC7E,qFAAqF"}

package/dist/states/IStateConfig.d.ts

@@ -0,0 +1,272 @@
+import type { ISteeringConfig } from '../navigation/SteeringBehaviors';
+import type { ConditionChannel } from '../conditions/ConditionBank';
+/**
+ * Movement speeds and distance thresholds used by locomotion logic.
+ *
+ * Any game that runs only melee/monster AI can satisfy this sub-interface
+ * without needing the full {@link IStateConfig}.
+ */
+export interface IMovementConfig {
+    /** Base approach speed when closing distance to an enemy. */
+    approachSpeed: number;
+    /** Speed multiplier applied when fleeing (FLEE state). */
+    fleeSpeedMultiplier: number;
+    /** Additional speed multiplier applied when morale is PANICKED. */
+    panicFleeMultiplier: number;
+    /** Speed multiplier for a wounded NPC crawling away. */
+    woundedCrawlMultiplier: number;
+    /** Speed multiplier for grenade evasion sprint. */
+    evadeSpeedMultiplier: number;
+    /** Speed multiplier for a boar charge attack. */
+    chargeSpeedMultiplier: number;
+    /** Speed multiplier for bloodsucker stalk approach. */
+    stalkSpeedMultiplier: number;
+    /** Arrival threshold for generic waypoint navigation (px). */
+    arriveThreshold: number;
+    /** Arrival threshold for patrol waypoint advance (px). */
+    waypointArriveThreshold: number;
+    /** Maximum distance to engage an enemy before stopping and firing (px). */
+    combatRange: number;
+    /** Distance an NPC tries to put between itself and a threat when fleeing (px). */
+    fleeDistance: number;
+    /** Safe distance after grenade evasion sprint before resuming previous state (px). */
+    evadeSafeDistance: number;
+    /** Range at which a wounded NPC may try a last-stand shot (px). */
+    woundedLastStandRange: number;
+    /** Melee attack range (px) for monster close-combat states. */
+    meleeRange: number;
+    /** Distance at which a bloodsucker uncloaks for the melee strike (px). */
+    stalkUnclockDistance: number;
+    /** Interval (ms) between restricted-zone position checks. */
+    restrictedZoneCheckIntervalMs: number;
+    /**
+     * Optional flocking / pack-movement configuration.
+     * State handlers that support group steering call
+     * `createDefaultSteeringConfig(cfg.steering)` once in their constructor.
+     * Omit to use the built-in defaults.
+     */
+    readonly steering?: Partial<ISteeringConfig>;
+}
+/**
+ * Weapons, firing rates, damage, and morale thresholds for human combat.
+ *
+ * Fields that control how ranged combat, grenades, covers, and HP/morale
+ * transitions work for human NPCs.
+ */
+export interface ICombatConfig {
+    /** HP ratio below which the NPC enters the WOUNDED state. */
+    woundedHpThreshold: number;
+    /** Morale value at which the NPC transitions from COMBAT to RETREAT. */
+    retreatMoraleThreshold: number;
+    /** Morale value at which the NPC transitions to FLEE (panic flight). */
+    panicMoraleThreshold: number;
+    /** Minimum interval (ms) between successive NPC gunshots. */
+    fireRateMs: number;
+    /** Wind-up duration (ms) before a grenade is thrown. */
+    grenadeWindupMs: number;
+    /** Base bullet damage when no weapon loadout is assigned. */
+    bulletDamage: number;
+    /** Fraction of max HP restored by a single medkit use. */
+    medkitHealRatio: number;
+    /** Duration (ms) of the medkit use animation before the heal is applied. */
+    medkitUseDurationMs: number;
+    /**
+     * HP ratio below which a visible enemy is considered "wounded" and may trigger
+     * the KILL_WOUNDED behavior in CombatState / AlertState.
+     * Opt-in — only used when `getWoundedEnemies()` is implemented by the host.
+     * @default 0.25
+     */
+    killWoundedEnemyHpThreshold: number;
+    /**
+     * Approach range (px) at which KillWoundedState stops moving and enters the
+     * AIM phase. Shorter than combatRange — execution happens at close quarters.
+     * @default 80
+     */
+    killWoundedExecuteRange: number;
+}
+/**
+ * Monster-specific melee, ability, and lair parameters.
+ *
+ * A zombie or creature game only needs this sub-interface — no ranged-weapon
+ * fields or grenade logic required.
+ */
+export interface IMonsterConfig {
+    /** Base melee damage for monster close-combat strikes. */
+    meleeDamage: number;
+    /** Damage multiplier for a boar charge impact hit. */
+    chargeDamageMultiplier: number;
+    /** Cooldown (ms) between successive melee strikes. */
+    meleeCooldownMs: number;
+    /** Wind-up phase duration (ms) before boar starts charging. */
+    chargeWindupMs: number;
+    /** Wind-up phase duration (ms) before a snork leaps. */
+    leapWindupMs: number;
+    /** Airborne phase duration (ms) for the snork leap. */
+    leapAirtimeMs: number;
+    /** Channel phase duration (ms) for the controller PSI attack. */
+    psiChannelMs: number;
+    /** Inner lair radius — monster will not leave without a target (px). */
+    innerLairRadius: number;
+    /** Patrol radius — normal movement band around the anchor (px). */
+    patrolRadius: number;
+    /** Outer lair radius — hard chase break distance (px). */
+    outerRadius: number;
+    /** Alpha while fully invisible during stalk approach. */
+    stalkAlphaInvisible: number;
+    /** Alpha shimmer while moving during stalk approach. */
+    stalkAlphaShimmer: number;
+}
+/**
+ * Timeouts, durations, and periodic intervals that drive state timing.
+ *
+ * Centralises all "how long does this state last?" constants so SDK users
+ * can tune AI responsiveness without touching individual state handlers.
+ */
+export interface ITimingConfig {
+    /** How long (ms) the NPC stays in ALERT before reverting to PATROL/IDLE. */
+    alertDuration: number;
+    /** How long (ms) the NPC searches before giving up and returning to IDLE. */
+    searchDuration: number;
+    /** Maximum time (ms) spent in WOUNDED state before transitioning to FLEE. */
+    woundedMaxDurationMs: number;
+    /** Maximum time (ms) spent in RETREAT state before transitioning to FLEE. */
+    retreatMaxDurationMs: number;
+    /** Interval (ms) between suppressive shots fired during RETREAT. */
+    retreatFireIntervalMs: number;
+    /** Duration (ms) of the target-inertia lock (prevents rapid target switching). */
+    inertiaLockMs: number;
+    /** Delay (ms) before a camp/sleep NPC reacts to a detected threat. */
+    schemeReactionDelayMs: number;
+    /** Delay (ms) before a sleeping NPC reacts (longer than normal camp delay). */
+    campSleepReactionDelayMs: number;
+    /**
+     * Condition channel monitored in IdleState for fatigue/sickness transitions.
+     * Opt-in — only checked when `ctx.conditions` is non-null.
+     * @default 'stamina'
+     */
+    idleConditionChannel: ConditionChannel;
+    /**
+     * Condition intensity above which IdleState transitions to rest/camp.
+     * Uses strict `>` comparison against the channel level.
+     * @default 0.8
+     */
+    idleConditionThreshold: number;
+    /**
+     * Suspicion level above which IDLE/PATROL transitions to the alert state.
+     * Opt-in — only checked when `ctx.suspicion` is non-null.
+     * Uses strict `>` comparison via {@link ISuspicionAccess.hasReachedAlert}.
+     * @default 0.7
+     */
+    suspicionAlertThreshold: number;
+    /**
+     * Maximum time (ms) spent in the APPROACH phase before giving up and
+     * transitioning via `investigateOnTimeout`. Prevents NPCs from getting
+     * stuck indefinitely when the investigation point is unreachable.
+     * @default 10000
+     */
+    investigateMaxDurationMs: number;
+    /**
+     * How long (ms) the NPC spends "looking around" at the investigate location
+     * before concluding no threat is present and returning to PATROL/IDLE.
+     * @default 3000
+     */
+    investigateLookAroundMs: number;
+    /**
+     * How long (ms) the NPC stands next to the wounded ally providing assistance.
+     * @default 5000
+     */
+    helpWoundedAssistMs: number;
+    /**
+     * Maximum time (ms) for the APPROACH phase of HelpWoundedState before giving up.
+     * @default 10000
+     */
+    helpWoundedMaxDurationMs: number;
+    /**
+     * Suspicion amount added to the accumulator when the NPC spots a friendly corpse.
+     * Only active when `ctx.suspicion` is non-null and `getVisibleCorpses()` is implemented.
+     * @default 0.6
+     */
+    corpseFoundSuspicion: number;
+    /**
+     * Maximum time (ms) allowed for the APPROACH phase of KillWoundedState before
+     * aborting and transitioning via `killWoundedOnTimeout`.
+     * @default 8000
+     */
+    killWoundedMaxApproachMs: number;
+    /**
+     * Duration (ms) of the AIM phase (weapon-raise pause) before taunting.
+     * @default 800
+     */
+    killWoundedAimMs: number;
+    /**
+     * Duration (ms) of the TAUNT phase (bark plays out) before firing.
+     * @default 1200
+     */
+    killWoundedTauntMs: number;
+    /**
+     * Number of shots to fire in the EXECUTE burst.
+     * @default 3
+     */
+    killWoundedBurstCount: number;
+    /**
+     * Duration (ms) to stand still after all burst shots fired (PAUSE phase).
+     * Equivalent to X-Ray's PauseAfterKill 1000ms inertia.
+     * @default 1000
+     */
+    killWoundedPauseMs: number;
+    /**
+     * Minimum interval (ms) between outgoing pack broadcasts from MonsterCombatController.
+     * Prevents saturating the host's pack record with per-frame writes.
+     * @default 500
+     */
+    packAlertIntervalMs: number;
+    /**
+     * Time-to-live (ms) for a pack alert level without a refresh broadcast.
+     * Host implementations should reset the level to 'NONE' after this duration
+     * to prevent PATROL↔ALERT livelock when contacts fade.
+     * @default 5000
+     */
+    packAlertTtlMs: number;
+    /** Minimum random wait duration (ms) while hiding behind cover. */
+    loopholeWaitMinMs: number;
+    /** Maximum random wait duration (ms) while hiding behind cover. */
+    loopholeWaitMaxMs: number;
+    /** Duration (ms) of the peek-out phase before firing. */
+    loopholePeekDurationMs: number;
+    /** Duration (ms) of the fire phase while peeked out. */
+    loopholeFireDurationMs: number;
+    /** Duration (ms) of the return-to-cover phase after firing. */
+    loopholeReturnDurationMs: number;
+}
+/**
+ * Complete set of tuning constants for all online AI state handlers.
+ *
+ * Composes all four sub-interfaces via intersection so existing code using
+ * `IStateConfig` compiles unchanged.  For minimal usage (e.g. a monster-only
+ * game that needs no ranged combat), you can satisfy individual sub-interfaces
+ * instead of the full `IStateConfig`.
+ *
+ * Create with {@link createDefaultStateConfig} and override individual fields
+ * to customise the AI behaviour without modifying any handler code.
+ *
+ * @example
+ * ```ts
+ * // Full config for a human NPC
+ * const cfg = createDefaultStateConfig({ combatRange: 250 });
+ *
+ * // Partial config — just movement for a simple platformer enemy
+ * const move: IMovementConfig = createDefaultStateConfig({ approachSpeed: 80 });
+ * ```
+ */
+export type IStateConfig = IMovementConfig & ICombatConfig & IMonsterConfig & ITimingConfig;
+/**
+ * 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 declare function createDefaultStateConfig(overrides?: Partial<IStateConfig>): IStateConfig;
+//# sourceMappingURL=IStateConfig.d.ts.map

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

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