@alife-sdk/core 0.1.0

package/dist/events/ALifeEvents.d.ts.map

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

package/dist/events/ALifeEvents.js

@@ -0,0 +1,53 @@
+export const ALifeEvents = {
+    // A-Life core
+    TICK: 'alife:tick',
+    NPC_MOVED: 'alife:npc_moved',
+    FACTION_CONFLICT: 'alife:faction_conflict',
+    NPC_ONLINE: 'alife:npc_online',
+    NPC_OFFLINE: 'alife:npc_offline',
+    TASK_ASSIGNED: 'alife:task_assigned',
+    NPC_DIED: 'alife:npc_died',
+    SPAWN_REQUESTED: 'alife:spawn_requested',
+    NPC_RELEASED: 'alife:npc_released',
+    TERRAIN_STATE_CHANGED: 'alife:terrain_state_changed',
+    MORALE_CHANGED: 'alife:morale_changed',
+    NPC_PANICKED: 'ai:npc_panicked',
+    // AI perception
+    SPOTTED_ENEMY: 'ai:spotted_enemy',
+    HEARD_SOUND: 'ai:heard_sound',
+    LOST_TARGET: 'ai:lost_target',
+    STATE_CHANGED: 'ai:state_changed',
+    NPC_SHOOT: 'ai:npc_shoot',
+    NPC_VOCALIZATION: 'ai:npc_vocalization',
+    NPC_ATTACKED: 'ai:npc_attacked',
+    // Surge
+    SURGE_WARNING: 'surge:warning',
+    SURGE_STARTED: 'surge:started',
+    SURGE_ENDED: 'surge:ended',
+    SURGE_DAMAGE: 'surge:damage',
+    // Anomaly
+    ANOMALY_DAMAGE: 'anomaly:damage',
+    ARTEFACT_SPAWNED: 'anomaly:artefact_spawned',
+    ARTEFACT_COLLECTED: 'anomaly:artefact_collected',
+    // Squad
+    SQUAD_FORMED: 'squad:formed',
+    SQUAD_MEMBER_ADDED: 'squad:member_added',
+    SQUAD_MEMBER_REMOVED: 'squad:member_removed',
+    SQUAD_DISBANDED: 'squad:disbanded',
+    SQUAD_COMMAND_ISSUED: 'squad:command_issued',
+    SQUAD_GOAL_SET: 'squad:goal_set',
+    SQUAD_GOAL_CLEARED: 'squad:goal_cleared',
+    // Faction
+    FACTION_RELATION_CHANGED: 'faction:relation_changed',
+    // Time
+    HOUR_CHANGED: 'time:hour_changed',
+    DAY_NIGHT_CHANGED: 'time:day_night_changed',
+    // Social
+    NPC_SOCIAL_BUBBLE: 'social:npc_bubble',
+    NPC_MEET_PLAYER: 'social:npc_meet_player',
+    KAMP_STATE_CHANGED: 'social:kamp_state_changed',
+    // Monster
+    MONSTER_MELEE_HIT: 'monster:melee_hit',
+    PSI_ATTACK_START: 'monster:psi_attack_start',
+};
+//# sourceMappingURL=ALifeEvents.js.map

package/dist/events/ALifeEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ALifeEvents.js","sourceRoot":"","sources":["../../src/events/ALifeEvents.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,cAAc;IACd,IAAI,EAAE,YAAY;IAClB,SAAS,EAAE,iBAAiB;IAC5B,gBAAgB,EAAE,wBAAwB;IAC1C,UAAU,EAAE,kBAAkB;IAC9B,WAAW,EAAE,mBAAmB;IAChC,aAAa,EAAE,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB;IAC1B,eAAe,EAAE,uBAAuB;IACxC,YAAY,EAAE,oBAAoB;IAClC,qBAAqB,EAAE,6BAA6B;IACpD,cAAc,EAAE,sBAAsB;IACtC,YAAY,EAAE,iBAAiB;IAE/B,gBAAgB;IAChB,aAAa,EAAE,kBAAkB;IACjC,WAAW,EAAE,gBAAgB;IAC7B,WAAW,EAAE,gBAAgB;IAC7B,aAAa,EAAE,kBAAkB;IACjC,SAAS,EAAE,cAAc;IACzB,gBAAgB,EAAE,qBAAqB;IACvC,YAAY,EAAE,iBAAiB;IAE/B,QAAQ;IACR,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,WAAW,EAAE,aAAa;IAC1B,YAAY,EAAE,cAAc;IAE5B,UAAU;IACV,cAAc,EAAE,gBAAgB;IAChC,gBAAgB,EAAE,0BAA0B;IAC5C,kBAAkB,EAAE,4BAA4B;IAEhD,QAAQ;IACR,YAAY,EAAE,cAAc;IAC5B,kBAAkB,EAAE,oBAAoB;IACxC,oBAAoB,EAAE,sBAAsB;IAC5C,eAAe,EAAE,iBAAiB;IAClC,oBAAoB,EAAE,sBAAsB;IAC5C,cAAc,EAAE,gBAAgB;IAChC,kBAAkB,EAAE,oBAAoB;IAExC,UAAU;IACV,wBAAwB,EAAE,0BAA0B;IAEpD,OAAO;IACP,YAAY,EAAE,mBAAmB;IACjC,iBAAiB,EAAE,wBAAwB;IAE3C,SAAS;IACT,iBAAiB,EAAE,mBAAmB;IACtC,eAAe,EAAE,wBAAwB;IACzC,kBAAkB,EAAE,2BAA2B;IAE/C,UAAU;IACV,iBAAiB,EAAE,mBAAmB;IACtC,gBAAgB,EAAE,0BAA0B;CACpC,CAAC"}

package/dist/events/EventBus.d.ts

@@ -0,0 +1,52 @@
+import type { ILogger } from '../ports/ILogger';
+/**
+ * Type-safe event emitter parameterised by a payload map.
+ *
+ * `TPayloads` maps event name strings to their payload types, giving full
+ * IntelliSense for both emitting and subscribing — wrong event names or
+ * payload shapes are caught at compile time.
+ *
+ * @typeParam TPayloads - Record mapping event name → payload type.
+ *
+ * @example
+ * ```ts
+ * interface MyEvents {
+ *   'player:hit': { damage: number };
+ *   'player:died': undefined;
+ * }
+ * const bus = new EventBus<MyEvents>();
+ * bus.on('player:hit', (p) => console.log(p.damage)); // p is typed
+ * bus.emit('player:hit', { damage: 10 });
+ * ```
+ */
+export declare class EventBus<TPayloads = Record<string, unknown>> {
+    private listeners;
+    private _frontQueue;
+    private _backQueue;
+    private readonly _onceEntries;
+    private readonly _logger;
+    /**
+     * @param logger - Optional logger for reporting listener errors. Defaults to
+     *   `console` when not provided, preserving backward-compatibility.
+     */
+    constructor(logger?: ILogger);
+    /** Queue an event for deferred dispatch. Call flush() to deliver. */
+    emit<K extends keyof TPayloads & string>(event: K, payload?: TPayloads[K]): void;
+    /**
+     * Process all queued events, dispatching to registered listeners.
+     * Handles re-entrant emit safely: events emitted during flush are
+     * appended to the queue and processed within the same flush cycle.
+     */
+    flush(): void;
+    /** Number of events waiting in the queue. */
+    get pendingCount(): number;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof TPayloads & string>(event: K, fn: (payload: TPayloads[K]) => void, context?: unknown): () => void;
+    /** Subscribe to an event for a single invocation. Returns an unsubscribe function. */
+    once<K extends keyof TPayloads & string>(event: K, fn: (payload: TPayloads[K]) => void): () => void;
+    /** Unsubscribe a specific listener. Both `fn` and `context` must match the original on() call. */
+    off<K extends keyof TPayloads & string>(event: K, fn: (payload: TPayloads[K]) => void, context?: unknown): void;
+    /** Remove all listeners for all events and clear the pending queue. */
+    destroy(): void;
+}
+//# sourceMappingURL=EventBus.d.ts.map

package/dist/events/EventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.d.ts","sourceRoot":"","sources":["../../src/events/EventBus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAShD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ,CACnB,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEnC,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,WAAW,CAAkD;IACrE,OAAO,CAAC,UAAU,CAAkD;IACpE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAE9C;;;OAGG;gBACS,MAAM,CAAC,EAAE,OAAO;IAI5B,qEAAqE;IACrE,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACrC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,GACrB,IAAI;IAIP;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAkCb,6CAA6C;IAC7C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,8DAA8D;IAC9D,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACnC,KAAK,EAAE,CAAC,EACR,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,EACnC,OAAO,CAAC,EAAE,OAAO,GAChB,MAAM,IAAI;IAeb,sFAAsF;IACtF,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACrC,KAAK,EAAE,CAAC,EACR,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAClC,MAAM,IAAI;IAeb,kGAAkG;IAClG,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACpC,KAAK,EAAE,CAAC,EACR,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,EACnC,OAAO,CAAC,EAAE,OAAO,GAChB,IAAI;IAYP,uEAAuE;IACvE,OAAO,IAAI,IAAI;CAKhB"}

package/dist/events/EventBus.js

@@ -0,0 +1,129 @@
+/**
+ * Type-safe event emitter parameterised by a payload map.
+ *
+ * `TPayloads` maps event name strings to their payload types, giving full
+ * IntelliSense for both emitting and subscribing — wrong event names or
+ * payload shapes are caught at compile time.
+ *
+ * @typeParam TPayloads - Record mapping event name → payload type.
+ *
+ * @example
+ * ```ts
+ * interface MyEvents {
+ *   'player:hit': { damage: number };
+ *   'player:died': undefined;
+ * }
+ * const bus = new EventBus<MyEvents>();
+ * bus.on('player:hit', (p) => console.log(p.damage)); // p is typed
+ * bus.emit('player:hit', { damage: 10 });
+ * ```
+ */
+export class EventBus {
+    /**
+     * @param logger - Optional logger for reporting listener errors. Defaults to
+     *   `console` when not provided, preserving backward-compatibility.
+     */
+    constructor(logger) {
+        this.listeners = new Map();
+        this._frontQueue = [];
+        this._backQueue = [];
+        this._onceEntries = [];
+        this._logger = logger;
+    }
+    /** Queue an event for deferred dispatch. Call flush() to deliver. */
+    emit(event, payload) {
+        this._frontQueue.push({ event: event, payload });
+    }
+    /**
+     * Process all queued events, dispatching to registered listeners.
+     * Handles re-entrant emit safely: events emitted during flush are
+     * appended to the queue and processed within the same flush cycle.
+     */
+    flush() {
+        try {
+            while (this._frontQueue.length > 0) {
+                // Swap: new emits during dispatch go to the fresh front buffer
+                const batch = this._frontQueue;
+                this._frontQueue = this._backQueue;
+                this._backQueue = batch;
+                this._frontQueue.length = 0;
+                for (const { event, payload } of this._backQueue) {
+                    const set = this.listeners.get(event);
+                    if (!set)
+                        continue;
+                    this._onceEntries.length = 0;
+                    for (const entry of set) {
+                        try {
+                            entry.fn.call(entry.context, payload);
+                        }
+                        catch (err) {
+                            if (this._logger) {
+                                this._logger.error('EventBus', `listener for "${event}" threw`, err);
+                            }
+                            else {
+                                console.error(`[EventBus] listener for "${event}" threw:`, err);
+                            }
+                        }
+                        if (entry.once)
+                            this._onceEntries.push(entry);
+                    }
+                    for (const entry of this._onceEntries)
+                        set.delete(entry);
+                }
+                this._backQueue.length = 0;
+            }
+        }
+        finally {
+            // flush complete
+        }
+    }
+    /** Number of events waiting in the queue. */
+    get pendingCount() {
+        return this._frontQueue.length;
+    }
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on(event, fn, context) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        const entry = { fn, context, once: false };
+        set.add(entry);
+        return () => {
+            set.delete(entry);
+        };
+    }
+    /** Subscribe to an event for a single invocation. Returns an unsubscribe function. */
+    once(event, fn) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        const entry = { fn, context: undefined, once: true };
+        set.add(entry);
+        return () => {
+            set.delete(entry);
+        };
+    }
+    /** Unsubscribe a specific listener. Both `fn` and `context` must match the original on() call. */
+    off(event, fn, context) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const entry of set) {
+            if (entry.fn === fn && entry.context === context) {
+                set.delete(entry);
+                return;
+            }
+        }
+    }
+    /** Remove all listeners for all events and clear the pending queue. */
+    destroy() {
+        this.listeners.clear();
+        this._frontQueue.length = 0;
+        this._backQueue.length = 0;
+    }
+}
+//# sourceMappingURL=EventBus.js.map

package/dist/events/EventBus.js.map

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

package/dist/events/index.d.ts

@@ -0,0 +1,4 @@
+export { EventBus } from './EventBus';
+export { ALifeEvents } from './ALifeEvents';
+export type { ALifeEventPayloads } from './ALifeEvents';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/events/index.js

@@ -0,0 +1,4 @@
+// events sub-path barrel
+export { EventBus } from './EventBus';
+export { ALifeEvents } from './ALifeEvents';
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/faction/Faction.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Faction — two-layer relation model.
+ *
+ * Base relations come from the config (IFactionDefinition) and are immutable.
+ * Dynamic goodwill is mutable at runtime and decays toward 0 each tick.
+ * The effective relation is the sum of both layers, clamped to [-100, 100].
+ */
+import type { IFactionDefinition } from '../registry/FactionRegistry';
+/** Configurable thresholds for faction diplomacy classification. */
+export interface IFactionThresholds {
+    /** Relation below this value is considered hostile. Default: -50. */
+    readonly hostile: number;
+    /** Relation above this value is considered allied. Default: 50. */
+    readonly ally: number;
+}
+export declare class Faction {
+    readonly id: string;
+    readonly name: string;
+    readonly metadata: ReadonlyMap<string, unknown>;
+    private readonly baseRelations;
+    private readonly dynamicGoodwill;
+    private readonly thresholds;
+    private readonly _keysToRemove;
+    constructor(id: string, definition: IFactionDefinition, thresholds?: Partial<IFactionThresholds>);
+    /**
+     * Combined relation = base + dynamic, clamped to [-100, 100].
+     * Returns 0 when no relation data exists for the other faction.
+     */
+    getRelation(otherFactionId: string): number;
+    /**
+     * Modify dynamic goodwill (not base). The stored value is clamped to [-100, 100].
+     */
+    adjustGoodwill(otherFactionId: string, delta: number): void;
+    /** Relation is hostile when the combined score drops below the hostile threshold. */
+    isHostile(otherFactionId: string): boolean;
+    /** Relation is allied when the combined score exceeds the ally threshold. */
+    isAlly(otherFactionId: string): boolean;
+    /** Relation is neutral when it falls between hostile and ally thresholds inclusive. */
+    isNeutral(otherFactionId: string): boolean;
+    /**
+     * Decay every dynamic goodwill entry toward 0 by the given rate.
+     * Entries that reach 0 are removed to keep the map clean.
+     */
+    decayGoodwill(rate: number): void;
+    /** Reset all dynamic goodwill to zero. */
+    resetGoodwill(): void;
+    serialize(): IFactionState;
+    restore(state: IFactionState): void;
+}
+export interface IFactionState {
+    readonly dynamicGoodwill: Readonly<Record<string, number>>;
+}
+//# sourceMappingURL=Faction.d.ts.map

package/dist/faction/Faction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Faction.d.ts","sourceRoot":"","sources":["../../src/faction/Faction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAQtE,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,OAAO;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAC5D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAG5C,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,kBAAkB,EAC9B,UAAU,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAY1C;;;OAGG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAM3C;;OAEG;IACH,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAW3D,qFAAqF;IACrF,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI1C,6EAA6E;IAC7E,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAIvC,uFAAuF;IACvF,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAK1C;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAoBjC,0CAA0C;IAC1C,aAAa,IAAI,IAAI;IAQrB,SAAS,IAAI,aAAa;IAM1B,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;CAMpC;AAMD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D"}

package/dist/faction/Faction.js

@@ -0,0 +1,101 @@
+/**
+ * Faction — two-layer relation model.
+ *
+ * Base relations come from the config (IFactionDefinition) and are immutable.
+ * Dynamic goodwill is mutable at runtime and decays toward 0 each tick.
+ * The effective relation is the sum of both layers, clamped to [-100, 100].
+ */
+import { clamp, moveTowardZero } from '../core/math/utils';
+const RELATION_MIN = -100;
+const RELATION_MAX = 100;
+const DEFAULT_HOSTILE_THRESHOLD = -50;
+const DEFAULT_ALLY_THRESHOLD = 50;
+export class Faction {
+    constructor(id, definition, thresholds) {
+        this.dynamicGoodwill = new Map();
+        this._keysToRemove = [];
+        this.id = id;
+        this.name = definition.name;
+        this.baseRelations = new Map(Object.entries(definition.baseRelations));
+        this.metadata = new Map(Object.entries(definition.metadata ?? {}));
+        this.thresholds = {
+            hostile: thresholds?.hostile ?? DEFAULT_HOSTILE_THRESHOLD,
+            ally: thresholds?.ally ?? DEFAULT_ALLY_THRESHOLD,
+        };
+    }
+    /**
+     * Combined relation = base + dynamic, clamped to [-100, 100].
+     * Returns 0 when no relation data exists for the other faction.
+     */
+    getRelation(otherFactionId) {
+        const base = this.baseRelations.get(otherFactionId) ?? 0;
+        const dynamic = this.dynamicGoodwill.get(otherFactionId) ?? 0;
+        return clamp(base + dynamic, RELATION_MIN, RELATION_MAX);
+    }
+    /**
+     * Modify dynamic goodwill (not base). The stored value is clamped to [-100, 100].
+     */
+    adjustGoodwill(otherFactionId, delta) {
+        const current = this.dynamicGoodwill.get(otherFactionId) ?? 0;
+        const next = clamp(current + delta, RELATION_MIN, RELATION_MAX);
+        if (next === 0) {
+            this.dynamicGoodwill.delete(otherFactionId);
+        }
+        else {
+            this.dynamicGoodwill.set(otherFactionId, next);
+        }
+    }
+    /** Relation is hostile when the combined score drops below the hostile threshold. */
+    isHostile(otherFactionId) {
+        return this.getRelation(otherFactionId) < this.thresholds.hostile;
+    }
+    /** Relation is allied when the combined score exceeds the ally threshold. */
+    isAlly(otherFactionId) {
+        return this.getRelation(otherFactionId) > this.thresholds.ally;
+    }
+    /** Relation is neutral when it falls between hostile and ally thresholds inclusive. */
+    isNeutral(otherFactionId) {
+        const relation = this.getRelation(otherFactionId);
+        return relation >= this.thresholds.hostile && relation <= this.thresholds.ally;
+    }
+    /**
+     * Decay every dynamic goodwill entry toward 0 by the given rate.
+     * Entries that reach 0 are removed to keep the map clean.
+     */
+    decayGoodwill(rate) {
+        if (rate <= 0)
+            return;
+        this._keysToRemove.length = 0;
+        for (const [factionId, value] of this.dynamicGoodwill) {
+            const decayed = moveTowardZero(value, rate);
+            if (decayed === 0) {
+                this._keysToRemove.push(factionId);
+            }
+            else {
+                this.dynamicGoodwill.set(factionId, decayed);
+            }
+        }
+        for (let i = 0; i < this._keysToRemove.length; i++) {
+            this.dynamicGoodwill.delete(this._keysToRemove[i]);
+        }
+    }
+    /** Reset all dynamic goodwill to zero. */
+    resetGoodwill() {
+        this.dynamicGoodwill.clear();
+    }
+    // -----------------------------------------------------------------------
+    // Serialisation
+    // -----------------------------------------------------------------------
+    serialize() {
+        return {
+            dynamicGoodwill: Object.fromEntries(this.dynamicGoodwill),
+        };
+    }
+    restore(state) {
+        this.dynamicGoodwill.clear();
+        for (const [id, value] of Object.entries(state.dynamicGoodwill)) {
+            this.dynamicGoodwill.set(id, value);
+        }
+    }
+}
+//# sourceMappingURL=Faction.js.map

package/dist/faction/Faction.js.map

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

package/dist/faction/FactionBuilder.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Fluent builder for creating IFactionDefinition objects.
+ *
+ * Usage:
+ *   const def = new FactionBuilder('stalkers')
+ *     .displayName('Stalkers')
+ *     .relation('bandits', -60)
+ *     .immunity('radiation', 0.2)
+ *     .equipmentPreference({ aggressiveness: 0.5 })
+ *     .spawn({ targetRatio: 0.25, balanceTolerance: 0.1 })
+ *     .build();
+ */
+import type { IFactionDefinition, IEquipmentPreference, IFactionSpawnRules } from '../registry/FactionRegistry';
+export declare class FactionBuilder {
+    private readonly id;
+    private name;
+    private readonly relations;
+    private readonly immunities;
+    private equipment;
+    private spawnRules;
+    private metadataEntries;
+    constructor(id: string);
+    displayName(name: string): this;
+    relation(factionId: string, score: number): this;
+    immunity(damageTypeId: string, factor: number): this;
+    equipmentPreference(prefs: Partial<IEquipmentPreference>): this;
+    spawn(rules: Partial<IFactionSpawnRules>): this;
+    withMetadata(key: string, value: unknown): this;
+    /** Validate required fields and return a frozen IFactionDefinition. */
+    build(): IFactionDefinition;
+}
+//# sourceMappingURL=FactionBuilder.d.ts.map

package/dist/faction/FactionBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FactionBuilder.d.ts","sourceRoot":"","sources":["../../src/faction/FactionBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AAOrC,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,UAAU,CAA2C;IAC7D,OAAO,CAAC,eAAe,CAA+B;gBAE1C,EAAE,EAAE,MAAM;IAOtB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK/B,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAehD,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAUpD,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;IAK/D,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI;IAK/C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAK/C,uEAAuE;IACvE,KAAK,IAAI,kBAAkB;CAkB5B"}

package/dist/faction/FactionBuilder.js

@@ -0,0 +1,80 @@
+/**
+ * Fluent builder for creating IFactionDefinition objects.
+ *
+ * Usage:
+ *   const def = new FactionBuilder('stalkers')
+ *     .displayName('Stalkers')
+ *     .relation('bandits', -60)
+ *     .immunity('radiation', 0.2)
+ *     .equipmentPreference({ aggressiveness: 0.5 })
+ *     .spawn({ targetRatio: 0.25, balanceTolerance: 0.1 })
+ *     .build();
+ */
+const DEFAULT_SPAWN_RULES = {
+    targetRatio: 0,
+    balanceTolerance: 0,
+};
+export class FactionBuilder {
+    constructor(id) {
+        this.name = '';
+        this.relations = {};
+        this.immunities = {};
+        this.equipment = {};
+        this.spawnRules = DEFAULT_SPAWN_RULES;
+        this.metadataEntries = {};
+        if (!id) {
+            throw new Error('[FactionBuilder] id must not be empty');
+        }
+        this.id = id;
+    }
+    displayName(name) {
+        this.name = name;
+        return this;
+    }
+    relation(factionId, score) {
+        if (factionId === this.id) {
+            throw new Error(`[FactionBuilder] Faction "${this.id}" cannot define a relation to itself`);
+        }
+        if (score < -100 || score > 100) {
+            throw new Error(`[FactionBuilder] Relation score for "${factionId}" must be in [-100, 100], got ${score}`);
+        }
+        this.relations[factionId] = score;
+        return this;
+    }
+    immunity(damageTypeId, factor) {
+        if (factor < 0 || factor > 1) {
+            throw new Error(`[FactionBuilder] Immunity factor for "${damageTypeId}" must be in [0, 1], got ${factor}`);
+        }
+        this.immunities[damageTypeId] = factor;
+        return this;
+    }
+    equipmentPreference(prefs) {
+        this.equipment = { ...this.equipment, ...prefs };
+        return this;
+    }
+    spawn(rules) {
+        this.spawnRules = { ...this.spawnRules, ...rules };
+        return this;
+    }
+    withMetadata(key, value) {
+        this.metadataEntries[key] = value;
+        return this;
+    }
+    /** Validate required fields and return a frozen IFactionDefinition. */
+    build() {
+        if (!this.name) {
+            throw new Error(`[FactionBuilder] Faction "${this.id}" requires a display name`);
+        }
+        return {
+            name: this.name,
+            baseRelations: { ...this.relations },
+            immunities: { ...this.immunities },
+            defaultEquipment: { ...this.equipment },
+            spawnRules: { ...this.spawnRules },
+            metadata: Object.keys(this.metadataEntries).length > 0
+                ? { ...this.metadataEntries }
+                : undefined,
+        };
+    }
+}
+//# sourceMappingURL=FactionBuilder.js.map

package/dist/faction/FactionBuilder.js.map

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

package/dist/faction/ImmunityProfile.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Extensible immunity profile based on Map<string, number>.
+ *
+ * Each entry maps a damage type ID to a resistance factor in [0, 1],
+ * where 0 = no resistance and 1 = full immunity.
+ * Missing entries default to 0 (no resistance).
+ */
+export type ImmunityProfile = ReadonlyMap<string, number>;
+/**
+ * Create an ImmunityProfile from an optional record of damage-type-to-resistance pairs.
+ * Values are clamped to [0, 1].
+ */
+export declare function createImmunityProfile(entries?: Record<string, number>): ImmunityProfile;
+/**
+ * Return the resistance factor for a given damage type.
+ * Returns 0 when the profile has no entry for that type.
+ */
+export declare function getResistance(profile: ImmunityProfile, damageTypeId: string): number;
+/**
+ * Reduce base damage by the profile's resistance to the given type.
+ * Formula: baseDamage * (1 - resistance).
+ */
+export declare function applyDamageReduction(baseDamage: number, profile: ImmunityProfile, damageTypeId: string): number;
+//# sourceMappingURL=ImmunityProfile.d.ts.map

package/dist/faction/ImmunityProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImmunityProfile.d.ts","sourceRoot":"","sources":["../../src/faction/ImmunityProfile.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,eAAe,CAWjB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,GACnB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,GACnB,MAAM,CAGR"}

package/dist/faction/ImmunityProfile.js

@@ -0,0 +1,43 @@
+/**
+ * Extensible immunity profile based on Map<string, number>.
+ *
+ * Each entry maps a damage type ID to a resistance factor in [0, 1],
+ * where 0 = no resistance and 1 = full immunity.
+ * Missing entries default to 0 (no resistance).
+ */
+/**
+ * Create an ImmunityProfile from an optional record of damage-type-to-resistance pairs.
+ * Values are clamped to [0, 1].
+ */
+export function createImmunityProfile(entries) {
+    const map = new Map();
+    if (entries) {
+        for (const [damageTypeId, rawFactor] of Object.entries(entries)) {
+            const factor = clampResistance(rawFactor);
+            map.set(damageTypeId, factor);
+        }
+    }
+    return map;
+}
+/**
+ * Return the resistance factor for a given damage type.
+ * Returns 0 when the profile has no entry for that type.
+ */
+export function getResistance(profile, damageTypeId) {
+    return profile.get(damageTypeId) ?? 0;
+}
+/**
+ * Reduce base damage by the profile's resistance to the given type.
+ * Formula: baseDamage * (1 - resistance).
+ */
+export function applyDamageReduction(baseDamage, profile, damageTypeId) {
+    const resistance = getResistance(profile, damageTypeId);
+    return baseDamage * (1 - resistance);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function clampResistance(value) {
+    return Math.max(0, Math.min(1, value));
+}
+//# sourceMappingURL=ImmunityProfile.js.map