@esengine/ecs-framework 2.2.20 → 2.3.0

package/bin/ECS/Serialization/VersionMigration.js

@@ -0,0 +1,279 @@
+/**
+ * 版本迁移系统
+ *
+ * 提供组件和场景数据的版本迁移支持
+ */
+/**
+ * 版本迁移管理器
+ */
+export class VersionMigrationManager {
+    /**
+     * 注册组件迁移函数
+     *
+     * @param componentType 组件类型名称
+     * @param fromVersion 源版本号
+     * @param toVersion 目标版本号
+     * @param migration 迁移函数
+     *
+     * @example
+     * ```typescript
+     * // 从版本1迁移到版本2
+     * VersionMigrationManager.registerComponentMigration(
+     *     'PlayerComponent',
+     *     1,
+     *     2,
+     *     (data) => {
+     *         // 添加新字段
+     *         data.experience = 0;
+     *         return data;
+     *     }
+     * );
+     * ```
+     */
+    static registerComponentMigration(componentType, fromVersion, _toVersion, migration) {
+        if (!this.componentMigrations.has(componentType)) {
+            this.componentMigrations.set(componentType, new Map());
+        }
+        const versionMap = this.componentMigrations.get(componentType);
+        // 使用fromVersion作为key，表示"从这个版本迁移"
+        versionMap.set(fromVersion, migration);
+    }
+    /**
+     * 注册场景迁移函数
+     *
+     * @param fromVersion 源版本号
+     * @param toVersion 目标版本号
+     * @param migration 迁移函数
+     *
+     * @example
+     * ```typescript
+     * VersionMigrationManager.registerSceneMigration(
+     *     1,
+     *     2,
+     *     (scene) => {
+     *         // 迁移场景结构
+     *         scene.metadata = { ...scene.metadata, migratedFrom: 1 };
+     *         return scene;
+     *     }
+     * );
+     * ```
+     */
+    static registerSceneMigration(fromVersion, _toVersion, migration) {
+        this.sceneMigrations.set(fromVersion, migration);
+    }
+    /**
+     * 迁移组件数据
+     *
+     * @param component 序列化的组件数据
+     * @param targetVersion 目标版本号
+     * @returns 迁移后的组件数据
+     */
+    static migrateComponent(component, targetVersion) {
+        const currentVersion = component.version;
+        if (currentVersion === targetVersion) {
+            return component; // 版本相同，无需迁移
+        }
+        const migrations = this.componentMigrations.get(component.type);
+        if (!migrations) {
+            console.warn(`No migration path found for component ${component.type}`);
+            return component;
+        }
+        const migratedData = { ...component };
+        let version = currentVersion;
+        // 执行迁移链
+        while (version < targetVersion) {
+            const migration = migrations.get(version);
+            if (!migration) {
+                console.warn(`Missing migration from version ${version} to ${version + 1} for ${component.type}`);
+                break;
+            }
+            migratedData.data = migration(migratedData.data, version, version + 1);
+            version++;
+        }
+        migratedData.version = version;
+        return migratedData;
+    }
+    /**
+     * 迁移场景数据
+     *
+     * @param scene 序列化的场景数据
+     * @param targetVersion 目标版本号
+     * @returns 迁移后的场景数据
+     */
+    static migrateScene(scene, targetVersion) {
+        const currentVersion = scene.version;
+        if (currentVersion === targetVersion) {
+            return scene; // 版本相同，无需迁移
+        }
+        let migratedScene = { ...scene };
+        let version = currentVersion;
+        // 执行场景级迁移
+        while (version < targetVersion) {
+            const migration = this.sceneMigrations.get(version);
+            if (!migration) {
+                console.warn(`Missing scene migration from version ${version} to ${version + 1}`);
+                break;
+            }
+            migratedScene = migration(migratedScene, version, version + 1);
+            version++;
+        }
+        migratedScene.version = version;
+        // 迁移所有组件
+        migratedScene = this.migrateSceneComponents(migratedScene);
+        return migratedScene;
+    }
+    /**
+     * 迁移场景中所有组件的版本
+     */
+    static migrateSceneComponents(scene) {
+        const migratedScene = { ...scene };
+        migratedScene.entities = scene.entities.map((entity) => ({
+            ...entity,
+            components: entity.components.map((component) => {
+                // 查找组件的目标版本
+                const typeInfo = scene.componentTypeRegistry.find((t) => t.typeName === component.type);
+                if (typeInfo && typeInfo.version !== component.version) {
+                    return this.migrateComponent(component, typeInfo.version);
+                }
+                return component;
+            }),
+            children: this.migrateEntitiesComponents(entity.children, scene.componentTypeRegistry)
+        }));
+        return migratedScene;
+    }
+    /**
+     * 递归迁移实体的组件
+     */
+    static migrateEntitiesComponents(entities, typeRegistry) {
+        return entities.map((entity) => ({
+            ...entity,
+            components: entity.components.map((component) => {
+                const typeInfo = typeRegistry.find((t) => t.typeName === component.type);
+                if (typeInfo && typeInfo.version !== component.version) {
+                    return this.migrateComponent(component, typeInfo.version);
+                }
+                return component;
+            }),
+            children: this.migrateEntitiesComponents(entity.children, typeRegistry)
+        }));
+    }
+    /**
+     * 清除所有迁移函数
+     */
+    static clearMigrations() {
+        this.componentMigrations.clear();
+        this.sceneMigrations.clear();
+    }
+    /**
+     * 获取组件的迁移路径
+     *
+     * @param componentType 组件类型名称
+     * @returns 可用的迁移版本列表
+     */
+    static getComponentMigrationPath(componentType) {
+        const migrations = this.componentMigrations.get(componentType);
+        if (!migrations) {
+            return [];
+        }
+        return Array.from(migrations.keys()).sort((a, b) => a - b);
+    }
+    /**
+     * 获取场景的迁移路径
+     *
+     * @returns 可用的场景迁移版本列表
+     */
+    static getSceneMigrationPath() {
+        return Array.from(this.sceneMigrations.keys()).sort((a, b) => a - b);
+    }
+    /**
+     * 检查是否可以迁移组件
+     *
+     * @param componentType 组件类型名称
+     * @param fromVersion 源版本
+     * @param toVersion 目标版本
+     * @returns 是否存在完整的迁移路径
+     */
+    static canMigrateComponent(componentType, fromVersion, toVersion) {
+        if (fromVersion === toVersion) {
+            return true;
+        }
+        const migrations = this.componentMigrations.get(componentType);
+        if (!migrations) {
+            return false;
+        }
+        // 检查是否存在完整的迁移路径
+        for (let v = fromVersion; v < toVersion; v++) {
+            if (!migrations.has(v)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 检查是否可以迁移场景
+     *
+     * @param fromVersion 源版本
+     * @param toVersion 目标版本
+     * @returns 是否存在完整的迁移路径
+     */
+    static canMigrateScene(fromVersion, toVersion) {
+        if (fromVersion === toVersion) {
+            return true;
+        }
+        // 检查是否存在完整的场景迁移路径
+        for (let v = fromVersion; v < toVersion; v++) {
+            if (!this.sceneMigrations.has(v)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+/**
+ * 组件迁移函数注册表
+ * Map<组件类型名, Map<版本号, 迁移函数>>
+ */
+VersionMigrationManager.componentMigrations = new Map();
+/**
+ * 场景迁移函数注册表
+ * Map<版本号, 迁移函数>
+ */
+VersionMigrationManager.sceneMigrations = new Map();
+/**
+ * 便捷的迁移构建器
+ *
+ * 提供链式API来定义迁移
+ */
+export class MigrationBuilder {
+    constructor() {
+        this.fromVersion = 1;
+        this.toVersion = 2;
+    }
+    /**
+     * 设置组件类型
+     */
+    forComponent(componentType) {
+        this.componentType = componentType;
+        return this;
+    }
+    /**
+     * 设置版本范围
+     */
+    fromVersionToVersion(from, to) {
+        this.fromVersion = from;
+        this.toVersion = to;
+        return this;
+    }
+    /**
+     * 注册迁移函数
+     */
+    migrate(migration) {
+        if (this.componentType) {
+            VersionMigrationManager.registerComponentMigration(this.componentType, this.fromVersion, this.toVersion, migration);
+        }
+        else {
+            VersionMigrationManager.registerSceneMigration(this.fromVersion, this.toVersion, migration);
+        }
+    }
+}
+//# sourceMappingURL=VersionMigration.js.map

package/bin/ECS/Serialization/VersionMigration.js.map

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

package/bin/ECS/Serialization/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ECS序列化系统
+ *
+ * 提供完整的场景、实体和组件序列化支持
+ */
+export { Serializable, Serialize, SerializeAsMap, SerializeAsSet, IgnoreSerialization, getSerializationMetadata, isSerializable, SERIALIZABLE_METADATA, SERIALIZE_FIELD, SERIALIZE_OPTIONS } from './SerializationDecorators';
+export type { SerializableOptions, FieldSerializeOptions, SerializationMetadata } from './SerializationDecorators';
+export { ComponentSerializer } from './ComponentSerializer';
+export type { SerializedComponent } from './ComponentSerializer';
+export { EntitySerializer } from './EntitySerializer';
+export type { SerializedEntity } from './EntitySerializer';
+export { SceneSerializer } from './SceneSerializer';
+export type { SerializedScene, SerializationFormat, DeserializationStrategy, MigrationFunction, SceneSerializationOptions, SceneDeserializationOptions } from './SceneSerializer';
+export { VersionMigrationManager, MigrationBuilder } from './VersionMigration';
+export type { ComponentMigrationFunction, SceneMigrationFunction } from './VersionMigration';
+export { IncrementalSerializer, ChangeOperation } from './IncrementalSerializer';
+export type { IncrementalSnapshot, IncrementalSerializationOptions, IncrementalSerializationFormat, EntityChange, ComponentChange, SceneDataChange } from './IncrementalSerializer';
+//# sourceMappingURL=index.d.ts.map

package/bin/ECS/Serialization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ECS/Serialization/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACH,YAAY,EACZ,SAAS,EACT,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACpB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACR,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACxB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACR,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EACzB,2BAA2B,EAC9B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,YAAY,EACR,0BAA0B,EAC1B,sBAAsB,EACzB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACjF,YAAY,EACR,mBAAmB,EACnB,+BAA+B,EAC/B,8BAA8B,EAC9B,YAAY,EACZ,eAAe,EACf,eAAe,EAClB,MAAM,yBAAyB,CAAC"}

package/bin/ECS/Serialization/index.js

@@ -0,0 +1,18 @@
+/**
+ * ECS序列化系统
+ *
+ * 提供完整的场景、实体和组件序列化支持
+ */
+// 装饰器
+export { Serializable, Serialize, SerializeAsMap, SerializeAsSet, IgnoreSerialization, getSerializationMetadata, isSerializable, SERIALIZABLE_METADATA, SERIALIZE_FIELD, SERIALIZE_OPTIONS } from './SerializationDecorators';
+// 组件序列化器
+export { ComponentSerializer } from './ComponentSerializer';
+// 实体序列化器
+export { EntitySerializer } from './EntitySerializer';
+// 场景序列化器
+export { SceneSerializer } from './SceneSerializer';
+// 版本迁移
+export { VersionMigrationManager, MigrationBuilder } from './VersionMigration';
+// 增量序列化
+export { IncrementalSerializer, ChangeOperation } from './IncrementalSerializer';
+//# sourceMappingURL=index.js.map

package/bin/ECS/Serialization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ECS/Serialization/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM;AACN,OAAO,EACH,YAAY,EACZ,SAAS,EACT,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACpB,MAAM,2BAA2B,CAAC;AAQnC,SAAS;AACT,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,SAAS;AACT,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,SAAS;AACT,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAUpD,OAAO;AACP,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM/E,QAAQ;AACR,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/bin/ECS/Systems/EntityCache.d.ts

@@ -0,0 +1,114 @@
+import { Entity } from '../Entity';
+/**
+ * 实体缓存管理器
+ *
+ * 负责管理 EntitySystem 中的实体缓存，提供帧缓存和持久缓存两级缓存机制。
+ * 使用面向对象设计，将数据和行为封装在类中。
+ *
+ * @example
+ * ```typescript
+ * const cache = new EntityCache();
+ * cache.setPersistent(entities);
+ * const cached = cache.getPersistent();
+ * cache.invalidate();
+ * ```
+ */
+export declare class EntityCache {
+    /**
+     * 帧缓存
+     *
+     * 在update周期内使用，每帧结束后清理
+     */
+    private _frameCache;
+    /**
+     * 持久缓存
+     *
+     * 跨帧使用，直到被显式失效
+     */
+    private _persistentCache;
+    /**
+     * 被跟踪的实体集合
+     *
+     * 用于跟踪哪些实体正在被此系统处理
+     */
+    private _trackedEntities;
+    /**
+     * 获取帧缓存
+     */
+    getFrame(): readonly Entity[] | null;
+    /**
+     * 设置帧缓存
+     *
+     * @param entities 要缓存的实体列表
+     */
+    setFrame(entities: readonly Entity[]): void;
+    /**
+     * 获取持久缓存
+     */
+    getPersistent(): readonly Entity[] | null;
+    /**
+     * 设置持久缓存
+     *
+     * @param entities 要缓存的实体列表
+     */
+    setPersistent(entities: readonly Entity[]): void;
+    /**
+     * 获取被跟踪的实体集合
+     */
+    getTracked(): ReadonlySet<Entity>;
+    /**
+     * 添加被跟踪的实体
+     *
+     * @param entity 要跟踪的实体
+     */
+    addTracked(entity: Entity): void;
+    /**
+     * 移除被跟踪的实体
+     *
+     * @param entity 要移除的实体
+     */
+    removeTracked(entity: Entity): void;
+    /**
+     * 检查实体是否被跟踪
+     *
+     * @param entity 要检查的实体
+     */
+    isTracked(entity: Entity): boolean;
+    /**
+     * 使持久缓存失效
+     *
+     * 当实体变化时调用，强制下次查询时重新计算
+     */
+    invalidate(): void;
+    /**
+     * 清除帧缓存
+     *
+     * 在每帧结束时调用
+     */
+    clearFrame(): void;
+    /**
+     * 清除所有缓存
+     *
+     * 在系统重置或销毁时调用
+     */
+    clearAll(): void;
+    /**
+     * 检查是否有有效的持久缓存
+     */
+    hasPersistent(): boolean;
+    /**
+     * 检查是否有有效的帧缓存
+     */
+    hasFrame(): boolean;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): {
+        hasFrame: boolean;
+        hasPersistent: boolean;
+        trackedCount: number;
+        frameEntityCount: number;
+        persistentEntityCount: number;
+    };
+}
+//# sourceMappingURL=EntityCache.d.ts.map

package/bin/ECS/Systems/EntityCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityCache.d.ts","sourceRoot":"","sources":["../../../src/ECS/Systems/EntityCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IACpB;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAkC;IAErD;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAkC;IAE1D;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAA0B;IAElD;;OAEG;IACI,QAAQ,IAAI,SAAS,MAAM,EAAE,GAAG,IAAI;IAI3C;;;;OAIG;IACI,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAIlD;;OAEG;IACI,aAAa,IAAI,SAAS,MAAM,EAAE,GAAG,IAAI;IAIhD;;;;OAIG;IACI,aAAa,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAIvD;;OAEG;IACI,UAAU,IAAI,WAAW,CAAC,MAAM,CAAC;IAIxC;;;;OAIG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIvC;;;;OAIG;IACI,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI1C;;;;OAIG;IACI,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIzC;;;;OAIG;IACI,UAAU,IAAI,IAAI;IAIzB;;;;OAIG;IACI,UAAU,IAAI,IAAI;IAIzB;;;;OAIG;IACI,QAAQ,IAAI,IAAI;IAMvB;;OAEG;IACI,aAAa,IAAI,OAAO;IAI/B;;OAEG;IACI,QAAQ,IAAI,OAAO;IAI1B;;OAEG;IACI,QAAQ,IAAI;QACf,QAAQ,EAAE,OAAO,CAAC;QAClB,aAAa,EAAE,OAAO,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,qBAAqB,EAAE,MAAM,CAAC;KAC7B;CASR"}

package/bin/ECS/Systems/EntityCache.js

@@ -0,0 +1,145 @@
+/**
+ * 实体缓存管理器
+ *
+ * 负责管理 EntitySystem 中的实体缓存，提供帧缓存和持久缓存两级缓存机制。
+ * 使用面向对象设计，将数据和行为封装在类中。
+ *
+ * @example
+ * ```typescript
+ * const cache = new EntityCache();
+ * cache.setPersistent(entities);
+ * const cached = cache.getPersistent();
+ * cache.invalidate();
+ * ```
+ */
+export class EntityCache {
+    constructor() {
+        /**
+         * 帧缓存
+         *
+         * 在update周期内使用，每帧结束后清理
+         */
+        this._frameCache = null;
+        /**
+         * 持久缓存
+         *
+         * 跨帧使用，直到被显式失效
+         */
+        this._persistentCache = null;
+        /**
+         * 被跟踪的实体集合
+         *
+         * 用于跟踪哪些实体正在被此系统处理
+         */
+        this._trackedEntities = new Set();
+    }
+    /**
+     * 获取帧缓存
+     */
+    getFrame() {
+        return this._frameCache;
+    }
+    /**
+     * 设置帧缓存
+     *
+     * @param entities 要缓存的实体列表
+     */
+    setFrame(entities) {
+        this._frameCache = entities;
+    }
+    /**
+     * 获取持久缓存
+     */
+    getPersistent() {
+        return this._persistentCache;
+    }
+    /**
+     * 设置持久缓存
+     *
+     * @param entities 要缓存的实体列表
+     */
+    setPersistent(entities) {
+        this._persistentCache = entities;
+    }
+    /**
+     * 获取被跟踪的实体集合
+     */
+    getTracked() {
+        return this._trackedEntities;
+    }
+    /**
+     * 添加被跟踪的实体
+     *
+     * @param entity 要跟踪的实体
+     */
+    addTracked(entity) {
+        this._trackedEntities.add(entity);
+    }
+    /**
+     * 移除被跟踪的实体
+     *
+     * @param entity 要移除的实体
+     */
+    removeTracked(entity) {
+        this._trackedEntities.delete(entity);
+    }
+    /**
+     * 检查实体是否被跟踪
+     *
+     * @param entity 要检查的实体
+     */
+    isTracked(entity) {
+        return this._trackedEntities.has(entity);
+    }
+    /**
+     * 使持久缓存失效
+     *
+     * 当实体变化时调用，强制下次查询时重新计算
+     */
+    invalidate() {
+        this._persistentCache = null;
+    }
+    /**
+     * 清除帧缓存
+     *
+     * 在每帧结束时调用
+     */
+    clearFrame() {
+        this._frameCache = null;
+    }
+    /**
+     * 清除所有缓存
+     *
+     * 在系统重置或销毁时调用
+     */
+    clearAll() {
+        this._frameCache = null;
+        this._persistentCache = null;
+        this._trackedEntities.clear();
+    }
+    /**
+     * 检查是否有有效的持久缓存
+     */
+    hasPersistent() {
+        return this._persistentCache !== null;
+    }
+    /**
+     * 检查是否有有效的帧缓存
+     */
+    hasFrame() {
+        return this._frameCache !== null;
+    }
+    /**
+     * 获取缓存统计信息
+     */
+    getStats() {
+        return {
+            hasFrame: this._frameCache !== null,
+            hasPersistent: this._persistentCache !== null,
+            trackedCount: this._trackedEntities.size,
+            frameEntityCount: this._frameCache?.length ?? 0,
+            persistentEntityCount: this._persistentCache?.length ?? 0
+        };
+    }
+}
+//# sourceMappingURL=EntityCache.js.map

package/bin/ECS/Systems/EntityCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityCache.js","sourceRoot":"","sources":["../../../src/ECS/Systems/EntityCache.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,WAAW;IAAxB;QACI;;;;WAIG;QACK,gBAAW,GAA6B,IAAI,CAAC;QAErD;;;;WAIG;QACK,qBAAgB,GAA6B,IAAI,CAAC;QAE1D;;;;WAIG;QACK,qBAAgB,GAAgB,IAAI,GAAG,EAAE,CAAC;IAiItD,CAAC;IA/HG;;OAEG;IACI,QAAQ;QACX,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACI,QAAQ,CAAC,QAA2B;QACvC,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC;IAChC,CAAC;IAED;;OAEG;IACI,aAAa;QAChB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,aAAa,CAAC,QAA2B;QAC5C,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;IACrC,CAAC;IAED;;OAEG;IACI,UAAU;QACb,OAAO,IAAI,CAAC,gBAAgB,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,UAAU,CAAC,MAAc;QAC5B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACI,aAAa,CAAC,MAAc;QAC/B,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACI,SAAS,CAAC,MAAc;QAC3B,OAAO,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACI,UAAU;QACb,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,UAAU;QACb,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACI,QAAQ;QACX,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC7B,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAClC,CAAC;IAED;;OAEG;IACI,aAAa;QAChB,OAAO,IAAI,CAAC,gBAAgB,KAAK,IAAI,CAAC;IAC1C,CAAC;IAED;;OAEG;IACI,QAAQ;QACX,OAAO,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC;IACrC,CAAC;IAED;;OAEG;IACI,QAAQ;QAOX,OAAO;YACH,QAAQ,EAAE,IAAI,CAAC,WAAW,KAAK,IAAI;YACnC,aAAa,EAAE,IAAI,CAAC,gBAAgB,KAAK,IAAI;YAC7C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI;YACxC,gBAAgB,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;YAC/C,qBAAqB,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC;SAC5D,CAAC;IACN,CAAC;CACJ"}