@esengine/ecs-framework 2.2.21 → 2.3.0

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

@@ -0,0 +1,458 @@
+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

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