@esengine/ecs-framework 2.1.46 → 2.1.48

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.46
+ * @esengine/ecs-framework v2.1.48
  * TypeScript definitions
  */
 /**
@@ -1353,6 +1353,41 @@ interface ILogger {
     error(message: string, ...args: unknown[]): void;
     fatal(message: string, ...args: unknown[]): void;
 }
+/**
+ * 日志颜色配置接口
+ */
+interface LoggerColorConfig {
+    debug?: string;
+    info?: string;
+    warn?: string;
+    error?: string;
+    fatal?: string;
+    reset?: string;
+}
+/**
+ * 预定义的颜色常量
+ */
+declare const Colors: {
+    readonly BLACK: "\u001B[30m";
+    readonly RED: "\u001B[31m";
+    readonly GREEN: "\u001B[32m";
+    readonly YELLOW: "\u001B[33m";
+    readonly BLUE: "\u001B[34m";
+    readonly MAGENTA: "\u001B[35m";
+    readonly CYAN: "\u001B[36m";
+    readonly WHITE: "\u001B[37m";
+    readonly BRIGHT_BLACK: "\u001B[90m";
+    readonly BRIGHT_RED: "\u001B[91m";
+    readonly BRIGHT_GREEN: "\u001B[92m";
+    readonly BRIGHT_YELLOW: "\u001B[93m";
+    readonly BRIGHT_BLUE: "\u001B[94m";
+    readonly BRIGHT_MAGENTA: "\u001B[95m";
+    readonly BRIGHT_CYAN: "\u001B[96m";
+    readonly BRIGHT_WHITE: "\u001B[97m";
+    readonly RESET: "\u001B[0m";
+    readonly BOLD: "\u001B[1m";
+    readonly UNDERLINE: "\u001B[4m";
+};
 /**
  * 日志配置
  */
@@ -1367,6 +1402,8 @@ interface LoggerConfig {
     prefix?: string;
     /** 自定义输出函数 */
     output?: (level: LogLevel, message: string) => void;
+    /** 自定义颜色配置 */
+    colors?: LoggerColorConfig;
 }
 /**
  * 默认控制台日志实现
@@ -1409,6 +1446,11 @@ declare class ConsoleLogger implements ILogger {
      * @param level 日志级别
      */
     setLevel(level: LogLevel): void;
+    /**
+     * 设置颜色配置
+     * @param colors 颜色配置
+     */
+    setColors(colors: LoggerColorConfig): void;
     /**
      * 设置日志前缀
      * @param prefix 前缀字符串
@@ -1441,6 +1483,7 @@ declare class LoggerManager {
     private static _instance;
     private _loggers;
     private _defaultLogger;
+    private _defaultLevel;
     private constructor();
     /**
      * 获取日志管理器实例
@@ -1471,6 +1514,15 @@ declare class LoggerManager {
      * @returns 子日志器实例
      */
     createChildLogger(parentName: string, childName: string): ILogger;
+    /**
+     * 设置全局颜色配置
+     * @param colors 颜色配置
+     */
+    setGlobalColors(colors: LoggerColorConfig): void;
+    /**
+     * 重置为默认颜色配置
+     */
+    resetColors(): void;
 }
 /**
  * 默认日志器实例
@@ -1482,6 +1534,15 @@ declare const Logger: ILogger;
  * @returns 日志器实例
  */
 declare function createLogger(name: string): ILogger;
+/**
+ * 设置全局日志颜色配置
+ * @param colors 颜色配置
+ */
+declare function setLoggerColors(colors: LoggerColorConfig): void;
+/**
+ * 重置日志颜色为默认配置
+ */
+declare function resetLoggerColors(): void;
 /**
  * 设置全局日志级别
  * @param level 日志级别
@@ -3370,6 +3431,7 @@ declare abstract class EntitySystem implements ISystemBase {
     private _initialized;
     private _matcher;
     private _trackedEntities;
+    private _eventListeners;
     /**
      * 获取系统处理的实体列表（动态查询）
      */
@@ -3494,7 +3556,7 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entities 要处理的实体列表
      */
-    protected process(_entities: Entity[]): void;
+    protected process(entities: Entity[]): void;
     /**
      * 后期处理实体列表
      *
@@ -3551,7 +3613,7 @@ declare abstract class EntitySystem implements ISystemBase {
      *
      * @param entity 被添加的实体
      */
-    protected onAdded(_entity: Entity): void;
+    protected onAdded(entity: Entity): void;
     /**
      * 当实体从系统中移除时调用
      *
@@ -3559,7 +3621,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;
 }
 
 /**
@@ -4959,8 +5052,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;
@@ -4974,9 +5075,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;
@@ -5013,8 +5123,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>;
     /**
      * 格式化属性值
      */
@@ -5037,8 +5150,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;
     /**
      * 根据路径获取对象
      */
@@ -5051,8 +5168,10 @@ declare class EntityDataCollector {
 declare class SystemDataCollector {
     /**
      * 收集系统数据
+     * @param performanceMonitor 性能监视器实例
+     * @param scene 场景实例
      */
-    collectSystemData(performanceMonitor: any): ISystemDebugData;
+    collectSystemData(performanceMonitor: any, scene?: IScene | null): ISystemDebugData;
 }
 
 /**
@@ -5093,8 +5212,9 @@ declare class ComponentDataCollector {
     private static componentSizeCache;
     /**
      * 收集组件数据（轻量版，不计算实际内存大小）
+     * @param scene 场景实例
      */
-    collectComponentData(): IComponentDebugData;
+    collectComponentData(scene?: IScene | null): IComponentDebugData;
     /**
      * 获取组件类型的估算内存大小（基于预设值，不进行实际计算）
      */
@@ -5103,8 +5223,10 @@ declare class ComponentDataCollector {
     /**
      * 为内存快照功能提供的详细内存计算
      * 只在用户主动请求内存快照时调用
+     * @param typeName 组件类型名称
+     * @param scene 场景实例
      */
-    calculateDetailedComponentMemory(typeName: string): number;
+    calculateDetailedComponentMemory(typeName: string, scene?: IScene | null): number;
     /**
      * 估算对象内存大小（仅用于内存快照）
      * 优化版本：减少递归深度，提高性能
@@ -5120,8 +5242,9 @@ declare class SceneDataCollector {
     private sceneStartTime;
     /**
      * 收集场景数据
+     * @param scene 场景实例
      */
-    collectSceneData(): ISceneDebugData;
+    collectSceneData(scene?: IScene | null): ISceneDebugData;
     /**
      * 设置场景开始时间
      */
@@ -5200,11 +5323,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);
     /**
      * 启动调试管理器
      */
@@ -7217,5 +7347,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMask64Utils, Bits, COMPONENT_TYPE_NAME, 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, setGlobalLogLevel };
-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, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+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 };