@alife-sdk/core 0.1.0

package/dist/ai/MemorySystem.js

@@ -0,0 +1,207 @@
+/**
+ * Multi-channel memory bank with confidence decay.
+ *
+ * MemoryBank provides per-NPC episodic memory storage. Memories are
+ * categorised by channel (visual, sound, hit, danger) and decay over time.
+ * Records below the minimum confidence threshold are pruned automatically
+ * during update().
+ *
+ * Storage layout: Map keyed by sourceId for O(1) read/write per entry.
+ * A single entity may have at most one record per sourceId; newer
+ * observations overwrite older ones.
+ */
+// ---------------------------------------------------------------------------
+// Memory channel
+// ---------------------------------------------------------------------------
+export const MemoryChannel = {
+    VISUAL: 'visual',
+    SOUND: 'sound',
+    HIT: 'hit',
+    DANGER: 'danger',
+};
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_RECORDS = 32;
+const DEFAULT_DECAY_RATE = 0.1; // confidence per second
+const DEFAULT_MIN_CONFIDENCE = 0.05;
+// ---------------------------------------------------------------------------
+// MemoryBank
+// ---------------------------------------------------------------------------
+export class MemoryBank {
+    constructor(config) {
+        this.records = new Map();
+        this.byChannel = new Map();
+        this._toDelete = [];
+        this.timeFn = config.timeFn;
+        this.maxRecords = config.maxRecords ?? DEFAULT_MAX_RECORDS;
+        this.decayRate = config.decayRate ?? DEFAULT_DECAY_RATE;
+        this.minConfidence = config.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+        this.channelDecayRates = config.channelDecayRates;
+    }
+    // -----------------------------------------------------------------------
+    // Mutation
+    // -----------------------------------------------------------------------
+    /**
+     * Add or update a memory record.
+     *
+     * If a record for this sourceId already exists, its position and timestamp
+     * are updated and confidence is reset to the provided value (default 1.0).
+     * If the bank is at capacity, the lowest-confidence record is evicted.
+     */
+    remember(input) {
+        const { sourceId, channel, position, confidence = 1.0 } = input;
+        const existing = this.records.get(sourceId);
+        if (existing) {
+            // If channel changed, migrate between index sets.
+            if (existing.channel !== channel) {
+                this.removeFromChannelIndex(existing);
+                existing.channel = channel;
+                this.addToChannelIndex(existing);
+            }
+            existing.position = position;
+            existing.confidence = Math.max(0, Math.min(1, confidence));
+            existing.timestamp = this.timeFn();
+            return;
+        }
+        if (this.records.size >= this.maxRecords) {
+            this.evictLowestConfidence();
+        }
+        const record = {
+            sourceId,
+            channel,
+            position,
+            confidence: Math.max(0, Math.min(1, confidence)),
+            timestamp: this.timeFn(),
+        };
+        this.records.set(sourceId, record);
+        this.addToChannelIndex(record);
+    }
+    // -----------------------------------------------------------------------
+    // Queries
+    // -----------------------------------------------------------------------
+    /** Get memory of a specific source. */
+    recall(sourceId) {
+        return this.records.get(sourceId);
+    }
+    /** Get all records on a specific channel. */
+    getByChannel(channel) {
+        const set = this.byChannel.get(channel);
+        if (!set || set.size === 0)
+            return [];
+        return Array.from(set);
+    }
+    /** Get the highest-confidence record, or undefined if the bank is empty. */
+    getMostConfident() {
+        let best;
+        for (const record of this.records.values()) {
+            if (!best || record.confidence > best.confidence) {
+                best = record;
+            }
+        }
+        return best;
+    }
+    // -----------------------------------------------------------------------
+    // Decay and housekeeping
+    // -----------------------------------------------------------------------
+    /**
+     * Decay all records and remove those below the minimum confidence threshold.
+     *
+     * @param deltaSec      - Seconds elapsed since the last update.
+     * @param minConfidence - Records below this threshold are pruned.
+     */
+    update(deltaSec) {
+        this._toDelete.length = 0;
+        for (const [id, record] of this.records) {
+            const rate = this.channelDecayRates?.[record.channel] ?? this.decayRate;
+            const decay = rate * deltaSec;
+            record.confidence = Math.max(0, record.confidence - decay);
+            if (record.confidence < this.minConfidence) {
+                this._toDelete.push(id);
+            }
+        }
+        for (let i = 0; i < this._toDelete.length; i++) {
+            const id = this._toDelete[i];
+            const record = this.records.get(id);
+            if (record) {
+                this.removeFromChannelIndex(record);
+                this.records.delete(id);
+            }
+        }
+    }
+    /** Forget a specific source. */
+    forget(sourceId) {
+        const record = this.records.get(sourceId);
+        if (record) {
+            this.removeFromChannelIndex(record);
+            this.records.delete(sourceId);
+        }
+    }
+    /** Clear all memories. */
+    clear() {
+        this.records.clear();
+        this.byChannel.clear();
+    }
+    get size() {
+        return this.records.size;
+    }
+    // -----------------------------------------------------------------------
+    // Serialisation
+    // -----------------------------------------------------------------------
+    serialize() {
+        return [...this.records.values()].map((r) => ({
+            sourceId: r.sourceId,
+            channel: r.channel,
+            position: r.position,
+            confidence: r.confidence,
+            timestamp: r.timestamp,
+        }));
+    }
+    restore(records) {
+        this.records.clear();
+        this.byChannel.clear();
+        for (const r of records) {
+            const mutable = { ...r };
+            this.records.set(r.sourceId, mutable);
+            this.addToChannelIndex(mutable);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Private
+    // -----------------------------------------------------------------------
+    /** Evict the record with the lowest confidence to make room. */
+    evictLowestConfidence() {
+        let lowestId;
+        let lowestConfidence = Infinity;
+        for (const [id, record] of this.records) {
+            if (record.confidence < lowestConfidence) {
+                lowestConfidence = record.confidence;
+                lowestId = id;
+            }
+        }
+        if (lowestId !== undefined) {
+            const record = this.records.get(lowestId);
+            if (record) {
+                this.removeFromChannelIndex(record);
+            }
+            this.records.delete(lowestId);
+        }
+    }
+    /** Add a record to the byChannel secondary index. */
+    addToChannelIndex(record) {
+        let set = this.byChannel.get(record.channel);
+        if (!set) {
+            set = new Set();
+            this.byChannel.set(record.channel, set);
+        }
+        set.add(record);
+    }
+    /** Remove a record from the byChannel secondary index. */
+    removeFromChannelIndex(record) {
+        const set = this.byChannel.get(record.channel);
+        if (set) {
+            set.delete(record);
+        }
+    }
+}
+//# sourceMappingURL=MemorySystem.js.map

package/dist/ai/MemorySystem.js.map

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

package/dist/ai/StateMachine.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Generic finite state machine that works with the AIStateRegistry plugin system.
+ *
+ * The FSM delegates state behaviour to IStateHandler instances registered
+ * in the AIStateRegistry. Each update tick runs the current handler's
+ * update() method and then evaluates auto-transition conditions.
+ *
+ * Lifecycle per state:
+ *   1. enter()  -- called once when transitioning into the state
+ *   2. update() -- called every tick while the state is active
+ *   3. exit()   -- called once when transitioning out of the state
+ */
+import type { IEntity } from '../entity/IEntity';
+import type { AIStateRegistry } from '../registry/AIStateRegistry';
+export type TransitionResult = {
+    readonly success: true;
+} | {
+    readonly success: false;
+    readonly reason: 'not_allowed' | 'exit_guard' | 'enter_guard';
+};
+export declare class StateMachine {
+    private currentStateId;
+    private readonly registry;
+    private readonly entity;
+    constructor(entity: IEntity, registry: AIStateRegistry, initialState: string);
+    /** Current active state identifier. */
+    get state(): string;
+    /**
+     * Force transition to a new state.
+     *
+     * Calls exit() on the current state handler, then enter() on the new one.
+     * If the target state is the same as the current state, the transition
+     * is still performed (exit + enter) to allow state reset semantics.
+     */
+    transition(newState: string): TransitionResult;
+    /**
+     * Run one tick of the FSM.
+     *
+     * First, the current handler's update() is called. Then the registry's
+     * auto-transition conditions are evaluated. If any condition fires,
+     * the FSM transitions to the target state automatically.
+     *
+     * @param delta - Seconds elapsed since the last update.
+     */
+    update(delta: number): void;
+    /** Exit the current state. Call when the entity is destroyed. */
+    destroy(): void;
+}
+//# sourceMappingURL=StateMachine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StateMachine.d.ts","sourceRoot":"","sources":["../../src/ai/StateMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAG,aAAa,CAAA;CAAE,CAAC;AAE/F,qBAAa,YAAY;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAErB,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM;IAa5E,uCAAuC;IACvC,IAAI,KAAK,IAAI,MAAM,CAElB;IAMD;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAsB9C;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAkB3B,iEAAiE;IACjE,OAAO,IAAI,IAAI;CAIhB"}

package/dist/ai/StateMachine.js

@@ -0,0 +1,83 @@
+/**
+ * Generic finite state machine that works with the AIStateRegistry plugin system.
+ *
+ * The FSM delegates state behaviour to IStateHandler instances registered
+ * in the AIStateRegistry. Each update tick runs the current handler's
+ * update() method and then evaluates auto-transition conditions.
+ *
+ * Lifecycle per state:
+ *   1. enter()  -- called once when transitioning into the state
+ *   2. update() -- called every tick while the state is active
+ *   3. exit()   -- called once when transitioning out of the state
+ */
+export class StateMachine {
+    constructor(entity, registry, initialState) {
+        this.entity = entity;
+        this.registry = registry;
+        this.currentStateId = initialState;
+        const definition = this.registry.get(this.currentStateId);
+        definition.handler.enter(this.entity);
+    }
+    // -----------------------------------------------------------------------
+    // Accessors
+    // -----------------------------------------------------------------------
+    /** Current active state identifier. */
+    get state() {
+        return this.currentStateId;
+    }
+    // -----------------------------------------------------------------------
+    // Transitions
+    // -----------------------------------------------------------------------
+    /**
+     * Force transition to a new state.
+     *
+     * Calls exit() on the current state handler, then enter() on the new one.
+     * If the target state is the same as the current state, the transition
+     * is still performed (exit + enter) to allow state reset semantics.
+     */
+    transition(newState) {
+        const oldDefinition = this.registry.get(this.currentStateId);
+        const newDefinition = this.registry.get(newState);
+        // Whitelist check: if allowedTransitions is set, only listed targets are permitted.
+        if (oldDefinition.allowedTransitions && !oldDefinition.allowedTransitions.includes(newState)) {
+            return { success: false, reason: 'not_allowed' };
+        }
+        if (oldDefinition.canExit?.(this.entity, newState) === false)
+            return { success: false, reason: 'exit_guard' };
+        if (newDefinition.canEnter?.(this.entity, this.currentStateId) === false)
+            return { success: false, reason: 'enter_guard' };
+        oldDefinition.handler.exit(this.entity);
+        this.currentStateId = newState;
+        newDefinition.handler.enter(this.entity);
+        return { success: true };
+    }
+    // -----------------------------------------------------------------------
+    // Update
+    // -----------------------------------------------------------------------
+    /**
+     * Run one tick of the FSM.
+     *
+     * First, the current handler's update() is called. Then the registry's
+     * auto-transition conditions are evaluated. If any condition fires,
+     * the FSM transitions to the target state automatically.
+     *
+     * @param delta - Seconds elapsed since the last update.
+     */
+    update(delta) {
+        const definition = this.registry.get(this.currentStateId);
+        definition.handler.update(this.entity, delta);
+        const nextState = this.registry.evaluateTransitions(this.currentStateId, this.entity);
+        if (nextState !== null) {
+            this.transition(nextState);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Cleanup
+    // -----------------------------------------------------------------------
+    /** Exit the current state. Call when the entity is destroyed. */
+    destroy() {
+        const definition = this.registry.get(this.currentStateId);
+        definition.handler.exit(this.entity);
+    }
+}
+//# sourceMappingURL=StateMachine.js.map

package/dist/ai/StateMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateMachine.js","sourceRoot":"","sources":["../../src/ai/StateMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,OAAO,YAAY;IAKvB,YAAY,MAAe,EAAE,QAAyB,EAAE,YAAoB;QAC1E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,YAAY,CAAC;QAEnC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1D,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,0EAA0E;IAC1E,YAAY;IACZ,0EAA0E;IAE1E,uCAAuC;IACvC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,0EAA0E;IAC1E,cAAc;IACd,0EAA0E;IAE1E;;;;;;OAMG;IACH,UAAU,CAAC,QAAgB;QACzB,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC7D,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAElD,oFAAoF;QACpF,IAAI,aAAa,CAAC,kBAAkB,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QACnD,CAAC;QAED,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,KAAK;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;QAC9G,IAAI,aAAa,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,KAAK,KAAK;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QAE3H,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;QAC/B,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,0EAA0E;IAC1E,SAAS;IACT,0EAA0E;IAE1E;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAa;QAClB,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1D,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAE9C,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CACjD,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,MAAM,CACZ,CAAC;QAEF,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,UAAU;IACV,0EAA0E;IAE1E,iEAAiE;IACjE,OAAO;QACL,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1D,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/ai/WorldState.d.ts

@@ -0,0 +1,48 @@
+/**
+ * GOAP world state -- a key-value map of planning properties.
+ *
+ * Used both as the "current world state" fed to the planner and as
+ * goal/precondition/effect descriptors on GOAPActions.
+ *
+ * Only properties that have been explicitly set() are considered active.
+ * Unset properties are treated as absent (not false/0/""). This distinction
+ * matters for satisfies(): a goal that only specifies { alive: true }
+ * matches any world state where "alive" is true, regardless of all other
+ * properties.
+ *
+ * Property values are polymorphic (boolean | number | string) to support
+ * both boolean flags and numeric planning properties (e.g., ammo count).
+ */
+export type WorldStateValue = boolean | number | string;
+export declare class WorldState {
+    private readonly properties;
+    set(key: string, value: WorldStateValue): void;
+    get(key: string): WorldStateValue | undefined;
+    has(key: string): boolean;
+    /**
+     * Check if this state satisfies all conditions in the goal.
+     *
+     * Returns true when every property defined in the goal has the same
+     * value in this state. Properties present in this state but absent
+     * in the goal are irrelevant.
+     */
+    satisfies(goal: WorldState): boolean;
+    /** Create a deep copy. */
+    clone(): WorldState;
+    /**
+     * Distance heuristic: count of differing properties.
+     *
+     * For A* planning, this counts properties in `other` that do not match
+     * this state. This is an admissible heuristic because each action can
+     * satisfy at most one property per step in the worst case.
+     */
+    distanceTo(other: WorldState): number;
+    /**
+     * Apply another state's properties as effects, returning a new WorldState.
+     * Does not mutate the original.
+     */
+    applyEffects(effects: WorldState): WorldState;
+    /** Return all property keys. Used by the planner for state fingerprinting. */
+    keys(): IterableIterator<string>;
+}
+//# sourceMappingURL=WorldState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WorldState.d.ts","sourceRoot":"","sources":["../../src/ai/WorldState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IAMjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAQ9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQzB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAQpC,0BAA0B;IAC1B,KAAK,IAAI,UAAU;IAQnB;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAUrC;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU;IAQ7C,8EAA8E;IAC9E,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;CAGjC"}

package/dist/ai/WorldState.js

@@ -0,0 +1,93 @@
+/**
+ * GOAP world state -- a key-value map of planning properties.
+ *
+ * Used both as the "current world state" fed to the planner and as
+ * goal/precondition/effect descriptors on GOAPActions.
+ *
+ * Only properties that have been explicitly set() are considered active.
+ * Unset properties are treated as absent (not false/0/""). This distinction
+ * matters for satisfies(): a goal that only specifies { alive: true }
+ * matches any world state where "alive" is true, regardless of all other
+ * properties.
+ *
+ * Property values are polymorphic (boolean | number | string) to support
+ * both boolean flags and numeric planning properties (e.g., ammo count).
+ */
+export class WorldState {
+    constructor() {
+        this.properties = new Map();
+    }
+    // -----------------------------------------------------------------------
+    // Mutators
+    // -----------------------------------------------------------------------
+    set(key, value) {
+        this.properties.set(key, value);
+    }
+    // -----------------------------------------------------------------------
+    // Accessors
+    // -----------------------------------------------------------------------
+    get(key) {
+        return this.properties.get(key);
+    }
+    has(key) {
+        return this.properties.has(key);
+    }
+    // -----------------------------------------------------------------------
+    // Planning utilities
+    // -----------------------------------------------------------------------
+    /**
+     * Check if this state satisfies all conditions in the goal.
+     *
+     * Returns true when every property defined in the goal has the same
+     * value in this state. Properties present in this state but absent
+     * in the goal are irrelevant.
+     */
+    satisfies(goal) {
+        for (const [key, goalValue] of goal.properties) {
+            const currentValue = this.properties.get(key);
+            if (currentValue !== goalValue)
+                return false;
+        }
+        return true;
+    }
+    /** Create a deep copy. */
+    clone() {
+        const copy = new WorldState();
+        for (const [key, value] of this.properties) {
+            copy.properties.set(key, value);
+        }
+        return copy;
+    }
+    /**
+     * Distance heuristic: count of differing properties.
+     *
+     * For A* planning, this counts properties in `other` that do not match
+     * this state. This is an admissible heuristic because each action can
+     * satisfy at most one property per step in the worst case.
+     */
+    distanceTo(other) {
+        let count = 0;
+        for (const [key, value] of other.properties) {
+            if (this.properties.get(key) !== value) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Apply another state's properties as effects, returning a new WorldState.
+     * Does not mutate the original.
+     */
+    applyEffects(effects) {
+        const next = this.clone();
+        for (const [key, value] of effects.properties) {
+            next.properties.set(key, value);
+        }
+        return next;
+    }
+    /** Return all property keys. Used by the planner for state fingerprinting. */
+    keys() {
+        return this.properties.keys();
+    }
+}
+//# sourceMappingURL=WorldState.js.map

package/dist/ai/WorldState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorldState.js","sourceRoot":"","sources":["../../src/ai/WorldState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,OAAO,UAAU;IAAvB;QACmB,eAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;IAmFnE,CAAC;IAjFC,0EAA0E;IAC1E,WAAW;IACX,0EAA0E;IAE1E,GAAG,CAAC,GAAW,EAAE,KAAsB;QACrC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,YAAY;IACZ,0EAA0E;IAE1E,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,qBAAqB;IACrB,0EAA0E;IAE1E;;;;;;OAMG;IACH,SAAS,CAAC,IAAgB;QACxB,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,YAAY,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0BAA0B;IAC1B,KAAK;QACH,MAAM,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,KAAiB;QAC1B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;gBACvC,KAAK,EAAE,CAAC;YACV,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,OAAmB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,IAAI;QACF,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;CACF"}

package/dist/ai/index.d.ts

@@ -0,0 +1,10 @@
+export { StateMachine } from './StateMachine';
+export type { TransitionResult } from './StateMachine';
+export { MemoryBank, MemoryChannel } from './MemorySystem';
+export type { MemoryRecord, IMemoryBankConfig, IMemoryInput } from './MemorySystem';
+export { DangerManager, DangerType } from './DangerManager';
+export type { IDangerEntry } from './DangerManager';
+export { WorldState } from './WorldState';
+export { GOAPPlanner } from './GOAPPlanner';
+export { GOAPAction, ActionStatus } from './GOAPAction';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/ai/index.js

@@ -0,0 +1,8 @@
+// ai sub-path barrel
+export { StateMachine } from './StateMachine';
+export { MemoryBank, MemoryChannel } from './MemorySystem';
+export { DangerManager, DangerType } from './DangerManager';
+export { WorldState } from './WorldState';
+export { GOAPPlanner } from './GOAPPlanner';
+export { GOAPAction, ActionStatus } from './GOAPAction';
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/combat/DamageInstance.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Value object representing a single damage event.
+ *
+ * Immutable by convention (all fields are readonly).
+ * Created exclusively through the {@link createDamageInstance} factory
+ * which validates that the amount is positive.
+ */
+export interface IDamageInstance {
+    readonly amount: number;
+    readonly damageTypeId: string;
+    readonly sourceId: string;
+    readonly sourceType: 'entity' | 'anomaly' | 'surge';
+}
+export interface IDamageInstanceParams {
+    readonly amount: number;
+    readonly damageTypeId: string;
+    readonly sourceId: string;
+    readonly sourceType: IDamageInstance['sourceType'];
+}
+/**
+ * Factory that creates a validated IDamageInstance.
+ *
+ * @throws if amount is not positive
+ */
+export declare function createDamageInstance(params: IDamageInstanceParams): IDamageInstance;
+//# sourceMappingURL=DamageInstance.d.ts.map

package/dist/combat/DamageInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DamageInstance.d.ts","sourceRoot":"","sources":["../../src/combat/DamageInstance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;CACrD;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAenF"}

package/dist/combat/DamageInstance.js

@@ -0,0 +1,25 @@
+/**
+ * Value object representing a single damage event.
+ *
+ * Immutable by convention (all fields are readonly).
+ * Created exclusively through the {@link createDamageInstance} factory
+ * which validates that the amount is positive.
+ */
+/**
+ * Factory that creates a validated IDamageInstance.
+ *
+ * @throws if amount is not positive
+ */
+export function createDamageInstance(params) {
+    const { amount, damageTypeId, sourceId, sourceType } = params;
+    if (amount <= 0) {
+        throw new Error(`[DamageInstance] amount must be positive, got ${amount}`);
+    }
+    return {
+        amount,
+        damageTypeId,
+        sourceId,
+        sourceType,
+    };
+}
+//# sourceMappingURL=DamageInstance.js.map

package/dist/combat/DamageInstance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DamageInstance.js","sourceRoot":"","sources":["../../src/combat/DamageInstance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA6B;IAChE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IAE9D,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,iDAAiD,MAAM,EAAE,CAC1D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM;QACN,YAAY;QACZ,QAAQ;QACR,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/combat/MoraleStateMachine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 3-state morale system: STABLE / SHAKEN / PANICKED.
+ *
+ * Morale is a value in [-1, 1] that determines the NPC's psychological state:
+ *   - STABLE:   morale > shakenThreshold  (-0.3 by default), recovery +0.005/s toward 0
+ *   - SHAKEN:   morale between shaken and panicked thresholds, recovery +0.01/s toward 0
+ *   - PANICKED: morale <= panicThreshold (-0.7 by default), no recovery
+ *
+ * External systems call {@link adjust} to apply morale hits/boosts
+ * and {@link update} each frame to apply recovery.
+ */
+export declare const MoraleState: {
+    readonly STABLE: "stable";
+    readonly SHAKEN: "shaken";
+    readonly PANICKED: "panicked";
+};
+export type MoraleState = (typeof MoraleState)[keyof typeof MoraleState];
+export interface IMoraleConfig {
+    /** Threshold below which the NPC becomes SHAKEN. Default -0.3. */
+    shakenThreshold: number;
+    /** Threshold at or below which the NPC becomes PANICKED. Default -0.7. */
+    panicThreshold: number;
+    /** Recovery rate (per second) while STABLE. Default 0.005. */
+    stableRecoveryRate: number;
+    /** Recovery rate (per second) while SHAKEN. Default 0.01. */
+    shakenRecoveryRate: number;
+}
+export declare class MoraleTracker {
+    private currentMorale;
+    private _cachedState;
+    private readonly config;
+    constructor(config?: Partial<IMoraleConfig>);
+    /** Current morale value in [-1, 1]. */
+    get morale(): number;
+    /** Derived morale state based on current value and thresholds. */
+    get state(): MoraleState;
+    /**
+     * Apply a morale adjustment (positive = boost, negative = hit).
+     * Result is clamped to [-1, 1].
+     */
+    adjust(delta: number): void;
+    /**
+     * Tick recovery. Should be called each frame with the elapsed seconds.
+     *
+     * - STABLE: recovers toward 0 at stableRecoveryRate per second.
+     * - SHAKEN: recovers toward 0 at shakenRecoveryRate per second.
+     * - PANICKED: no recovery.
+     */
+    update(deltaSec: number): void;
+    /** Reset morale to 0 (STABLE). */
+    reset(): void;
+}
+//# sourceMappingURL=MoraleStateMachine.d.ts.map