@esengine/ecs-framework 2.3.0 → 2.3.1

package/bin/ECS/Core/QuerySystem.d.ts

@@ -1,458 +0,0 @@
-import { Entity } from '../Entity';
-import { Component } from '../Component';
-import { ComponentType } from './ComponentStorage';
-import { Archetype } from './ArchetypeSystem';
-import { ReactiveQuery, ReactiveQueryConfig } from './ReactiveQuery';
-import { QueryCondition, QueryConditionType, QueryResult } from './QueryTypes';
-export { QueryCondition, QueryConditionType, QueryResult };
-/**
- * 高性能实体查询系统
- *
- * 提供快速的实体查询功能，支持按组件类型、标签、名称等多种方式查询实体。
- *
- * @example
- * ```typescript
- * // 查询所有包含Position和Velocity组件的实体
- * const movingEntities = querySystem.queryAll(PositionComponent, VelocityComponent);
- *
- * // 查询特定标签的实体
- * const playerEntities = querySystem.queryByTag(PLAYER_TAG);
- * ```
- */
-export declare class QuerySystem {
-    private readonly _logger;
-    private _entities;
-    private _entityIndex;
-    private _version;
-    private _queryCache;
-    private _cacheMaxSize;
-    private _cacheTimeout;
-    private _componentMaskCache;
-    private _archetypeSystem;
-    private _queryStats;
-    constructor();
-    /**
-     * 设置实体列表并重建索引
-     *
-     * 当实体集合发生大规模变化时调用此方法。
-     * 系统将重新构建所有索引以确保查询性能。
-     *
-     * @param entities 新的实体列表
-     */
-    setEntities(entities: Entity[]): void;
-    /**
-     * 添加单个实体到查询系统
-     *
-     * 将新实体添加到查询系统中，并自动更新相关索引。
-     * 为了提高批量添加性能，可以延迟缓存清理。
-     *
-     * @param entity 要添加的实体
-     * @param deferCacheClear 是否延迟缓存清理（用于批量操作）
-     */
-    addEntity(entity: Entity, deferCacheClear?: boolean): void;
-    /**
-     * 批量添加实体
-     *
-     * 高效地批量添加多个实体，减少缓存清理次数。
-     * 使用Set来避免O(n)的重复检查。
-     *
-     * @param entities 要添加的实体列表
-     */
-    addEntities(entities: Entity[]): void;
-    /**
-     * 批量添加实体（无重复检查版本）
-     *
-     * 假设所有实体都是新的，跳过重复检查以获得最大性能。
-     * 仅在确保没有重复实体时使用。
-     *
-     * @param entities 要添加的实体列表
-     */
-    addEntitiesUnchecked(entities: Entity[]): void;
-    /**
-     * 从查询系统移除实体
-     *
-     * 从查询系统中移除指定实体，并清理相关索引。
-     *
-     * @param entity 要移除的实体
-     */
-    removeEntity(entity: Entity): void;
-    /**
-     * 更新实体在查询系统中的索引
-     *
-     * 当实体的组件组合发生变化时调用此方法，高效地更新实体在查询系统中的索引。
-     *
-     * @param entity 要更新的实体
-     */
-    updateEntity(entity: Entity): void;
-    /**
-     * 将实体添加到各种索引中
-     */
-    private addEntityToIndexes;
-    private createAndSetTagIndex;
-    private createAndSetNameIndex;
-    /**
-     * 从各种索引中移除实体
-     */
-    private removeEntityFromIndexes;
-    /**
-     * 重建所有索引
-     *
-     * 清空并重新构建所有查询索引。
-     * 通常在大量实体变更后调用以确保索引一致性。
-     */
-    private rebuildIndexes;
-    /**
-     * 查询包含所有指定组件的实体
-     *
-     * 返回同时包含所有指定组件类型的实体列表。
-     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
-     *
-     * @param componentTypes 要查询的组件类型列表
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询同时具有位置和速度组件的实体
-     * const result = querySystem.queryAll(PositionComponent, VelocityComponent);
-     * logger.info(`找到 ${result.count} 个移动实体`);
-     * ```
-     */
-    queryAll(...componentTypes: ComponentType[]): QueryResult;
-    /**
-     * 查询包含任意指定组件的实体
-     *
-     * 返回包含任意一个指定组件类型的实体列表。
-     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
-     *
-     * @param componentTypes 要查询的组件类型列表
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询具有武器或护甲组件的实体
-     * const result = querySystem.queryAny(WeaponComponent, ArmorComponent);
-     * logger.info(`找到 ${result.count} 个装备实体`);
-     * ```
-     */
-    queryAny(...componentTypes: ComponentType[]): QueryResult;
-    /**
-     * 查询不包含任何指定组件的实体
-     *
-     * 返回不包含任何指定组件类型的实体列表。
-     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
-     *
-     * @param componentTypes 要排除的组件类型列表
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询不具有AI和玩家控制组件的实体（如静态物体）
-     * const result = querySystem.queryNone(AIComponent, PlayerControlComponent);
-     * logger.info(`找到 ${result.count} 个静态实体`);
-     * ```
-     */
-    queryNone(...componentTypes: ComponentType[]): QueryResult;
-    /**
-     * 按标签查询实体
-     *
-     * 返回具有指定标签的所有实体。
-     * 标签查询使用专用索引，具有很高的查询性能。
-     *
-     * @param tag 要查询的标签值
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询所有玩家实体
-     * const players = querySystem.queryByTag(PLAYER_TAG);
-     * ```
-     */
-    queryByTag(tag: number): QueryResult;
-    /**
-     * 按名称查询实体
-     *
-     * 返回具有指定名称的所有实体。
-     * 名称查询使用专用索引，适用于查找特定的命名实体。
-     *
-     * @param name 要查询的实体名称
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查找名为"Player"的实体
-     * const player = querySystem.queryByName("Player");
-     * ```
-     */
-    queryByName(name: string): QueryResult;
-    /**
-     * 按单个组件类型查询实体
-     *
-     * 返回包含指定组件类型的所有实体。
-     * 这是最基础的查询方法，具有最高的查询性能。
-     *
-     * @param componentType 要查询的组件类型
-     * @returns 查询结果，包含匹配的实体和性能信息
-     *
-     * @example
-     * ```typescript
-     * // 查询所有具有位置组件的实体
-     * const entitiesWithPosition = querySystem.queryByComponent(PositionComponent);
-     * ```
-     */
-    queryByComponent<T extends Component>(componentType: ComponentType<T>): QueryResult;
-    /**
-     * 从缓存获取查询结果
-     */
-    private getFromCache;
-    /**
-     * 添加查询结果到缓存
-     */
-    private addToCache;
-    /**
-     * 清理缓存
-     */
-    private cleanupCache;
-    /**
-     * 清除所有查询缓存
-     */
-    private clearQueryCache;
-    /**
-     * 清除所有响应式查询
-     *
-     * 销毁所有响应式查询实例并清理索引
-     * 通常在setEntities时调用以确保缓存一致性
-     */
-    private clearReactiveQueries;
-    /**
-     * 高效的缓存键生成
-     */
-    private generateCacheKey;
-    /**
-     * 清理查询缓存
-     *
-     * 用于外部调用清理缓存，通常在批量操作后使用。
-     * 注意:此方法也会清理响应式查询缓存
-     */
-    clearCache(): void;
-    /**
-     * 创建响应式查询
-     *
-     * 响应式查询会自动跟踪实体/组件的变化,并通过事件通知订阅者。
-     * 适合需要实时响应实体变化的场景(如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: ComponentType[], config?: ReactiveQueryConfig): ReactiveQuery;
-    /**
-     * 销毁响应式查询
-     *
-     * 清理查询占用的资源,包括监听器和实体引用。
-     * 销毁后的查询不应再被使用。
-     *
-     * @param query 要销毁的响应式查询
-     *
-     * @example
-     * ```typescript
-     * const query = querySystem.createReactiveQuery([Position, Velocity]);
-     * // ... 使用查询
-     * querySystem.destroyReactiveQuery(query);
-     * ```
-     */
-    destroyReactiveQuery(query: ReactiveQuery): void;
-    /**
-     * 创建组件掩码
-     *
-     * 根据组件类型列表生成对应的位掩码。
-     * 使用缓存避免重复计算。
-     * 注意:必须使用ComponentRegistry来确保与Entity.componentMask使用相同的bitIndex
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 生成的位掩码
-     */
-    private createComponentMask;
-    /**
-     * 获取当前版本号（用于缓存失效）
-     */
-    get version(): number;
-    /**
-     * 获取所有实体
-     */
-    getAllEntities(): readonly Entity[];
-    /**
-     * 获取系统统计信息
-     *
-     * 返回查询系统的详细统计信息，包括实体数量、索引状态、
-     * 查询性能统计等，用于性能监控和调试。
-     *
-     * @returns 系统统计信息对象
-     */
-    getStats(): {
-        entityCount: number;
-        indexStats: {
-            componentIndexSize: number;
-            tagIndexSize: number;
-            nameIndexSize: number;
-        };
-        queryStats: {
-            totalQueries: number;
-            cacheHits: number;
-            indexHits: number;
-            linearScans: number;
-            archetypeHits: number;
-            dirtyChecks: number;
-            cacheHitRate: string;
-        };
-        optimizationStats: {
-            archetypeSystem: any;
-        };
-        cacheStats: {
-            size: number;
-            hitRate: string;
-        };
-    };
-    /**
-     * 获取实体所属的原型信息
-     *
-     * @param entity 要查询的实体
-     */
-    getEntityArchetype(entity: Entity): Archetype | undefined;
-    /**
-     * 响应式查询集合(内部使用,作为智能缓存)
-     * 传统查询API(queryAll/queryAny/queryNone)内部自动使用响应式查询优化性能
-     */
-    private _reactiveQueries;
-    /**
-     * 按组件类型索引的响应式查询
-     * 用于快速定位哪些查询关心某个组件类型
-     */
-    private _reactiveQueriesByComponent;
-    /**
-     * 获取或创建内部响应式查询(作为智能缓存)
-     *
-     * @param queryType 查询类型
-     * @param componentTypes 组件类型列表
-     * @returns 响应式查询实例
-     */
-    private getOrCreateReactiveQuery;
-    /**
-     * 执行传统查询(内部使用,用于响应式查询初始化)
-     *
-     * @param queryType 查询类型
-     * @param componentTypes 组件类型列表
-     * @returns 匹配的实体列表
-     */
-    private executeTraditionalQuery;
-    /**
-     * 通知所有响应式查询实体已添加
-     *
-     * 使用组件类型索引,只通知关心该实体组件的查询
-     *
-     * @param entity 添加的实体
-     */
-    private notifyReactiveQueriesEntityAdded;
-    /**
-     * 通知响应式查询实体已移除
-     *
-     * 使用组件类型索引,只通知关心该实体组件的查询
-     *
-     * @param entity 移除的实体
-     * @param componentTypes 实体移除前的组件类型列表
-     */
-    private notifyReactiveQueriesEntityRemoved;
-    /**
-     * 通知响应式查询实体已移除(后备方案)
-     *
-     * 当实体已经清空组件时使用,通知所有查询
-     *
-     * @param entity 移除的实体
-     */
-    private notifyReactiveQueriesEntityRemovedFallback;
-    /**
-     * 通知响应式查询实体已变化
-     *
-     * 使用混合策略:
-     * 1. 首先通知关心实体当前组件的查询
-     * 2. 然后通知所有其他查询(包括那些可能因为组件移除而不再匹配的查询)
-     *
-     * @param entity 变化的实体
-     */
-    private notifyReactiveQueriesEntityChanged;
-}
-/**
- * 查询构建器
- *
- * 提供链式API来构建复杂的实体查询条件。
- * 支持组合多种查询条件，创建灵活的查询表达式。
- *
- * @example
- * ```typescript
- * const result = new QueryBuilder(querySystem)
- *     .withAll(PositionComponent, VelocityComponent)
- *     .without(DeadComponent)
- *     .execute();
- * ```
- */
-export declare class QueryBuilder {
-    private _logger;
-    private conditions;
-    private querySystem;
-    constructor(querySystem: QuerySystem);
-    /**
-     * 添加"必须包含所有组件"条件
-     *
-     * @param componentTypes 必须包含的组件类型
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withAll(...componentTypes: ComponentType[]): QueryBuilder;
-    /**
-     * 添加"必须包含任意组件"条件
-     *
-     * @param componentTypes 必须包含其中任意一个的组件类型
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withAny(...componentTypes: ComponentType[]): QueryBuilder;
-    /**
-     * 添加"不能包含任何组件"条件
-     *
-     * @param componentTypes 不能包含的组件类型
-     * @returns 查询构建器实例，支持链式调用
-     */
-    without(...componentTypes: ComponentType[]): QueryBuilder;
-    /**
-     * 执行查询并返回结果
-     *
-     * 根据已添加的查询条件执行实体查询。
-     *
-     * @returns 查询结果，包含匹配的实体和性能信息
-     */
-    execute(): QueryResult;
-    /**
-     * 创建组件掩码
-     */
-    private createComponentMask;
-    /**
-     * 重置查询构建器
-     *
-     * 清除所有已添加的查询条件，重新开始构建查询。
-     *
-     * @returns 查询构建器实例，支持链式调用
-     */
-    reset(): QueryBuilder;
-}
-//# sourceMappingURL=QuerySystem.d.ts.map

package/bin/ECS/Core/QuerySystem.d.ts.map

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