@alife-sdk/core 0.1.0

package/dist/navigation/NPCGraphMover.d.ts

@@ -0,0 +1,87 @@
+import { LevelGraph } from './LevelGraph';
+import type { TerrainFilter } from './LevelGraph';
+import type { ISerializable } from '../core/ISerializable';
+export type GraphMoverEvent = {
+    readonly type: 'arrived';
+    readonly vertexId: string;
+} | {
+    readonly type: 'completed';
+    readonly vertexId: string;
+} | {
+    readonly type: 'no_path';
+    readonly from: string;
+    readonly to: string;
+};
+export interface INPCGraphMoverState {
+    currentVertexId: string;
+    nextVertexId: string | null;
+    remainingPath: string[];
+    pathCursor: number;
+    walkedDistance: number;
+    speed: number;
+    timeFactor: number;
+}
+export declare class NPCGraphMover implements ISerializable<INPCGraphMoverState> {
+    private readonly _graph;
+    /** Current vertex the NPC is AT (or moving away from) */
+    private _currentVertexId;
+    /** Next vertex in current path segment (null = idle) */
+    private _nextVertexId;
+    /** Remaining path after _nextVertexId (from index 0 = next after next) */
+    private _remainingPath;
+    /** Cursor index into _remainingPath — avoids O(n) shift() */
+    private _pathCursor;
+    /** Distance walked along current edge [0, edgeWeight] */
+    private _walkedDistance;
+    /** Current edge total weight (cached) */
+    private _currentEdgeWeight;
+    /** Events emitted during last update() */
+    private _pendingEvents;
+    /** Movement speed in world units per second */
+    private _speed;
+    /** Time scale factor */
+    private _timeFactor;
+    /**
+     * @param graph         - The level graph used for pathfinding.
+     * @param startVertexId - Initial vertex ID for this NPC.
+     * @param speed         - Movement speed in world units per second.
+     * @param timeFactor    - Optional time scale factor (default 1.0).
+     */
+    constructor(graph: LevelGraph, startVertexId: string, speed: number, timeFactor?: number);
+    /** Change movement speed at runtime. */
+    setSpeed(speed: number): void;
+    /** Current movement speed in world units per second. */
+    get speed(): number;
+    /**
+     * Request movement to a destination vertex.
+     * Computes A* path immediately. Returns false if no path found.
+     *
+     * @param destinationId - Target vertex ID.
+     * @param filter        - Optional terrain filter for path finding.
+     */
+    moveTo(destinationId: string, filter?: TerrainFilter): boolean;
+    /**
+     * Advance movement by deltaMs milliseconds using stored speed and timeFactor.
+     *
+     * @param deltaMs - Time elapsed since last tick (milliseconds).
+     */
+    update(deltaMs: number): void;
+    /** Current world position (interpolated along current edge). */
+    get worldPosition(): {
+        x: number;
+        y: number;
+    };
+    get currentVertexId(): string;
+    get nextVertexId(): string | null;
+    get isMoving(): boolean;
+    get walkedDistance(): number;
+    /** Events from the last update() call. */
+    get events(): ReadonlyArray<GraphMoverEvent>;
+    /** Teleport NPC to a vertex (e.g. on spawn/load). Clears all movement state. */
+    teleport(vertexId: string): void;
+    /** Serialize for save/load. */
+    serialize(): INPCGraphMoverState;
+    /** Restore from serialized state. */
+    restore(state: INPCGraphMoverState): void;
+}
+//# sourceMappingURL=NPCGraphMover.d.ts.map

package/dist/navigation/NPCGraphMover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NPCGraphMover.d.ts","sourceRoot":"","sources":["../../src/navigation/NPCGraphMover.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAM/E,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,qBAAa,aAAc,YAAW,aAAa,CAAC,mBAAmB,CAAC;IACtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,yDAAyD;IACzD,OAAO,CAAC,gBAAgB,CAAS;IACjC,wDAAwD;IACxD,OAAO,CAAC,aAAa,CAAuB;IAC5C,0EAA0E;IAC1E,OAAO,CAAC,cAAc,CAAgB;IACtC,6DAA6D;IAC7D,OAAO,CAAC,WAAW,CAAK;IACxB,yDAAyD;IACzD,OAAO,CAAC,eAAe,CAAK;IAC5B,yCAAyC;IACzC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,0CAA0C;IAC1C,OAAO,CAAC,cAAc,CAAyB;IAC/C,+CAA+C;IAC/C,OAAO,CAAC,MAAM,CAAS;IACvB,wBAAwB;IACxB,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;;OAKG;gBACS,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,SAAI;IAWnF,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B,wDAAwD;IACxD,IAAI,KAAK,IAAI,MAAM,CAAwB;IAM3C;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO;IA6B9D;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IA+C7B,gEAAgE;IAChE,IAAI,aAAa,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAO5C;IAMD,IAAI,eAAe,IAAI,MAAM,CAAkC;IAC/D,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,CAA+B;IAChE,IAAI,QAAQ,IAAI,OAAO,CAAwC;IAC/D,IAAI,cAAc,IAAI,MAAM,CAAiC;IAE7D,0CAA0C;IAC1C,IAAI,MAAM,IAAI,aAAa,CAAC,eAAe,CAAC,CAAgC;IAM5E,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAchC,+BAA+B;IAC/B,SAAS,IAAI,mBAAmB;IAYhC,qCAAqC;IACrC,OAAO,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;CAgB1C"}

package/dist/navigation/NPCGraphMover.js

@@ -0,0 +1,193 @@
+// navigation/NPCGraphMover.ts
+// Per-NPC cursor for offline graph-based movement.
+//
+// Stores (currentVertexId, walkedDistance) and advances along edges each tick.
+// worldPosition is linearly interpolated along the current edge.
+//
+// Usage:
+//   const mover = new NPCGraphMover(graph, 'spawn_point', 80);
+//   mover.moveTo('base_camp');
+//   mover.update(deltaMs);
+//   const { x, y } = mover.worldPosition;
+// ---------------------------------------------------------------------------
+// NPCGraphMover
+// ---------------------------------------------------------------------------
+export class NPCGraphMover {
+    /**
+     * @param graph         - The level graph used for pathfinding.
+     * @param startVertexId - Initial vertex ID for this NPC.
+     * @param speed         - Movement speed in world units per second.
+     * @param timeFactor    - Optional time scale factor (default 1.0).
+     */
+    constructor(graph, startVertexId, speed, timeFactor = 1) {
+        /** Next vertex in current path segment (null = idle) */
+        this._nextVertexId = null;
+        /** Remaining path after _nextVertexId (from index 0 = next after next) */
+        this._remainingPath = [];
+        /** Cursor index into _remainingPath — avoids O(n) shift() */
+        this._pathCursor = 0;
+        /** Distance walked along current edge [0, edgeWeight] */
+        this._walkedDistance = 0;
+        /** Current edge total weight (cached) */
+        this._currentEdgeWeight = 0;
+        /** Events emitted during last update() */
+        this._pendingEvents = [];
+        this._graph = graph;
+        this._currentVertexId = startVertexId;
+        this._speed = speed;
+        this._timeFactor = timeFactor;
+    }
+    // -------------------------------------------------------------------------
+    // Speed control
+    // -------------------------------------------------------------------------
+    /** Change movement speed at runtime. */
+    setSpeed(speed) {
+        this._speed = speed;
+    }
+    /** Current movement speed in world units per second. */
+    get speed() { return this._speed; }
+    // -------------------------------------------------------------------------
+    // Path control
+    // -------------------------------------------------------------------------
+    /**
+     * Request movement to a destination vertex.
+     * Computes A* path immediately. Returns false if no path found.
+     *
+     * @param destinationId - Target vertex ID.
+     * @param filter        - Optional terrain filter for path finding.
+     */
+    moveTo(destinationId, filter) {
+        if (destinationId === this._currentVertexId) {
+            this._nextVertexId = null;
+            this._remainingPath = [];
+            this._pathCursor = 0;
+            this._walkedDistance = 0;
+            this._currentEdgeWeight = 0;
+            return true;
+        }
+        const path = this._graph.findPath(this._currentVertexId, destinationId, filter);
+        if (!path || path.length < 2) {
+            this._pendingEvents.push({ type: 'no_path', from: this._currentVertexId, to: destinationId });
+            return false;
+        }
+        // path[0] = current, path[1] = next, path[2..] = remaining
+        this._nextVertexId = path[1];
+        this._remainingPath = path.slice(2);
+        this._pathCursor = 0;
+        this._walkedDistance = 0;
+        this._currentEdgeWeight = this._graph.edgeWeight(this._currentVertexId, this._nextVertexId);
+        return true;
+    }
+    // -------------------------------------------------------------------------
+    // Simulation tick
+    // -------------------------------------------------------------------------
+    /**
+     * Advance movement by deltaMs milliseconds using stored speed and timeFactor.
+     *
+     * @param deltaMs - Time elapsed since last tick (milliseconds).
+     */
+    update(deltaMs) {
+        this._pendingEvents = [];
+        if (this._nextVertexId === null)
+            return;
+        if (this._speed <= 0 || this._timeFactor <= 0)
+            return;
+        // Fix C2: timeFactor multiplies (not divides) — larger factor = more movement per real ms
+        let remaining = (deltaMs / 1000) * this._timeFactor * this._speed;
+        // Fix C1: bound iterations by number of path vertices to prevent infinite loop
+        // on consecutive zero-weight edges (distToNext=0, remaining never decreases).
+        const maxSteps = this._remainingPath.length - this._pathCursor + 2;
+        let steps = 0;
+        while (remaining > 0 && this._nextVertexId !== null && steps++ < maxSteps) {
+            const distToNext = this._currentEdgeWeight - this._walkedDistance;
+            if (remaining < distToNext) {
+                this._walkedDistance += remaining;
+                break;
+            }
+            // Reached next vertex
+            remaining -= distToNext;
+            this._currentVertexId = this._nextVertexId;
+            this._walkedDistance = 0;
+            // Fix P4: use cursor index instead of shift() (O(1) vs O(n))
+            if (this._pathCursor >= this._remainingPath.length) {
+                // Arrived at final destination
+                this._nextVertexId = null;
+                this._currentEdgeWeight = 0;
+                this._pendingEvents.push({ type: 'completed', vertexId: this._currentVertexId });
+                break;
+            }
+            // Advance to next segment
+            const nextInPath = this._remainingPath[this._pathCursor++];
+            this._pendingEvents.push({ type: 'arrived', vertexId: this._currentVertexId });
+            this._nextVertexId = nextInPath;
+            this._currentEdgeWeight = this._graph.edgeWeight(this._currentVertexId, this._nextVertexId);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // World position
+    // -------------------------------------------------------------------------
+    /** Current world position (interpolated along current edge). */
+    get worldPosition() {
+        if (this._nextVertexId === null || this._currentEdgeWeight === 0) {
+            const v = this._graph.getVertex(this._currentVertexId);
+            return v ? { x: v.x, y: v.y } : { x: 0, y: 0 };
+        }
+        const t = this._walkedDistance / this._currentEdgeWeight;
+        return this._graph.interpolatePosition(this._currentVertexId, this._nextVertexId, t);
+    }
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+    get currentVertexId() { return this._currentVertexId; }
+    get nextVertexId() { return this._nextVertexId; }
+    get isMoving() { return this._nextVertexId !== null; }
+    get walkedDistance() { return this._walkedDistance; }
+    /** Events from the last update() call. */
+    get events() { return this._pendingEvents; }
+    // -------------------------------------------------------------------------
+    // Teleport
+    // -------------------------------------------------------------------------
+    /** Teleport NPC to a vertex (e.g. on spawn/load). Clears all movement state. */
+    teleport(vertexId) {
+        this._currentVertexId = vertexId;
+        this._nextVertexId = null;
+        this._remainingPath = [];
+        this._pathCursor = 0;
+        this._walkedDistance = 0;
+        this._currentEdgeWeight = 0;
+        this._pendingEvents = [];
+    }
+    // -------------------------------------------------------------------------
+    // Serialization — implements ISerializable<INPCGraphMoverState>
+    // -------------------------------------------------------------------------
+    /** Serialize for save/load. */
+    serialize() {
+        return {
+            currentVertexId: this._currentVertexId,
+            nextVertexId: this._nextVertexId,
+            remainingPath: [...this._remainingPath],
+            pathCursor: this._pathCursor,
+            walkedDistance: this._walkedDistance,
+            speed: this._speed,
+            timeFactor: this._timeFactor,
+        };
+    }
+    /** Restore from serialized state. */
+    restore(state) {
+        this._currentVertexId = state.currentVertexId;
+        this._nextVertexId = state.nextVertexId;
+        this._remainingPath = [...state.remainingPath];
+        this._pathCursor = state.pathCursor;
+        this._walkedDistance = state.walkedDistance;
+        this._speed = state.speed;
+        this._timeFactor = state.timeFactor;
+        this._pendingEvents = [];
+        if (this._nextVertexId !== null) {
+            this._currentEdgeWeight = this._graph.edgeWeight(this._currentVertexId, this._nextVertexId);
+        }
+        else {
+            this._currentEdgeWeight = 0;
+        }
+    }
+}
+//# sourceMappingURL=NPCGraphMover.js.map

package/dist/navigation/NPCGraphMover.js.map

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

package/dist/navigation/index.d.ts

@@ -0,0 +1,5 @@
+export { LevelGraph } from './LevelGraph';
+export type { IGraphVertex, IGraphEdge, TerrainFilter, ILevelGraphState } from './LevelGraph';
+export { NPCGraphMover } from './NPCGraphMover';
+export type { GraphMoverEvent, INPCGraphMoverState } from './NPCGraphMover';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/navigation/index.js

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

package/dist/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/plugins/AnomaliesPlugin.d.ts

@@ -0,0 +1,26 @@
+import type { IALifePlugin } from './IALifePlugin';
+import type { ALifeKernel } from '../core/ALifeKernel';
+import { AnomalyTypeRegistry } from '../registry/AnomalyTypeRegistry';
+/**
+ * Adds anomaly type registration to the A-Life kernel.
+ *
+ * Install this plugin when your game has environmental hazard zones
+ * (anomalies) that deal damage and spawn artefacts.
+ *
+ * @example
+ * ```ts
+ * const alife = new ALifeKernel(ports);
+ * alife.use(new AnomaliesPlugin());
+ *
+ * const ap = alife.getPlugin<AnomaliesPlugin>('anomalies');
+ * ap.anomalyTypes.register('fire_vortex', { name: 'Fire Vortex', ... });
+ * ```
+ */
+export declare class AnomaliesPlugin implements IALifePlugin {
+    readonly name = "anomalies";
+    readonly anomalyTypes: AnomalyTypeRegistry;
+    private kernel;
+    install(kernel: ALifeKernel): void;
+    init(): void;
+}
+//# sourceMappingURL=AnomaliesPlugin.d.ts.map

package/dist/plugins/AnomaliesPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnomaliesPlugin.d.ts","sourceRoot":"","sources":["../../src/plugins/AnomaliesPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,YAAY,sBAA6B;IAElD,OAAO,CAAC,MAAM,CAAe;IAE7B,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,IAAI,IAAI;CAIb"}

package/dist/plugins/AnomaliesPlugin.js

@@ -0,0 +1,30 @@
+import { AnomalyTypeRegistry } from '../registry/AnomalyTypeRegistry';
+/**
+ * Adds anomaly type registration to the A-Life kernel.
+ *
+ * Install this plugin when your game has environmental hazard zones
+ * (anomalies) that deal damage and spawn artefacts.
+ *
+ * @example
+ * ```ts
+ * const alife = new ALifeKernel(ports);
+ * alife.use(new AnomaliesPlugin());
+ *
+ * const ap = alife.getPlugin<AnomaliesPlugin>('anomalies');
+ * ap.anomalyTypes.register('fire_vortex', { name: 'Fire Vortex', ... });
+ * ```
+ */
+export class AnomaliesPlugin {
+    constructor() {
+        this.name = 'anomalies';
+        this.anomalyTypes = new AnomalyTypeRegistry();
+    }
+    install(kernel) {
+        this.kernel = kernel;
+    }
+    init() {
+        this.anomalyTypes.freeze();
+        this.kernel.logger.info('plugin', `AnomaliesPlugin: ${this.anomalyTypes.size} types registered`);
+    }
+}
+//# sourceMappingURL=AnomaliesPlugin.js.map

package/dist/plugins/AnomaliesPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnomaliesPlugin.js","sourceRoot":"","sources":["../../src/plugins/AnomaliesPlugin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,eAAe;IAA5B;QACW,SAAI,GAAG,WAAW,CAAC;QACnB,iBAAY,GAAG,IAAI,mBAAmB,EAAE,CAAC;IAYpD,CAAC;IARC,OAAO,CAAC,MAAmB;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,oBAAoB,IAAI,CAAC,YAAY,CAAC,IAAI,mBAAmB,CAAC,CAAC;IACnG,CAAC;CACF"}

package/dist/plugins/CombatSchemaPlugin.d.ts

@@ -0,0 +1,35 @@
+import type { IALifePlugin } from './IALifePlugin';
+import type { ALifeKernel } from '../core/ALifeKernel';
+import { DamageTypeRegistry } from '../registry/DamageTypeRegistry';
+import { AIStateRegistry } from '../registry/AIStateRegistry';
+import { BehaviorSchemeRegistry } from '../registry/BehaviorSchemeRegistry';
+import { TaskTypeRegistry } from '../registry/TaskTypeRegistry';
+/**
+ * Groups the four combat-related registries that change together:
+ * damage types, AI states, behavior schemes, and task types.
+ *
+ * These registries share the Common Closure Principle — a change in
+ * combat design (e.g. adding a new damage type) typically touches
+ * AI states and behavior schemes in the same commit.
+ *
+ * @example
+ * ```ts
+ * const alife = new ALifeKernel(ports);
+ * alife.use(new CombatSchemaPlugin());
+ *
+ * const cs = alife.getPlugin<CombatSchemaPlugin>('combatSchema');
+ * cs.damageTypes.register('fire', { name: 'Вогонь', ... });
+ * cs.aiStates.register('combat', { name: 'Бій', ... });
+ * ```
+ */
+export declare class CombatSchemaPlugin implements IALifePlugin {
+    readonly name = "combatSchema";
+    readonly damageTypes: DamageTypeRegistry;
+    readonly aiStates: AIStateRegistry;
+    readonly behaviorSchemes: BehaviorSchemeRegistry;
+    readonly taskTypes: TaskTypeRegistry;
+    private kernel;
+    install(kernel: ALifeKernel): void;
+    init(): void;
+}
+//# sourceMappingURL=CombatSchemaPlugin.d.ts.map

package/dist/plugins/CombatSchemaPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatSchemaPlugin.d.ts","sourceRoot":"","sources":["../../src/plugins/CombatSchemaPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,WAAW,qBAA4B;IAChD,QAAQ,CAAC,QAAQ,kBAAyB;IAC1C,QAAQ,CAAC,eAAe,yBAAgC;IACxD,QAAQ,CAAC,SAAS,mBAA0B;IAE5C,OAAO,CAAC,MAAM,CAAe;IAE7B,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,IAAI,IAAI;CAUb"}

package/dist/plugins/CombatSchemaPlugin.js

@@ -0,0 +1,44 @@
+import { DamageTypeRegistry } from '../registry/DamageTypeRegistry';
+import { AIStateRegistry } from '../registry/AIStateRegistry';
+import { BehaviorSchemeRegistry } from '../registry/BehaviorSchemeRegistry';
+import { TaskTypeRegistry } from '../registry/TaskTypeRegistry';
+/**
+ * Groups the four combat-related registries that change together:
+ * damage types, AI states, behavior schemes, and task types.
+ *
+ * These registries share the Common Closure Principle — a change in
+ * combat design (e.g. adding a new damage type) typically touches
+ * AI states and behavior schemes in the same commit.
+ *
+ * @example
+ * ```ts
+ * const alife = new ALifeKernel(ports);
+ * alife.use(new CombatSchemaPlugin());
+ *
+ * const cs = alife.getPlugin<CombatSchemaPlugin>('combatSchema');
+ * cs.damageTypes.register('fire', { name: 'Вогонь', ... });
+ * cs.aiStates.register('combat', { name: 'Бій', ... });
+ * ```
+ */
+export class CombatSchemaPlugin {
+    constructor() {
+        this.name = 'combatSchema';
+        this.damageTypes = new DamageTypeRegistry();
+        this.aiStates = new AIStateRegistry();
+        this.behaviorSchemes = new BehaviorSchemeRegistry();
+        this.taskTypes = new TaskTypeRegistry();
+    }
+    install(kernel) {
+        this.kernel = kernel;
+    }
+    init() {
+        this.damageTypes.freeze();
+        this.aiStates.freeze();
+        this.behaviorSchemes.freeze();
+        this.taskTypes.freeze();
+        const total = this.damageTypes.size + this.aiStates.size
+            + this.behaviorSchemes.size + this.taskTypes.size;
+        this.kernel.logger.info('plugin', `CombatSchemaPlugin: ${total} schema entries registered`);
+    }
+}
+//# sourceMappingURL=CombatSchemaPlugin.js.map

package/dist/plugins/CombatSchemaPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatSchemaPlugin.js","sourceRoot":"","sources":["../../src/plugins/CombatSchemaPlugin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,kBAAkB;IAA/B;QACW,SAAI,GAAG,cAAc,CAAC;QACtB,gBAAW,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACvC,aAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;QACjC,oBAAe,GAAG,IAAI,sBAAsB,EAAE,CAAC;QAC/C,cAAS,GAAG,IAAI,gBAAgB,EAAE,CAAC;IAkB9C,CAAC;IAdC,OAAO,CAAC,MAAmB;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC;QAC9B,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;QAExB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI;cACpD,IAAI,CAAC,eAAe,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,uBAAuB,KAAK,4BAA4B,CAAC,CAAC;IAC9F,CAAC;CACF"}

package/dist/plugins/FactionsPlugin.d.ts

@@ -0,0 +1,26 @@
+import type { IALifePlugin } from './IALifePlugin';
+import type { ALifeKernel } from '../core/ALifeKernel';
+import { FactionRegistry } from '../registry/FactionRegistry';
+/**
+ * Owns faction definitions and inter-faction relations.
+ *
+ * Install this plugin when your game has multiple factions with
+ * configurable hostility / alliance relationships.
+ *
+ * @example
+ * ```ts
+ * const alife = new ALifeKernel(ports);
+ * alife.use(new FactionsPlugin());
+ *
+ * const fp = alife.getPlugin<FactionsPlugin>('factions');
+ * fp.factions.register('loners', { name: 'Одинаки', ... });
+ * ```
+ */
+export declare class FactionsPlugin implements IALifePlugin {
+    readonly name = "factions";
+    readonly factions: FactionRegistry;
+    private kernel;
+    install(kernel: ALifeKernel): void;
+    init(): void;
+}
+//# sourceMappingURL=FactionsPlugin.d.ts.map

package/dist/plugins/FactionsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FactionsPlugin.d.ts","sourceRoot":"","sources":["../../src/plugins/FactionsPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,QAAQ,kBAAyB;IAE1C,OAAO,CAAC,MAAM,CAAe;IAE7B,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIlC,IAAI,IAAI,IAAI;CAIb"}

package/dist/plugins/FactionsPlugin.js

@@ -0,0 +1,30 @@
+import { FactionRegistry } from '../registry/FactionRegistry';
+/**
+ * Owns faction definitions and inter-faction relations.
+ *
+ * Install this plugin when your game has multiple factions with
+ * configurable hostility / alliance relationships.
+ *
+ * @example
+ * ```ts
+ * const alife = new ALifeKernel(ports);
+ * alife.use(new FactionsPlugin());
+ *
+ * const fp = alife.getPlugin<FactionsPlugin>('factions');
+ * fp.factions.register('loners', { name: 'Одинаки', ... });
+ * ```
+ */
+export class FactionsPlugin {
+    constructor() {
+        this.name = 'factions';
+        this.factions = new FactionRegistry();
+    }
+    install(kernel) {
+        this.kernel = kernel;
+    }
+    init() {
+        this.factions.freeze();
+        this.kernel.logger.info('plugin', `FactionsPlugin: ${this.factions.size} factions registered`);
+    }
+}
+//# sourceMappingURL=FactionsPlugin.js.map

package/dist/plugins/FactionsPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FactionsPlugin.js","sourceRoot":"","sources":["../../src/plugins/FactionsPlugin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,cAAc;IAA3B;QACW,SAAI,GAAG,UAAU,CAAC;QAClB,aAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IAY5C,CAAC;IARC,OAAO,CAAC,MAAmB;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,mBAAmB,IAAI,CAAC,QAAQ,CAAC,IAAI,sBAAsB,CAAC,CAAC;IACjG,CAAC;CACF"}

package/dist/plugins/IALifePlugin.d.ts

@@ -0,0 +1,91 @@
+import type { ALifeKernel } from '../core/ALifeKernel';
+import type { PortToken } from '../core/PortRegistry';
+/**
+ * Lifecycle contract for A-Life kernel plugins.
+ *
+ * Plugins extend the kernel with domain-specific registries, event handlers,
+ * and per-frame logic. Each plugin has a unique string name used for typed
+ * retrieval via `kernel.getPlugin<T>(name)`.
+ *
+ * Lifecycle order:
+ *   install() → init() → update() per frame → destroy()
+ *
+ * Only `name` and `install` are required. The remaining hooks are optional.
+ */
+export interface IALifePlugin {
+    /** Unique identifier. Convention: lowercase noun ('monsters', 'surge'). */
+    readonly name: string;
+    /**
+     * Hard dependencies — plugin names that must be installed before this one.
+     * Init fails with a diagnostic error if any hard dependency is missing.
+     */
+    readonly dependencies?: readonly string[];
+    /**
+     * Soft dependencies — plugin names that this plugin can use but doesn't require.
+     * A warning is emitted if a soft dependency is missing, but init continues.
+     */
+    readonly optionalDependencies?: readonly string[];
+    /**
+     * Port tokens that this plugin requires to function.
+     * Init fails with a diagnostic error if any required port is not provided.
+     */
+    readonly requiredPorts?: readonly PortToken<unknown>[];
+    /**
+     * Called when `kernel.use(plugin)` is invoked.
+     *
+     * Registries are still mutable at this point — use this hook to store the
+     * kernel reference and perform any pre-init setup.
+     */
+    install(kernel: ALifeKernel): void;
+    /**
+     * Called during `kernel.init()`, after all core registries are frozen.
+     *
+     * Use this to freeze plugin-owned registries and create internal
+     * subsystems that depend on frozen registry data.
+     */
+    init?(): void;
+    /**
+     * Called every frame from `kernel.update(deltaMs)`, after core systems.
+     *
+     * Only implement when the plugin has per-frame simulation logic.
+     */
+    update?(deltaMs: number): void;
+    /**
+     * Called during `kernel.destroy()`, in reverse installation order.
+     *
+     * Use this to release subscriptions, timers, and internal state.
+     */
+    destroy?(): void;
+    /**
+     * Capture plugin-specific state for save/load.
+     *
+     * Return a plain JSON-serialisable object. Called by `kernel.serialize()`.
+     */
+    serialize?(): Record<string, unknown>;
+    /**
+     * Restore plugin state from a previously serialised snapshot.
+     *
+     * Called by `kernel.restoreState()` with the object returned by `serialize()`.
+     */
+    restore?(state: Record<string, unknown>): void;
+    /**
+     * Migrate plugin state from an older version.
+     *
+     * Called by `kernel.restoreState()` when the saved plugin state version
+     * is older than the current version. Implementations should return the
+     * migrated state object.
+     *
+     * @param state - The serialised plugin state from the save.
+     * @param fromVersion - The version the state was saved with.
+     * @returns The migrated state, compatible with the current version.
+     */
+    migrateState?(state: Record<string, unknown>, fromVersion: number): Record<string, unknown>;
+    /**
+     * Return a snapshot of the plugin's internal state for developer tooling.
+     *
+     * Called by `kernel.inspect()`. Return a plain object with whatever
+     * diagnostic data is useful (entity counts, queue lengths, etc.).
+     */
+    inspect?(): Record<string, unknown>;
+}
+//# sourceMappingURL=IALifePlugin.d.ts.map

package/dist/plugins/IALifePlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IALifePlugin.d.ts","sourceRoot":"","sources":["../../src/plugins/IALifePlugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAElD;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;IAEvD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAEnC;;;;;OAKG;IACH,IAAI,CAAC,IAAI,IAAI,CAAC;IAEd;;;;OAIG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;OAIG;IACH,OAAO,CAAC,IAAI,IAAI,CAAC;IAEjB;;;;OAIG;IACH,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtC;;;;OAIG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;OAUG;IACH,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5F;;;;;OAKG;IACH,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC"}

package/dist/plugins/IALifePlugin.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IALifePlugin.js.map

package/dist/plugins/IALifePlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IALifePlugin.js","sourceRoot":"","sources":["../../src/plugins/IALifePlugin.ts"],"names":[],"mappings":""}