@esengine/ecs-framework 2.3.0 → 2.3.1

package/bin/ECS/Core/QuerySystem.js

@@ -1,1069 +0,0 @@
-import { ComponentRegistry } from './ComponentStorage';
-import { BitMask64Utils } from '../Utils/BigIntCompatibility';
-import { createLogger } from '../../Utils/Logger';
-import { getComponentTypeName } from '../Decorators';
-import { ArchetypeSystem } from './ArchetypeSystem';
-import { ReactiveQuery } from './ReactiveQuery';
-import { QueryConditionType } from './QueryTypes';
-export { QueryConditionType };
-/**
- * 高性能实体查询系统
- *
- * 提供快速的实体查询功能，支持按组件类型、标签、名称等多种方式查询实体。
- *
- * @example
- * ```typescript
- * // 查询所有包含Position和Velocity组件的实体
- * const movingEntities = querySystem.queryAll(PositionComponent, VelocityComponent);
- *
- * // 查询特定标签的实体
- * const playerEntities = querySystem.queryByTag(PLAYER_TAG);
- * ```
- */
-export class QuerySystem {
-    constructor() {
-        this._logger = createLogger('QuerySystem');
-        this._entities = [];
-        this._version = 0;
-        this._queryCache = new Map();
-        this._cacheMaxSize = 1000;
-        this._cacheTimeout = 5000;
-        this._componentMaskCache = new Map();
-        this._queryStats = {
-            totalQueries: 0,
-            cacheHits: 0,
-            indexHits: 0,
-            linearScans: 0,
-            archetypeHits: 0,
-            dirtyChecks: 0
-        };
-        /**
-         * 响应式查询集合(内部使用,作为智能缓存)
-         * 传统查询API(queryAll/queryAny/queryNone)内部自动使用响应式查询优化性能
-         */
-        this._reactiveQueries = new Map();
-        /**
-         * 按组件类型索引的响应式查询
-         * 用于快速定位哪些查询关心某个组件类型
-         */
-        this._reactiveQueriesByComponent = new Map();
-        this._entityIndex = {
-            byTag: new Map(),
-            byName: new Map()
-        };
-        this._archetypeSystem = new ArchetypeSystem();
-    }
-    /**
-     * 设置实体列表并重建索引
-     *
-     * 当实体集合发生大规模变化时调用此方法。
-     * 系统将重新构建所有索引以确保查询性能。
-     *
-     * @param entities 新的实体列表
-     */
-    setEntities(entities) {
-        this._entities = entities;
-        this.clearQueryCache();
-        this.clearReactiveQueries();
-        this.rebuildIndexes();
-    }
-    /**
-     * 添加单个实体到查询系统
-     *
-     * 将新实体添加到查询系统中，并自动更新相关索引。
-     * 为了提高批量添加性能，可以延迟缓存清理。
-     *
-     * @param entity 要添加的实体
-     * @param deferCacheClear 是否延迟缓存清理（用于批量操作）
-     */
-    addEntity(entity, deferCacheClear = false) {
-        if (!this._entities.includes(entity)) {
-            this._entities.push(entity);
-            this.addEntityToIndexes(entity);
-            this._archetypeSystem.addEntity(entity);
-            // 通知响应式查询
-            this.notifyReactiveQueriesEntityAdded(entity);
-            // 只有在非延迟模式下才立即清理缓存
-            if (!deferCacheClear) {
-                this.clearQueryCache();
-            }
-            // 更新版本号
-            this._version++;
-        }
-    }
-    /**
-     * 批量添加实体
-     *
-     * 高效地批量添加多个实体，减少缓存清理次数。
-     * 使用Set来避免O(n)的重复检查。
-     *
-     * @param entities 要添加的实体列表
-     */
-    addEntities(entities) {
-        if (entities.length === 0)
-            return;
-        // 使用Set来快速检查重复
-        const existingIds = new Set(this._entities.map((e) => e.id));
-        let addedCount = 0;
-        for (const entity of entities) {
-            if (!existingIds.has(entity.id)) {
-                this._entities.push(entity);
-                this.addEntityToIndexes(entity);
-                // 更新索引管理器
-                this._archetypeSystem.addEntity(entity);
-                existingIds.add(entity.id);
-                addedCount++;
-            }
-        }
-        // 只在有实体被添加时才清理缓存
-        if (addedCount > 0) {
-            this.clearQueryCache();
-        }
-    }
-    /**
-     * 批量添加实体（无重复检查版本）
-     *
-     * 假设所有实体都是新的，跳过重复检查以获得最大性能。
-     * 仅在确保没有重复实体时使用。
-     *
-     * @param entities 要添加的实体列表
-     */
-    addEntitiesUnchecked(entities) {
-        if (entities.length === 0)
-            return;
-        // 避免调用栈溢出，分批添加
-        for (const entity of entities) {
-            this._entities.push(entity);
-        }
-        // 批量更新索引
-        for (const entity of entities) {
-            this.addEntityToIndexes(entity);
-            // 更新索引管理器
-            this._archetypeSystem.addEntity(entity);
-        }
-        // 清理缓存
-        this.clearQueryCache();
-    }
-    /**
-     * 从查询系统移除实体
-     *
-     * 从查询系统中移除指定实体，并清理相关索引。
-     *
-     * @param entity 要移除的实体
-     */
-    removeEntity(entity) {
-        const index = this._entities.indexOf(entity);
-        if (index !== -1) {
-            const componentTypes = [];
-            for (const component of entity.components) {
-                componentTypes.push(component.constructor);
-            }
-            this._entities.splice(index, 1);
-            this.removeEntityFromIndexes(entity);
-            this._archetypeSystem.removeEntity(entity);
-            if (componentTypes.length > 0) {
-                this.notifyReactiveQueriesEntityRemoved(entity, componentTypes);
-            }
-            else {
-                this.notifyReactiveQueriesEntityRemovedFallback(entity);
-            }
-            this.clearQueryCache();
-            this._version++;
-        }
-    }
-    /**
-     * 更新实体在查询系统中的索引
-     *
-     * 当实体的组件组合发生变化时调用此方法，高效地更新实体在查询系统中的索引。
-     *
-     * @param entity 要更新的实体
-     */
-    updateEntity(entity) {
-        // 检查实体是否在查询系统中
-        if (!this._entities.includes(entity)) {
-            // 如果实体不在系统中，直接添加
-            this.addEntity(entity);
-            return;
-        }
-        // 先从索引中移除实体的旧状态
-        this.removeEntityFromIndexes(entity);
-        // 更新ArchetypeSystem中的实体状态
-        this._archetypeSystem.updateEntity(entity);
-        // 重新添加实体到索引（基于新的组件状态）
-        this.addEntityToIndexes(entity);
-        // 通知响应式查询
-        this.notifyReactiveQueriesEntityChanged(entity);
-        // 清理查询缓存，因为实体组件状态已改变
-        this.clearQueryCache();
-        // 更新版本号以使缓存失效
-        this._version++;
-    }
-    /**
-     * 将实体添加到各种索引中
-     */
-    addEntityToIndexes(entity) {
-        // 标签索引
-        const tag = entity.tag;
-        if (tag !== undefined) {
-            const tagSet = this._entityIndex.byTag.get(tag) || this.createAndSetTagIndex(tag);
-            tagSet.add(entity);
-        }
-        // 名称索引
-        const name = entity.name;
-        if (name) {
-            const nameSet = this._entityIndex.byName.get(name) || this.createAndSetNameIndex(name);
-            nameSet.add(entity);
-        }
-    }
-    createAndSetTagIndex(tag) {
-        const set = new Set();
-        this._entityIndex.byTag.set(tag, set);
-        return set;
-    }
-    createAndSetNameIndex(name) {
-        const set = new Set();
-        this._entityIndex.byName.set(name, set);
-        return set;
-    }
-    /**
-     * 从各种索引中移除实体
-     */
-    removeEntityFromIndexes(entity) {
-        // 从标签索引移除
-        if (entity.tag !== undefined) {
-            const tagSet = this._entityIndex.byTag.get(entity.tag);
-            if (tagSet) {
-                tagSet.delete(entity);
-                if (tagSet.size === 0) {
-                    this._entityIndex.byTag.delete(entity.tag);
-                }
-            }
-        }
-        // 从名称索引移除
-        if (entity.name) {
-            const nameSet = this._entityIndex.byName.get(entity.name);
-            if (nameSet) {
-                nameSet.delete(entity);
-                if (nameSet.size === 0) {
-                    this._entityIndex.byName.delete(entity.name);
-                }
-            }
-        }
-    }
-    /**
-     * 重建所有索引
-     *
-     * 清空并重新构建所有查询索引。
-     * 通常在大量实体变更后调用以确保索引一致性。
-     */
-    rebuildIndexes() {
-        this._entityIndex.byTag.clear();
-        this._entityIndex.byName.clear();
-        // 清理ArchetypeSystem和ComponentIndexManager
-        this._archetypeSystem.clear();
-        for (const entity of this._entities) {
-            this.addEntityToIndexes(entity);
-            this._archetypeSystem.addEntity(entity);
-        }
-    }
-    /**
-     * 查询包含所有指定组件的实体
-     *
-     * 返回同时包含所有指定组件类型的实体列表。
-     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
-     *
-     * @param componentTypes 要查询的组件类型列表
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询同时具有位置和速度组件的实体
-     * const result = querySystem.queryAll(PositionComponent, VelocityComponent);
-     * logger.info(`找到 ${result.count} 个移动实体`);
-     * ```
-     */
-    queryAll(...componentTypes) {
-        const startTime = performance.now();
-        this._queryStats.totalQueries++;
-        // 使用内部响应式查询作为智能缓存
-        const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.ALL, componentTypes);
-        // 从响应式查询获取结果(永远是最新的)
-        const entities = reactiveQuery.getEntities();
-        // 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
-        this._queryStats.cacheHits++;
-        return {
-            entities,
-            count: entities.length,
-            executionTime: performance.now() - startTime,
-            fromCache: true
-        };
-    }
-    /**
-     * 查询包含任意指定组件的实体
-     *
-     * 返回包含任意一个指定组件类型的实体列表。
-     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
-     *
-     * @param componentTypes 要查询的组件类型列表
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询具有武器或护甲组件的实体
-     * const result = querySystem.queryAny(WeaponComponent, ArmorComponent);
-     * logger.info(`找到 ${result.count} 个装备实体`);
-     * ```
-     */
-    queryAny(...componentTypes) {
-        const startTime = performance.now();
-        this._queryStats.totalQueries++;
-        // 使用内部响应式查询作为智能缓存
-        const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.ANY, componentTypes);
-        // 从响应式查询获取结果(永远是最新的)
-        const entities = reactiveQuery.getEntities();
-        // 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
-        this._queryStats.cacheHits++;
-        return {
-            entities,
-            count: entities.length,
-            executionTime: performance.now() - startTime,
-            fromCache: true
-        };
-    }
-    /**
-     * 查询不包含任何指定组件的实体
-     *
-     * 返回不包含任何指定组件类型的实体列表。
-     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
-     *
-     * @param componentTypes 要排除的组件类型列表
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询不具有AI和玩家控制组件的实体（如静态物体）
-     * const result = querySystem.queryNone(AIComponent, PlayerControlComponent);
-     * logger.info(`找到 ${result.count} 个静态实体`);
-     * ```
-     */
-    queryNone(...componentTypes) {
-        const startTime = performance.now();
-        this._queryStats.totalQueries++;
-        // 使用内部响应式查询作为智能缓存
-        const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.NONE, componentTypes);
-        // 从响应式查询获取结果(永远是最新的)
-        const entities = reactiveQuery.getEntities();
-        // 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
-        this._queryStats.cacheHits++;
-        return {
-            entities,
-            count: entities.length,
-            executionTime: performance.now() - startTime,
-            fromCache: true
-        };
-    }
-    /**
-     * 按标签查询实体
-     *
-     * 返回具有指定标签的所有实体。
-     * 标签查询使用专用索引，具有很高的查询性能。
-     *
-     * @param tag 要查询的标签值
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询所有玩家实体
-     * const players = querySystem.queryByTag(PLAYER_TAG);
-     * ```
-     */
-    queryByTag(tag) {
-        const startTime = performance.now();
-        this._queryStats.totalQueries++;
-        const cacheKey = `tag:${tag}`;
-        // 检查缓存
-        const cached = this.getFromCache(cacheKey);
-        if (cached) {
-            this._queryStats.cacheHits++;
-            return {
-                entities: cached,
-                count: cached.length,
-                executionTime: performance.now() - startTime,
-                fromCache: true
-            };
-        }
-        // 使用索引查询
-        this._queryStats.indexHits++;
-        const entities = Array.from(this._entityIndex.byTag.get(tag) || []);
-        // 缓存结果
-        this.addToCache(cacheKey, entities);
-        return {
-            entities,
-            count: entities.length,
-            executionTime: performance.now() - startTime,
-            fromCache: false
-        };
-    }
-    /**
-     * 按名称查询实体
-     *
-     * 返回具有指定名称的所有实体。
-     * 名称查询使用专用索引，适用于查找特定的命名实体。
-     *
-     * @param name 要查询的实体名称
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查找名为"Player"的实体
-     * const player = querySystem.queryByName("Player");
-     * ```
-     */
-    queryByName(name) {
-        const startTime = performance.now();
-        this._queryStats.totalQueries++;
-        const cacheKey = `name:${name}`;
-        // 检查缓存
-        const cached = this.getFromCache(cacheKey);
-        if (cached) {
-            this._queryStats.cacheHits++;
-            return {
-                entities: cached,
-                count: cached.length,
-                executionTime: performance.now() - startTime,
-                fromCache: true
-            };
-        }
-        // 使用索引查询
-        this._queryStats.indexHits++;
-        const entities = Array.from(this._entityIndex.byName.get(name) || []);
-        // 缓存结果
-        this.addToCache(cacheKey, entities);
-        return {
-            entities,
-            count: entities.length,
-            executionTime: performance.now() - startTime,
-            fromCache: false
-        };
-    }
-    /**
-     * 按单个组件类型查询实体
-     *
-     * 返回包含指定组件类型的所有实体。
-     * 这是最基础的查询方法，具有最高的查询性能。
-     *
-     * @param componentType 要查询的组件类型
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询所有具有位置组件的实体
-     * const entitiesWithPosition = querySystem.queryByComponent(PositionComponent);
-     * ```
-     */
-    queryByComponent(componentType) {
-        const startTime = performance.now();
-        this._queryStats.totalQueries++;
-        const cacheKey = this.generateCacheKey('component', [componentType]);
-        // 检查缓存
-        const cached = this.getFromCache(cacheKey);
-        if (cached) {
-            this._queryStats.cacheHits++;
-            return {
-                entities: cached,
-                count: cached.length,
-                executionTime: performance.now() - startTime,
-                fromCache: true
-            };
-        }
-        this._queryStats.indexHits++;
-        const entities = this._archetypeSystem.getEntitiesByComponent(componentType);
-        // 缓存结果
-        this.addToCache(cacheKey, entities);
-        return {
-            entities,
-            count: entities.length,
-            executionTime: performance.now() - startTime,
-            fromCache: false
-        };
-    }
-    /**
-     * 从缓存获取查询结果
-     */
-    getFromCache(cacheKey) {
-        const entry = this._queryCache.get(cacheKey);
-        if (!entry)
-            return null;
-        // 检查缓存是否过期或版本过期
-        if (Date.now() - entry.timestamp > this._cacheTimeout || entry.version !== this._version) {
-            this._queryCache.delete(cacheKey);
-            return null;
-        }
-        entry.hitCount++;
-        return entry.entities;
-    }
-    /**
-     * 添加查询结果到缓存
-     */
-    addToCache(cacheKey, entities) {
-        // 如果缓存已满，清理最少使用的条目
-        if (this._queryCache.size >= this._cacheMaxSize) {
-            this.cleanupCache();
-        }
-        this._queryCache.set(cacheKey, {
-            entities: entities, // 直接使用引用，通过版本号控制失效
-            timestamp: Date.now(),
-            hitCount: 0,
-            version: this._version
-        });
-    }
-    /**
-     * 清理缓存
-     */
-    cleanupCache() {
-        // 移除过期的缓存条目
-        const now = Date.now();
-        for (const [key, entry] of this._queryCache.entries()) {
-            if (now - entry.timestamp > this._cacheTimeout) {
-                this._queryCache.delete(key);
-            }
-        }
-        // 如果还是太满，移除最少使用的条目
-        if (this._queryCache.size >= this._cacheMaxSize) {
-            let minHitCount = Infinity;
-            let oldestKey = '';
-            let oldestTimestamp = Infinity;
-            // 单次遍历找到最少使用或最旧的条目
-            for (const [key, entry] of this._queryCache.entries()) {
-                if (entry.hitCount < minHitCount ||
-                    (entry.hitCount === minHitCount && entry.timestamp < oldestTimestamp)) {
-                    minHitCount = entry.hitCount;
-                    oldestKey = key;
-                    oldestTimestamp = entry.timestamp;
-                }
-            }
-            if (oldestKey) {
-                this._queryCache.delete(oldestKey);
-            }
-        }
-    }
-    /**
-     * 清除所有查询缓存
-     */
-    clearQueryCache() {
-        this._queryCache.clear();
-        this._componentMaskCache.clear();
-    }
-    /**
-     * 清除所有响应式查询
-     *
-     * 销毁所有响应式查询实例并清理索引
-     * 通常在setEntities时调用以确保缓存一致性
-     */
-    clearReactiveQueries() {
-        for (const query of this._reactiveQueries.values()) {
-            query.dispose();
-        }
-        this._reactiveQueries.clear();
-        this._reactiveQueriesByComponent.clear();
-    }
-    /**
-     * 高效的缓存键生成
-     */
-    generateCacheKey(prefix, componentTypes) {
-        // 快速路径：单组件查询
-        if (componentTypes.length === 1) {
-            const name = getComponentTypeName(componentTypes[0]);
-            return `${prefix}:${name}`;
-        }
-        // 多组件查询：使用排序后的类型名称创建键
-        const sortKey = componentTypes
-            .map((t) => {
-            const name = getComponentTypeName(t);
-            return name;
-        })
-            .sort()
-            .join(',');
-        const fullKey = `${prefix}:${sortKey}`;
-        return fullKey;
-    }
-    /**
-     * 清理查询缓存
-     *
-     * 用于外部调用清理缓存，通常在批量操作后使用。
-     * 注意:此方法也会清理响应式查询缓存
-     */
-    clearCache() {
-        this.clearQueryCache();
-        this.clearReactiveQueries();
-    }
-    /**
-     * 创建响应式查询
-     *
-     * 响应式查询会自动跟踪实体/组件的变化,并通过事件通知订阅者。
-     * 适合需要实时响应实体变化的场景(如UI更新、AI系统等)。
-     *
-     * @param componentTypes 查询的组件类型列表
-     * @param config 可选的查询配置
-     * @returns 响应式查询实例
-     *
-     * @example
-     * ```typescript
-     * const query = querySystem.createReactiveQuery([Position, Velocity], {
-     *     enableBatchMode: true,
-     *     batchDelay: 16
-     * });
-     *
-     * query.subscribe((change) => {
-     *     if (change.type === ReactiveQueryChangeType.ADDED) {
-     *         console.log('新实体:', change.entity);
-     *     }
-     * });
-     * ```
-     */
-    createReactiveQuery(componentTypes, config) {
-        if (!componentTypes || componentTypes.length === 0) {
-            throw new Error('组件类型列表不能为空');
-        }
-        const mask = this.createComponentMask(componentTypes);
-        const condition = {
-            type: QueryConditionType.ALL,
-            componentTypes,
-            mask
-        };
-        const query = new ReactiveQuery(condition, config);
-        const initialEntities = this.executeTraditionalQuery(QueryConditionType.ALL, componentTypes);
-        query.initializeWith(initialEntities);
-        const cacheKey = this.generateCacheKey('all', componentTypes);
-        this._reactiveQueries.set(cacheKey, query);
-        for (const type of componentTypes) {
-            let queries = this._reactiveQueriesByComponent.get(type);
-            if (!queries) {
-                queries = new Set();
-                this._reactiveQueriesByComponent.set(type, queries);
-            }
-            queries.add(query);
-        }
-        return query;
-    }
-    /**
-     * 销毁响应式查询
-     *
-     * 清理查询占用的资源,包括监听器和实体引用。
-     * 销毁后的查询不应再被使用。
-     *
-     * @param query 要销毁的响应式查询
-     *
-     * @example
-     * ```typescript
-     * const query = querySystem.createReactiveQuery([Position, Velocity]);
-     * // ... 使用查询
-     * querySystem.destroyReactiveQuery(query);
-     * ```
-     */
-    destroyReactiveQuery(query) {
-        if (!query) {
-            return;
-        }
-        const cacheKey = query.id;
-        this._reactiveQueries.delete(cacheKey);
-        for (const type of query.condition.componentTypes) {
-            const queries = this._reactiveQueriesByComponent.get(type);
-            if (queries) {
-                queries.delete(query);
-                if (queries.size === 0) {
-                    this._reactiveQueriesByComponent.delete(type);
-                }
-            }
-        }
-        query.dispose();
-    }
-    /**
-     * 创建组件掩码
-     *
-     * 根据组件类型列表生成对应的位掩码。
-     * 使用缓存避免重复计算。
-     * 注意:必须使用ComponentRegistry来确保与Entity.componentMask使用相同的bitIndex
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 生成的位掩码
-     */
-    createComponentMask(componentTypes) {
-        // 生成缓存键
-        const cacheKey = componentTypes
-            .map((t) => {
-            return getComponentTypeName(t);
-        })
-            .sort()
-            .join(',');
-        // 检查缓存
-        const cached = this._componentMaskCache.get(cacheKey);
-        if (cached) {
-            return cached;
-        }
-        // 使用ComponentRegistry而不是ComponentTypeManager,确保bitIndex一致
-        const mask = BitMask64Utils.clone(BitMask64Utils.ZERO);
-        for (const type of componentTypes) {
-            // 确保组件已注册
-            if (!ComponentRegistry.isRegistered(type)) {
-                ComponentRegistry.register(type);
-            }
-            const bitMask = ComponentRegistry.getBitMask(type);
-            BitMask64Utils.orInPlace(mask, bitMask);
-        }
-        // 缓存结果
-        this._componentMaskCache.set(cacheKey, mask);
-        return mask;
-    }
-    /**
-     * 获取当前版本号（用于缓存失效）
-     */
-    get version() {
-        return this._version;
-    }
-    /**
-     * 获取所有实体
-     */
-    getAllEntities() {
-        return this._entities;
-    }
-    /**
-     * 获取系统统计信息
-     *
-     * 返回查询系统的详细统计信息，包括实体数量、索引状态、
-     * 查询性能统计等，用于性能监控和调试。
-     *
-     * @returns 系统统计信息对象
-     */
-    getStats() {
-        return {
-            entityCount: this._entities.length,
-            indexStats: {
-                componentIndexSize: this._archetypeSystem.getAllArchetypes().length,
-                tagIndexSize: this._entityIndex.byTag.size,
-                nameIndexSize: this._entityIndex.byName.size
-            },
-            queryStats: {
-                ...this._queryStats,
-                cacheHitRate: this._queryStats.totalQueries > 0
-                    ? ((this._queryStats.cacheHits / this._queryStats.totalQueries) * 100).toFixed(2) + '%'
-                    : '0%'
-            },
-            optimizationStats: {
-                archetypeSystem: this._archetypeSystem.getAllArchetypes().map((a) => ({
-                    id: a.id,
-                    componentTypes: a.componentTypes.map((t) => getComponentTypeName(t)),
-                    entityCount: a.entities.size
-                }))
-            },
-            cacheStats: {
-                size: this._reactiveQueries.size,
-                hitRate: this._queryStats.totalQueries > 0
-                    ? ((this._queryStats.cacheHits / this._queryStats.totalQueries) * 100).toFixed(2) + '%'
-                    : '0%'
-            }
-        };
-    }
-    /**
-     * 获取实体所属的原型信息
-     *
-     * @param entity 要查询的实体
-     */
-    getEntityArchetype(entity) {
-        return this._archetypeSystem.getEntityArchetype(entity);
-    }
-    /**
-     * 获取或创建内部响应式查询(作为智能缓存)
-     *
-     * @param queryType 查询类型
-     * @param componentTypes 组件类型列表
-     * @returns 响应式查询实例
-     */
-    getOrCreateReactiveQuery(queryType, componentTypes) {
-        // 生成缓存键(与传统缓存键格式一致)
-        const cacheKey = this.generateCacheKey(queryType, componentTypes);
-        // 检查是否已存在响应式查询
-        let reactiveQuery = this._reactiveQueries.get(cacheKey);
-        if (!reactiveQuery) {
-            // 创建查询条件
-            const mask = this.createComponentMask(componentTypes);
-            const condition = {
-                type: queryType,
-                componentTypes,
-                mask
-            };
-            // 创建响应式查询(禁用批量模式,保持实时性)
-            reactiveQuery = new ReactiveQuery(condition, {
-                enableBatchMode: false,
-                debug: false
-            });
-            // 初始化查询结果(使用传统方式获取初始数据)
-            const initialEntities = this.executeTraditionalQuery(queryType, componentTypes);
-            reactiveQuery.initializeWith(initialEntities);
-            // 注册响应式查询
-            this._reactiveQueries.set(cacheKey, reactiveQuery);
-            // 为每个组件类型注册索引
-            for (const type of componentTypes) {
-                let queries = this._reactiveQueriesByComponent.get(type);
-                if (!queries) {
-                    queries = new Set();
-                    this._reactiveQueriesByComponent.set(type, queries);
-                }
-                queries.add(reactiveQuery);
-            }
-            this._logger.debug(`创建内部响应式查询缓存: ${cacheKey}`);
-        }
-        return reactiveQuery;
-    }
-    /**
-     * 执行传统查询(内部使用,用于响应式查询初始化)
-     *
-     * @param queryType 查询类型
-     * @param componentTypes 组件类型列表
-     * @returns 匹配的实体列表
-     */
-    executeTraditionalQuery(queryType, componentTypes) {
-        switch (queryType) {
-            case QueryConditionType.ALL: {
-                const archetypeResult = this._archetypeSystem.queryArchetypes(componentTypes, 'AND');
-                const entities = [];
-                for (const archetype of archetypeResult.archetypes) {
-                    for (const entity of archetype.entities) {
-                        entities.push(entity);
-                    }
-                }
-                return entities;
-            }
-            case QueryConditionType.ANY: {
-                const archetypeResult = this._archetypeSystem.queryArchetypes(componentTypes, 'OR');
-                const entities = [];
-                for (const archetype of archetypeResult.archetypes) {
-                    for (const entity of archetype.entities) {
-                        entities.push(entity);
-                    }
-                }
-                return entities;
-            }
-            case QueryConditionType.NONE: {
-                const mask = this.createComponentMask(componentTypes);
-                return this._entities.filter((entity) => BitMask64Utils.hasNone(entity.componentMask, mask));
-            }
-            default:
-                return [];
-        }
-    }
-    /**
-     * 通知所有响应式查询实体已添加
-     *
-     * 使用组件类型索引,只通知关心该实体组件的查询
-     *
-     * @param entity 添加的实体
-     */
-    notifyReactiveQueriesEntityAdded(entity) {
-        if (this._reactiveQueries.size === 0)
-            return;
-        const notified = new Set();
-        for (const component of entity.components) {
-            const componentType = component.constructor;
-            const queries = this._reactiveQueriesByComponent.get(componentType);
-            if (queries) {
-                for (const query of queries) {
-                    if (!notified.has(query)) {
-                        query.notifyEntityAdded(entity);
-                        notified.add(query);
-                    }
-                }
-            }
-        }
-    }
-    /**
-     * 通知响应式查询实体已移除
-     *
-     * 使用组件类型索引,只通知关心该实体组件的查询
-     *
-     * @param entity 移除的实体
-     * @param componentTypes 实体移除前的组件类型列表
-     */
-    notifyReactiveQueriesEntityRemoved(entity, componentTypes) {
-        if (this._reactiveQueries.size === 0)
-            return;
-        const notified = new Set();
-        for (const componentType of componentTypes) {
-            const queries = this._reactiveQueriesByComponent.get(componentType);
-            if (queries) {
-                for (const query of queries) {
-                    if (!notified.has(query)) {
-                        query.notifyEntityRemoved(entity);
-                        notified.add(query);
-                    }
-                }
-            }
-        }
-    }
-    /**
-     * 通知响应式查询实体已移除(后备方案)
-     *
-     * 当实体已经清空组件时使用,通知所有查询
-     *
-     * @param entity 移除的实体
-     */
-    notifyReactiveQueriesEntityRemovedFallback(entity) {
-        if (this._reactiveQueries.size === 0)
-            return;
-        for (const query of this._reactiveQueries.values()) {
-            query.notifyEntityRemoved(entity);
-        }
-    }
-    /**
-     * 通知响应式查询实体已变化
-     *
-     * 使用混合策略:
-     * 1. 首先通知关心实体当前组件的查询
-     * 2. 然后通知所有其他查询(包括那些可能因为组件移除而不再匹配的查询)
-     *
-     * @param entity 变化的实体
-     */
-    notifyReactiveQueriesEntityChanged(entity) {
-        if (this._reactiveQueries.size === 0) {
-            return;
-        }
-        const notified = new Set();
-        for (const component of entity.components) {
-            const componentType = component.constructor;
-            const queries = this._reactiveQueriesByComponent.get(componentType);
-            if (queries) {
-                for (const query of queries) {
-                    if (!notified.has(query)) {
-                        query.notifyEntityChanged(entity);
-                        notified.add(query);
-                    }
-                }
-            }
-        }
-        for (const query of this._reactiveQueries.values()) {
-            if (!notified.has(query)) {
-                query.notifyEntityChanged(entity);
-            }
-        }
-    }
-}
-/**
- * 查询构建器
- *
- * 提供链式API来构建复杂的实体查询条件。
- * 支持组合多种查询条件，创建灵活的查询表达式。
- *
- * @example
- * ```typescript
- * const result = new QueryBuilder(querySystem)
- *     .withAll(PositionComponent, VelocityComponent)
- *     .without(DeadComponent)
- *     .execute();
- * ```
- */
-export class QueryBuilder {
-    constructor(querySystem) {
-        this._logger = createLogger('QueryBuilder');
-        this.conditions = [];
-        this.querySystem = querySystem;
-    }
-    /**
-     * 添加"必须包含所有组件"条件
-     *
-     * @param componentTypes 必须包含的组件类型
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withAll(...componentTypes) {
-        this.conditions.push({
-            type: QueryConditionType.ALL,
-            componentTypes,
-            mask: this.createComponentMask(componentTypes)
-        });
-        return this;
-    }
-    /**
-     * 添加"必须包含任意组件"条件
-     *
-     * @param componentTypes 必须包含其中任意一个的组件类型
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withAny(...componentTypes) {
-        this.conditions.push({
-            type: QueryConditionType.ANY,
-            componentTypes,
-            mask: this.createComponentMask(componentTypes)
-        });
-        return this;
-    }
-    /**
-     * 添加"不能包含任何组件"条件
-     *
-     * @param componentTypes 不能包含的组件类型
-     * @returns 查询构建器实例，支持链式调用
-     */
-    without(...componentTypes) {
-        this.conditions.push({
-            type: QueryConditionType.NONE,
-            componentTypes,
-            mask: this.createComponentMask(componentTypes)
-        });
-        return this;
-    }
-    /**
-     * 执行查询并返回结果
-     *
-     * 根据已添加的查询条件执行实体查询。
-     *
-     * @returns 查询结果，包含匹配的实体和性能信息
-     */
-    execute() {
-        const startTime = performance.now();
-        // 简化实现：目前只支持单一条件
-        if (this.conditions.length === 1) {
-            const condition = this.conditions[0];
-            switch (condition.type) {
-                case QueryConditionType.ALL:
-                    return this.querySystem.queryAll(...condition.componentTypes);
-                case QueryConditionType.ANY:
-                    return this.querySystem.queryAny(...condition.componentTypes);
-                case QueryConditionType.NONE:
-                    return this.querySystem.queryNone(...condition.componentTypes);
-            }
-        }
-        // 多条件查询的复杂实现留待后续扩展
-        return {
-            entities: [],
-            count: 0,
-            executionTime: performance.now() - startTime,
-            fromCache: false
-        };
-    }
-    /**
-     * 创建组件掩码
-     */
-    createComponentMask(componentTypes) {
-        const mask = BitMask64Utils.clone(BitMask64Utils.ZERO);
-        for (const type of componentTypes) {
-            try {
-                const bitMask = ComponentRegistry.getBitMask(type);
-                BitMask64Utils.orInPlace(mask, bitMask);
-            }
-            catch (error) {
-                this._logger.warn(`组件类型 ${getComponentTypeName(type)} 未注册，跳过`);
-            }
-        }
-        return mask;
-    }
-    /**
-     * 重置查询构建器
-     *
-     * 清除所有已添加的查询条件，重新开始构建查询。
-     *
-     * @returns 查询构建器实例，支持链式调用
-     */
-    reset() {
-        this.conditions = [];
-        return this;
-    }
-}
-//# sourceMappingURL=QuerySystem.js.map