@esengine/ecs-framework 2.1.29 → 2.1.31

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.29
+ * @esengine/ecs-framework v2.1.31
  * TypeScript definitions
  */
 /**
@@ -334,6 +334,7 @@ interface PoolStats {
     /** 内存使用估算（字节） */
     estimatedMemoryUsage: number;
 }
+
 /**
  * 高性能通用对象池
  * 支持任意类型的对象池化，包含详细的统计信息
@@ -366,145 +367,82 @@ declare class Pool<T extends IPoolable> {
      */
     obtain(): T;
     /**
-     * 将对象归还到池中
-     * @param obj 要归还的对象
+     * 释放对象回池中
+     * @param obj 要释放的对象
      */
-    free(obj: T): void;
+    release(obj: T): void;
     /**
-     * 预热池，创建指定数量的对象
-     * @param count 要创建的对象数量
+     * 获取池统计信息
+     * @returns 统计信息对象
      */
-    warmUp(count: number): void;
+    getStats(): Readonly<PoolStats>;
     /**
      * 清空池
      */
     clear(): void;
     /**
-     * 获取池中对象数量
-     */
-    get size(): number;
-    /**
-     * 获取池的最大大小
-     */
-    get maxSize(): number;
-    /**
-     * 设置池的最大大小
+     * 压缩池（移除多余的对象）
+     * @param targetSize 目标大小，默认为当前大小的一半
      */
-    set maxSize(value: number);
+    compact(targetSize?: number): void;
     /**
-     * 获取池的统计信息
+     * 预填充池
+     * @param count 预填充的对象数量
      */
-    getStats(): PoolStats;
+    prewarm(count: number): void;
     /**
-     * 重置统计信息
+     * 设置最大池大小
+     * @param maxSize 新的最大大小
      */
-    resetStats(): void;
+    setMaxSize(maxSize: number): void;
     /**
-     * 更新命中率
+     * 获取池中可用对象数量
+     * @returns 可用对象数量
      */
-    private _updateHitRate;
+    getAvailableCount(): number;
     /**
-     * 更新内存使用估算
+     * 检查池是否为空
+     * @returns 如果池为空返回true
      */
-    private _updateMemoryUsage;
+    isEmpty(): boolean;
     /**
-     * 静态方法：从指定类型的池中获取对象
-     * @param type 对象类型
-     * @returns 对象实例
+     * 检查池是否已满
+     * @returns 如果池已满返回true
      */
-    static obtain<T extends IPoolable>(type: new (...args: unknown[]) => T): T;
+    isFull(): boolean;
     /**
-     * 静态方法：将对象归还到对应类型的池中
-     * @param type 对象类型
-     * @param obj 要归还的对象
+     * 获取所有已注册的池类型
+     * @returns 所有池类型的数组
      */
-    static free<T extends IPoolable>(type: new (...args: unknown[]) => T, obj: T): void;
+    static getAllPoolTypes(): Function[];
     /**
-     * 静态方法：预热指定类型的池
-     * @param type 对象类型
-     * @param count 要创建的对象数量
+     * 获取所有池的统计信息
+     * @returns 包含所有池统计信息的对象
      */
-    static warmUp<T extends IPoolable>(type: new (...args: unknown[]) => T, count: number): void;
+    static getAllPoolStats(): Record<string, PoolStats>;
     /**
-     * 静态方法：清空指定类型的池
-     * @param type 对象类型
+     * 压缩所有池
      */
-    static clearPool<T extends IPoolable>(type: new (...args: unknown[]) => T): void;
+    static compactAllPools(): void;
     /**
-     * 静态方法：清空所有池
+     * 清空所有池
      */
     static clearAllPools(): void;
     /**
-     * 静态方法：获取池的统计信息
-     * @returns 池的统计信息
-     */
-    static getStats(): {
-        [typeName: string]: PoolStats;
-    };
-    /**
-     * 静态方法：获取所有池的总内存使用量
-     * @returns 总内存使用量（字节）
-     */
-    static getTotalMemoryUsage(): number;
-    /**
-     * 静态方法：获取性能报告
-     * @returns 格式化的性能报告
-     */
-    static getPerformanceReport(): string;
-}
-/**
- * 分层对象池
- * 使用多个不同大小的池来优化内存使用
- */
-declare class TieredObjectPool<T extends IPoolable> {
-    private pools;
-    private createFn;
-    private resetFn;
-    private tierSizes;
-    private totalObtained;
-    private totalReleased;
-    /**
-     * 构造函数
-     * @param createFn 创建对象的函数
-     * @param resetFn 重置对象的函数
-     * @param tierSizes 各层级的大小，默认[10, 50, 200]
-     * @param estimatedObjectSize 估算的单个对象大小
-     */
-    constructor(createFn: () => T, resetFn: (obj: T) => void, tierSizes?: number[], estimatedObjectSize?: number);
-    /**
-     * 获取对象
-     * @returns 对象实例
-     */
-    obtain(): T;
-    /**
-     * 释放对象
-     * @param obj 要释放的对象
-     */
-    release(obj: T): void;
-    /**
-     * 预热所有池
-     * @param totalCount 总预热数量
-     */
-    warmUp(totalCount: number): void;
-    /**
-     * 清空所有池
+     * 获取全局池统计信息的格式化字符串
+     * @returns 格式化的统计信息字符串
      */
-    clear(): void;
+    static getGlobalStatsString(): string;
     /**
-     * 获取统计信息
+     * 更新命中率
      */
-    getStats(): {
-        totalSize: number;
-        totalMaxSize: number;
-        totalMemoryUsage: number;
-        tierStats: PoolStats[];
-        hitRate: number;
-    };
+    private _updateHitRate;
     /**
-     * 获取总创建数量
+     * 更新内存使用估算
      */
-    private getTotalCreated;
+    private _updateMemoryUsage;
 }
+
 /**
  * 池管理器
  * 统一管理所有对象池
@@ -520,29 +458,78 @@ declare class PoolManager {
      * @param name 池名称
      * @param pool 池实例
      */
-    registerPool<T extends IPoolable>(name: string, pool: Pool<T> | TieredObjectPool<T>): void;
+    registerPool<T extends IPoolable>(name: string, pool: Pool<T>): void;
     /**
      * 获取池
      * @param name 池名称
      * @returns 池实例
      */
-    getPool<T extends IPoolable>(name: string): Pool<T> | TieredObjectPool<T> | null;
+    getPool<T extends IPoolable>(name: string): Pool<T> | null;
     /**
      * 更新池管理器（应在游戏循环中调用）
      */
     update(): void;
     /**
-     * 压缩所有池（清理碎片）
+     * 创建或获取标准池
+     * @param name 池名称
+     * @param createFn 创建函数
+     * @param maxSize 最大大小
+     * @param estimatedObjectSize 估算对象大小
+     * @returns 池实例
+     */
+    createPool<T extends IPoolable>(name: string, createFn: () => T, maxSize?: number, estimatedObjectSize?: number): Pool<T>;
+    /**
+     * 移除池
+     * @param name 池名称
+     * @returns 是否成功移除
+     */
+    removePool(name: string): boolean;
+    /**
+     * 获取所有池名称
+     * @returns 池名称数组
+     */
+    getPoolNames(): string[];
+    /**
+     * 获取池数量
+     * @returns 池数量
+     */
+    getPoolCount(): number;
+    /**
+     * 压缩所有池
      */
     compactAllPools(): void;
+    /**
+     * 清空所有池
+     */
+    clearAllPools(): void;
     /**
      * 获取所有池的统计信息
+     * @returns 统计信息映射
      */
-    getAllStats(): Map<string, any>;
+    getAllStats(): Map<string, PoolStats>;
+    /**
+     * 获取总体统计信息
+     * @returns 总体统计信息
+     */
+    getGlobalStats(): PoolStats;
+    /**
+     * 获取格式化的统计信息字符串
+     * @returns 格式化字符串
+     */
+    getStatsString(): string;
+    /**
+     * 设置自动压缩间隔
+     * @param intervalMs 间隔毫秒数
+     */
+    setAutoCompactInterval(intervalMs: number): void;
+    /**
+     * 预填充所有池
+     */
+    prewarmAllPools(): void;
     /**
-     * 生成性能报告
+     * 重置池管理器
      */
-    generateReport(): string;
+    reset(): void;
 }
 
 /**
@@ -1294,6 +1281,7 @@ interface EventBatchConfig {
  * 支持同步/异步事件、优先级、批处理等功能
  */
 declare class TypeSafeEventSystem {
+    private static readonly _logger;
     private listeners;
     private stats;
     private batchQueue;
@@ -1460,6 +1448,162 @@ declare class TypeSafeEventSystem {
     private createEmptyStats;
 }
 
+/**
+ * 日志级别
+ */
+declare enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3,
+    Fatal = 4,
+    None = 5
+}
+/**
+ * 日志接口
+ */
+interface ILogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    fatal(message: string, ...args: unknown[]): void;
+}
+/**
+ * 日志配置
+ */
+interface LoggerConfig {
+    /** 日志级别 */
+    level: LogLevel;
+    /** 是否启用时间戳 */
+    enableTimestamp: boolean;
+    /** 是否启用颜色 */
+    enableColors: boolean;
+    /** 日志前缀 */
+    prefix?: string;
+    /** 自定义输出函数 */
+    output?: (level: LogLevel, message: string) => void;
+}
+/**
+ * 默认控制台日志实现
+ */
+declare class ConsoleLogger implements ILogger {
+    private _config;
+    constructor(config?: Partial<LoggerConfig>);
+    /**
+     * 输出调试级别日志
+     * @param message 日志消息
+     * @param args 附加参数
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * 输出信息级别日志
+     * @param message 日志消息
+     * @param args 附加参数
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * 输出警告级别日志
+     * @param message 日志消息
+     * @param args 附加参数
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * 输出错误级别日志
+     * @param message 日志消息
+     * @param args 附加参数
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * 输出致命错误级别日志
+     * @param message 日志消息
+     * @param args 附加参数
+     */
+    fatal(message: string, ...args: unknown[]): void;
+    /**
+     * 设置日志级别
+     * @param level 日志级别
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * 设置日志前缀
+     * @param prefix 前缀字符串
+     */
+    setPrefix(prefix: string): void;
+    /**
+     * 内部日志输出方法
+     * @param level 日志级别
+     * @param message 日志消息
+     * @param args 附加参数
+     */
+    private log;
+    /**
+     * 输出到控制台
+     * @param level 日志级别
+     * @param message 格式化后的消息
+     * @param args 附加参数
+     */
+    private outputToConsole;
+    /**
+     * 获取控制台颜色配置
+     * @returns 颜色配置对象
+     */
+    private getColors;
+}
+/**
+ * 日志管理器
+ */
+declare class LoggerManager {
+    private static _instance;
+    private _loggers;
+    private _defaultLogger;
+    private constructor();
+    /**
+     * 获取日志管理器实例
+     * @returns 日志管理器实例
+     */
+    static getInstance(): LoggerManager;
+    /**
+     * 获取或创建日志器
+     * @param name 日志器名称
+     * @returns 日志器实例
+     */
+    getLogger(name?: string): ILogger;
+    /**
+     * 设置日志器
+     * @param name 日志器名称
+     * @param logger 日志器实例
+     */
+    setLogger(name: string, logger: ILogger): void;
+    /**
+     * 设置全局日志级别
+     * @param level 日志级别
+     */
+    setGlobalLevel(level: LogLevel): void;
+    /**
+     * 创建子日志器
+     * @param parentName 父日志器名称
+     * @param childName 子日志器名称
+     * @returns 子日志器实例
+     */
+    createChildLogger(parentName: string, childName: string): ILogger;
+}
+/**
+ * 默认日志器实例
+ */
+declare const Logger: ILogger;
+/**
+ * 创建命名日志器
+ * @param name 日志器名称
+ * @returns 日志器实例
+ */
+declare function createLogger(name: string): ILogger;
+/**
+ * 设置全局日志级别
+ * @param level 日志级别
+ */
+declare function setGlobalLogLevel(level: LogLevel): void;
+
 /**
  * BigInt兼容性抽象层
  *
@@ -1548,6 +1692,70 @@ interface IBigIntLike {
      */
     clone(): IBigIntLike;
 }
+/**
+ * BigInt工厂类
+ *
+ * 自动检测运行时环境的BigInt支持情况，并提供统一的创建接口。
+ * 在支持BigInt的环境中使用原生实现，在不支持的环境中使用兼容实现。
+ */
+declare class BigIntFactory {
+    private static _supportsBigInt;
+    private static _cachedZero;
+    private static _cachedOne;
+    /**
+     * 检查是否支持原生BigInt
+     * @returns 是否支持原生BigInt
+     */
+    static isNativeSupported(): boolean;
+    /**
+     * 检测BigInt支持情况
+     * @returns 是否支持BigInt
+     */
+    private static detectBigIntSupport;
+    /**
+     * 创建BigInt兼容值
+     * @param value 初始值
+     * @returns IBigIntLike实例
+     */
+    static create(value?: number | string | bigint): IBigIntLike;
+    /**
+     * 创建零值
+     * @returns 零值的IBigIntLike实例
+     */
+    static zero(): IBigIntLike;
+    /**
+     * 创建1值
+     * @returns 1值的IBigIntLike实例
+     */
+    static one(): IBigIntLike;
+    /**
+     * 从二进制字符串创建
+     * @param binary 二进制字符串
+     * @returns IBigIntLike实例
+     */
+    static fromBinaryString(binary: string): IBigIntLike;
+    /**
+     * 从十六进制字符串创建
+     * @param hex 十六进制字符串
+     * @returns IBigIntLike实例
+     */
+    static fromHexString(hex: string): IBigIntLike;
+    /**
+     * 获取环境信息
+     * @returns 环境信息对象
+     */
+    static getEnvironmentInfo(): EnvironmentInfo;
+    /**
+     * 检测运行环境
+     * @returns 环境类型
+     */
+    private static detectEnvironment;
+    /**
+     * 检测JavaScript引擎
+     * @returns JS引擎信息
+     */
+    private static detectJSEngine;
+}
 /**
  * 环境信息接口
  */
@@ -1560,11 +1768,42 @@ interface EnvironmentInfo {
     jsEngine: string;
 }
 
+/**
+ * 启用SoA优化装饰器
+ * 默认关闭SoA，只有在大规模批量操作场景下才建议开启
+ */
+declare function EnableSoA<T extends ComponentType>(target: T): T;
+/**
+ * 高精度数值装饰器
+ * 标记字段需要保持完整精度，存储为复杂对象而非TypedArray
+ */
+declare function HighPrecision(target: any, propertyKey: string | symbol): void;
+/**
+ * 64位浮点数装饰器
+ * 标记字段使用Float64Array存储（更高精度但更多内存）
+ */
+declare function Float64(target: any, propertyKey: string | symbol): void;
+/**
+ * 32位浮点数装饰器
+ * 标记字段使用Float32Array存储（默认类型，平衡性能和精度）
+ */
+declare function Float32(target: any, propertyKey: string | symbol): void;
+/**
+ * 32位整数装饰器
+ * 标记字段使用Int32Array存储（适用于整数值）
+ */
+declare function Int32(target: any, propertyKey: string | symbol): void;
+/**
+ * 序列化Map装饰器
+ * 标记Map字段需要序列化/反序列化存储
+ */
+declare function SerializeMap(target: any, propertyKey: string | symbol): void;
 /**
  * SoA存储器（需要装饰器启用）
  * 使用Structure of Arrays存储模式，在大规模批量操作时提供优异性能
  */
 declare class SoAStorage<T extends Component> {
+    private static readonly _logger;
     private fields;
     private stringFields;
     private serializedFields;
@@ -1613,6 +1852,91 @@ declare class SoAStorage<T extends Component> {
  * 组件类型定义
  */
 type ComponentType<T extends Component = Component> = new (...args: unknown[]) => T;
+/**
+ * 组件注册表
+ * 管理组件类型的位掩码分配
+ */
+declare class ComponentRegistry {
+    protected static readonly _logger: ILogger;
+    private static componentTypes;
+    private static componentNameToType;
+    private static componentNameToId;
+    private static maskCache;
+    private static nextBitIndex;
+    private static maxComponents;
+    /**
+     * 注册组件类型并分配位掩码
+     * @param componentType 组件类型
+     * @returns 分配的位索引
+     */
+    static register<T extends Component>(componentType: ComponentType<T>): number;
+    /**
+     * 获取组件类型的位掩码
+     * @param componentType 组件类型
+     * @returns 位掩码
+     */
+    static getBitMask<T extends Component>(componentType: ComponentType<T>): IBigIntLike;
+    /**
+     * 获取组件类型的位索引
+     * @param componentType 组件类型
+     * @returns 位索引
+     */
+    static getBitIndex<T extends Component>(componentType: ComponentType<T>): number;
+    /**
+     * 检查组件类型是否已注册
+     * @param componentType 组件类型
+     * @returns 是否已注册
+     */
+    static isRegistered<T extends Component>(componentType: ComponentType<T>): boolean;
+    /**
+     * 通过名称获取组件类型
+     * @param componentName 组件名称
+     * @returns 组件类型构造函数
+     */
+    static getComponentType(componentName: string): Function | null;
+    /**
+     * 获取所有已注册的组件类型
+     * @returns 组件类型映射
+     */
+    static getAllRegisteredTypes(): Map<Function, number>;
+    /**
+     * 获取所有组件名称到类型的映射
+     * @returns 名称到类型的映射
+     */
+    static getAllComponentNames(): Map<string, Function>;
+    /**
+     * 通过名称获取组件类型ID
+     * @param componentName 组件名称
+     * @returns 组件类型ID
+     */
+    static getComponentId(componentName: string): number | undefined;
+    /**
+     * 注册组件类型（通过名称）
+     * @param componentName 组件名称
+     * @returns 分配的组件ID
+     */
+    static registerComponentByName(componentName: string): number;
+    /**
+     * 创建单个组件的掩码
+     * @param componentName 组件名称
+     * @returns 组件掩码
+     */
+    static createSingleComponentMask(componentName: string): IBigIntLike;
+    /**
+     * 创建多个组件的掩码
+     * @param componentNames 组件名称数组
+     * @returns 组合掩码
+     */
+    static createComponentMask(componentNames: string[]): IBigIntLike;
+    /**
+     * 清除掩码缓存
+     */
+    static clearMaskCache(): void;
+    /**
+     * 重置注册表（用于测试）
+     */
+    static reset(): void;
+}
 /**
  * 高性能组件存储器
  * 使用SoA（Structure of Arrays）模式存储组件
@@ -1693,6 +2017,7 @@ declare class ComponentStorage<T extends Component> {
  * 管理所有组件类型的存储器
  */
 declare class ComponentStorageManager {
+    private static readonly _logger;
     private storages;
     /**
      * 获取或创建组件存储器（默认原始存储）
@@ -2032,6 +2357,7 @@ interface QueryResult {
  * ```
  */
 declare class QuerySystem {
+    private _logger;
     private entities;
     private entityIndex;
     private indexDirty;
@@ -2040,8 +2366,6 @@ declare class QuerySystem {
     private cacheMaxSize;
     private cacheTimeout;
     private componentPoolManager;
-    private bitMaskOptimizer;
-    private indexUpdateBatcher;
     private componentIndexManager;
     private archetypeSystem;
     private dirtyTrackingSystem;
@@ -2120,7 +2444,7 @@ declare class QuerySystem {
      * ```typescript
      * // 查询同时具有位置和速度组件的实体
      * const result = querySystem.queryAll(PositionComponent, VelocityComponent);
-     * console.log(`找到 ${result.count} 个移动实体`);
+     * logger.info(`找到 ${result.count} 个移动实体`);
      * ```
      */
     queryAll(...componentTypes: ComponentType[]): QueryResult;
@@ -2147,7 +2471,7 @@ declare class QuerySystem {
      * ```typescript
      * // 查询具有武器或护甲组件的实体
      * const result = querySystem.queryAny(WeaponComponent, ArmorComponent);
-     * console.log(`找到 ${result.count} 个装备实体`);
+     * logger.info(`找到 ${result.count} 个装备实体`);
      * ```
      */
     queryAny(...componentTypes: ComponentType[]): QueryResult;
@@ -2164,7 +2488,7 @@ declare class QuerySystem {
      * ```typescript
      * // 查询不具有AI和玩家控制组件的实体（如静态物体）
      * const result = querySystem.queryNone(AIComponent, PlayerControlComponent);
-     * console.log(`找到 ${result.count} 个静态实体`);
+     * logger.info(`找到 ${result.count} 个静态实体`);
      * ```
      */
     queryNone(...componentTypes: ComponentType[]): QueryResult;
@@ -2366,6 +2690,7 @@ declare class QuerySystem {
  * ```
  */
 declare class QueryBuilder {
+    private _logger;
     private conditions;
     private querySystem;
     constructor(querySystem: QuerySystem);
@@ -2417,6 +2742,7 @@ declare class QueryBuilder {
  * 基于TypeSafeEventSystem，提供类型安全的事件发布订阅机制
  */
 declare class EventBus implements IEventBus {
+    private static readonly _logger;
     private eventSystem;
     private eventIdCounter;
     private isDebugMode;
@@ -2680,6 +3006,10 @@ declare class EntityComparer {
  * ```
  */
 declare class Entity {
+    /**
+     * Entity专用日志器
+     */
+    private static _logger;
     /**
      * 实体比较器实例
      */
@@ -3416,6 +3746,7 @@ declare abstract class EntitySystem implements ISystemBase {
  * 管理场景中的所有实体系统
  */
 declare class EntityProcessorList {
+    private static readonly _logger;
     private _processors;
     private _isDirty;
     /**
@@ -3990,6 +4321,7 @@ declare class EntityBuilder {
      */
     clone(): EntityBuilder;
 }
+
 /**
  * 场景构建器 - 提供流式API创建和配置场景
  */
@@ -4038,6 +4370,7 @@ declare class SceneBuilder {
      */
     build(): Scene;
 }
+
 /**
  * 组件构建器 - 提供流式API创建组件
  */
@@ -4071,30 +4404,86 @@ declare class ComponentBuilder<T extends Component> {
      */
     build(): T;
 }
+
 /**
- * ECS流式API主入口
- * 提供统一的流式接口
+ * 实体批量操作器
+ * 提供对多个实体的批量操作
  */
-declare class ECSFluentAPI {
-    private scene;
-    private querySystem;
-    private eventSystem;
-    constructor(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem);
+declare class EntityBatchOperator {
+    private entities;
+    constructor(entities: Entity[]);
     /**
-     * 创建实体构建器
-     * @returns 实体构建器
+     * 批量添加组件
+     * @param component 组件实例
+     * @returns 批量操作器
      */
-    createEntity(): EntityBuilder;
+    addComponent<T extends Component>(component: T): EntityBatchOperator;
     /**
-     * 创建场景构建器
-     * @returns 场景构建器
+     * 批量移除组件
+     * @param componentType 组件类型
+     * @returns 批量操作器
      */
-    createScene(): SceneBuilder;
+    removeComponent<T extends Component>(componentType: ComponentType<T>): EntityBatchOperator;
     /**
-     * 创建组件构建器
-     * @param componentClass 组件类
-     * @param args 构造参数
-     * @returns 组件构建器
+     * 批量设置活跃状态
+     * @param active 是否活跃
+     * @returns 批量操作器
+     */
+    setActive(active: boolean): EntityBatchOperator;
+    /**
+     * 批量设置标签
+     * @param tag 标签
+     * @returns 批量操作器
+     */
+    setTag(tag: number): EntityBatchOperator;
+    /**
+     * 批量执行操作
+     * @param operation 操作函数
+     * @returns 批量操作器
+     */
+    forEach(operation: (entity: Entity, index: number) => void): EntityBatchOperator;
+    /**
+     * 过滤实体
+     * @param predicate 过滤条件
+     * @returns 新的批量操作器
+     */
+    filter(predicate: (entity: Entity) => boolean): EntityBatchOperator;
+    /**
+     * 获取实体数组
+     * @returns 实体数组
+     */
+    toArray(): Entity[];
+    /**
+     * 获取实体数量
+     * @returns 实体数量
+     */
+    count(): number;
+}
+
+/**
+ * ECS流式API主入口
+ * 提供统一的流式接口
+ */
+declare class ECSFluentAPI {
+    private scene;
+    private querySystem;
+    private eventSystem;
+    constructor(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem);
+    /**
+     * 创建实体构建器
+     * @returns 实体构建器
+     */
+    createEntity(): EntityBuilder;
+    /**
+     * 创建场景构建器
+     * @returns 场景构建器
+     */
+    createScene(): SceneBuilder;
+    /**
+     * 创建组件构建器
+     * @param componentClass 组件类
+     * @param args 构造参数
+     * @returns 组件构建器
      */
     createComponent<T extends Component>(componentClass: new (...args: unknown[]) => T, ...args: unknown[]): ComponentBuilder<T>;
     /**
@@ -4176,60 +4565,6 @@ declare class ECSFluentAPI {
         eventStats: Map<string, any>;
     };
 }
-/**
- * 实体批量操作器
- * 提供对多个实体的批量操作
- */
-declare class EntityBatchOperator {
-    private entities;
-    constructor(entities: Entity[]);
-    /**
-     * 批量添加组件
-     * @param component 组件实例
-     * @returns 批量操作器
-     */
-    addComponent<T extends Component>(component: T): EntityBatchOperator;
-    /**
-     * 批量移除组件
-     * @param componentType 组件类型
-     * @returns 批量操作器
-     */
-    removeComponent<T extends Component>(componentType: ComponentType<T>): EntityBatchOperator;
-    /**
-     * 批量设置活跃状态
-     * @param active 是否活跃
-     * @returns 批量操作器
-     */
-    setActive(active: boolean): EntityBatchOperator;
-    /**
-     * 批量设置标签
-     * @param tag 标签
-     * @returns 批量操作器
-     */
-    setTag(tag: number): EntityBatchOperator;
-    /**
-     * 批量执行操作
-     * @param operation 操作函数
-     * @returns 批量操作器
-     */
-    forEach(operation: (entity: Entity, index: number) => void): EntityBatchOperator;
-    /**
-     * 过滤实体
-     * @param predicate 过滤条件
-     * @returns 新的批量操作器
-     */
-    filter(predicate: (entity: Entity) => boolean): EntityBatchOperator;
-    /**
-     * 获取实体数组
-     * @returns 实体数组
-     */
-    toArray(): Entity[];
-    /**
-     * 获取实体数量
-     * @returns 实体数量
-     */
-    count(): number;
-}
 /**
  * 创建ECS流式API实例
  * @param scene 场景
@@ -4595,7 +4930,7 @@ declare class DebugManager {
  *
  * // 调度定时器
  * Core.schedule(1.0, false, null, (timer) => {
- *     console.log("1秒后执行");
+ *     Core._logger.info("1秒后执行");
  * });
  * ```
  */
@@ -4610,6 +4945,10 @@ declare class Core {
      * 全局核心实例
      */
     private static _instance;
+    /**
+     * Core专用日志器
+     */
+    private static _logger;
     /**
      * 实体系统启用状态
      *
@@ -5742,7 +6081,7 @@ interface DirtyStats {
  * dirtySystem.addListener({
  *     flags: DirtyFlag.TRANSFORM_CHANGED,
  *     callback: (data) => {
- *         console.log('Entity position changed:', data.entity.name);
+ *         logger.debug('Entity position changed:', data.entity.name);
  *     }
  * });
  *
@@ -5751,6 +6090,7 @@ interface DirtyStats {
  * ```
  */
 declare class DirtyTrackingSystem {
+    private static readonly _logger;
     /** 脏实体映射表 */
     private _dirtyEntities;
     /** 脏标记监听器 */
@@ -5853,201 +6193,6 @@ declare class DirtyTrackingSystem {
     private estimateMemoryUsage;
 }
 
-/**
- * 索引更新操作类型
- */
-declare enum IndexUpdateType {
-    ADD_ENTITY = "add_entity",
-    REMOVE_ENTITY = "remove_entity",
-    UPDATE_ENTITY = "update_entity"
-}
-/**
- * 索引更新操作
- */
-interface IndexUpdateOperation {
-    type: IndexUpdateType;
-    entity: Entity;
-    oldMask?: bigint;
-    newMask?: bigint;
-}
-/**
- * 延迟索引更新器，用于批量更新查询索引以提高性能
- */
-declare class IndexUpdateBatcher {
-    private pendingOperations;
-    private isProcessing;
-    private batchSize;
-    private flushTimeout;
-    private flushDelay;
-    /**
-     * 添加索引更新操作
-     */
-    addOperation(operation: IndexUpdateOperation): void;
-    /**
-     * 批量添加实体
-     */
-    addEntities(entities: Entity[]): void;
-    /**
-     * 批量移除实体
-     */
-    removeEntities(entities: Entity[]): void;
-    /**
-     * 批量更新实体
-     */
-    updateEntities(updates: Array<{
-        entity: Entity;
-        oldMask: bigint;
-        newMask: bigint;
-    }>): void;
-    /**
-     * 安排延迟刷新
-     */
-    private scheduleFlush;
-    /**
-     * 立即处理所有待处理的操作
-     */
-    flush(): void;
-    /**
-     * 处理批量操作
-     */
-    private processBatch;
-    /**
-     * 批量处理添加操作
-     */
-    private processBatchAdd;
-    /**
-     * 批量处理移除操作
-     */
-    private processBatchRemove;
-    /**
-     * 批量处理更新操作
-     */
-    private processBatchUpdate;
-    /**
-     * 设置批量大小
-     */
-    setBatchSize(size: number): void;
-    /**
-     * 设置刷新延迟
-     */
-    setFlushDelay(delay: number): void;
-    /**
-     * 获取待处理操作数量
-     */
-    getPendingCount(): number;
-    /**
-     * 清空所有待处理操作
-     */
-    clear(): void;
-    /**
-     * 检查是否有待处理操作
-     */
-    hasPendingOperations(): boolean;
-    onBatchAdd?: (entities: Entity[]) => void;
-    onBatchRemove?: (entities: Entity[]) => void;
-    onBatchUpdate?: (updates: Array<{
-        entity: Entity;
-        oldMask: bigint;
-        newMask: bigint;
-    }>) => void;
-}
-
-/**
- * 位掩码优化器，用于预计算和缓存常用的组件掩码
- *
- * 使用BigInt兼容层确保在所有平台上的正常运行。
- */
-declare class BitMaskOptimizer {
-    private static instance;
-    private maskCache;
-    private componentTypeMap;
-    private nextComponentId;
-    private constructor();
-    static getInstance(): BitMaskOptimizer;
-    /**
-     * 注册组件类型
-     */
-    registerComponentType(componentName: string): number;
-    /**
-     * 获取组件类型ID
-     */
-    getComponentTypeId(componentName: string): number | undefined;
-    /**
-     * 创建单个组件的掩码
-     * @param componentName 组件名称
-     * @returns 组件掩码
-     */
-    createSingleComponentMask(componentName: string): IBigIntLike;
-    /**
-     * 创建多个组件的组合掩码
-     * @param componentNames 组件名称数组
-     * @returns 组合掩码
-     */
-    createCombinedMask(componentNames: string[]): IBigIntLike;
-    /**
-     * 检查掩码是否包含指定组件
-     * @param mask 要检查的掩码
-     * @param componentName 组件名称
-     * @returns 是否包含指定组件
-     */
-    maskContainsComponent(mask: IBigIntLike, componentName: string): boolean;
-    /**
-     * 检查掩码是否包含所有指定组件
-     * @param mask 要检查的掩码
-     * @param componentNames 组件名称数组
-     * @returns 是否包含所有指定组件
-     */
-    maskContainsAllComponents(mask: IBigIntLike, componentNames: string[]): boolean;
-    /**
-     * 检查掩码是否包含任一指定组件
-     * @param mask 要检查的掩码
-     * @param componentNames 组件名称数组
-     * @returns 是否包含任一指定组件
-     */
-    maskContainsAnyComponent(mask: IBigIntLike, componentNames: string[]): boolean;
-    /**
-     * 添加组件到掩码
-     * @param mask 原始掩码
-     * @param componentName 要添加的组件名称
-     * @returns 新的掩码
-     */
-    addComponentToMask(mask: IBigIntLike, componentName: string): IBigIntLike;
-    /**
-     * 从掩码中移除组件
-     * @param mask 原始掩码
-     * @param componentName 要移除的组件名称
-     * @returns 新的掩码
-     */
-    removeComponentFromMask(mask: IBigIntLike, componentName: string): IBigIntLike;
-    /**
-     * 预计算常用掩码组合
-     */
-    precomputeCommonMasks(commonCombinations: string[][]): void;
-    /**
-     * 获取掩码缓存统计信息
-     */
-    getCacheStats(): {
-        size: number;
-        componentTypes: number;
-    };
-    /**
-     * 清空缓存
-     */
-    clearCache(): void;
-    /**
-     * 重置优化器
-     */
-    reset(): void;
-    /**
-     * 将掩码转换为组件名称数组
-     */
-    maskToComponentNames(mask: IBigIntLike): string[];
-    /**
-     * 获取掩码中组件的数量
-     */
-    getComponentCount(mask: IBigIntLike): number;
-}
-
 /**
  * 组件对象池，用于复用组件实例以减少内存分配
  */
@@ -6208,355 +6353,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-/**
- * 可序列化接口
- *
- * 实现此接口的类可以被快照系统序列化和反序列化
- */
-interface ISnapshotable {
-    /**
-     * 序列化对象到可传输的数据格式
-     *
-     * @returns 序列化后的数据
-     */
-    serialize(): any;
-    /**
-     * 从序列化数据恢复对象状态
-     *
-     * @param data - 序列化数据
-     */
-    deserialize(data: any): void;
-}
-/**
- * 快照配置接口
- */
-interface SnapshotConfig {
-    /** 是否包含在快照中 */
-    includeInSnapshot: boolean;
-    /** 压缩级别 (0-9) */
-    compressionLevel: number;
-    /** 同步优先级 (数字越大优先级越高) */
-    syncPriority: number;
-    /** 是否启用增量快照 */
-    enableIncremental: boolean;
-}
-/**
- * 组件快照数据
- */
-interface ComponentSnapshot {
-    /** 组件类型名称 */
-    type: string;
-    /** 组件ID */
-    id: number;
-    /** 序列化数据 */
-    data: any;
-    /** 是否启用 */
-    enabled: boolean;
-    /** 快照配置 */
-    config?: SnapshotConfig;
-}
-/**
- * 实体快照数据
- */
-interface EntitySnapshot {
-    /** 实体ID */
-    id: number;
-    /** 实体名称 */
-    name: string;
-    /** 是否启用 */
-    enabled: boolean;
-    /** 是否激活 */
-    active: boolean;
-    /** 标签 */
-    tag: number;
-    /** 更新顺序 */
-    updateOrder: number;
-    /** 组件快照列表 */
-    components: ComponentSnapshot[];
-    /** 子实体ID列表 */
-    children: number[];
-    /** 父实体ID */
-    parent?: number;
-    /** 快照时间戳 */
-    timestamp: number;
-}
-/**
- * 场景快照数据
- */
-interface SceneSnapshot {
-    /** 实体快照列表 */
-    entities: EntitySnapshot[];
-    /** 快照时间戳 */
-    timestamp: number;
-    /** 框架版本 */
-    version: string;
-    /** 快照类型 */
-    type: 'full' | 'incremental';
-    /** 基础快照ID（增量快照使用） */
-    baseSnapshotId?: string;
-}
-
-/**
- * 快照管理器
- *
- * 负责创建和管理ECS系统的快照，支持完整快照和增量快照
- */
-declare class SnapshotManager {
-    /** 默认快照配置 */
-    private static readonly DEFAULT_CONFIG;
-    /** 框架版本 */
-    private readonly version;
-    /** 最后快照时间戳 */
-    private lastSnapshotTime;
-    /** 快照缓存 */
-    private snapshotCache;
-    /** 最大缓存数量 */
-    private maxCacheSize;
-    /**
-     * 创建场景快照
-     *
-     * @param entities - 实体列表
-     * @param type - 快照类型
-     * @returns 场景快照
-     */
-    createSceneSnapshot(entities: Entity[], type?: 'full' | 'incremental'): SceneSnapshot;
-    /**
-     * 从快照恢复场景
-     *
-     * @param snapshot - 场景快照
-     * @param targetEntities - 目标实体列表（用于增量恢复）
-     * @param createMissingEntities - 是否创建缺失的实体
-     */
-    restoreFromSnapshot(snapshot: SceneSnapshot, targetEntities?: Entity[], createMissingEntities?: boolean): Entity[];
-    /**
-     * 从快照恢复实体列表
-     *
-     * @param snapshot - 场景快照
-     * @param targetEntities - 目标实体列表
-     * @param createMissingEntities - 是否创建缺失的实体
-     */
-    restoreEntitiesFromSnapshot(snapshot: SceneSnapshot, targetEntities: Entity[], createMissingEntities?: boolean): Entity[];
-    /**
-     * 从快照创建实体
-     */
-    private createEntityFromSnapshot;
-    /**
-     * 从快照创建组件
-     */
-    private createComponentFromSnapshot;
-    /**
-     * 获取组件类型
-     */
-    private getComponentType;
-    /**
-     * 创建快速快照（跳过变化检测）
-     *
-     * @param entities - 实体列表
-     * @returns 场景快照
-     */
-    createQuickSnapshot(entities: Entity[]): SceneSnapshot;
-    /**
-     * 创建增量快照
-     *
-     * @param entities - 实体列表
-     * @param baseSnapshot - 基础快照
-     * @param enableChangeDetection - 是否启用变化检测
-     * @returns 增量快照
-     */
-    createIncrementalSnapshot(entities: Entity[], baseSnapshot: SceneSnapshot, enableChangeDetection?: boolean): SceneSnapshot;
-    /**
-     * 缓存快照
-     *
-     * @param id - 快照ID
-     * @param snapshot - 快照数据
-     */
-    cacheSnapshot(id: string, snapshot: SceneSnapshot): void;
-    /**
-     * 获取缓存的快照
-     *
-     * @param id - 快照ID
-     * @returns 快照数据或undefined
-     */
-    getCachedSnapshot(id: string): SceneSnapshot | undefined;
-    /**
-     * 清空快照缓存
-     */
-    clearCache(): void;
-    /**
-     * 清空所有缓存
-     */
-    clearAllCaches(): void;
-    /**
-     * 获取缓存统计信息
-     */
-    getCacheStats(): {
-        snapshotCacheSize: number;
-    };
-    /**
-     * 创建实体快照
-     */
-    private createEntitySnapshot;
-    /**
-     * 创建组件快照
-     */
-    private createComponentSnapshot;
-    /**
-     * 默认组件序列化
-     */
-    private defaultSerializeComponent;
-    /**
-     * 检查值是否可序列化
-     */
-    private isSerializableValue;
-    /**
-     * 检查组件是否支持快照
-     */
-    private isComponentSnapshotable;
-    /**
-     * 获取组件快照配置
-     */
-    private getComponentSnapshotConfig;
-    /**
-     * 检查组件是否有序列化方法
-     */
-    private hasSerializeMethod;
-    /**
-     * 恢复完整快照
-     */
-    private restoreFullSnapshot;
-    /**
-     * 恢复增量快照
-     */
-    private restoreIncrementalSnapshot;
-    /**
-     * 从快照恢复实体
-     */
-    private restoreEntityFromSnapshot;
-    /**
-     * 从快照恢复组件
-     */
-    private restoreComponentFromSnapshot;
-    /**
-     * 默认组件反序列化
-     */
-    private defaultDeserializeComponent;
-    /**
-     * 检查实体结构是否发生变化（组件数量、类型等）
-     */
-    private hasEntityStructureChanged;
-    /**
-     * 获取发生变化的组件列表
-     */
-    private getChangedComponents;
-    /**
-     * 检查组件数据是否发生变化
-     */
-    private hasComponentDataChanged;
-    /**
-     * 检查组件是否有变化检测方法
-     */
-    private hasChangeDetectionMethod;
-    /**
-     * 创建增量实体快照（只包含变化的组件）
-     */
-    private createIncrementalEntitySnapshot;
-    /**
-     * 生成快照ID
-     */
-    private generateSnapshotId;
-}
-
-/**
- * 快照扩展接口
- *
- * 为Component基类提供快照功能的扩展接口
- */
-interface ISnapshotExtension {
-    /** 快照配置 */
-    snapshotConfig?: SnapshotConfig;
-    /** 序列化方法 */
-    serialize?(): any;
-    /** 反序列化方法 */
-    deserialize?(data: any): void;
-    /** 变化检测方法 */
-    hasChanged?(baseData: any): boolean;
-}
-/**
- * 快照装饰器
- *
- * 用于标记组件属性为可序列化
- */
-declare function Serializable(config?: Partial<SnapshotConfig>): (target: any, propertyKey: string) => void;
-/**
- * 快照配置装饰器
- *
- * 用于配置组件的快照行为
- */
-declare function SnapshotConfigDecorator(config: SnapshotConfig): (target: any) => void;
-/**
- * 快照扩展工具类
- */
-declare class SnapshotExtension {
-    /**
-     * 为组件添加快照支持
-     *
-     * @param component - 目标组件
-     * @param config - 快照配置
-     */
-    static enableSnapshot(component: Component, config?: Partial<SnapshotConfig>): void;
-    /**
-     * 禁用组件的快照功能
-     *
-     * @param component - 目标组件
-     */
-    static disableSnapshot(component: Component): void;
-    /**
-     * 检查组件是否支持快照
-     *
-     * @param component - 目标组件
-     * @returns 是否支持快照
-     */
-    static isSnapshotable(component: Component): boolean;
-    /**
-     * 获取组件的可序列化属性
-     *
-     * @param component - 目标组件
-     * @returns 可序列化属性列表
-     */
-    static getSerializableProperties(component: Component): string[];
-    /**
-     * 创建组件的默认序列化方法
-     *
-     * @param component - 目标组件
-     * @returns 序列化数据
-     */
-    static createDefaultSerializer(component: Component): () => any;
-    /**
-     * 创建组件的默认反序列化方法
-     *
-     * @param component - 目标组件
-     * @returns 反序列化函数
-     */
-    static createDefaultDeserializer(component: Component): (data: any) => void;
-    /**
-     * 创建简单的变化检测方法
-     *
-     * @param component - 目标组件
-     * @returns 变化检测函数
-     */
-    static createSimpleChangeDetector(component: Component): (baseData: any) => boolean;
-    /**
-     * 创建深度变化检测方法
-     *
-     * @param component - 目标组件
-     * @returns 变化检测函数
-     */
-    static createDeepChangeDetector(component: Component): (baseData: any) => boolean;
-    /**
-     * 深度比较两个值
-     */
-    private static deepCompare;
-}
-
-export { ArchetypeSystem, AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentStorage, ComponentTypeManager, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, SceneDataCollector, Serializable, SnapshotConfigDecorator, SnapshotExtension, SnapshotManager, SystemDataCollector, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI };
-export type { Archetype, ArchetypeQueryResult, ComponentSnapshot, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EntitySnapshot, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceDebugData, IPerformanceEventData, IPoolable, ISceneDebugData, ISceneEventData, ISnapshotExtension, ISnapshotable, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats, SceneSnapshot, SnapshotConfig };
+export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, BitmapComponentIndex, Bits, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, HighPrecision, IdentifierPool, IndexType, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, SceneDataCollector, SerializeMap, SoAStorage, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI, createLogger, setGlobalLogLevel };
+export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, ISceneDebugData, ISceneEventData, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };