@esengine/ecs-framework 2.1.47 → 2.1.49

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.47
+ * @esengine/ecs-framework v2.1.49
  * TypeScript definitions
  */
 /**
@@ -557,7 +557,10 @@ interface IComponent {
     onEnabled(): void;
     /** 组件禁用时的回调 */
     onDisabled(): void;
-    /** 更新组件 */
+    /**
+     * 更新组件
+     * @deprecated 不符合ECS架构规范，建议使用EntitySystem来处理更新逻辑
+     */
     update(): void;
 }
 /**
@@ -1053,6 +1056,8 @@ declare abstract class Component implements IComponent {
      * 更新顺序
      *
      * 决定组件在更新循环中的执行顺序。
+     *
+     * @see EntitySystem
      */
     private _updateOrder;
     /**
@@ -1066,6 +1071,7 @@ declare abstract class Component implements IComponent {
      *
      * 组件的实际启用状态取决于自身状态和所属实体的状态。
      *
+     * @deprecated 不符合ECS架构规范，建议自己实现DisabledComponent标记组件替代
      * @returns 如果组件和所属实体都启用则返回true
      */
     get enabled(): boolean;
@@ -1074,18 +1080,23 @@ declare abstract class Component implements IComponent {
      *
      * 当状态改变时会触发相应的生命周期回调。
      *
+     * @deprecated 不符合ECS架构规范，建议自己实现DisabledComponent标记组件替代
      * @param value - 新的启用状态
      */
     set enabled(value: boolean);
     /**
      * 获取更新顺序
      *
+     * @deprecated 不符合ECS架构规范，更新顺序应该由EntitySystem管理
+     * @see EntitySystem
      * @returns 组件的更新顺序值
      */
     get updateOrder(): number;
     /**
      * 设置更新顺序
      *
+     * @deprecated 不符合ECS架构规范，更新顺序应该由EntitySystem管理
+     * @see EntitySystem
      * @param value - 新的更新顺序值
      */
     set updateOrder(value: number);
@@ -1116,8 +1127,7 @@ declare abstract class Component implements IComponent {
     /**
      * 更新组件
      *
-     * 每帧调用，用于更新组件的逻辑。
-     * 子类应该重写此方法来实现具体的更新逻辑。
+     * @deprecated 不符合ECS架构规范，建议使用EntitySystem来处理更新逻辑
      */
     update(): void;
 }
@@ -1483,6 +1493,7 @@ declare class LoggerManager {
     private static _instance;
     private _loggers;
     private _defaultLogger;
+    private _defaultLevel;
     private constructor();
     /**
      * 获取日志管理器实例
@@ -1827,14 +1838,16 @@ declare class EventBus implements IEventBus {
      * 发射事件
      * @param eventType 事件类型
      * @param data 事件数据
+     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
      */
-    emit<T>(eventType: string, data: T): void;
+    emit<T>(eventType: string, data: T, enhance?: boolean): void;
     /**
      * 异步发射事件
      * @param eventType 事件类型
      * @param data 事件数据
+     * @param enhance 是否增强事件数据（添加timestamp、eventId等），默认false提升性能
      */
-    emitAsync<T>(eventType: string, data: T): Promise<void>;
+    emitAsync<T>(eventType: string, data: T, enhance?: boolean): Promise<void>;
     /**
      * 监听事件
      * @param eventType 事件类型
@@ -1986,7 +1999,7 @@ declare class EventBus implements IEventBus {
      */
     onPerformanceWarning(handler: (data: IPerformanceEventData) => void, config?: IEventListenerConfig): string;
     /**
-     * 验证事件类型
+     * 验证事件类型（仅在debug模式下执行，提升性能）
      * @param eventType 事件类型
      */
     private validateEventType;
@@ -2042,8 +2055,13 @@ declare class EntityList {
     private _entitiesToAdd;
     private _entitiesToRemove;
     private _isUpdating;
+    private _enableEntityDirectUpdate;
     get count(): number;
     constructor(scene: any);
+    /**
+     * 设置是否启用实体直接更新
+     */
+    setEnableEntityDirectUpdate(enabled: boolean): void;
     /**
      * 添加实体（立即添加或延迟添加）
      * @param entity 要添加的实体
@@ -2073,7 +2091,7 @@ declare class EntityList {
      */
     updateLists(): void;
     /**
-     * 更新所有实体
+     * 更新实体列表和实体
      */
     update(): void;
     /**
@@ -2105,7 +2123,7 @@ declare class EntityList {
      * @param componentType 组件类型
      * @returns 找到的所有实体数组
      */
-    findEntitiesWithComponent<T extends Component>(componentType: new (...args: unknown[]) => T): Entity[];
+    findEntitiesWithComponent<T extends Component>(componentType: new (...args: any[]) => T): Entity[];
     /**
      * 批量操作：对所有实体执行指定操作
      * @param action 要执行的操作
@@ -2200,7 +2218,7 @@ declare class Matcher {
      */
     static complex(): Matcher;
     /**
-     * 创建空匙配器（向后兼容）
+     * 创建空匙配器
      */
     static empty(): Matcher;
     /**
@@ -2499,90 +2517,12 @@ interface Archetype {
     /** 最后更新时间 */
     updatedAt: number;
 }
-/**
- * 原型查询结果
- */
-interface ArchetypeQueryResult {
-    /** 匹配的原型列表 */
-    archetypes: Archetype[];
-    /** 所有匹配实体的总数 */
-    totalEntities: number;
-    /** 查询执行时间（毫秒） */
-    executionTime: number;
-    /** 是否使用了缓存 */
-    fromCache: boolean;
-}
-/**
- * Archetype系统
- *
- * 根据实体的组件组合将实体分组到不同的原型中，提供高效的查询性能。
- */
-declare class ArchetypeSystem {
-    /** 所有原型的映射表 */
-    private _archetypes;
-    /** 实体到原型的映射 */
-    private _entityToArchetype;
-    /** 组件类型到原型的映射 */
-    private _componentToArchetypes;
-    /** 查询缓存 */
-    private _queryCache;
-    private _cacheTimeout;
-    private _maxCacheSize;
-    /**
-     * 添加实体到原型系统
-     */
-    addEntity(entity: Entity): void;
-    /**
-     * 从原型系统中移除实体
-     */
-    removeEntity(entity: Entity): void;
-    /**
-     * 查询包含指定组件组合的原型
-     */
-    queryArchetypes(componentTypes: ComponentType[], operation?: 'AND' | 'OR'): ArchetypeQueryResult;
-    /**
-     * 获取实体所属的原型
-     */
-    getEntityArchetype(entity: Entity): Archetype | undefined;
-    /**
-     * 获取所有原型
-     */
-    getAllArchetypes(): Archetype[];
-    /**
-     * 清空所有数据
-     */
-    clear(): void;
-    /**
-     * 获取实体的组件类型列表
-     */
-    private getEntityComponentTypes;
-    /**
-     * 生成原型ID
-     */
-    private generateArchetypeId;
-    /**
-     * 创建新原型
-     */
-    private createArchetype;
-    /**
-     * 检查原型是否包含所有指定组件
-     */
-    private archetypeContainsAllComponents;
-    /**
-     * 更新组件索引
-     */
-    private updateComponentIndexes;
-    /**
-     * 使查询缓存失效
-     */
-    private invalidateQueryCache;
-}
 
 /**
  * 实体查询结果接口
  */
 interface QueryResult {
-    entities: Entity[];
+    entities: readonly Entity[];
     count: number;
     /** 查询执行时间（毫秒） */
     executionTime: number;
@@ -2614,15 +2554,15 @@ declare class QuerySystem {
     private _logger;
     private entities;
     private entityIndex;
-    private indexDirty;
     private _version;
     private queryCache;
     private cacheMaxSize;
     private cacheTimeout;
-    private componentPoolManager;
+    private componentNameCache;
+    private cacheKeyCache;
+    private componentMaskCache;
     private componentIndexManager;
     private archetypeSystem;
-    private dirtyTrackingSystem;
     private queryStats;
     constructor();
     /**
@@ -2671,9 +2611,13 @@ declare class QuerySystem {
      */
     removeEntity(entity: Entity): void;
     /**
-     * 将实体添加到各种索引中（优化版本）
+     * 将实体添加到各种索引中
      */
     private addEntityToIndexes;
+    private createAndSetMaskIndex;
+    private createAndSetComponentIndex;
+    private createAndSetTagIndex;
+    private createAndSetNameIndex;
     /**
      * 从各种索引中移除实体
      */
@@ -2811,37 +2755,20 @@ declare class QuerySystem {
      */
     private clearQueryCache;
     /**
-     * 公共方法：清理查询缓存
-     *
-     * 用于外部调用清理缓存，通常在批量操作后使用。
+     * 高效的缓存键生成
      */
-    clearCache(): void;
+    private generateCacheKey;
     /**
-     * 批量更新实体组件
-     *
-     * 对大量实体进行批量组件更新操作。
-     *
-     * @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;
+    clearCache(): void;
     /**
      * 创建组件掩码
      *
      * 根据组件类型列表生成对应的位掩码。
-     * 使用位掩码优化器进行缓存和预计算。
+     * 使用缓存避免重复计算。
      *
      * @param componentTypes 组件类型列表
      * @returns 生成的位掩码
@@ -2854,7 +2781,7 @@ declare class QuerySystem {
     /**
      * 获取所有实体
      */
-    getAllEntities(): Entity[];
+    getAllEntities(): readonly Entity[];
     /**
      * 获取系统统计信息
      *
@@ -2883,39 +2810,12 @@ declare class QuerySystem {
         optimizationStats: {
             componentIndex: any;
             archetypeSystem: any;
-            dirtyTracking: any;
         };
         cacheStats: {
             size: number;
             hitRate: string;
         };
     };
-    /**
-     * 配置脏标记系统
-     *
-     * @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;
     /**
      * 获取实体所属的原型信息
      *
@@ -3298,7 +3198,7 @@ declare class Scene implements IScene {
      */
     end(): void;
     /**
-     * 更新场景，更新实体组件、实体处理器等
+     * 更新场景
      */
     update(): void;
     /**
@@ -3306,6 +3206,11 @@ declare class Scene implements IScene {
      * @param name 实体名称
      */
     createEntity(name: string): Entity;
+    /**
+     * 清除所有EntitySystem的实体缓存
+     * 当实体或组件发生变化时调用
+     */
+    clearSystemEntityCaches(): void;
     /**
      * 在场景的实体列表中添加一个实体
      * @param entity 要添加的实体
@@ -3363,6 +3268,11 @@ declare class Scene implements IScene {
      * @param processor 要删除的处理器
      */
     removeEntityProcessor(processor: EntitySystem): void;
+    /**
+     * 从场景中删除系统（removeEntityProcessor的别名）
+     * @param system 系统
+     */
+    removeSystem(system: EntitySystem): void;
     /**
      * 获取指定类型的EntitySystem处理器
      * @param type 处理器类型
@@ -3412,7 +3322,7 @@ declare class Scene implements IScene {
  *         super(Transform, Velocity);
  *     }
  *
- *     protected process(entities: Entity[]): void {
+ *     protected process(entities: readonly Entity[]): void {
  *         for (const entity of entities) {
  *             const transform = entity.getComponent(Transform);
  *             const velocity = entity.getComponent(Velocity);
@@ -3429,9 +3339,20 @@ declare abstract class EntitySystem implements ISystemBase {
     private _systemName;
     private _initialized;
     private _matcher;
-    private _trackedEntities;
+    private _eventListeners;
+    private _scene;
+    /**
+     * 实体ID映射缓存
+     */
+    private _entityIdMap;
+    private _entityIdMapVersion;
+    private _entityIdMapSize;
+    /**
+     * 统一的实体缓存管理器
+     */
+    private _entityCache;
     /**
-     * 获取系统处理的实体列表（动态查询）
+     * 获取系统处理的实体列表
      */
     get entities(): readonly Entity[];
     /**
@@ -3452,7 +3373,6 @@ declare abstract class EntitySystem implements ISystemBase {
      */
     get systemName(): string;
     constructor(matcher?: Matcher);
-    private _scene;
     /**
      * 这个系统所属的场景
      */
@@ -3479,6 +3399,11 @@ declare abstract class EntitySystem implements ISystemBase {
      * 子类可以重写此方法进行初始化操作。
      */
     protected onInitialize(): void;
+    /**
+     * 清除实体缓存（内部使用）
+     * 当Scene中的实体发生变化时调用
+     */
+    clearEntityCache(): void;
     /**
      * 重置系统状态
      *
@@ -3507,20 +3432,22 @@ declare abstract class EntitySystem implements ISystemBase {
     private extractEntityIds;
     /**
      * ID集合交集运算
-     *
-     * 使用单次扫描算法，选择较小集合进行迭代以提高效率
      */
     private intersectIdSets;
     /**
      * ID集合差集运算
-     *
-     * 使用单次扫描算法计算setA - setB
      */
     private differenceIdSets;
+    /**
+     * 获取或构建实体ID映射
+     */
+    private getEntityIdMap;
+    /**
+     * 重建实体ID映射
+     */
+    private rebuildEntityIdMap;
     /**
      * 从ID集合构建Entity数组
-     *
-     * 先构建ID到Entity的映射，然后根据ID集合构建结果数组
      */
     private idSetToEntityArray;
     /**
@@ -3531,14 +3458,10 @@ declare abstract class EntitySystem implements ISystemBase {
     private executeComplexQuery;
     /**
      * 更新系统
-     *
-     * 在每帧调用，处理系统的主要逻辑。
      */
     update(): void;
     /**
      * 后期更新系统
-     *
-     * 在所有系统的update方法执行完毕后调用。
      */
     lateUpdate(): void;
     /**
@@ -3554,7 +3477,7 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entities 要处理的实体列表
      */
-    protected process(_entities: Entity[]): void;
+    protected process(entities: readonly Entity[]): void;
     /**
      * 后期处理实体列表
      *
@@ -3562,7 +3485,7 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entities 要处理的实体列表
      */
-    protected lateProcess(_entities: Entity[]): void;
+    protected lateProcess(_entities: readonly Entity[]): void;
     /**
      * 系统处理完毕后调用
      *
@@ -3611,7 +3534,7 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entity 被添加的实体
      */
-    protected onAdded(_entity: Entity): void;
+    protected onAdded(entity: Entity): void;
     /**
      * 当实体从系统中移除时调用
      *
@@ -3619,7 +3542,38 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entity 被移除的实体
      */
-    protected onRemoved(_entity: Entity): void;
+    protected onRemoved(entity: Entity): void;
+    /**
+     * 添加事件监听器
+     *
+     * 推荐使用此方法而不是直接调用eventSystem.on()，
+     * 这样可以确保系统移除时自动清理监听器，避免内存泄漏。
+     *
+     * @param eventType 事件类型
+     * @param handler 事件处理函数
+     * @param config 监听器配置
+     */
+    protected addEventListener<T = any>(eventType: string, handler: EventHandler<T>, config?: EventListenerConfig): void;
+    /**
+     * 移除特定的事件监听器
+     *
+     * @param eventType 事件类型
+     * @param handler 事件处理函数
+     */
+    protected removeEventListener<T = any>(eventType: string, handler: EventHandler<T>): void;
+    /**
+     * 清理所有事件监听器
+     *
+     * 系统移除时自动调用，清理所有通过addEventListener添加的监听器。
+     */
+    private cleanupEventListeners;
+    /**
+     * 系统销毁时的回调
+     *
+     * 当系统从场景中移除时调用，子类可以重写此方法进行清理操作。
+     * 注意：事件监听器会被框架自动清理，无需手动处理。
+     */
+    protected onDestroy(): void;
 }
 
 /**
@@ -3743,6 +3697,10 @@ interface IScene {
      * 创建实体
      */
     createEntity(name: string): Entity;
+    /**
+     * 清除所有EntitySystem的实体缓存
+     */
+    clearSystemEntityCaches(): void;
     /**
      * 添加实体
      */
@@ -3797,6 +3755,11 @@ interface ISceneConfig {
      * 调试配置
      */
     debug?: boolean;
+    /**
+     * 是否启用实体直接更新
+     * @default false
+     */
+    enableEntityDirectUpdate?: boolean;
 }
 
 /**
@@ -4486,11 +4449,11 @@ declare class ECSFluentAPI {
      */
     query(): QueryBuilder;
     /**
-     * 查找实体（简化版）
+     * 查找实体
      * @param componentTypes 组件类型
      * @returns 实体数组
      */
-    find(...componentTypes: ComponentType[]): Entity[];
+    find(...componentTypes: ComponentType[]): readonly Entity[];
     /**
      * 查找第一个匹配的实体
      * @param componentTypes 组件类型
@@ -5019,8 +4982,16 @@ declare class WorldManager {
  * 实体数据收集器
  */
 declare class EntityDataCollector {
-    collectEntityData(): IEntityDebugData;
-    getRawEntityList(): Array<{
+    /**
+     * 收集实体数据
+     * @param scene 场景实例
+     */
+    collectEntityData(scene?: IScene | null): IEntityDebugData;
+    /**
+     * 获取原始实体列表
+     * @param scene 场景实例
+     */
+    getRawEntityList(scene?: IScene | null): Array<{
         id: number;
         name: string;
         active: boolean;
@@ -5034,9 +5005,18 @@ declare class EntityDataCollector {
         tag: number;
         updateOrder: number;
     }>;
-    getEntityDetails(entityId: number): any;
+    /**
+     * 获取实体详细信息
+     * @param entityId 实体ID
+     * @param scene 场景实例
+     */
+    getEntityDetails(entityId: number, scene?: IScene | null): any;
     private getSceneInfo;
-    collectEntityDataWithMemory(): IEntityDebugData;
+    /**
+     * 收集实体数据（包含内存信息）
+     * @param scene 场景实例
+     */
+    collectEntityDataWithMemory(scene?: IScene | null): IEntityDebugData;
     private collectArchetypeData;
     private getArchetypeDistributionFast;
     private getTopEntitiesByComponentsFast;
@@ -5073,8 +5053,11 @@ declare class EntityDataCollector {
     }>;
     /**
      * 获取组件的完整属性信息（仅在需要时调用）
+     * @param entityId 实体ID
+     * @param componentIndex 组件索引
+     * @param scene 场景实例
      */
-    getComponentProperties(entityId: number, componentIndex: number): Record<string, any>;
+    getComponentProperties(entityId: number, componentIndex: number, scene?: IScene | null): Record<string, any>;
     /**
      * 格式化属性值
      */
@@ -5097,8 +5080,12 @@ declare class EntityDataCollector {
     private generateObjectId;
     /**
      * 展开懒加载对象（供调试面板调用）
+     * @param entityId 实体ID
+     * @param componentIndex 组件索引
+     * @param propertyPath 属性路径
+     * @param scene 场景实例
      */
-    expandLazyObject(entityId: number, componentIndex: number, propertyPath: string): any;
+    expandLazyObject(entityId: number, componentIndex: number, propertyPath: string, scene?: IScene | null): any;
     /**
      * 根据路径获取对象
      */
@@ -5111,8 +5098,10 @@ declare class EntityDataCollector {
 declare class SystemDataCollector {
     /**
      * 收集系统数据
+     * @param performanceMonitor 性能监视器实例
+     * @param scene 场景实例
      */
-    collectSystemData(performanceMonitor: any): ISystemDebugData;
+    collectSystemData(performanceMonitor: any, scene?: IScene | null): ISystemDebugData;
 }
 
 /**
@@ -5153,8 +5142,9 @@ declare class ComponentDataCollector {
     private static componentSizeCache;
     /**
      * 收集组件数据（轻量版，不计算实际内存大小）
+     * @param scene 场景实例
      */
-    collectComponentData(): IComponentDebugData;
+    collectComponentData(scene?: IScene | null): IComponentDebugData;
     /**
      * 获取组件类型的估算内存大小（基于预设值，不进行实际计算）
      */
@@ -5163,8 +5153,10 @@ declare class ComponentDataCollector {
     /**
      * 为内存快照功能提供的详细内存计算
      * 只在用户主动请求内存快照时调用
+     * @param typeName 组件类型名称
+     * @param scene 场景实例
      */
-    calculateDetailedComponentMemory(typeName: string): number;
+    calculateDetailedComponentMemory(typeName: string, scene?: IScene | null): number;
     /**
      * 估算对象内存大小（仅用于内存快照）
      * 优化版本：减少递归深度，提高性能
@@ -5180,8 +5172,9 @@ declare class SceneDataCollector {
     private sceneStartTime;
     /**
      * 收集场景数据
+     * @param scene 场景实例
      */
-    collectSceneData(): ISceneDebugData;
+    collectSceneData(scene?: IScene | null): ISceneDebugData;
     /**
      * 设置场景开始时间
      */
@@ -5260,11 +5253,18 @@ declare class DebugManager {
     private performanceCollector;
     private componentCollector;
     private sceneCollector;
+    private sceneProvider;
+    private performanceMonitorProvider;
     private frameCounter;
     private lastSendTime;
     private sendInterval;
     private isRunning;
-    constructor(core: Core, config: IECSDebugConfig);
+    /**
+     * 构造调试管理器
+     * @param core Core实例
+     * @param config 调试配置
+     */
+    constructor(core: any, config: IECSDebugConfig);
     /**
      * 启动调试管理器
      */
@@ -6454,669 +6454,6 @@ declare function getComponentInstanceTypeName(component: Component): string;
  */
 declare function getSystemInstanceTypeName(system: EntitySystem): string;
 
-/**
- * 实体查询构建器
- *
- * 提供流式API来构建复杂的实体查询条件。支持组件过滤、标签过滤、状态过滤和自定义条件。
- *
- * @example
- * ```typescript
- * const results = entityManager.query()
- *     .withAll(PositionComponent, HealthComponent)
- *     .without(VelocityComponent)
- *     .withTag(1)
- *     .active()
- *     .where(entity => entity.name.startsWith("Player"))
- *     .execute();
- * ```
- */
-declare class EntityQueryBuilder {
-    private entityManager;
-    /** 必须包含的组件类型 */
-    private _allComponents;
-    /** 至少包含一个的组件类型 */
-    private _anyComponents;
-    /** 不能包含的组件类型 */
-    private _withoutComponents;
-    /** 必须包含的标签 */
-    private _withTags;
-    /** 不能包含的标签 */
-    private _withoutTags;
-    /** 是否只查询激活状态的实体 */
-    private _activeOnly;
-    /** 是否只查询启用状态的实体 */
-    private _enabledOnly;
-    /** 自定义过滤条件 */
-    private _customPredicates;
-    /**
-     * 创建查询构建器实例
-     * @param entityManager 实体管理器实例
-     */
-    constructor(entityManager: EntityManager);
-    /**
-     * 添加必须包含的组件条件
-     *
-     * 返回的实体必须包含所有指定的组件类型。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withAll(...componentTypes: ComponentType[]): EntityQueryBuilder;
-    /**
-     * 添加至少包含一个的组件条件
-     *
-     * 返回的实体必须至少包含其中一个指定的组件类型。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withAny(...componentTypes: ComponentType[]): EntityQueryBuilder;
-    /**
-     * 添加不能包含的组件条件
-     *
-     * 返回的实体不能包含任何指定的组件类型。
-     *
-     * @param componentTypes 组件类型列表
-     * @returns 查询构建器实例，支持链式调用
-     */
-    without(...componentTypes: ComponentType[]): EntityQueryBuilder;
-    /**
-     * 添加必须包含的标签条件
-     *
-     * 返回的实体必须具有指定的标签。
-     *
-     * @param tag 标签值
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withTag(tag: number): EntityQueryBuilder;
-    /**
-     * 添加不能包含的标签条件
-     *
-     * 返回的实体不能具有指定的标签。
-     *
-     * @param tag 标签值
-     * @returns 查询构建器实例，支持链式调用
-     */
-    withoutTag(tag: number): EntityQueryBuilder;
-    /**
-     * 添加激活状态过滤条件
-     *
-     * 返回的实体必须处于激活状态（active = true）。
-     *
-     * @returns 查询构建器实例，支持链式调用
-     */
-    active(): EntityQueryBuilder;
-    /**
-     * 添加启用状态过滤条件
-     *
-     * 返回的实体必须处于启用状态（enabled = true）。
-     *
-     * @returns 查询构建器实例，支持链式调用
-     */
-    enabled(): EntityQueryBuilder;
-    /**
-     * 添加自定义过滤条件
-     *
-     * 允许用户定义复杂的过滤逻辑。
-     *
-     * @param predicate 自定义过滤函数，接收实体作为参数，返回布尔值
-     * @returns 查询构建器实例，支持链式调用
-     *
-     * @example
-     * ```typescript
-     * .where(entity => entity.name.startsWith("Player"))
-     * .where(entity => entity.components.length > 5)
-     * ```
-     */
-    where(predicate: (entity: Entity) => boolean): EntityQueryBuilder;
-    /**
-     * 执行查询并返回所有匹配的实体
-     *
-     * @returns 符合所有查询条件的实体数组
-     */
-    execute(): Entity[];
-    /**
-     * 执行查询并返回第一个匹配的实体
-     *
-     * @returns 第一个符合查询条件的实体，如果没有找到则返回null
-     */
-    first(): Entity | null;
-    /**
-     * 执行查询并返回匹配实体的数量
-     *
-     * @returns 符合查询条件的实体数量
-     */
-    count(): number;
-    /**
-     * 对所有匹配的实体执行指定操作
-     *
-     * @param action 要执行的操作函数，接收匹配的实体作为参数
-     */
-    forEach(action: (entity: Entity) => void): void;
-    /**
-     * 检查实体是否匹配所有查询条件
-     *
-     * 按优先级顺序检查各种过滤条件，一旦发现不匹配立即返回false。
-     *
-     * @param entity 要检查的实体
-     * @returns 实体是否匹配所有查询条件
-     */
-    private matchesEntity;
-}
-/**
- * 实体管理器
- *
- * 提供统一的实体管理和查询机制，支持高效的实体操作。
- * 包括实体的创建、销毁、查询和索引管理功能。
- *
- * @example
- * ```typescript
- * const entityManager = new EntityManager();
- *
- * // 创建实体
- * const player = entityManager.createEntity("Player");
- *
- * // 查询实体
- * const playerEntity = entityManager.getEntityByName("Player");
- *
- * // 复杂查询
- * const results = entityManager.query()
- *     .withAll(HealthComponent, PositionComponent)
- *     .active()
- *     .execute();
- * ```
- */
-declare class EntityManager {
-    /** 主要实体存储，使用ID作为键 */
-    private _entities;
-    /** 按名称索引的实体映射 */
-    private _entitiesByName;
-    /** 按标签索引的实体映射 */
-    private _entitiesByTag;
-    /** 实体ID分配器 */
-    private _identifierPool;
-    /** 已销毁实体的ID集合 */
-    private _destroyedEntities;
-    /** 性能优化系统 */
-    private _componentIndexManager;
-    private _archetypeSystem;
-    private _dirtyTrackingSystem;
-    /** 事件总线 */
-    private _eventBus;
-    /**
-     * 创建实体管理器实例
-     *
-     * 初始化内部数据结构和ID分配器。
-     */
-    constructor();
-    /**
-     * 获取实体总数
-     *
-     * @returns 当前管理的实体总数量
-     */
-    get entityCount(): number;
-    /**
-     * 获取激活状态的实体数量
-     *
-     * 只计算同时满足激活状态且未被销毁的实体。
-     *
-     * @returns 激活状态的实体数量
-     */
-    get activeEntityCount(): number;
-    /**
-     * 创建新实体
-     *
-     * 分配唯一ID并将实体添加到管理系统中，同时更新相关索引。
-     *
-     * @param name 实体名称，如果未指定则使用时间戳生成默认名称
-     * @returns 创建的实体实例
-     *
-     * @example
-     * ```typescript
-     * const player = entityManager.createEntity("Player");
-     * const enemy = entityManager.createEntity(); // 使用默认名称
-     * ```
-     */
-    createEntity(name?: string): Entity;
-    /**
-     * 批量创建实体
-     *
-     * 为了优化大量实体创建的性能，批量处理索引更新和事件发射。
-     * 适用于需要创建大量实体的场景，如子弹、粒子等。
-     *
-     * @param count 要创建的实体数量
-     * @param namePrefix 实体名称前缀，默认为 Entity
-     * @param skipEvents 是否跳过事件发射以提升性能，默认为 false
-     * @returns 创建的实体数组
-     *
-     * @example
-     * const bullets = entityManager.createEntitiesBatch(100, "Bullet", true);
-     * const particles = entityManager.createEntitiesBatch(500, "Particle");
-     */
-    createEntitiesBatch(count: number, namePrefix?: string, skipEvents?: boolean): Entity[];
-    /**
-     * 销毁实体
-     *
-     * 支持通过实体对象、名称或ID来销毁实体。
-     * 会清理所有相关索引并回收ID。
-     *
-     * @param entityOrId 要销毁的实体，可以是实体对象、名称字符串或ID数字
-     * @returns 是否成功销毁实体
-     *
-     * @example
-     * ```typescript
-     * // 通过实体对象销毁
-     * entityManager.destroyEntity(player);
-     *
-     * // 通过名称销毁
-     * entityManager.destroyEntity("Enemy_1");
-     *
-     * // 通过ID销毁
-     * entityManager.destroyEntity(123);
-     * ```
-     */
-    destroyEntity(entityOrId: Entity | string | number): boolean;
-    /**
-     * 获取所有实体
-     *
-     * 返回当前管理的所有实体的副本数组。
-     *
-     * @returns 所有实体的数组
-     */
-    getAllEntities(): Entity[];
-    /**
-     * 根据ID获取实体
-     *
-     * 支持字符串和数字类型的ID。
-     *
-     * @param id 实体ID，可以是字符串或数字
-     * @returns 对应的实体，如果不存在则返回null
-     */
-    getEntity(id: string | number): Entity | null;
-    /**
-     * 根据名称获取实体
-     *
-     * 如果存在多个同名实体，返回第一个找到的实体。
-     *
-     * @param name 实体名称
-     * @returns 匹配的实体，如果不存在则返回null
-     */
-    getEntityByName(name: string): Entity | null;
-    /**
-     * 根据标签获取实体列表
-     *
-     * 返回所有具有指定标签的实体。
-     *
-     * @param tag 标签值
-     * @returns 具有指定标签的实体数组
-     */
-    getEntitiesByTag(tag: number): Entity[];
-    /**
-     * 获取包含指定组件的所有实体
-     *
-     * 遍历所有实体，查找包含指定组件类型的实体。
-     *
-     * @param componentType 组件类型
-     * @returns 包含指定组件的实体数组
-     *
-     * @example
-     * ```typescript
-     * const entitiesWithHealth = entityManager.getEntitiesWithComponent(HealthComponent);
-     * ```
-     */
-    getEntitiesWithComponent<T extends Component>(componentType: ComponentType<T>): Entity[];
-    /**
-     * 创建查询构建器
-     *
-     * 返回一个新的查询构建器实例，用于构建复杂的实体查询。
-     *
-     * @returns 新的查询构建器实例
-     *
-     * @example
-     * ```typescript
-     * const results = entityManager.query()
-     *     .withAll(PositionComponent, HealthComponent)
-     *     .without(VelocityComponent)
-     *     .active()
-     *     .execute();
-     * ```
-     */
-    query(): EntityQueryBuilder;
-    /**
-     * 使用组件索引进行多组件查询
-     *
-     * @param componentTypes 组件类型数组
-     * @param operation 查询操作：'AND' 或 'OR'
-     * @returns 匹配的实体集合
-     */
-    queryWithComponentIndex(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    /**
-     * 标记实体组件已修改
-     *
-     * @param entity 修改的实体
-     * @param componentTypes 修改的组件类型
-     */
-    markEntityDirty(entity: Entity, componentTypes: ComponentType[]): void;
-    /**
-     * 获取性能优化统计信息
-     */
-    getOptimizationStats(): any;
-    /**
-     * 获取事件总线实例
-     *
-     * 允许外部代码监听和发射ECS相关事件。
-     *
-     * @returns 事件总线实例
-     */
-    get eventBus(): EventBus;
-    /**
-     * 更新名称索引
-     *
-     * 维护按名称查找实体的索引结构。支持添加和移除操作。
-     *
-     * @param entity 要更新索引的实体
-     * @param isAdd true表示添加到索引，false表示从索引中移除
-     */
-    private updateNameIndex;
-    /**
-     * 更新标签索引
-     *
-     * 维护按标签查找实体的索引结构。支持添加和移除操作。
-     *
-     * @param entity 要更新索引的实体
-     * @param isAdd true表示添加到索引，false表示从索引中移除
-     */
-    private updateTagIndex;
-}
-
-/**
- * 索引统计信息
- */
-interface IndexStats {
-    /** 索引大小 */
-    size: number;
-    /** 内存使用量（字节） */
-    memoryUsage: number;
-    /** 查询次数 */
-    queryCount: number;
-    /** 平均查询时间（毫秒） */
-    avgQueryTime: number;
-    /** 最后更新时间 */
-    lastUpdated: number;
-}
-/**
- * 组件索引接口
- */
-interface IComponentIndex {
-    /** 添加实体到索引 */
-    addEntity(entity: Entity): void;
-    /** 从索引中移除实体 */
-    removeEntity(entity: Entity): void;
-    /** 查询包含指定组件的实体 */
-    query(componentType: ComponentType): Set<Entity>;
-    /** 批量查询多个组件 */
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    /** 清空索引 */
-    clear(): void;
-    /** 获取索引统计信息 */
-    getStats(): IndexStats;
-}
-/**
- * 通用组件索引实现
- *
- * 基于Sparse Set算法：
- * - O(1)的实体添加、删除、查找
- * - 高效的位运算查询
- * - 内存紧凑的存储结构
- * - 缓存友好的遍历性能
- */
-declare class ComponentIndex implements IComponentIndex {
-    /**
-     * 组件稀疏集合
-     *
-     * 核心存储结构，处理所有实体和组件的索引操作。
-     */
-    private _sparseSet;
-    private _queryCount;
-    private _totalQueryTime;
-    private _lastUpdated;
-    constructor();
-    addEntity(entity: Entity): void;
-    removeEntity(entity: Entity): void;
-    query(componentType: ComponentType): Set<Entity>;
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    clear(): void;
-    getStats(): IndexStats;
-}
-/**
- * 组件索引管理器
- *
- * 使用统一的组件索引实现，自动优化查询性能。
- */
-declare class ComponentIndexManager {
-    private _index;
-    constructor();
-    /**
-     * 添加实体到索引
-     */
-    addEntity(entity: Entity): void;
-    /**
-     * 从索引中移除实体
-     */
-    removeEntity(entity: Entity): void;
-    /**
-     * 查询包含指定组件的实体
-     */
-    query(componentType: ComponentType): Set<Entity>;
-    /**
-     * 批量查询多个组件
-     */
-    queryMultiple(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
-    /**
-     * 获取索引统计信息
-     */
-    getStats(): IndexStats;
-    /**
-     * 清空索引
-     */
-    clear(): void;
-}
-
-/**
- * 脏标记类型
- */
-declare enum DirtyFlag {
-    /** 组件数据已修改 */
-    COMPONENT_MODIFIED = 1,
-    /** 组件已添加 */
-    COMPONENT_ADDED = 2,
-    /** 组件已移除 */
-    COMPONENT_REMOVED = 4,
-    /** 实体位置已改变 */
-    TRANSFORM_CHANGED = 8,
-    /** 实体状态已改变 */
-    STATE_CHANGED = 16,
-    /** 自定义标记1 */
-    CUSTOM_1 = 256,
-    /** 自定义标记2 */
-    CUSTOM_2 = 512,
-    /** 自定义标记3 */
-    CUSTOM_3 = 1024,
-    /** 所有标记 */
-    ALL = 4294967295
-}
-/**
- * 脏标记数据
- */
-interface DirtyData {
-    /** 实体引用 */
-    entity: Entity;
-    /** 脏标记位 */
-    flags: number;
-    /** 修改的组件类型列表 */
-    modifiedComponents: Set<ComponentType>;
-    /** 标记时间戳 */
-    timestamp: number;
-    /** 帧编号 */
-    frameNumber: number;
-}
-/**
- * 脏标记监听器
- */
-interface DirtyListener {
-    /** 感兴趣的标记类型 */
-    flags: number;
-    /** 回调函数 */
-    callback: (dirtyData: DirtyData) => void;
-    /** 监听器优先级（数字越小优先级越高） */
-    priority?: number;
-}
-/**
- * 脏标记统计信息
- */
-interface DirtyStats {
-    /** 当前脏实体数量 */
-    dirtyEntityCount: number;
-    /** 总标记次数 */
-    totalMarkings: number;
-    /** 总清理次数 */
-    totalCleanups: number;
-    /** 监听器数量 */
-    listenerCount: number;
-    /** 平均每帧脏实体数量 */
-    avgDirtyPerFrame: number;
-    /** 内存使用量估算 */
-    estimatedMemoryUsage: number;
-}
-/**
- * 脏标记追踪系统
- *
- * 提供高效的组件和实体变更追踪，避免不必要的计算和更新。
- * 支持细粒度的脏标记和批量处理机制。
- *
- * @example
- * ```typescript
- * const dirtySystem = new DirtyTrackingSystem();
- *
- * // 标记实体的位置组件已修改
- * dirtySystem.markDirty(entity, DirtyFlag.TRANSFORM_CHANGED, [PositionComponent]);
- *
- * // 监听位置变化
- * dirtySystem.addListener({
- *     flags: DirtyFlag.TRANSFORM_CHANGED,
- *     callback: (data) => {
- *         logger.debug('Entity position changed:', data.entity.name);
- *     }
- * });
- *
- * // 处理所有脏标记
- * dirtySystem.processDirtyEntities();
- * ```
- */
-declare class DirtyTrackingSystem {
-    private static readonly _logger;
-    /** 脏实体映射表 */
-    private _dirtyEntities;
-    /** 脏标记监听器 */
-    private _listeners;
-    /** 性能统计 */
-    private _stats;
-    /** 当前帧编号 */
-    private _currentFrame;
-    private _batchSize;
-    private _maxProcessingTime;
-    /** 延迟处理队列 */
-    private _processingQueue;
-    private _isProcessing;
-    /**
-     * 标记实体为脏状态
-     *
-     * @param entity 要标记的实体
-     * @param flags 脏标记位
-     * @param modifiedComponents 修改的组件类型列表
-     */
-    markDirty(entity: Entity, flags: DirtyFlag, modifiedComponents?: ComponentType[]): void;
-    /**
-     * 检查实体是否有指定的脏标记
-     *
-     * @param entity 要检查的实体
-     * @param flags 要检查的标记位
-     * @returns 是否有指定的脏标记
-     */
-    isDirty(entity: Entity, flags?: DirtyFlag): boolean;
-    /**
-     * 清除实体的脏标记
-     *
-     * @param entity 要清除的实体
-     * @param flags 要清除的标记位，默认清除所有
-     */
-    clearDirty(entity: Entity, flags?: DirtyFlag): void;
-    /**
-     * 获取所有脏实体
-     *
-     * @param flags 过滤标记位，只返回包含指定标记的实体
-     * @returns 脏实体数据数组
-     */
-    getDirtyEntities(flags?: DirtyFlag): DirtyData[];
-    /**
-     * 批量处理脏实体
-     *
-     * 使用时间分片的方式处理脏实体，避免单帧卡顿
-     */
-    processDirtyEntities(): void;
-    /**
-     * 添加脏标记监听器
-     *
-     * @param listener 监听器配置
-     */
-    addListener(listener: DirtyListener): void;
-    /**
-     * 移除脏标记监听器
-     *
-     * @param callback 要移除的回调函数
-     */
-    removeListener(callback: (dirtyData: DirtyData) => void): void;
-    /**
-     * 开始新的帧
-     */
-    beginFrame(): void;
-    /**
-     * 结束当前帧
-     */
-    endFrame(): void;
-    /**
-     * 获取统计信息
-     */
-    getStats(): DirtyStats;
-    /**
-     * 清空所有脏标记和统计信息
-     */
-    clear(): void;
-    /**
-     * 配置批量处理参数
-     *
-     * @param batchSize 每次处理的最大实体数量
-     * @param maxProcessingTime 每帧最大处理时间（毫秒）
-     */
-    configureBatchProcessing(batchSize: number, maxProcessingTime: number): void;
-    /**
-     * 处理单个脏实体
-     */
-    private processEntity;
-    /**
-     * 通知监听器
-     */
-    private notifyListeners;
-    /**
-     * 帧结束时的统计更新
-     */
-    private onFrameEnd;
-    /**
-     * 估算内存使用量
-     */
-    private estimateMemoryUsage;
-}
-
 /**
  * 组件对象池，用于复用组件实例以减少内存分配
  */
@@ -7277,5 +6614,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, Colors, Component, ComponentDataCollector, ComponentIndex, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, World, WorldManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, resetLoggerColors, setGlobalLogLevel, setLoggerColors };
-export type { Archetype, ArchetypeQueryResult, BitMask64Data, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, IComponentIndex, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IWorldConfig, IWorldManagerConfig, IndexStats, LoggerColorConfig, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+export { AsyncEventHandler$1 as AsyncEventHandler, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, Colors, Component, ComponentDataCollector, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentSparseSet, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, ECSComponent, ECSEventType, ECSFluentAPI, ECSSystem, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityProcessorList, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HighPrecision, IdentifierPool, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, SYSTEM_TYPE_NAME, Scene, SceneDataCollector, SerializeMap, SoAStorage, SparseSet, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, World, WorldManager, createECSAPI, createLogger, getComponentInstanceTypeName, getComponentTypeName, getSystemInstanceTypeName, getSystemTypeName, resetLoggerColors, setGlobalLogLevel, setLoggerColors };
+export type { BitMask64Data, ComponentType$1 as ComponentType, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, IWorldConfig, IWorldManagerConfig, LoggerColorConfig, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };