@esengine/ecs-framework 2.1.18 → 2.1.20

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.18
+ * @esengine/ecs-framework v2.1.20
  * TypeScript definitions
  */
 /**
@@ -759,6 +759,207 @@ interface IPerformanceEventData extends IEventData {
     /** 额外数据 */
     metadata?: Record<string, any>;
 }
+/**
+ * ECS调试配置接口
+ */
+interface IECSDebugConfig {
+    /** 是否启用调试 */
+    enabled: boolean;
+    /** WebSocket服务器URL */
+    websocketUrl: string;
+    /** 是否自动重连 */
+    autoReconnect?: boolean;
+    /** 数据更新间隔（毫秒） */
+    updateInterval?: number;
+    /** 数据通道配置 */
+    channels: {
+        entities: boolean;
+        systems: boolean;
+        performance: boolean;
+        components: boolean;
+        scenes: boolean;
+    };
+}
+/**
+ * Core配置接口
+ */
+interface ICoreConfig {
+    /** 是否启用调试模式 */
+    debug?: boolean;
+    /** 是否启用实体系统 */
+    enableEntitySystems?: boolean;
+    /** 调试配置 */
+    debugConfig?: IECSDebugConfig;
+}
+/**
+ * ECS调试数据接口
+ */
+interface IECSDebugData {
+    /** 时间戳 */
+    timestamp: number;
+    /** 框架版本 */
+    frameworkVersion?: string;
+    /** 是否正在运行 */
+    isRunning: boolean;
+    /** 框架是否已加载 */
+    frameworkLoaded: boolean;
+    /** 当前场景名称 */
+    currentScene: string;
+    /** 实体数据 */
+    entities?: IEntityDebugData;
+    /** 系统数据 */
+    systems?: ISystemDebugData;
+    /** 性能数据 */
+    performance?: IPerformanceDebugData;
+    /** 组件数据 */
+    components?: IComponentDebugData;
+    /** 场景数据 */
+    scenes?: ISceneDebugData;
+}
+/**
+ * 实体调试数据接口
+ */
+interface IEntityDebugData {
+    /** 总实体数 */
+    totalEntities: number;
+    /** 激活实体数 */
+    activeEntities: number;
+    /** 待添加实体数 */
+    pendingAdd: number;
+    /** 待移除实体数 */
+    pendingRemove: number;
+    /** 按Archetype分组的实体分布 */
+    entitiesPerArchetype: Array<{
+        signature: string;
+        count: number;
+        memory: number;
+    }>;
+    /** 组件数量最多的前几个实体 */
+    topEntitiesByComponents: Array<{
+        id: string;
+        name: string;
+        componentCount: number;
+        memory: number;
+    }>;
+    /** 实体详情列表 */
+    entityDetails?: Array<{
+        id: string | number;
+        name?: string;
+        tag?: string;
+        enabled: boolean;
+        componentCount: number;
+        components: string[];
+    }>;
+}
+/**
+ * 系统调试数据接口
+ */
+interface ISystemDebugData {
+    /** 总系统数 */
+    totalSystems: number;
+    /** 系统信息列表 */
+    systemsInfo: Array<{
+        name: string;
+        type: string;
+        entityCount: number;
+        executionTime?: number;
+        averageExecutionTime?: number;
+        minExecutionTime?: number;
+        maxExecutionTime?: number;
+        executionTimeHistory?: number[];
+        memoryUsage?: number;
+        updateOrder: number;
+        enabled: boolean;
+        lastUpdateTime?: number;
+    }>;
+}
+/**
+ * 性能调试数据接口
+ */
+interface IPerformanceDebugData {
+    /** ECS框架执行时间（毫秒） */
+    frameTime: number;
+    /** 引擎总帧时间（毫秒） */
+    engineFrameTime?: number;
+    /** ECS占总帧时间百分比 */
+    ecsPercentage?: number;
+    /** 内存使用量（MB） */
+    memoryUsage: number;
+    /** FPS */
+    fps: number;
+    /** 平均ECS执行时间（毫秒） */
+    averageFrameTime: number;
+    /** 最小ECS执行时间（毫秒） */
+    minFrameTime: number;
+    /** 最大ECS执行时间（毫秒） */
+    maxFrameTime: number;
+    /** ECS执行时间历史记录 */
+    frameTimeHistory: number[];
+    /** 系统性能详情 */
+    systemPerformance: Array<{
+        systemName: string;
+        averageTime: number;
+        maxTime: number;
+        minTime: number;
+        samples: number;
+        percentage?: number;
+    }>;
+    /** 系统占比分析数据 */
+    systemBreakdown?: Array<{
+        systemName: string;
+        executionTime: number;
+        percentage: number;
+    }>;
+    /** 内存分配详情 */
+    memoryDetails?: {
+        entities: number;
+        components: number;
+        systems: number;
+        pooled: number;
+        totalMemory: number;
+        usedMemory: number;
+        freeMemory: number;
+        gcCollections: number;
+    };
+}
+/**
+ * 组件调试数据接口
+ */
+interface IComponentDebugData {
+    /** 组件类型数 */
+    componentTypes: number;
+    /** 组件实例总数 */
+    componentInstances: number;
+    /** 组件分布统计 */
+    componentStats: Array<{
+        typeName: string;
+        instanceCount: number;
+        memoryPerInstance: number;
+        totalMemory: number;
+        poolSize: number;
+        poolUtilization: number;
+        averagePerEntity?: number;
+    }>;
+}
+/**
+ * 场景调试数据接口
+ */
+interface ISceneDebugData {
+    /** 当前场景名称 */
+    currentSceneName: string;
+    /** 场景是否已初始化 */
+    isInitialized: boolean;
+    /** 场景运行时间（秒） */
+    sceneRunTime: number;
+    /** 场景实体数 */
+    sceneEntityCount: number;
+    /** 场景系统数 */
+    sceneSystemCount: number;
+    /** 场景内存使用量 */
+    sceneMemory: number;
+    /** 场景启动时间 */
+    sceneUptime: number;
+}
 
 /**
  * 游戏组件基类
@@ -1885,44 +2086,33 @@ declare class EntityList {
 
 /**
  * 高性能位操作类
- * 用于快速操作位数组，支持组件匹配等场景
+ * 基于BigInt实现，支持任意数量的位操作
  */
 declare class Bits {
-    private _words;
-    private static readonly WORD_SIZE;
-    constructor();
+    private _value;
+    constructor(initialValue?: bigint);
     /**
      * 设置指定位置的位为1
-     * @param index 位置索引
      */
     set(index: number): void;
     /**
      * 清除指定位置的位（设为0）
-     * @param index 位置索引
      */
     clear(index: number): void;
     /**
      * 获取指定位置的位值
-     * @param index 位置索引
-     * @returns 位值（true或false）
      */
     get(index: number): boolean;
     /**
      * 检查是否包含所有指定的位
-     * @param other 另一个Bits对象
-     * @returns 如果包含所有位则返回true
      */
     containsAll(other: Bits): boolean;
     /**
      * 检查是否包含任意一个指定的位
-     * @param other 另一个Bits对象
-     * @returns 如果包含任意位则返回true
      */
     intersects(other: Bits): boolean;
     /**
      * 检查是否不包含任何指定的位
-     * @param other 另一个Bits对象
-     * @returns 如果不包含任何位则返回true
      */
     excludes(other: Bits): boolean;
     /**
@@ -1931,30 +2121,76 @@ declare class Bits {
     clearAll(): void;
     /**
      * 检查是否为空（没有设置任何位）
-     * @returns 如果为空则返回true
      */
     isEmpty(): boolean;
     /**
      * 获取设置的位数量
-     * @returns 设置的位数量
      */
     cardinality(): number;
     /**
-     * 计算一个32位整数中设置的位数量
-     * @param n 32位整数
-     * @returns 设置的位数量
+     * 位运算：与
+     */
+    and(other: Bits): Bits;
+    /**
+     * 位运算：或
+     */
+    or(other: Bits): Bits;
+    /**
+     * 位运算：异或
      */
-    private popCount;
+    xor(other: Bits): Bits;
+    /**
+     * 位运算：非
+     */
+    not(maxBits?: number): Bits;
     /**
      * 复制另一个Bits对象
-     * @param other 要复制的Bits对象
      */
     copyFrom(other: Bits): void;
     /**
      * 创建当前Bits的副本
-     * @returns 新的Bits对象
      */
     clone(): Bits;
+    /**
+     * 获取原始BigInt值
+     */
+    getValue(): bigint;
+    /**
+     * 设置原始BigInt值
+     */
+    setValue(value: bigint): void;
+    /**
+     * 获取调试信息
+     */
+    toString(): string;
+    /**
+     * 获取二进制表示
+     */
+    toBinaryString(maxBits?: number): string;
+    /**
+     * 获取十六进制表示
+     */
+    toHexString(): string;
+    /**
+     * 从二进制字符串创建Bits
+     */
+    static fromBinaryString(binaryString: string): Bits;
+    /**
+     * 从十六进制字符串创建Bits
+     */
+    static fromHexString(hexString: string): Bits;
+    /**
+     * 比较两个Bits对象是否相等
+     */
+    equals(other: Bits): boolean;
+    /**
+     * 获取最高位的索引
+     */
+    getHighestBitIndex(): number;
+    /**
+     * 获取最低位的索引
+     */
+    getLowestBitIndex(): number;
 }
 
 /**
@@ -3719,6 +3955,150 @@ declare class EntityBatchOperator {
  */
 declare function createECSAPI(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem): ECSFluentAPI;
 
+/**
+ * ECS调试报告器 - WebSocket模式
+ *
+ * 负责收集ECS框架的运行时调试数据并通过WebSocket发送到调试服务器
+ */
+declare class DebugReporter {
+    private config;
+    private core;
+    private timer?;
+    private ws?;
+    private lastFrameTime;
+    private frameCount;
+    private lastFpsTime;
+    private fps;
+    private sceneStartTime;
+    private isConnected;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private frameTimeHistory;
+    private maxHistoryLength;
+    /**
+     * 构造函数
+     * @param core Core实例
+     * @param config 调试配置
+     */
+    constructor(core: Core, config: IECSDebugConfig);
+    /**
+     * 启动调试报告器
+     */
+    private start;
+    /**
+     * 停止调试报告器
+     */
+    stop(): void;
+    /**
+     * 更新配置
+     * @param newConfig 新配置
+     */
+    updateConfig(newConfig: IECSDebugConfig): void;
+    /**
+     * 连接WebSocket
+     */
+    private connectWebSocket;
+    /**
+     * 启动数据流
+     */
+    private startDataStream;
+    /**
+     * 发送消息
+     */
+    private send;
+    /**
+     * 处理接收到的消息
+     * @param message 消息内容
+     */
+    private handleMessage;
+    /**
+     * 收集调试数据
+     * @returns 调试数据对象
+     */
+    private collectDebugData;
+    /**
+     * 更新FPS计算
+     */
+    private updateFPS;
+    /**
+     * 获取框架版本
+     */
+    private getFrameworkVersion;
+    /**
+     * 获取当前场景名称
+     */
+    private getCurrentSceneName;
+    /**
+     * 收集实体数据
+     */
+    private collectEntityData;
+    /**
+     * 获取实体详情
+     */
+    private getEntityDetails;
+    /**
+     * 收集系统数据
+     */
+    private collectSystemData;
+    /**
+     * 收集性能数据
+     */
+    private collectPerformanceData;
+    /**
+     * 获取ECS框架整体性能数据
+     */
+    private getECSPerformanceData;
+    /**
+     * 获取系统性能数据
+     */
+    private getSystemPerformance;
+    /**
+     * 获取内存详情
+     */
+    private getMemoryDetails;
+    /**
+     * 收集组件数据
+     */
+    private collectComponentData;
+    /**
+     * 计算组件实际内存大小
+     */
+    private calculateComponentMemorySize;
+    /**
+     * 估算对象内存大小（字节）
+     */
+    private estimateObjectSize;
+    /**
+     * 收集场景数据
+     */
+    private collectSceneData;
+    /**
+     * 手动触发数据收集
+     * @returns 当前调试数据
+     */
+    getDebugData(): IECSDebugData;
+    /**
+     * 重置场景时间
+     */
+    onSceneChanged(): void;
+    /**
+     * 获取连接状态
+     */
+    get connected(): boolean;
+    /**
+     * 手动重连
+     */
+    reconnect(): void;
+    /**
+     * 获取Archetype分布
+     */
+    private getArchetypeDistribution;
+    /**
+     * 获取组件数量最多的实体
+     */
+    private getTopEntitiesByComponents;
+}
+
 /**
  * 游戏引擎核心类
  *
@@ -3808,11 +4188,20 @@ declare class Core {
      * 当前活动场景
      */
     _scene?: Scene;
+    /**
+     * 调试报告器
+     *
+     * 负责收集和发送调试数据。
+     */
+    _debugReporter?: DebugReporter;
+    /**
+     * Core配置
+     */
+    private _config;
     /**
      * 创建核心实例
      *
-     * @param debug - 是否启用调试模式，默认为true
-     * @param enableEntitySystems - 是否启用实体系统，默认为true
+     * @param config - Core配置对象
      */
     private constructor();
     /**
@@ -3841,10 +4230,10 @@ declare class Core {
      *
      * 如果实例已存在，则返回现有实例。
      *
-     * @param debug - 是否为调试模式，默认为true
+     * @param config - Core配置，也可以直接传入boolean表示debug模式（向后兼容）
      * @returns Core实例
      */
-    static create(debug?: boolean): Core;
+    static create(config?: ICoreConfig | boolean): Core;
     /**
      * 更新游戏逻辑
      *
@@ -3910,6 +4299,28 @@ declare class Core {
      * @returns ECS API实例，如果未初始化则返回null
      */
     static get ecsAPI(): ECSFluentAPI | null;
+    /**
+     * 启用调试功能
+     *
+     * @param config 调试配置
+     */
+    static enableDebug(config: IECSDebugConfig): void;
+    /**
+     * 禁用调试功能
+     */
+    static disableDebug(): void;
+    /**
+     * 获取调试数据
+     *
+     * @returns 当前调试数据，如果调试未启用则返回null
+     */
+    static getDebugData(): any;
+    /**
+     * 检查调试是否启用
+     *
+     * @returns 调试状态
+     */
+    static get isDebugEnabled(): boolean;
     /**
      * 场景切换回调
      *
@@ -5059,4 +5470,4 @@ declare class Time {
 }
 
 export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentIndexManager, ComponentPool, ComponentStorage, ComponentTypeManager, Core, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, createECSAPI };
-export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentEventData, IEntityEventData, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceEventData, IPoolable, ISceneEventData, ISystemBase, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceDebugData, IPerformanceEventData, IPoolable, ISceneDebugData, ISceneEventData, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };