@alife-sdk/ai 0.1.0

package/dist/animation/AnimationSelector.js

@@ -0,0 +1,194 @@
+// animation/AnimationSelector.ts
+// Pure state → animation key resolver.
+// No framework dependencies — only string/number operations.
+/**
+ * 8-way directional system for animation facing.
+ * Indexed 0–7 clockwise from North.
+ */
+export const CompassIndex = {
+    N: 0,
+    NE: 1,
+    E: 2,
+    SE: 3,
+    S: 4,
+    SW: 5,
+    W: 6,
+    NW: 7,
+};
+const DIRECTION_SUFFIXES = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
+/**
+ * Animation layer for multi-layer sprite rigs.
+ */
+export const AnimLayer = {
+    LEGS: 0,
+    TORSO: 1,
+    HEAD: 2,
+};
+/**
+ * AI state → animation descriptor mapping.
+ * Exported as default; callers may supply a custom map to override.
+ */
+export const DEFAULT_STATE_ANIM_MAP = {
+    IDLE: { base: 'idle', loop: true, frameRate: 10, layer: AnimLayer.LEGS, omitDirection: false },
+    PATROL: { base: 'walk', loop: true, frameRate: 10, layer: AnimLayer.LEGS, omitDirection: false },
+    ALERT: { base: 'walk_alert', loop: true, frameRate: 10, layer: AnimLayer.LEGS, omitDirection: false },
+    COMBAT: { base: 'combat', loop: false, frameRate: 12, layer: AnimLayer.TORSO, omitDirection: false },
+    TAKE_COVER: { base: 'crouch', loop: true, frameRate: 10, layer: AnimLayer.LEGS, omitDirection: false },
+    SEARCH: { base: 'walk_search', loop: true, frameRate: 10, layer: AnimLayer.LEGS, omitDirection: false },
+    FLEE: { base: 'run', loop: true, frameRate: 14, layer: AnimLayer.LEGS, omitDirection: false },
+    DEAD: { base: 'death', loop: false, frameRate: 8, layer: AnimLayer.LEGS, omitDirection: true },
+    GRENADE: { base: 'throw', loop: false, frameRate: 10, layer: AnimLayer.TORSO, omitDirection: true },
+    EVADE_GRENADE: { base: 'sprint', loop: true, frameRate: 14, layer: AnimLayer.LEGS, omitDirection: false },
+    WOUNDED: { base: 'crawl', loop: true, frameRate: 6, layer: AnimLayer.LEGS, omitDirection: false },
+    RETREAT: { base: 'run_fire', loop: true, frameRate: 14, layer: AnimLayer.LEGS, omitDirection: false },
+    CAMP: { base: 'idle', loop: true, frameRate: 10, layer: AnimLayer.LEGS, omitDirection: false },
+    SLEEP: { base: 'sleep', loop: true, frameRate: 4, layer: AnimLayer.LEGS, omitDirection: true },
+    // Monster states
+    CHARGE: { base: 'charge', loop: false, frameRate: 14, layer: AnimLayer.LEGS, omitDirection: false },
+    STALK: { base: 'stalk', loop: true, frameRate: 8, layer: AnimLayer.LEGS, omitDirection: false },
+    LEAP: { base: 'leap', loop: false, frameRate: 14, layer: AnimLayer.LEGS, omitDirection: false },
+    PSI_ATTACK: { base: 'psi', loop: false, frameRate: 10, layer: AnimLayer.TORSO, omitDirection: true },
+};
+const DEFAULT_DESCRIPTOR = {
+    base: 'idle', loop: true, frameRate: 10, layer: AnimLayer.LEGS, omitDirection: false,
+};
+/**
+ * Weapon suffix lookup.
+ * GRENADE and MEDKIT use 'unarmed' (no held weapon visible).
+ * Keys are strings for extensibility; numeric categories are stringified at lookup time.
+ */
+export const DEFAULT_WEAPON_SUFFIXES = {
+    '0': 'pistol',
+    '1': 'shotgun',
+    '2': 'rifle',
+    '3': 'sniper',
+    '4': 'unarmed',
+    '5': 'unarmed',
+};
+// ---------------------------------------------------------------------------
+// Direction caching — avoids atan2 + quantize when velocity barely changes.
+// ---------------------------------------------------------------------------
+/** Squared magnitude threshold below which a velocity delta is "insignificant". */
+const DIRECTION_CACHE_EPSILON_SQ = 4.0; // ~2px/s change
+/**
+ * Per-entity direction cache.  Stores the last computed direction and the
+ * velocity that produced it.  `resolve()` only calls `getDirection()` when the
+ * velocity has changed more than a small epsilon (squared-magnitude test).
+ *
+ * Allocate one instance per NPC and pass it into `getAnimationRequest()`.
+ */
+export class DirectionCache {
+    constructor() {
+        this._lastVx = NaN;
+        this._lastVy = NaN;
+        this._dir = CompassIndex.S;
+    }
+    /**
+     * Return the cached direction or recompute if velocity changed significantly.
+     */
+    resolve(vx, vy) {
+        const dx = vx - this._lastVx;
+        const dy = vy - this._lastVy;
+        // NaN check on first call (NaN - anything = NaN, NaN > anything = false)
+        if (dx * dx + dy * dy > DIRECTION_CACHE_EPSILON_SQ || this._lastVx !== this._lastVx) {
+            this._lastVx = vx;
+            this._lastVy = vy;
+            this._dir = getDirection(vx, vy);
+        }
+        return this._dir;
+    }
+    /** Force-invalidate the cache (e.g. on teleport). */
+    invalidate() {
+        this._lastVx = NaN;
+        this._lastVy = NaN;
+    }
+}
+// ---------------------------------------------------------------------------
+// Pre-built lookup table for default maps — avoids template literal per frame.
+// Key format: `${state}|${weaponCategory}|${direction}`
+// ---------------------------------------------------------------------------
+const _defaultKeyLookup = /* @__PURE__ */ (() => {
+    const lut = new Map();
+    const states = Object.keys(DEFAULT_STATE_ANIM_MAP);
+    const weaponKeys = Object.keys(DEFAULT_WEAPON_SUFFIXES);
+    for (const state of states) {
+        const desc = DEFAULT_STATE_ANIM_MAP[state];
+        for (const wk of weaponKeys) {
+            const weapon = DEFAULT_WEAPON_SUFFIXES[wk];
+            if (desc.omitDirection) {
+                const animKey = `${desc.base}_${weapon}`;
+                for (let d = 0; d < 8; d++) {
+                    lut.set(`${state}|${wk}|${d}`, animKey);
+                }
+            }
+            else {
+                for (let d = 0; d < 8; d++) {
+                    lut.set(`${state}|${wk}|${d}`, `${desc.base}_${weapon}_${DIRECTION_SUFFIXES[d]}`);
+                }
+            }
+        }
+    }
+    return lut;
+})();
+/**
+ * Convert a 2D velocity vector to an 8-way CompassIndex.
+ * Zero vector defaults to South (rest facing).
+ */
+export function getDirection(vx, vy) {
+    if (Math.abs(vx) < 0.01 && Math.abs(vy) < 0.01)
+        return CompassIndex.S;
+    // atan2 gives angle from positive X axis, CCW positive.
+    // Adding π/2 rotates so that North (vy<0 in screen space) maps to 0,
+    // East to π/2, South to π, West to 3π/2 — clockwise from North.
+    const angle = Math.atan2(vy, vx);
+    // Map to [0, 2π] then quantize into 8 sectors (each sector = π/4).
+    const normalized = ((angle + Math.PI * 0.5) % (Math.PI * 2) + Math.PI * 2) % (Math.PI * 2);
+    const sector = Math.floor((normalized + Math.PI / 8) / (Math.PI / 4)) % 8;
+    return sector;
+}
+/**
+ * Build an animation key from state, weapon type, and direction.
+ *
+ * Format: `{base}_{weapon}_{direction}` or `{base}_{weapon}` if direction omitted.
+ * Falls back to 'rifle' for unknown weapon types.
+ *
+ * @param animMap - Custom state → descriptor map. Uses DEFAULT_STATE_ANIM_MAP when omitted.
+ * @param weaponSuffixes - Custom weapon suffix map. Uses DEFAULT_WEAPON_SUFFIXES when omitted.
+ */
+export function getAnimationKey(state, weaponType, direction, animMap, weaponSuffixes) {
+    // Fast path: use pre-built lookup table when both maps are defaults
+    if (animMap === undefined && weaponSuffixes === undefined) {
+        const cached = _defaultKeyLookup.get(`${state}|${String(weaponType)}|${direction}`);
+        if (cached !== undefined)
+            return cached;
+    }
+    // Slow path: custom maps or unknown state/weapon combination
+    const map = animMap ?? DEFAULT_STATE_ANIM_MAP;
+    const suffixes = weaponSuffixes ?? DEFAULT_WEAPON_SUFFIXES;
+    const desc = map[state] ?? DEFAULT_DESCRIPTOR;
+    const weapon = suffixes[String(weaponType)] ?? 'rifle';
+    if (desc.omitDirection) {
+        return `${desc.base}_${weapon}`;
+    }
+    return `${desc.base}_${weapon}_${DIRECTION_SUFFIXES[direction]}`;
+}
+/**
+ * Resolve a full animation request from AI state and movement data.
+ *
+ * @param input - Animation input (state, weapon, velocity, optional maps/cache).
+ * @returns Complete animation request with key, loop, frame rate, and layer.
+ */
+export function getAnimationRequest(input) {
+    const { state, weaponCategory, velocity, animMap, weaponSuffixes, directionCache } = input;
+    const map = animMap ?? DEFAULT_STATE_ANIM_MAP;
+    const desc = map[state] ?? DEFAULT_DESCRIPTOR;
+    const direction = directionCache ? directionCache.resolve(velocity.x, velocity.y) : getDirection(velocity.x, velocity.y);
+    const key = getAnimationKey(state, weaponCategory, direction, animMap, weaponSuffixes);
+    return {
+        key,
+        loop: desc.loop,
+        frameRate: desc.frameRate,
+        layer: desc.layer,
+    };
+}
+//# sourceMappingURL=AnimationSelector.js.map

package/dist/animation/AnimationSelector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationSelector.js","sourceRoot":"","sources":["../../src/animation/AnimationSelector.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,uCAAuC;AACvC,6DAA6D;AAI7D;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,CAAC,EAAE,CAAC;IACJ,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,CAAC;IACJ,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,CAAC;IACJ,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,CAAC;IACJ,EAAE,EAAE,CAAC;CACG,CAAC;AAIX,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAU,CAAC;AAEjF;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;CACC,CAAC;AAyBX;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA8C;IAC/E,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC9F,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAChG,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACrG,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE;IACpG,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACtG,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACvG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC7F,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAC9F,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE;IACnG,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACzG,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACjG,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACrG,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC9F,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAC9F,iBAAiB;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IACnG,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC/F,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC/F,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE;CACrG,CAAC;AAEF,MAAM,kBAAkB,GAAoB;IAC1C,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK;CACrF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAqC;IACvE,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,SAAS;IACd,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,SAAS;IACd,GAAG,EAAE,SAAS;CACf,CAAC;AAEF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAE9E,mFAAmF;AACnF,MAAM,0BAA0B,GAAG,GAAG,CAAC,CAAC,gBAAgB;AAExD;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAA3B;QACU,YAAO,GAAG,GAAG,CAAC;QACd,YAAO,GAAG,GAAG,CAAC;QACd,SAAI,GAAiB,YAAY,CAAC,CAAC,CAAC;IAwB9C,CAAC;IAtBC;;OAEG;IACH,OAAO,CAAC,EAAU,EAAE,EAAU;QAC5B,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAE7B,yEAAyE;QACzE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,0BAA0B,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;YACpF,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;YAClB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,qDAAqD;IACrD,UAAU;QACR,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;IACrB,CAAC;CACF;AAED,8EAA8E;AAC9E,+EAA+E;AAC/E,wDAAwD;AACxD,8EAA8E;AAC9E,MAAM,iBAAiB,GAAwB,eAAe,CAAC,CAAC,GAAG,EAAE;IACnE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAExD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC3C,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,uBAAuB,CAAC,EAAE,CAAC,CAAC;YAC3C,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,MAAM,EAAE,CAAC;gBACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC3B,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC3B,GAAG,CAAC,GAAG,CACL,GAAG,KAAK,IAAI,EAAE,IAAI,CAAC,EAAE,EACrB,GAAG,IAAI,CAAC,IAAI,IAAI,MAAM,IAAI,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAClD,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC,EAAE,CAAC;AAEL;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,EAAU;IACjD,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI;QAAE,OAAO,YAAY,CAAC,CAAC,CAAC;IAEtE,wDAAwD;IACxD,qEAAqE;IACrE,gEAAgE;IAChE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAEjC,mEAAmE;IACnE,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAE1E,OAAO,MAAsB,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAa,EACb,UAA2B,EAC3B,SAAuB,EACvB,OAAmD,EACnD,cAAiD;IAEjD,oEAAoE;IACpE,IAAI,OAAO,KAAK,SAAS,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,GAAG,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC;QACpF,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;IAC1C,CAAC;IAED,6DAA6D;IAC7D,MAAM,GAAG,GAAG,OAAO,IAAI,sBAAsB,CAAC;IAC9C,MAAM,QAAQ,GAAG,cAAc,IAAI,uBAAuB,CAAC;IAC3D,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC;IAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,OAAO,CAAC;IAEvD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,MAAM,EAAE,CAAC;IAClC,CAAC;IAED,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,MAAM,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;AACnE,CAAC;AAeD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAsB;IAEtB,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IAC3F,MAAM,GAAG,GAAG,OAAO,IAAI,sBAAsB,CAAC;IAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC;IAC9C,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzH,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;IAEvF,OAAO;QACL,GAAG;QACH,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC;AACJ,CAAC"}

package/dist/animation/index.d.ts

@@ -0,0 +1,5 @@
+export { getDirection, getAnimationKey, getAnimationRequest, DirectionCache, CompassIndex, AnimLayer, DEFAULT_STATE_ANIM_MAP, DEFAULT_WEAPON_SUFFIXES, } from './AnimationSelector';
+export type { IAnimationRequest, IAnimDescriptor, IAnimationInput } from './AnimationSelector';
+export { AnimationController, } from './AnimationController';
+export type { IAnimationDriver, IAnimPlayOptions, ILayerPriorityMap, IAnimationControllerConfig, } from './AnimationController';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/animation/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,SAAS,EACT,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,EACL,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC"}

package/dist/animation/index.js

@@ -0,0 +1,4 @@
+// animation sub-path barrel
+export { getDirection, getAnimationKey, getAnimationRequest, DirectionCache, CompassIndex, AnimLayer, DEFAULT_STATE_ANIM_MAP, DEFAULT_WEAPON_SUFFIXES, } from './AnimationSelector';
+export { AnimationController, } from './AnimationController';
+//# sourceMappingURL=index.js.map

package/dist/animation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/animation/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,SAAS,EACT,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/combat/CombatTransitionChain.d.ts

@@ -0,0 +1,95 @@
+import type { INPCLoadout } from '../types/IWeaponTypes';
+/**
+ * Snapshot of an NPC's combat state for transition evaluation.
+ * Framework-agnostic — no entity references, only data.
+ */
+export interface ICombatContext {
+    /** Current HP / max HP [0, 1]. */
+    readonly hpRatio: number;
+    /** Morale value [-1, 1]. */
+    readonly moraleValue: number;
+    /** Is morale in PANICKED state. */
+    readonly isPanicked: boolean;
+    /** Time since last visual contact with enemy (ms). */
+    readonly lostSightMs: number;
+    /** Distance to nearest known enemy (px). */
+    readonly distanceToEnemy: number;
+    /** Number of visible enemies. */
+    readonly visibleEnemyCount: number;
+    /** NPC weapon loadout for tactical decisions. */
+    readonly loadout: INPCLoadout;
+    /** Whether the NPC can switch targets (not inertia-locked). */
+    readonly canSwitchTarget: boolean;
+    /** Time since the NPC last exited wounded state (ms). Infinity if never. */
+    readonly timeSinceWoundedMs: number;
+    /** Whether a grenade/explosion danger is active near the NPC. */
+    readonly hasExplosiveDanger: boolean;
+    /** Whether the NPC has any ammo remaining. */
+    readonly hasAmmo: boolean;
+}
+/**
+ * Result of a transition rule evaluation.
+ * A string state key (framework-agnostic) or null to continue the chain.
+ */
+export type TransitionResult = string | null;
+/**
+ * A single rule in the combat transition chain.
+ *
+ * Rules are stateless pure functions — they read the combat context
+ * and return a target state string, or null to pass to the next rule.
+ */
+export interface ITransitionRule {
+    readonly name: string;
+    readonly priority: number;
+    evaluate(context: ICombatContext, config: ICombatTransitionConfig): TransitionResult;
+}
+/**
+ * Configuration thresholds for combat transitions.
+ */
+export interface ICombatTransitionConfig {
+    /** HP ratio below which the NPC is considered wounded. */
+    readonly woundedHpThreshold: number;
+    /** Minimum time before re-entering wounded state (ms). */
+    readonly woundedReentryCooldownMs: number;
+    /** Morale below which the NPC should retreat. */
+    readonly retreatMoraleThreshold: number;
+    /** Time without visual contact before throwing a grenade (ms). */
+    readonly grenadeLostSightMs: number;
+    /** Time without visual contact before searching (ms). */
+    readonly lostSightThresholdMs: number;
+    /** Minimum enemies for grenade throw. */
+    readonly grenadeMinEnemies: number;
+    /** Grenade throw distance range [min, max] (px). */
+    readonly grenadeMinDistance: number;
+    readonly grenadeMaxDistance: number;
+}
+/** Default production configuration. */
+export declare function createDefaultCombatTransitionConfig(overrides?: Partial<ICombatTransitionConfig>): ICombatTransitionConfig;
+/** Priority 1: Critically wounded NPC seeks safety. */
+export declare const WoundedRule: ITransitionRule;
+/** Priority 2: No ammo → retreat. */
+export declare const NoAmmoRule: ITransitionRule;
+/** Priority 3: Explosive danger nearby → evade. */
+export declare const EvadeDangerRule: ITransitionRule;
+/** Priority 4: Low morale → retreat; panicked → flee. */
+export declare const MoraleRule: ITransitionRule;
+/** Priority 5: Lost sight long enough, has grenades → throw. */
+export declare const GrenadeOpportunityRule: ITransitionRule;
+/** Priority 6: Lost sight for extended time → search. */
+export declare const SearchRule: ITransitionRule;
+/**
+ * The complete default combat transition chain.
+ * Rules are sorted by priority (lowest number = highest priority).
+ */
+export declare const DEFAULT_COMBAT_RULES: readonly ITransitionRule[];
+/**
+ * Evaluate all rules in priority order. Returns the first matching
+ * state transition, or null if no rule triggers.
+ *
+ * @param rules - Transition rules sorted by priority.
+ * @param context - Current combat snapshot.
+ * @param config - Threshold configuration.
+ * @returns Target state string, or null.
+ */
+export declare function evaluateTransitions(rules: readonly ITransitionRule[], context: ICombatContext, config: ICombatTransitionConfig): TransitionResult;
+//# sourceMappingURL=CombatTransitionChain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CombatTransitionChain.d.ts","sourceRoot":"","sources":["../../src/combat/CombatTransitionChain.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,iCAAiC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAAC;CACtF;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,iDAAiD;IACjD,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,yDAAyD;IACzD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,yCAAyC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,wCAAwC;AACxC,wBAAgB,mCAAmC,CACjD,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAC3C,uBAAuB,CAYzB;AAMD,uDAAuD;AACvD,eAAO,MAAM,WAAW,EAAE,eAQzB,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,UAAU,EAAE,eAMxB,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,eAAe,EAAE,eAM7B,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,UAAU,EAAE,eASxB,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,EAAE,eAepC,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,UAAU,EAAE,eAMxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,eAAe,EAO1D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,uBAAuB,GAC9B,gBAAgB,CAMlB"}

package/dist/combat/CombatTransitionChain.js

@@ -0,0 +1,117 @@
+// combat/CombatTransitionChain.ts
+// Chain of Responsibility pattern for combat state transitions.
+// Each rule is a pure function evaluated in priority order.
+/** Default production configuration. */
+export function createDefaultCombatTransitionConfig(overrides) {
+    return {
+        woundedHpThreshold: 0.2,
+        woundedReentryCooldownMs: 10000,
+        retreatMoraleThreshold: -0.3,
+        grenadeLostSightMs: 2000,
+        lostSightThresholdMs: 3000,
+        grenadeMinEnemies: 2,
+        grenadeMinDistance: 80,
+        grenadeMaxDistance: 250,
+        ...overrides,
+    };
+}
+// -----------------------------------------------------------------------
+// Concrete rules — priority ordered
+// -----------------------------------------------------------------------
+/** Priority 1: Critically wounded NPC seeks safety. */
+export const WoundedRule = {
+    name: 'wounded',
+    priority: 1,
+    evaluate(ctx, cfg) {
+        if (ctx.hpRatio >= cfg.woundedHpThreshold)
+            return null;
+        if (ctx.timeSinceWoundedMs < cfg.woundedReentryCooldownMs)
+            return null;
+        return 'WOUNDED';
+    },
+};
+/** Priority 2: No ammo → retreat. */
+export const NoAmmoRule = {
+    name: 'noAmmo',
+    priority: 2,
+    evaluate(ctx) {
+        return ctx.hasAmmo ? null : 'RETREAT';
+    },
+};
+/** Priority 3: Explosive danger nearby → evade. */
+export const EvadeDangerRule = {
+    name: 'evadeDanger',
+    priority: 3,
+    evaluate(ctx) {
+        return ctx.hasExplosiveDanger ? 'EVADE_GRENADE' : null;
+    },
+};
+/** Priority 4: Low morale → retreat; panicked → flee. */
+export const MoraleRule = {
+    name: 'morale',
+    priority: 4,
+    evaluate(ctx, cfg) {
+        if (ctx.isPanicked)
+            return 'FLEE';
+        if (ctx.moraleValue < cfg.retreatMoraleThreshold && ctx.canSwitchTarget)
+            return 'RETREAT';
+        return null;
+    },
+};
+/** Priority 5: Lost sight long enough, has grenades → throw. */
+export const GrenadeOpportunityRule = {
+    name: 'grenadeOpportunity',
+    priority: 5,
+    evaluate(ctx, cfg) {
+        if (ctx.lostSightMs < cfg.grenadeLostSightMs)
+            return null;
+        if (ctx.lostSightMs >= cfg.lostSightThresholdMs)
+            return null;
+        if (ctx.loadout.grenades <= 0)
+            return null;
+        if (ctx.visibleEnemyCount < cfg.grenadeMinEnemies)
+            return null;
+        if (ctx.distanceToEnemy < cfg.grenadeMinDistance ||
+            ctx.distanceToEnemy > cfg.grenadeMaxDistance)
+            return null;
+        return 'GRENADE';
+    },
+};
+/** Priority 6: Lost sight for extended time → search. */
+export const SearchRule = {
+    name: 'search',
+    priority: 6,
+    evaluate(ctx, cfg) {
+        return ctx.lostSightMs >= cfg.lostSightThresholdMs ? 'SEARCH' : null;
+    },
+};
+/**
+ * The complete default combat transition chain.
+ * Rules are sorted by priority (lowest number = highest priority).
+ */
+export const DEFAULT_COMBAT_RULES = [
+    WoundedRule,
+    NoAmmoRule,
+    EvadeDangerRule,
+    MoraleRule,
+    GrenadeOpportunityRule,
+    SearchRule,
+];
+/**
+ * Evaluate all rules in priority order. Returns the first matching
+ * state transition, or null if no rule triggers.
+ *
+ * @param rules - Transition rules sorted by priority.
+ * @param context - Current combat snapshot.
+ * @param config - Threshold configuration.
+ * @returns Target state string, or null.
+ */
+export function evaluateTransitions(rules, context, config) {
+    for (const rule of rules) {
+        const result = rule.evaluate(context, config);
+        if (result !== null)
+            return result;
+    }
+    return null;
+}
+//# sourceMappingURL=CombatTransitionChain.js.map

package/dist/combat/CombatTransitionChain.js.map

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

package/dist/combat/LoadoutBuilder.d.ts

@@ -0,0 +1,83 @@
+import { WeaponCategory } from '../types/IWeaponTypes';
+import type { INPCLoadout } from '../types/IWeaponTypes';
+import type { IWeaponSelectionConfig } from '../types/IOnlineAIConfig';
+/**
+ * Builds an NPC loadout step-by-step with a fluent API.
+ *
+ * @example
+ * ```ts
+ * const loadout = new LoadoutBuilder(config.weapon)
+ *   .withPrimary(WeaponCategory.RIFLE)
+ *   .withSecondary(WeaponCategory.PISTOL)
+ *   .withGrenades(2)
+ *   .withMedkits(1)
+ *   .build();
+ * ```
+ */
+export declare class LoadoutBuilder {
+    private primary;
+    private secondary;
+    private grenades;
+    private medkits;
+    private readonly weaponConfigs;
+    constructor(weaponConfigs: IWeaponSelectionConfig);
+    withPrimary(category: WeaponCategory, ammo?: number): this;
+    withSecondary(category: WeaponCategory, ammo?: number): this;
+    withGrenades(count: number): this;
+    withMedkits(count: number): this;
+    build(): INPCLoadout;
+    private createSlot;
+}
+/**
+ * Preferred weapon type for faction-based loadout generation.
+ * Maps to a WeaponCategory used as the primary at mid ranks.
+ */
+/**
+ * Recipe for creating a rank-appropriate NPC loadout.
+ * When `useFactionPreference` is true, the primary weapon is resolved
+ * via `resolveMidRankPrimary(factionPreference)` instead of using the literal `primary` value.
+ */
+export interface ILoadoutRecipe {
+    readonly primary: WeaponCategory;
+    readonly secondary?: WeaponCategory | null;
+    readonly grenades: number;
+    readonly medkits: number;
+    readonly useFactionPreference?: boolean;
+}
+/**
+ * Default rank → loadout recipes matching the original if-else chain.
+ * Ranks not present (7+) fall through to formula-based generation.
+ */
+export declare const DEFAULT_LOADOUT_RECIPES: Readonly<Record<number, ILoadoutRecipe>>;
+export declare const FactionWeaponPreference: {
+    readonly rifle: 2;
+    readonly shotgun: 1;
+    readonly pistol: 0;
+    readonly sniper: 3;
+};
+export type FactionWeaponPreference = (typeof FactionWeaponPreference)[keyof typeof FactionWeaponPreference];
+/**
+ * Create a rank-appropriate loadout for an NPC.
+ *
+ * Rank determines the tier of equipment. Faction preference
+ * influences weapon choice at mid ranks where multiple options
+ * are viable.
+ *
+ * | Rank | Primary | Secondary | Grenades | Medkits |
+ * |------|---------|-----------|----------|---------|
+ * | 1    | PISTOL  | —         | 0        | 0       |
+ * | 2    | PISTOL  | —         | 0        | 1       |
+ * | 3    | faction | PISTOL    | 0        | 1       |
+ * | 4    | faction | PISTOL    | 1        | 2       |
+ * | 5    | RIFLE   | SHOTGUN   | 1        | 2       |
+ * | 6    | RIFLE*  | SHOTGUN   | 2        | 2       |
+ * | 7+   | SNIPER  | RIFLE     | min(r-4,3) | 3    |
+ *
+ * *At rank 6, sniper factions get SNIPER as primary.
+ *
+ * @param recipes - Optional custom recipe map. If provided and a matching rank
+ *   entry exists (exact or highest rank <= current), it is used instead of the
+ *   built-in if-else chain. If not provided, the original hardcoded logic applies.
+ */
+export declare function createLoadout(rank: number, factionPreference: WeaponCategory, config: IWeaponSelectionConfig, recipes?: Readonly<Record<number, ILoadoutRecipe>>): INPCLoadout;
+//# sourceMappingURL=LoadoutBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LoadoutBuilder.d.ts","sourceRoot":"","sources":["../../src/combat/LoadoutBuilder.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;gBAE3C,aAAa,EAAE,sBAAsB;IAIjD,WAAW,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAK1D,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAK5D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKjC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKhC,KAAK,IAAI,WAAW;IASpB,OAAO,CAAC,UAAU;CAenB;AAED;;;GAGG;AACH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAO5E,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;CAK1B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAYzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,iBAAiB,EAAE,cAAc,EACjC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,GACjD,WAAW,CASb"}