@esengine/ecs-framework 2.1.28 → 2.1.30

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

@@ -0,0 +1,438 @@
+import { Entity } from '../Entity';
+import { Component } from '../Component';
+import { ComponentType } from './ComponentStorage';
+import { IBigIntLike } from '../Utils/BigIntCompatibility';
+import { IndexType } from './ComponentIndex';
+import { Archetype } from './ArchetypeSystem';
+/**
+ * 查询条件类型
+ */
+export declare enum QueryConditionType {
+    /** 必须包含所有指定组件 */
+    ALL = "all",
+    /** 必须包含任意一个指定组件 */
+    ANY = "any",
+    /** 不能包含任何指定组件 */
+    NONE = "none"
+}
+/**
+ * 查询条件接口
+ */
+export interface QueryCondition {
+    type: QueryConditionType;
+    componentTypes: ComponentType[];
+    mask: IBigIntLike;
+}
+/**
+ * 实体查询结果接口
+ */
+export interface QueryResult {
+    entities: Entity[];
+    count: number;
+    /** 查询执行时间（毫秒） */
+    executionTime: number;
+    /** 是否来自缓存 */
+    fromCache: boolean;
+}
+/**
+ * 高性能实体查询系统
+ *
+ * 提供快速的实体查询功能，支持按组件类型、标签、名称等多种方式查询实体。
+ * 系统采用多级索引和智能缓存机制，确保在大量实体场景下的查询性能。
+ *
+ * 主要特性：
+ * - 支持单组件和多组件查询
+ * - 自动索引管理和缓存优化
+ * - WebAssembly计算加速（如果可用）
+ * - 详细的性能统计信息
+ *
+ * @example
+ * ```typescript
+ * // 查询所有包含Position和Velocity组件的实体
+ * const movingEntities = querySystem.queryAll(PositionComponent, VelocityComponent);
+ *
+ * // 查询特定标签的实体
+ * const playerEntities = querySystem.queryByTag(PLAYER_TAG);
+ * ```
+ */
+export declare class QuerySystem {
+    private _logger;
+    private entities;
+    private entityIndex;
+    private indexDirty;
+    private _version;
+    private queryCache;
+    private cacheMaxSize;
+    private cacheTimeout;
+    private componentPoolManager;
+    private componentIndexManager;
+    private archetypeSystem;
+    private dirtyTrackingSystem;
+    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;
+    /**
+     * 将实体添加到各种索引中（优化版本）
+     */
+    private addEntityToIndexes;
+    /**
+     * 从各种索引中移除实体
+     */
+    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 匹配的实体列表
+     */
+    private queryMultipleComponents;
+    /**
+     * 查询包含任意指定组件的实体
+     *
+     * 返回包含任意一个指定组件类型的实体列表。
+     * 使用集合合并算法确保高效的查询性能。
+     *
+     * @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;
+    /**
+     * 公共方法：清理查询缓存
+     *
+     * 用于外部调用清理缓存，通常在批量操作后使用。
+     */
+    clearCache(): void;
+    /**
+     * 批量更新实体组件
+     *
+     * 对大量实体进行批量组件更新操作。
+     *
+     * @param updates 更新操作列表，包含实体ID和新的组件掩码
+     *
+     * @example
+     * ```typescript
+     * // 批量更新实体的组件配置
+     * const updates = [
+     *     { entityId: 1, componentMask: BigInt(0b1011) },
+     *     { entityId: 2, componentMask: BigInt(0b1101) }
+     * ];
+     * querySystem.batchUpdateComponents(updates);
+     * ```
+     */
+    batchUpdateComponents(updates: Array<{
+        entityId: number;
+        componentMask: bigint;
+    }>): void;
+    /**
+     * 创建组件掩码
+     *
+     * 根据组件类型列表生成对应的位掩码。
+     * 使用位掩码优化器进行缓存和预计算。
+     *
+     * @param componentTypes 组件类型列表
+     * @returns 生成的位掩码
+     */
+    private createComponentMask;
+    /**
+     * 获取当前版本号（用于缓存失效）
+     */
+    get version(): number;
+    /**
+     * 获取所有实体
+     */
+    getAllEntities(): Entity[];
+    /**
+     * 获取系统统计信息
+     *
+     * 返回查询系统的详细统计信息，包括实体数量、索引状态、
+     * 查询性能统计等，用于性能监控和调试。
+     *
+     * @returns 系统统计信息对象
+     */
+    getStats(): {
+        entityCount: number;
+        indexStats: {
+            maskIndexSize: number;
+            componentIndexSize: number;
+            tagIndexSize: number;
+            nameIndexSize: number;
+        };
+        queryStats: {
+            totalQueries: number;
+            cacheHits: number;
+            indexHits: number;
+            linearScans: number;
+            archetypeHits: number;
+            dirtyChecks: number;
+            cacheHitRate: string;
+        };
+        optimizationStats: {
+            componentIndex: any;
+            archetypeSystem: any;
+            dirtyTracking: any;
+        };
+        cacheStats: {
+            size: number;
+            hitRate: string;
+        };
+    };
+    /**
+     * 切换组件索引类型
+     *
+     * @param indexType 新的索引类型
+     */
+    switchComponentIndexType(indexType: IndexType): void;
+    /**
+     * 配置脏标记系统
+     *
+     * @param batchSize 批处理大小
+     * @param maxProcessingTime 最大处理时间
+     */
+    configureDirtyTracking(batchSize: number, maxProcessingTime: number): void;
+    /**
+     * 手动触发性能优化
+     */
+    optimizePerformance(): void;
+    /**
+     * 开始新的帧
+     */
+    beginFrame(): void;
+    /**
+     * 结束当前帧
+     */
+    endFrame(): void;
+    /**
+     * 标记实体组件已修改（用于脏标记追踪）
+     *
+     * @param entity 修改的实体
+     * @param componentTypes 修改的组件类型
+     */
+    markEntityDirty(entity: Entity, componentTypes: ComponentType[]): void;
+    /**
+     * 获取实体所属的原型信息
+     *
+     * @param entity 要查询的实体
+     */
+    getEntityArchetype(entity: Entity): Archetype | undefined;
+}
+/**
+ * 查询构建器
+ *
+ * 提供链式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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"}