@alife-sdk/core 0.1.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Framework-agnostic A-Life simulation and AI decision-making system.
 
-Zero external dependencies. Works with Phaser, Unity, Node.js, or any other runtime.
+Zero external dependencies. Works with Phaser, PixiJS, Node.js, or any JavaScript runtime.
 
 ```
 npm install @alife-sdk/core
@@ -16,7 +16,7 @@ npm install @alife-sdk/core
 
 - **NPC AI** — finite state machines, GOAP planners, memory and perception systems
 - **A-Life simulation** — offline NPC brains, terrain selection, spawn cooldowns, faction diplomacy
-- **Game clock** — accelerated in-game time, day/night cycle, hour events
+- **Game clock** — accelerated in-game time with configurable day/night cycle and time-change callbacks (HOUR_CHANGED, DAY_NIGHT_CHANGED events)
 - **World graph** — waypoint graph with A* pathfinding for offline NPC movement
 - **Plugin system** — extend the kernel with your own domain features
 
@@ -52,6 +52,8 @@ kernel.provide(Ports.PlayerPosition, { getPlayerPosition: () => ({ x: player.x,
 fullPreset(kernel);
 
 // 4. Register game data (before init)
+// Plugins is a set of typed plugin tokens — alternative to string IDs
+// e.g. kernel.getPlugin(Plugins.FACTIONS) is equivalent to kernel.getPlugin('factions')
 const factions = kernel.getPlugin(Plugins.FACTIONS).factions;
 factions.register('stalker', { name: 'Stalker', baseRelations: { bandit: -80 } });
 factions.register('bandit',  { name: 'Bandit',  baseRelations: { stalker: -80 } });
@@ -83,7 +85,7 @@ Each module has its own import path for optimal tree-shaking:
 
 | Import path | What's inside | Module docs |
 |-------------|--------------|-------------|
-| `@alife-sdk/core` | `ALifeKernel`, `Clock`, `SpatialGrid`, `Ports` | [core/](src/core/) |
+| `@alife-sdk/core` | `ALifeKernel`, `Clock`, `SpatialGrid`, `Ports`, `PortRegistry`, `Vec2`, `createPortToken` | [core/](src/core/) |
 | `@alife-sdk/core/ai` | `StateMachine`, `MemoryBank`, `DangerManager`, `GOAPPlanner` | [ai/](src/ai/README.md) |
 | `@alife-sdk/core/combat` | `DamageInstance`, `MoraleTracker`, `ImmunityProfile` | [combat/](src/combat/README.md) |
 | `@alife-sdk/core/config` | `createDefaultConfig`, `IALifeConfig` | [config/](src/config/README.md) |
@@ -187,7 +189,7 @@ kernel.events.on(ALifeEvents.NPC_DIED, ({ npcId, killedBy }) => {
 });
 ```
 
-38 typed events across 9 categories: A-Life, AI, Surge, Anomaly, Squad,
+41 typed events across 9 categories: A-Life, AI, Surge, Anomaly, Squad,
 Faction, Time, Social, Monster. See [`events/README.md`](src/events/README.md).
 
 ### AI — StateMachine + GOAP
@@ -231,6 +233,23 @@ kernel.restoreState()  ← restore from save
 kernel.destroy()       ← cleanup, call plugin.destroy() in reverse order
 ```
 
+### Save versioning and migrations
+
+The kernel supports versioned saves. When a save file was created by an older
+version of your game, you can register migration functions to transform the
+state forward. Migrations are applied automatically during `restoreState()`.
+
+```ts
+// Register a migration that upgrades state from version 0 → 1
+kernel.registerMigration(0, (state) => {
+  // transform state as needed
+  return { ...state, version: 1, newField: 'default' };
+});
+
+// Later, restoreState() applies all needed migrations automatically
+kernel.restoreState(oldSave);
+```
+
 ---
 
 ## Testing

package/dist/ai/BehaviorTree.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Behavior Tree — hierarchical AI task composition.
+ *
+ * Pairs well with GOAP: GOAP decides *what* goal to pursue, the BT decides
+ * *how* to execute it step by step. The BT is driven externally by calling
+ * `tree.tick(blackboard)` each frame or simulation step.
+ *
+ * Node types:
+ *   Composites  — Sequence, Selector, Parallel
+ *   Decorators  — Inverter, Repeater, AlwaysSucceed, AlwaysFail, Cooldown
+ *   Leaves      — Task (action), Condition
+ *
+ * Blackboard:
+ *   Typed key-value store shared across all nodes in one tick. Nodes read
+ *   perception data from it and write intermediate results to it.
+ *
+ * @example
+ * ```ts
+ * const bb = new Blackboard({ canSeeTarget: false, ammoCount: 10 });
+ *
+ * const tree = new Selector([
+ *   new Sequence([
+ *     new Condition((bb) => bb.get('canSeeTarget')),
+ *     new Condition((bb) => bb.get('ammoCount') > 0),
+ *     new Task((bb) => { shoot(); return 'success'; }),
+ *   ]),
+ *   new Task(() => { patrol(); return 'running'; }),
+ * ]);
+ *
+ * // Each frame:
+ * tree.tick(bb);
+ * ```
+ */
+/** Result returned by every node's `tick()`. */
+export type TaskStatus = 'success' | 'failure' | 'running';
+/**
+ * Typed key-value store shared across all nodes during a single tick.
+ *
+ * Initialize it with a plain object; the keys become the allowed set of keys
+ * via the generic type parameter.
+ */
+export declare class Blackboard<T extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly data;
+    constructor(initial?: Partial<T>);
+    get<K extends keyof T>(key: K): T[K] | undefined;
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    has(key: keyof T): boolean;
+    delete(key: keyof T): void;
+}
+/** Every node in the tree implements this single interface. */
+export interface ITreeNode<TBB extends Blackboard = Blackboard> {
+    tick(blackboard: TBB): TaskStatus;
+}
+/**
+ * Task (action leaf).
+ * Runs an arbitrary callback; the callback returns the status directly.
+ */
+export declare class Task<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly action;
+    constructor(action: (bb: TBB) => TaskStatus);
+    tick(bb: TBB): TaskStatus;
+}
+/**
+ * Condition (boolean leaf).
+ * Returns 'success' when the predicate is true, 'failure' otherwise.
+ */
+export declare class Condition<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly predicate;
+    constructor(predicate: (bb: TBB) => boolean);
+    tick(bb: TBB): TaskStatus;
+}
+/**
+ * Sequence — AND gate.
+ * Ticks children left-to-right. Returns 'failure' on the first failing child,
+ * 'running' on the first running child, 'success' when all succeed.
+ */
+export declare class Sequence<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly children;
+    constructor(children: ITreeNode<TBB>[]);
+    tick(bb: TBB): TaskStatus;
+}
+/**
+ * Selector — OR gate.
+ * Ticks children left-to-right. Returns 'success' on the first succeeding
+ * child, 'running' on the first running child, 'failure' when all fail.
+ */
+export declare class Selector<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly children;
+    constructor(children: ITreeNode<TBB>[]);
+    tick(bb: TBB): TaskStatus;
+}
+/** Policy for the Parallel node. */
+export type ParallelPolicy = 'require-all' | 'require-one';
+/**
+ * Parallel — ticks ALL children every tick simultaneously.
+ *
+ * `require-all` (default — AND semantics):
+ *   - Success: all children succeed.
+ *   - Failure: any child fails.
+ *   - Running: otherwise.
+ *
+ * `require-one` (OR semantics):
+ *   - Success: at least one child succeeds.
+ *   - Failure: all children fail.
+ *   - Running: otherwise (some running, none succeeded yet).
+ */
+export declare class Parallel<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly children;
+    private readonly successPolicy;
+    constructor(children: ITreeNode<TBB>[], successPolicy?: ParallelPolicy);
+    tick(bb: TBB): TaskStatus;
+}
+/**
+ * Inverter — flips 'success' ↔ 'failure'; passes 'running' unchanged.
+ */
+export declare class Inverter<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly child;
+    constructor(child: ITreeNode<TBB>);
+    tick(bb: TBB): TaskStatus;
+}
+/**
+ * AlwaysSucceed — maps any child result to 'success'.
+ */
+export declare class AlwaysSucceed<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly child;
+    constructor(child: ITreeNode<TBB>);
+    tick(bb: TBB): TaskStatus;
+}
+/**
+ * AlwaysFail — maps any child result to 'failure'.
+ */
+export declare class AlwaysFail<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly child;
+    constructor(child: ITreeNode<TBB>);
+    tick(bb: TBB): TaskStatus;
+}
+/**
+ * Repeater — ticks its child N times, returning 'success' after all iterations.
+ * If the child returns 'failure' the repeater short-circuits with 'failure'.
+ * Pass `Infinity` for an endless loop (returns 'running' every tick).
+ */
+export declare class Repeater<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly child;
+    private readonly times;
+    private remaining;
+    constructor(child: ITreeNode<TBB>, times: number);
+    tick(bb: TBB): TaskStatus;
+    /** Reset the repeat counter to allow reuse. */
+    reset(): void;
+}
+/**
+ * Cooldown — blocks its child while a cooldown timer is active.
+ *
+ * When the cooldown is inactive: ticks the child normally. If the child
+ * succeeds, starts the cooldown and returns 'success'. While the cooldown
+ * is active: immediately returns 'failure' (the action is on cooldown).
+ *
+ * `now` defaults to `Date.now` — inject a custom clock for deterministic tests.
+ */
+export declare class Cooldown<TBB extends Blackboard = Blackboard> implements ITreeNode<TBB> {
+    private readonly child;
+    private readonly durationMs;
+    private readonly clock;
+    private readyAt;
+    constructor(child: ITreeNode<TBB>, durationMs: number, clock?: () => number);
+    tick(bb: TBB): TaskStatus;
+    /** Force the cooldown to expire immediately. */
+    reset(): void;
+    /** `true` while the cooldown timer is active. */
+    get isOnCooldown(): boolean;
+}
+//# sourceMappingURL=BehaviorTree.d.ts.map

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

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

package/dist/ai/BehaviorTree.js

@@ -0,0 +1,275 @@
+/**
+ * Behavior Tree — hierarchical AI task composition.
+ *
+ * Pairs well with GOAP: GOAP decides *what* goal to pursue, the BT decides
+ * *how* to execute it step by step. The BT is driven externally by calling
+ * `tree.tick(blackboard)` each frame or simulation step.
+ *
+ * Node types:
+ *   Composites  — Sequence, Selector, Parallel
+ *   Decorators  — Inverter, Repeater, AlwaysSucceed, AlwaysFail, Cooldown
+ *   Leaves      — Task (action), Condition
+ *
+ * Blackboard:
+ *   Typed key-value store shared across all nodes in one tick. Nodes read
+ *   perception data from it and write intermediate results to it.
+ *
+ * @example
+ * ```ts
+ * const bb = new Blackboard({ canSeeTarget: false, ammoCount: 10 });
+ *
+ * const tree = new Selector([
+ *   new Sequence([
+ *     new Condition((bb) => bb.get('canSeeTarget')),
+ *     new Condition((bb) => bb.get('ammoCount') > 0),
+ *     new Task((bb) => { shoot(); return 'success'; }),
+ *   ]),
+ *   new Task(() => { patrol(); return 'running'; }),
+ * ]);
+ *
+ * // Each frame:
+ * tree.tick(bb);
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Blackboard
+// ---------------------------------------------------------------------------
+/**
+ * Typed key-value store shared across all nodes during a single tick.
+ *
+ * Initialize it with a plain object; the keys become the allowed set of keys
+ * via the generic type parameter.
+ */
+export class Blackboard {
+    constructor(initial = {}) {
+        this.data = new Map(Object.entries(initial));
+    }
+    get(key) {
+        return this.data.get(key);
+    }
+    set(key, value) {
+        this.data.set(key, value);
+    }
+    has(key) {
+        return this.data.has(key);
+    }
+    delete(key) {
+        this.data.delete(key);
+    }
+}
+// ---------------------------------------------------------------------------
+// Leaf nodes
+// ---------------------------------------------------------------------------
+/**
+ * Task (action leaf).
+ * Runs an arbitrary callback; the callback returns the status directly.
+ */
+export class Task {
+    constructor(action) {
+        this.action = action;
+    }
+    tick(bb) {
+        return this.action(bb);
+    }
+}
+/**
+ * Condition (boolean leaf).
+ * Returns 'success' when the predicate is true, 'failure' otherwise.
+ */
+export class Condition {
+    constructor(predicate) {
+        this.predicate = predicate;
+    }
+    tick(bb) {
+        return this.predicate(bb) ? 'success' : 'failure';
+    }
+}
+// ---------------------------------------------------------------------------
+// Composite nodes
+// ---------------------------------------------------------------------------
+/**
+ * Sequence — AND gate.
+ * Ticks children left-to-right. Returns 'failure' on the first failing child,
+ * 'running' on the first running child, 'success' when all succeed.
+ */
+export class Sequence {
+    constructor(children) {
+        this.children = children;
+    }
+    tick(bb) {
+        for (const child of this.children) {
+            const status = child.tick(bb);
+            if (status !== 'success')
+                return status;
+        }
+        return 'success';
+    }
+}
+/**
+ * Selector — OR gate.
+ * Ticks children left-to-right. Returns 'success' on the first succeeding
+ * child, 'running' on the first running child, 'failure' when all fail.
+ */
+export class Selector {
+    constructor(children) {
+        this.children = children;
+    }
+    tick(bb) {
+        for (const child of this.children) {
+            const status = child.tick(bb);
+            if (status !== 'failure')
+                return status;
+        }
+        return 'failure';
+    }
+}
+/**
+ * Parallel — ticks ALL children every tick simultaneously.
+ *
+ * `require-all` (default — AND semantics):
+ *   - Success: all children succeed.
+ *   - Failure: any child fails.
+ *   - Running: otherwise.
+ *
+ * `require-one` (OR semantics):
+ *   - Success: at least one child succeeds.
+ *   - Failure: all children fail.
+ *   - Running: otherwise (some running, none succeeded yet).
+ */
+export class Parallel {
+    constructor(children, successPolicy = 'require-all') {
+        this.children = children;
+        this.successPolicy = successPolicy;
+    }
+    tick(bb) {
+        let successCount = 0;
+        let failureCount = 0;
+        for (const child of this.children) {
+            const status = child.tick(bb);
+            if (status === 'success')
+                successCount++;
+            else if (status === 'failure')
+                failureCount++;
+        }
+        if (this.successPolicy === 'require-all') {
+            if (failureCount > 0)
+                return 'failure';
+            if (successCount === this.children.length)
+                return 'success';
+        }
+        else {
+            if (successCount > 0)
+                return 'success';
+            if (failureCount === this.children.length)
+                return 'failure';
+        }
+        return 'running';
+    }
+}
+// ---------------------------------------------------------------------------
+// Decorator nodes
+// ---------------------------------------------------------------------------
+/**
+ * Inverter — flips 'success' ↔ 'failure'; passes 'running' unchanged.
+ */
+export class Inverter {
+    constructor(child) {
+        this.child = child;
+    }
+    tick(bb) {
+        const status = this.child.tick(bb);
+        if (status === 'success')
+            return 'failure';
+        if (status === 'failure')
+            return 'success';
+        return 'running';
+    }
+}
+/**
+ * AlwaysSucceed — maps any child result to 'success'.
+ */
+export class AlwaysSucceed {
+    constructor(child) {
+        this.child = child;
+    }
+    tick(bb) {
+        this.child.tick(bb);
+        return 'success';
+    }
+}
+/**
+ * AlwaysFail — maps any child result to 'failure'.
+ */
+export class AlwaysFail {
+    constructor(child) {
+        this.child = child;
+    }
+    tick(bb) {
+        this.child.tick(bb);
+        return 'failure';
+    }
+}
+/**
+ * Repeater — ticks its child N times, returning 'success' after all iterations.
+ * If the child returns 'failure' the repeater short-circuits with 'failure'.
+ * Pass `Infinity` for an endless loop (returns 'running' every tick).
+ */
+export class Repeater {
+    constructor(child, times) {
+        this.child = child;
+        this.times = times;
+        this.remaining = times;
+    }
+    tick(bb) {
+        if (this.remaining <= 0)
+            return 'success';
+        const status = this.child.tick(bb);
+        if (status === 'failure')
+            return 'failure';
+        if (status === 'success') {
+            this.remaining--;
+            if (this.remaining <= 0)
+                return 'success';
+        }
+        return 'running';
+    }
+    /** Reset the repeat counter to allow reuse. */
+    reset() {
+        this.remaining = this.times;
+    }
+}
+/**
+ * Cooldown — blocks its child while a cooldown timer is active.
+ *
+ * When the cooldown is inactive: ticks the child normally. If the child
+ * succeeds, starts the cooldown and returns 'success'. While the cooldown
+ * is active: immediately returns 'failure' (the action is on cooldown).
+ *
+ * `now` defaults to `Date.now` — inject a custom clock for deterministic tests.
+ */
+export class Cooldown {
+    constructor(child, durationMs, clock = Date.now) {
+        this.child = child;
+        this.durationMs = durationMs;
+        this.clock = clock;
+        this.readyAt = 0;
+    }
+    tick(bb) {
+        if (this.clock() < this.readyAt)
+            return 'failure';
+        const status = this.child.tick(bb);
+        if (status === 'success') {
+            this.readyAt = this.clock() + this.durationMs;
+        }
+        return status;
+    }
+    /** Force the cooldown to expire immediately. */
+    reset() {
+        this.readyAt = 0;
+    }
+    /** `true` while the cooldown timer is active. */
+    get isOnCooldown() {
+        return this.clock() < this.readyAt;
+    }
+}
+//# sourceMappingURL=BehaviorTree.js.map

package/dist/ai/BehaviorTree.js.map

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

package/dist/ai/StateMachine.d.ts

@@ -18,13 +18,51 @@ export type TransitionResult = {
     readonly success: false;
     readonly reason: 'not_allowed' | 'exit_guard' | 'enter_guard';
 };
+export interface StateTransitionEvent {
+    readonly from: string;
+    readonly to: string;
+    readonly timestamp: number;
+}
 export declare class StateMachine {
     private currentStateId;
+    private previousStateId;
+    private stateEnterTime;
     private readonly registry;
     private readonly entity;
+    private readonly enterListeners;
+    private readonly exitListeners;
+    private readonly changeListeners;
+    private readonly historyLog;
     constructor(entity: IEntity, registry: AIStateRegistry, initialState: string);
     /** Current active state identifier. */
     get state(): string;
+    /** Previous state identifier, or `null` if no transition has occurred yet. */
+    get previous(): string | null;
+    /** Milliseconds elapsed since entering the current state. */
+    get currentStateDuration(): number;
+    /** Returns `true` if the current state has the given tag. */
+    hasTag(tag: string): boolean;
+    /** Returns the metadata object of the current state, or `undefined`. */
+    get metadata(): Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Subscribe to the moment the FSM enters `state`.
+     * @returns Unsubscribe function.
+     */
+    onEnter(state: string, callback: (from: string | null) => void): () => void;
+    /**
+     * Subscribe to the moment the FSM exits `state`.
+     * @returns Unsubscribe function.
+     */
+    onExit(state: string, callback: (to: string) => void): () => void;
+    /**
+     * Subscribe to any state change.
+     * @returns Unsubscribe function.
+     */
+    onChange(callback: (from: string, to: string) => void): () => void;
+    /** Returns a snapshot of the transition history (oldest first). */
+    getHistory(): readonly StateTransitionEvent[];
+    /** Clears the transition history. */
+    clearHistory(): void;
     /**
      * Force transition to a new state.
      *

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

@@ -1 +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"}
+{"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,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyD;IACxF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgD;IAC9E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiD;IACjF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;gBAE7C,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM;IAc5E,uCAAuC;IACvC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8EAA8E;IAC9E,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,6DAA6D;IAC7D,IAAI,oBAAoB,IAAI,MAAM,CAEjC;IAMD,6DAA6D;IAC7D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK5B,wEAAwE;IACxE,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAE5D;IAMD;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI;IAM3E;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAMjE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IASlE,mEAAmE;IACnE,UAAU,IAAI,SAAS,oBAAoB,EAAE;IAI7C,qCAAqC;IACrC,YAAY,IAAI,IAAI;IAQpB;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAwC9C;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAkB3B,iEAAiE;IACjE,OAAO,IAAI,IAAI;CAIhB"}