@esengine/ecs-framework/index.d.ts

用于Laya、Cocos Creator等JavaScript游戏引擎的高性能ECS框架

/**
 * @esengine/ecs-framework v2.1.47
 * TypeScript definitions
 */
/**
 * 全局管理器的基类。所有全局管理器都应该从此类继承。
 */
declare class GlobalManager {
    /**
     * 表示管理器是否启用
     */
    _enabled: boolean;
    /**
     * 获取或设置管理器是否启用
     */
    get enabled(): boolean;
    set enabled(value: boolean);
    /**
     * 设置管理器是否启用
     * @param isEnabled 如果为true，则启用管理器；否则禁用管理器
     */
    setEnabled(isEnabled: boolean): void;
    /**
     * 在启用管理器时调用的回调方法
     */
    protected onEnabled(): void;
    /**
     * 在禁用管理器时调用的回调方法
     */
    protected onDisabled(): void;
    /**
     * 更新管理器状态的方法
     */
    update(): void;
}

interface ITimer<TContext = unknown> {
    context: TContext;
    /**
     * 调用stop以停止此计时器再次运行。这对非重复计时器没有影响。
     */
    stop(): void;
    /**
     * 将计时器的运行时间重置为0
     */
    reset(): void;
    /**
     * 返回投向T的上下文，作为方便
     */
    getContext<T>(): T;
}

/**
 * 私有类隐藏ITimer的实现
 */
declare class Timer<TContext = unknown> implements ITimer<TContext> {
    context: TContext;
    _timeInSeconds: number;
    _repeats: boolean;
    _onTime: (timer: ITimer<TContext>) => void;
    _isDone: boolean;
    _elapsedTime: number;
    getContext<T>(): T;
    /**
     * 定时器是否已完成
     */
    get isDone(): boolean;
    /**
     * 定时器已运行的时间
     */
    get elapsedTime(): number;
    reset(): void;
    stop(): void;
    tick(): boolean;
    initialize(timeInsSeconds: number, repeats: boolean, context: TContext, onTime: (timer: ITimer<TContext>) => void): void;
    /**
     * 空出对象引用，以便在js需要时GC可以清理它们的引用
     */
    unload(): void;
}

/**
 * 允许动作的延迟和重复执行
 */
declare class TimerManager extends GlobalManager {
    _timers: Array<Timer<unknown>>;
    update(): void;
    /**
     * 调度一个一次性或重复的计时器，该计时器将调用已传递的动作
     * @param timeInSeconds
     * @param repeats
     * @param context
     * @param onTime
     */
    schedule<TContext = unknown>(timeInSeconds: number, repeats: boolean, context: TContext, onTime: (timer: ITimer<TContext>) => void): Timer<TContext>;
}

/**
 * 性能监控数据
 */
interface PerformanceData {
    /** 系统名称 */
    name: string;
    /** 执行时间（毫秒） */
    executionTime: number;
    /** 处理的实体数量 */
    entityCount: number;
    /** 平均每个实体的处理时间 */
    averageTimePerEntity: number;
    /** 最后更新时间戳 */
    lastUpdateTime: number;
    /** 内存使用量（字节） */
    memoryUsage?: number;
    /** CPU使用率（百分比） */
    cpuUsage?: number;
}
/**
 * 性能统计信息
 */
interface PerformanceStats {
    /** 总执行时间 */
    totalTime: number;
    /** 平均执行时间 */
    averageTime: number;
    /** 最小执行时间 */
    minTime: number;
    /** 最大执行时间 */
    maxTime: number;
    /** 执行次数 */
    executionCount: number;
    /** 最近的执行时间列表 */
    recentTimes: number[];
    /** 标准差 */
    standardDeviation: number;
    /** 95百分位数 */
    percentile95: number;
    /** 99百分位数 */
    percentile99: number;
}
/**
 * 性能警告类型
 */
declare enum PerformanceWarningType {
    HIGH_EXECUTION_TIME = "high_execution_time",
    HIGH_MEMORY_USAGE = "high_memory_usage",
    HIGH_CPU_USAGE = "high_cpu_usage",
    FREQUENT_GC = "frequent_gc",
    LOW_FPS = "low_fps",
    HIGH_ENTITY_COUNT = "high_entity_count"
}
/**
 * 性能警告
 */
interface PerformanceWarning {
    type: PerformanceWarningType;
    systemName: string;
    message: string;
    severity: 'low' | 'medium' | 'high' | 'critical';
    timestamp: number;
    value: number;
    threshold: number;
    suggestion?: string;
}
/**
 * 性能阈值配置
 */
interface PerformanceThresholds {
    /** 执行时间阈值（毫秒） */
    executionTime: {
        warning: number;
        critical: number;
    };
    /** 内存使用阈值（MB） */
    memoryUsage: {
        warning: number;
        critical: number;
    };
    /** CPU使用率阈值（百分比） */
    cpuUsage: {
        warning: number;
        critical: number;
    };
    /** FPS阈值 */
    fps: {
        warning: number;
        critical: number;
    };
    /** 实体数量阈值 */
    entityCount: {
        warning: number;
        critical: number;
    };
}
/**
 * 高性能监控器
 * 用于监控ECS系统的性能表现，提供详细的分析和优化建议
 */
declare class PerformanceMonitor {
    private static _instance;
    private _systemData;
    private _systemStats;
    private _warnings;
    private _isEnabled;
    private _maxRecentSamples;
    private _maxWarnings;
    private _thresholds;
    private _fpsHistory;
    private _lastFrameTime;
    private _frameCount;
    private _fpsUpdateInterval;
    private _lastFpsUpdate;
    private _currentFps;
    private _memoryCheckInterval;
    private _lastMemoryCheck;
    private _memoryHistory;
    private _gcCount;
    private _lastGcCheck;
    private _gcCheckInterval;
    /**
     * 获取单例实例
     */
    static get instance(): PerformanceMonitor;
    private constructor();
    /**
     * 启用性能监控
     */
    enable(): void;
    /**
     * 禁用性能监控
     */
    disable(): void;
    /**
     * 检查是否启用了性能监控
     */
    get isEnabled(): boolean;
    /**
     * 开始监控系统性能
     * @param systemName 系统名称
     * @returns 开始时间戳
     */
    startMonitoring(systemName: string): number;
    /**
     * 结束监控并记录性能数据
     * @param systemName 系统名称
     * @param startTime 开始时间戳
     * @param entityCount 处理的实体数量
     */
    endMonitoring(systemName: string, startTime: number, entityCount?: number): void;
    /**
     * 更新系统统计信息
     * @param systemName 系统名称
     * @param executionTime 执行时间
     */
    private updateStats;
    /**
     * 计算高级统计信息
     * @param stats 统计信息对象
     */
    private calculateAdvancedStats;
    /**
     * 获取系统的当前性能数据
     * @param systemName 系统名称
     * @returns 性能数据或undefined
     */
    getSystemData(systemName: string): PerformanceData | undefined;
    /**
     * 获取系统的统计信息
     * @param systemName 系统名称
     * @returns 统计信息或undefined
     */
    getSystemStats(systemName: string): PerformanceStats | undefined;
    /**
     * 获取所有系统的性能数据
     * @returns 所有系统的性能数据
     */
    getAllSystemData(): Map<string, PerformanceData>;
    /**
     * 获取所有系统的统计信息
     * @returns 所有系统的统计信息
     */
    getAllSystemStats(): Map<string, PerformanceStats>;
    /**
     * 获取性能报告
     * @returns 格式化的性能报告字符串
     */
    getPerformanceReport(): string;
    /**
     * 重置所有性能数据
     */
    reset(): void;
    /**
     * 重置指定系统的性能数据
     * @param systemName 系统名称
     */
    resetSystem(systemName: string): void;
    /**
     * 获取性能警告
     * @param thresholdMs 警告阈值（毫秒）
     * @returns 超过阈值的系统列表
     */
    getPerformanceWarnings(thresholdMs?: number): string[];
    /**
     * 设置最大保留样本数
     * @param maxSamples 最大样本数
     */
    setMaxRecentSamples(maxSamples: number): void;
}

/**
 * 可池化对象接口
 */
interface IPoolable {
    /**
     * 重置对象状态，准备重用
     */
    reset(): void;
}
/**
 * 对象池统计信息
 */
interface PoolStats {
    /** 池中对象数量 */
    size: number;
    /** 池的最大大小 */
    maxSize: number;
    /** 总共创建的对象数量 */
    totalCreated: number;
    /** 总共获取的次数 */
    totalObtained: number;
    /** 总共释放的次数 */
    totalReleased: number;
    /** 命中率（从池中获取的比例） */
    hitRate: number;
    /** 内存使用估算（字节） */
    estimatedMemoryUsage: number;
}

/**
 * 高性能通用对象池
 * 支持任意类型的对象池化，包含详细的统计信息
 */
declare class Pool<T extends IPoolable> {
    private static _pools;
    private _objects;
    private _createFn;
    private _maxSize;
    private _stats;
    private _objectSize;
    /**
     * 构造函数
     * @param createFn 创建对象的函数
     * @param maxSize 池的最大大小，默认100
     * @param estimatedObjectSize 估算的单个对象大小（字节），默认1024
     */
    constructor(createFn: () => T, maxSize?: number, estimatedObjectSize?: number);
    /**
     * 获取指定类型的对象池
     * @param type 对象类型
     * @param maxSize 池的最大大小
     * @param estimatedObjectSize 估算的单个对象大小
     * @returns 对象池实例
     */
    static getPool<T extends IPoolable>(type: new (...args: unknown[]) => T, maxSize?: number, estimatedObjectSize?: number): Pool<T>;
    /**
     * 从池中获取对象
     * @returns 对象实例
     */
    obtain(): T;
    /**
     * 释放对象回池中
     * @param obj 要释放的对象
     */
    release(obj: T): void;
    /**
     * 获取池统计信息
     * @returns 统计信息对象
     */
    getStats(): Readonly<PoolStats>;
    /**
     * 清空池
     */
    clear(): void;
    /**
     * 压缩池（移除多余的对象）
     * @param targetSize 目标大小，默认为当前大小的一半
     */
    compact(targetSize?: number): void;
    /**
     * 预填充池
     * @param count 预填充的对象数量
     */
    prewarm(count: number): void;
    /**
     * 设置最大池大小
     * @param maxSize 新的最大大小
     */
    setMaxSize(maxSize: number): void;
    /**
     * 获取池中可用对象数量
     * @returns 可用对象数量
     */
    getAvailableCount(): number;
    /**
     * 检查池是否为空
     * @returns 如果池为空返回true
     */
    isEmpty(): boolean;
    /**
     * 检查池是否已满
     * @returns 如果池已满返回true
     */
    isFull(): boolean;
    /**
     * 获取所有已注册的池类型
     * @returns 所有池类型的数组
     */
    static getAllPoolTypes(): Function[];
    /**
     * 获取所有池的统计信息
     * @returns 包含所有池统计信息的对象
     */
    static getAllPoolStats(): Record<string, PoolStats>;
    /**
     * 压缩所有池
     */
    static compactAllPools(): void;
    /**
     * 清空所有池
     */
    static clearAllPools(): void;
    /**
     * 获取全局池统计信息的格式化字符串
     * @returns 格式化的统计信息字符串
     */
    static getGlobalStatsString(): string;
    /**
     * 更新命中率
     */
    private _updateHitRate;
    /**
     * 更新内存使用估算
     */
    private _updateMemoryUsage;
}

/**
 * 池管理器
 * 统一管理所有对象池
 */
declare class PoolManager {
    private static instance;
    private pools;
    private autoCompactInterval;
    private lastCompactTime;
    static getInstance(): PoolManager;
    /**
     * 注册池
     * @param name 池名称
     * @param pool 池实例
     */
    registerPool<T extends IPoolable>(name: string, pool: Pool<T>): void;
    /**
     * 获取池
     * @param name 池名称
     * @returns 池实例
     */
    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, PoolStats>;
    /**
     * 获取总体统计信息
     * @returns 总体统计信息
     */
    getGlobalStats(): PoolStats;
    /**
     * 获取格式化的统计信息字符串
     * @returns 格式化字符串
     */
    getStatsString(): string;
    /**
     * 设置自动压缩间隔
     * @param intervalMs 间隔毫秒数
     */
    setAutoCompactInterval(intervalMs: number): void;
    /**
     * 预填充所有池
     */
    prewarmAllPools(): void;
    /**
     * 重置池管理器
     */
    reset(): void;
}

/**
 * 框架核心类型定义
 */
/**
 * 组件接口
 *
 * 定义组件的基本契约，所有组件都应该实现此接口
 */
interface IComponent {
    /** 组件唯一标识符 */
    readonly id: number;
    /** 组件所属的实体ID */
    entityId?: string | number;
    /** 组件启用状态 */
    enabled: boolean;
    /** 更新顺序 */
    updateOrder: number;
    /** 组件添加到实体时的回调 */
    onAddedToEntity(): void;
    /** 组件从实体移除时的回调 */
    onRemovedFromEntity(): void;
    /** 组件启用时的回调 */
    onEnabled(): void;
    /** 组件禁用时的回调 */
    onDisabled(): void;
    /** 更新组件 */
    update(): void;
}
/**
 * 系统基础接口
 *
 * 为现有的EntitySystem类提供类型定义
 */
interface ISystemBase {
    /** 系统名称 */
    readonly systemName: string;
    /** 更新顺序/优先级 */
    updateOrder: number;
    /** 系统启用状态 */
    enabled: boolean;
    /** 系统初始化 */
    initialize(): void;
    /** 更新系统（主要处理阶段） */
    update(): void;
    /** 延迟更新系统 */
    lateUpdate?(): void;
}
/**
 * 组件类型定义
 *
 * 用于类型安全的组件操作
 * 支持任意构造函数签名，提供更好的类型安全性
 */
type ComponentType$1<T extends IComponent = IComponent> = new (...args: any[]) => T;
/**
 * 事件总线接口
 * 提供类型安全的事件发布订阅机制
 */
interface IEventBus {
    /**
     * 发射事件
     * @param eventType 事件类型
     * @param data 事件数据
     */
    emit<T>(eventType: string, data: T): void;
    /**
     * 异步发射事件
     * @param eventType 事件类型
     * @param data 事件数据
     */
    emitAsync<T>(eventType: string, data: T): Promise<void>;
    /**
     * 监听事件
     * @param eventType 事件类型
     * @param handler 事件处理器
     * @param config 监听器配置
     * @returns 监听器ID
     */
    on<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
    /**
     * 监听事件（一次性）
     * @param eventType 事件类型
     * @param handler 事件处理器
     * @param config 监听器配置
     * @returns 监听器ID
     */
    once<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
    /**
     * 异步监听事件
     * @param eventType 事件类型
     * @param handler 异步事件处理器
     * @param config 监听器配置
     * @returns 监听器ID
     */
    onAsync<T>(eventType: string, handler: (data: T) => Promise<void>, config?: IEventListenerConfig): string;
    /**
     * 移除事件监听器
     * @param eventType 事件类型
     * @param listenerId 监听器ID
     */
    off(eventType: string, listenerId: string): boolean;
    /**
     * 移除指定事件类型的所有监听器
     * @param eventType 事件类型
     */
    offAll(eventType: string): void;
    /**
     * 检查是否有指定事件的监听器
     * @param eventType 事件类型
     */
    hasListeners(eventType: string): boolean;
    /**
     * 获取事件统计信息
     * @param eventType 事件类型（可选）
     */
    getStats(eventType?: string): IEventStats | Map<string, IEventStats>;
    /**
     * 清空所有监听器
     */
    clear(): void;
}
/**
 * 事件监听器配置接口
 */
interface IEventListenerConfig {
    /** 是否只执行一次 */
    once?: boolean;
    /** 优先级（数字越大优先级越高） */
    priority?: number;
    /** 是否异步执行 */
    async?: boolean;
    /** 执行上下文 */
    context?: unknown;
}
/**
 * 事件统计信息接口
 */
interface IEventStats {
    /** 事件类型 */
    eventType: string;
    /** 监听器数量 */
    listenerCount: number;
    /** 触发次数 */
    triggerCount: number;
    /** 总执行时间（毫秒） */
    totalExecutionTime: number;
    /** 平均执行时间（毫秒） */
    averageExecutionTime: number;
    /** 最后触发时间 */
    lastTriggerTime: number;
}
/**
 * 事件数据基类接口
 */
interface IEventData {
    /** 事件时间戳 */
    timestamp: number;
    /** 事件来源 */
    source?: string;
    /** 事件ID */
    eventId?: string;
}
/**
 * 实体事件数据接口
 */
interface IEntityEventData extends IEventData {
    /** 实体ID */
    entityId: number;
    /** 实体名称 */
    entityName?: string;
    /** 实体标签 */
    entityTag?: string;
}
/**
 * 组件事件数据接口
 */
interface IComponentEventData extends IEntityEventData {
    /** 组件类型名称 */
    componentType: string;
    /** 组件实例 */
    component?: IComponent;
}
/**
 * 系统事件数据接口
 */
interface ISystemEventData extends IEventData {
    /** 系统名称 */
    systemName: string;
    /** 系统类型 */
    systemType: string;
}
/**
 * 场景事件数据接口
 */
interface ISceneEventData extends IEventData {
    /** 场景名称 */
    sceneName: string;
    /** 前一个场景名称 */
    previousSceneName?: string;
}
/**
 * 性能事件数据接口
 */
interface IPerformanceEventData extends IEventData {
    /** 操作类型 */
    operation: string;
    /** 执行时间（毫秒） */
    executionTime: number;
    /** 内存使用量 */
    memoryUsage?: number;
    /** 额外数据 */
    metadata?: Record<string, unknown>;
}
/**
 * ECS调试配置接口
 */
interface IECSDebugConfig {
    /** 是否启用调试 */
    enabled: boolean;
    /** WebSocket服务器URL */
    websocketUrl: string;
    /** 是否自动重连 */
    autoReconnect?: boolean;
    /** 数据更新间隔（毫秒）- 已弃用，使用debugFrameRate替代 */
    updateInterval?: number;
    /** 调试数据发送帧率 (60fps, 30fps, 15fps) */
    debugFrameRate?: 60 | 30 | 15;
    /** 数据通道配置 */
    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 IEntityHierarchyNode {
    id: number;
    name: string;
    active: boolean;
    enabled: boolean;
    activeInHierarchy: boolean;
    componentCount: number;
    componentTypes: string[];
    parentId: number | null;
    children: IEntityHierarchyNode[];
    depth: number;
    tag: number;
    updateOrder: number;
}
/**
 * 实体调试数据接口
 */
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[];
    }>;
    /** 实体层次结构（根实体） */
    entityHierarchy?: Array<{
        id: number;
        name: string;
        active: boolean;
        enabled: boolean;
        activeInHierarchy: boolean;
        componentCount: number;
        componentTypes: string[];
        parentId: number | null;
        children: IEntityHierarchyNode[];
        depth: number;
        tag: number;
        updateOrder: number;
    }>;
    /** 实体详细信息映射 */
    entityDetailsMap?: Record<number, {
        id: number;
        name: string;
        active: boolean;
        enabled: boolean;
        activeInHierarchy: boolean;
        destroyed: boolean;
        tag: number;
        updateOrder: number;
        componentMask: string;
        parentId: number | null;
        parentName: string | null;
        childCount: number;
        childIds: number[];
        depth: number;
        components: Array<{
            typeName: string;
            properties: Record<string, unknown>;
        }>;
        componentCount: number;
        componentTypes: 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;
}

/**
 * 游戏组件基类
 *
 * ECS架构中的组件（Component），用于实现具体的游戏功能。
 * 组件包含数据和行为，可以被添加到实体上以扩展实体的功能。
 *
 * @example
 * ```typescript
 * class HealthComponent extends Component {
 *     public health: number = 100;
 *
 *     public takeDamage(damage: number): void {
 *         this.health -= damage;
 *         if (this.health <= 0) {
 *             this.entity.destroy();
 *         }
 *     }
 * }
 * ```
 */
declare abstract class Component implements IComponent {
    /**
     * 组件ID生成器
     *
     * 用于为每个组件分配唯一的ID。
     */
    static _idGenerator: number;
    /**
     * 组件唯一标识符
     *
     * 在整个游戏生命周期中唯一的数字ID。
     */
    readonly id: number;
    /**
     * 组件所属的实体
     *
     * 指向拥有此组件的实体实例。
     */
    entity: Entity;
    /**
     * 组件启用状态
     *
     * 控制组件是否参与更新循环。
     */
    private _enabled;
    /**
     * 更新顺序
     *
     * 决定组件在更新循环中的执行顺序。
     */
    private _updateOrder;
    /**
     * 创建组件实例
     *
     * 自动分配唯一ID给组件。
     */
    constructor();
    /**
     * 获取组件启用状态
     *
     * 组件的实际启用状态取决于自身状态和所属实体的状态。
     *
     * @returns 如果组件和所属实体都启用则返回true
     */
    get enabled(): boolean;
    /**
     * 设置组件启用状态
     *
     * 当状态改变时会触发相应的生命周期回调。
     *
     * @param value - 新的启用状态
     */
    set enabled(value: boolean);
    /**
     * 获取更新顺序
     *
     * @returns 组件的更新顺序值
     */
    get updateOrder(): number;
    /**
     * 设置更新顺序
     *
     * @param value - 新的更新顺序值
     */
    set updateOrder(value: number);
    /**
     * 组件添加到实体时的回调
     *
     * 当组件被添加到实体时调用，可以在此方法中进行初始化操作。
     */
    onAddedToEntity(): void;
    /**
     * 组件从实体移除时的回调
     *
     * 当组件从实体中移除时调用，可以在此方法中进行清理操作。
     */
    onRemovedFromEntity(): void;
    /**
     * 组件启用时的回调
     *
     * 当组件被启用时调用。
     */
    onEnabled(): void;
    /**
     * 组件禁用时的回调
     *
     * 当组件被禁用时调用。
     */
    onDisabled(): void;
    /**
     * 更新组件
     *
     * 每帧调用，用于更新组件的逻辑。
     * 子类应该重写此方法来实现具体的更新逻辑。
     */
    update(): void;
}

/**
 * 64位掩码兼容层
 */
/**
 * 64位掩码数据结构，使用两个32位整数表示
 */
interface BitMask64Data {
    /** 低32位 */
    lo: number;
    /** 高32位 */
    hi: number;
}
declare class BitMask64Utils {
    /** 零掩码常量，所有位都为0 */
    static readonly ZERO: BitMask64Data;
    /**
     * 根据位索引创建64位掩码
     * @param bitIndex 位索引，范围 [0, 63]
     * @returns 包含指定位设置为1的掩码
     * @throws 当位索引超出范围时抛出错误
     */
    static create(bitIndex: number): BitMask64Data;
    /**
     * 从32位数字创建64位掩码
     * @param value 32位数字值
     * @returns 低32位为输入值、高32位为0的掩码
     */
    static fromNumber(value: number): BitMask64Data;
    /**
     * 检查掩码是否包含任意指定的位
     * @param mask 要检查的掩码
     * @param bits 指定的位模式
     * @returns 如果掩码包含bits中的任意位则返回true
     */
    static hasAny(mask: BitMask64Data, bits: BitMask64Data): boolean;
    /**
     * 检查掩码是否包含所有指定的位
     * @param mask 要检查的掩码
     * @param bits 指定的位模式
     * @returns 如果掩码包含bits中的所有位则返回true
     */
    static hasAll(mask: BitMask64Data, bits: BitMask64Data): boolean;
    /**
     * 检查掩码是否不包含任何指定的位
     * @param mask 要检查的掩码
     * @param bits 指定的位模式
     * @returns 如果掩码不包含bits中的任何位则返回true
     */
    static hasNone(mask: BitMask64Data, bits: BitMask64Data): boolean;
    /**
     * 检查掩码是否为零
     * @param mask 要检查的掩码
     * @returns 如果掩码所有位都为0则返回true
     */
    static isZero(mask: BitMask64Data): boolean;
    /**
     * 检查两个掩码是否相等
     * @param a 第一个掩码
     * @param b 第二个掩码
     * @returns 如果两个掩码完全相等则返回true
     */
    static equals(a: BitMask64Data, b: BitMask64Data): boolean;
    /**
     * 设置掩码中指定位为1
     * @param mask 要修改的掩码（原地修改）
     * @param bitIndex 位索引，范围 [0, 63]
     * @throws 当位索引超出范围时抛出错误
     */
    static setBit(mask: BitMask64Data, bitIndex: number): void;
    /**
     * 清除掩码中指定位为0
     * @param mask 要修改的掩码（原地修改）
     * @param bitIndex 位索引，范围 [0, 63]
     * @throws 当位索引超出范围时抛出错误
     */
    static clearBit(mask: BitMask64Data, bitIndex: number): void;
    /**
     * 对目标掩码执行按位或操作
     * @param target 目标掩码（原地修改）
     * @param other 用于按位或的掩码
     */
    static orInPlace(target: BitMask64Data, other: BitMask64Data): void;
    /**
     * 对目标掩码执行按位与操作
     * @param target 目标掩码（原地修改）
     * @param other 用于按位与的掩码
     */
    static andInPlace(target: BitMask64Data, other: BitMask64Data): void;
    /**
     * 对目标掩码执行按位异或操作
     * @param target 目标掩码（原地修改）
     * @param other 用于按位异或的掩码
     */
    static xorInPlace(target: BitMask64Data, other: BitMask64Data): void;
    /**
     * 清除掩码的所有位为0
     * @param mask 要清除的掩码（原地修改）
     */
    static clear(mask: BitMask64Data): void;
    /**
     * 将源掩码的值复制到目标掩码
     * @param source 源掩码
     * @param target 目标掩码（原地修改）
     */
    static copy(source: BitMask64Data, target: BitMask64Data): void;
    /**
     * 创建掩码的深拷贝
     * @param mask 要拷贝的掩码
     * @returns 新的掩码对象，内容与源掩码相同
     */
    static clone(mask: BitMask64Data): BitMask64Data;
    /**
     * 将掩码转换为字符串表示
     * @param mask 要转换的掩码
     * @param radix 进制，支持2（二进制）或16（十六进制），默认为2
     * @returns 掩码的字符串表示，二进制不带前缀，十六进制带0x前缀
     * @throws 当进制不支持时抛出错误
     */
    static toString(mask: BitMask64Data, radix?: number): string;
    /**
     * 计算掩码中设置为1的位数
     * @param mask 要计算的掩码
     * @returns 掩码中1的位数
     */
    static popCount(mask: BitMask64Data): number;
}

/**
 * 启用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;
    private complexFields;
    private entityToIndex;
    private indexToEntity;
    private freeIndices;
    private _size;
    private _capacity;
    readonly type: ComponentType<T>;
    constructor(componentType: ComponentType<T>);
    private initializeFields;
    addComponent(entityId: number, component: T): void;
    private updateComponentAtIndex;
    /**
     * 序列化值为JSON字符串
     */
    private serializeValue;
    /**
     * 反序列化JSON字符串为值
     */
    private deserializeValue;
    /**
     * 深拷贝对象
     */
    private deepClone;
    getComponent(entityId: number): T | null;
    private getFieldType;
    hasComponent(entityId: number): boolean;
    removeComponent(entityId: number): T | null;
    private resize;
    getActiveIndices(): number[];
    getFieldArray(fieldName: string): Float32Array | Float64Array | Int32Array | null;
    getTypedFieldArray<K extends keyof T>(fieldName: K): Float32Array | Float64Array | Int32Array | null;
    getEntityIndex(entityId: number): number | undefined;
    getEntityIdByIndex(index: number): number | undefined;
    size(): number;
    clear(): void;
    compact(): void;
    getStats(): any;
    /**
     * 执行向量化批量操作
     * @param operation 操作函数，接收字段数组和活跃索引
     */
    performVectorizedOperation(operation: (fieldArrays: Map<string, Float32Array | Float64Array | Int32Array>, activeIndices: number[]) => void): void;
}

/**
 * 日志级别
 */
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 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";
};
/**
 * 日志配置
 */
interface LoggerConfig {
    /** 日志级别 */
    level: LogLevel;
    /** 是否启用时间戳 */
    enableTimestamp: boolean;
    /** 是否启用颜色 */
    enableColors: boolean;
    /** 日志前缀 */
    prefix?: string;
    /** 自定义输出函数 */
    output?: (level: LogLevel, message: string) => void;
    /** 自定义颜色配置 */
    colors?: LoggerColorConfig;
}
/**
 * 默认控制台日志实现
 */
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 colors 颜色配置
     */
    setColors(colors: LoggerColorConfig): 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;
    /**
     * 设置全局颜色配置
     * @param colors 颜色配置
     */
    setGlobalColors(colors: LoggerColorConfig): void;
    /**
     * 重置为默认颜色配置
     */
    resetColors(): void;
}
/**
 * 默认日志器实例
 */
declare const Logger: ILogger;
/**
 * 创建命名日志器
 * @param name 日志器名称
 * @returns 日志器实例
 */
declare function createLogger(name: string): ILogger;
/**
 * 设置全局日志颜色配置
 * @param colors 颜色配置
 */
declare function setLoggerColors(colors: LoggerColorConfig): void;
/**
 * 重置日志颜色为默认配置
 */
declare function resetLoggerColors(): void;
/**
 * 设置全局日志级别
 * @param level 日志级别
 */
declare function setGlobalLogLevel(level: LogLevel): void;

/**
 * 组件类型定义
 */
type ComponentType<T extends Component = Component> = new (...args: any[]) => 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>): BitMask64Data;
    /**
     * 获取组件类型的位索引
     * @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): BitMask64Data;
    /**
     * 创建多个组件的掩码
     * @param componentNames 组件名称数组
     * @returns 组合掩码
     */
    static createComponentMask(componentNames: string[]): BitMask64Data;
    /**
     * 清除掩码缓存
     */
    static clearMaskCache(): void;
    /**
     * 重置注册表（用于测试）
     */
    static reset(): void;
}

/**
 * 高性能组件存储器
 */
declare class ComponentStorage<T extends Component> {
    private dense;
    private entityIds;
    private entityToIndex;
    private componentType;
    constructor(componentType: ComponentType<T>);
    /**
     * 添加组件
     * @param entityId 实体ID
     * @param component 组件实例
     */
    addComponent(entityId: number, component: T): void;
    /**
     * 获取组件
     * @param entityId 实体ID
     * @returns 组件实例或null
     */
    getComponent(entityId: number): T | null;
    /**
     * 检查实体是否有此组件
     * @param entityId 实体ID
     * @returns 是否有组件
     */
    hasComponent(entityId: number): boolean;
    /**
     * 移除组件
     * @param entityId 实体ID
     * @returns 被移除的组件或null
     */
    removeComponent(entityId: number): T | null;
    /**
     * 高效遍历所有组件
     * @param callback 回调函数
     */
    forEach(callback: (component: T, entityId: number, index: number) => void): void;
    /**
     * 获取所有组件
     * @returns 组件数组
     */
    getDenseArray(): {
        components: T[];
        entityIds: number[];
    };
    /**
     * 清空所有组件
     */
    clear(): void;
    /**
     * 获取组件数量
     */
    get size(): number;
    /**
     * 获取组件类型
     */
    get type(): ComponentType<T>;
    /**
     * 获取存储统计信息
     */
    getStats(): {
        totalSlots: number;
        usedSlots: number;
        freeSlots: number;
        fragmentation: number;
    };
}
/**
 * 组件存储管理器
 * 管理所有组件类型的存储器
 */
declare class ComponentStorageManager {
    private static readonly _logger;
    private storages;
    /**
     * 检查组件类型是否启用SoA存储
     * @param componentType 组件类型
     * @returns 是否为SoA存储
     */
    isSoAStorage<T extends Component>(componentType: ComponentType<T>): boolean;
    /**
     * 获取SoA存储器（类型安全）
     * @param componentType 组件类型
     * @returns SoA存储器或null
     */
    getSoAStorage<T extends Component>(componentType: ComponentType<T>): SoAStorage<T> | null;
    /**
     * 直接获取SoA字段数组（类型安全）
     * @param componentType 组件类型
     * @param fieldName 字段名
     * @returns TypedArray或null
     */
    getFieldArray<T extends Component>(componentType: ComponentType<T>, fieldName: string): Float32Array | Float64Array | Int32Array | null;
    /**
     * 直接获取SoA字段数组（类型安全，带字段名检查）
     * @param componentType 组件类型
     * @param fieldName 字段名（类型检查）
     * @returns TypedArray或null
     */
    getTypedFieldArray<T extends Component, K extends keyof T>(componentType: ComponentType<T>, fieldName: K): Float32Array | Float64Array | Int32Array | null;
    /**
     * 获取SoA存储的活跃索引
     * @param componentType 组件类型
     * @returns 活跃索引数组或空数组
     */
    getActiveIndices<T extends Component>(componentType: ComponentType<T>): number[];
    /**
     * 获取实体在SoA存储中的索引
     * @param componentType 组件类型
     * @param entityId 实体ID
     * @returns 存储索引或undefined
     */
    getEntityIndex<T extends Component>(componentType: ComponentType<T>, entityId: number): number | undefined;
    /**
     * 根据索引获取实体ID
     * @param componentType 组件类型
     * @param index 存储索引
     * @returns 实体ID或undefined
     */
    getEntityIdByIndex<T extends Component>(componentType: ComponentType<T>, index: number): number | undefined;
    /**
     * 获取或创建组件存储器（默认原始存储）
     * @param componentType 组件类型
     * @returns 组件存储器
     */
    getStorage<T extends Component>(componentType: ComponentType<T>): ComponentStorage<T> | SoAStorage<T>;
    /**
     * 添加组件
     * @param entityId 实体ID
     * @param component 组件实例
     */
    addComponent<T extends Component>(entityId: number, component: T): void;
    /**
     * 获取组件
     * @param entityId 实体ID
     * @param componentType 组件类型
     * @returns 组件实例或null
     */
    getComponent<T extends Component>(entityId: number, componentType: ComponentType<T>): T | null;
    /**
     * 检查实体是否有组件
     * @param entityId 实体ID
     * @param componentType 组件类型
     * @returns 是否有组件
     */
    hasComponent<T extends Component>(entityId: number, componentType: ComponentType<T>): boolean;
    /**
     * 移除组件
     * @param entityId 实体ID
     * @param componentType 组件类型
     * @returns 被移除的组件或null
     */
    removeComponent<T extends Component>(entityId: number, componentType: ComponentType<T>): T | null;
    /**
     * 移除实体的所有组件
     * @param entityId 实体ID
     */
    removeAllComponents(entityId: number): void;
    /**
     * 获取实体的组件位掩码
     * @param entityId 实体ID
     * @returns 组件位掩码
     */
    getComponentMask(entityId: number): BitMask64Data;
    /**
     * 获取所有存储器的统计信息
     */
    getAllStats(): Map<string, any>;
    /**
     * 清空所有存储器
     */
    clear(): void;
}

/**
 * 增强的事件总线实现
 * 基于TypeSafeEventSystem，提供类型安全的事件发布订阅机制
 */
declare class EventBus implements IEventBus {
    private static readonly _logger;
    private eventSystem;
    private eventIdCounter;
    private isDebugMode;
    constructor(debugMode?: boolean);
    /**
     * 发射事件
     * @param eventType 事件类型
     * @param data 事件数据
     */
    emit<T>(eventType: string, data: T): void;
    /**
     * 异步发射事件
     * @param eventType 事件类型
     * @param data 事件数据
     */
    emitAsync<T>(eventType: string, data: T): Promise<void>;
    /**
     * 监听事件
     * @param eventType 事件类型
     * @param handler 事件处理器
     * @param config 监听器配置
     * @returns 监听器ID
     */
    on<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
    /**
     * 监听事件（一次性）
     * @param eventType 事件类型
     * @param handler 事件处理器
     * @param config 监听器配置
     * @returns 监听器ID
     */
    once<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
    /**
     * 异步监听事件
     * @param eventType 事件类型
     * @param handler 异步事件处理器
     * @param config 监听器配置
     * @returns 监听器ID
     */
    onAsync<T>(eventType: string, handler: (data: T) => Promise<void>, config?: IEventListenerConfig): string;
    /**
     * 移除事件监听器
     * @param eventType 事件类型
     * @param listenerId 监听器ID
     */
    off(eventType: string, listenerId: string): boolean;
    /**
     * 移除指定事件类型的所有监听器
     * @param eventType 事件类型
     */
    offAll(eventType: string): void;
    /**
     * 检查是否有指定事件的监听器
     * @param eventType 事件类型
     */
    hasListeners(eventType: string): boolean;
    /**
     * 获取事件统计信息
     * @param eventType 事件类型（可选）
     */
    getStats(eventType?: string): IEventStats | Map<string, IEventStats>;
    /**
     * 清空所有监听器
     */
    clear(): void;
    /**
     * 启用或禁用事件系统
     * @param enabled 是否启用
     */
    setEnabled(enabled: boolean): void;
    /**
     * 设置调试模式
     * @param debug 是否启用调试
     */
    setDebugMode(debug: boolean): void;
    /**
     * 设置最大监听器数量
     * @param max 最大数量
     */
    setMaxListeners(max: number): void;
    /**
     * 获取监听器数量
     * @param eventType 事件类型
     */
    getListenerCount(eventType: string): number;
    /**
     * 设置事件批处理配置
     * @param eventType 事件类型
     * @param batchSize 批处理大小
     * @param delay 延迟时间（毫秒）
     */
    setBatchConfig(eventType: string, batchSize: number, delay: number): void;
    /**
     * 刷新指定事件的批处理队列
     * @param eventType 事件类型
     */
    flushBatch(eventType: string): void;
    /**
     * 重置事件统计
     * @param eventType 事件类型（可选）
     */
    resetStats(eventType?: string): void;
    /**
     * 发射实体创建事件
     * @param entityData 实体事件数据
     */
    emitEntityCreated(entityData: IEntityEventData): void;
    /**
     * 发射实体销毁事件
     * @param entityData 实体事件数据
     */
    emitEntityDestroyed(entityData: IEntityEventData): void;
    /**
     * 发射组件添加事件
     * @param componentData 组件事件数据
     */
    emitComponentAdded(componentData: IComponentEventData): void;
    /**
     * 发射组件移除事件
     * @param componentData 组件事件数据
     */
    emitComponentRemoved(componentData: IComponentEventData): void;
    /**
     * 发射系统添加事件
     * @param systemData 系统事件数据
     */
    emitSystemAdded(systemData: ISystemEventData): void;
    /**
     * 发射系统移除事件
     * @param systemData 系统事件数据
     */
    emitSystemRemoved(systemData: ISystemEventData): void;
    /**
     * 发射场景变化事件
     * @param sceneData 场景事件数据
     */
    emitSceneChanged(sceneData: ISceneEventData): void;
    /**
     * 发射性能警告事件
     * @param performanceData 性能事件数据
     */
    emitPerformanceWarning(performanceData: IPerformanceEventData): void;
    /**
     * 监听实体创建事件
     * @param handler 事件处理器
     * @param config 监听器配置
     */
    onEntityCreated(handler: (data: IEntityEventData) => void, config?: IEventListenerConfig): string;
    /**
     * 监听组件添加事件
     * @param handler 事件处理器
     * @param config 监听器配置
     */
    onComponentAdded(handler: (data: IComponentEventData) => void, config?: IEventListenerConfig): string;
    /**
     * 监听系统错误事件
     * @param handler 事件处理器
     * @param config 监听器配置
     */
    onSystemError(handler: (data: ISystemEventData) => void, config?: IEventListenerConfig): string;
    /**
     * 监听性能警告事件
     * @param handler 事件处理器
     * @param config 监听器配置
     */
    onPerformanceWarning(handler: (data: IPerformanceEventData) => void, config?: IEventListenerConfig): string;
    /**
     * 验证事件类型
     * @param eventType 事件类型
     */
    private validateEventType;
    /**
     * 增强事件数据
     * @param eventType 事件类型
     * @param data 原始数据
     */
    private enhanceEventData;
    /**
     * 转换EventStats为IEventStats
     * @param stats EventStats实例
     */
    private convertEventStats;
}
/**
 * 全局事件总线实例
 * 提供全局访问的事件总线
 */
declare class GlobalEventBus {
    private static instance;
    /**
     * 获取全局事件总线实例
     * @param debugMode 是否启用调试模式
     */
    static getInstance(debugMode?: boolean): EventBus;
    /**
     * 重置全局事件总线实例
     * @param debugMode 是否启用调试模式
     */
    static reset(debugMode?: boolean): EventBus;
}
/**
 * 事件装饰器工厂
 * 用于自动注册事件监听器
 */
declare function EventHandler$1(eventType: string, config?: IEventListenerConfig): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
/**
 * 异步事件装饰器工厂
 * 用于自动注册异步事件监听器
 */
declare function AsyncEventHandler$1(eventType: string, config?: IEventListenerConfig): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

/**
 * 高性能实体列表管理器
 * 管理场景中的所有实体，支持快速查找和批量操作
 */
declare class EntityList {
    buffer: Entity[];
    private _scene;
    private _idToEntity;
    private _nameToEntities;
    private _entitiesToAdd;
    private _entitiesToRemove;
    private _isUpdating;
    get count(): number;
    constructor(scene: any);
    /**
     * 添加实体（立即添加或延迟添加）
     * @param entity 要添加的实体
     */
    add(entity: Entity): void;
    /**
     * 立即添加实体
     * @param entity 要添加的实体
     */
    private addImmediate;
    /**
     * 移除实体（立即移除或延迟移除）
     * @param entity 要移除的实体
     */
    remove(entity: Entity): void;
    /**
     * 立即移除实体
     * @param entity 要移除的实体
     */
    private removeImmediate;
    /**
     * 移除所有实体
     */
    removeAllEntities(): void;
    /**
     * 更新实体列表，处理延迟操作
     */
    updateLists(): void;
    /**
     * 更新所有实体
     */
    update(): void;
    /**
     * 根据名称查找实体（使用索引，O(1)复杂度）
     * @param name 实体名称
     * @returns 找到的第一个实体或null
     */
    findEntity(name: string): Entity | null;
    /**
     * 根据名称查找所有实体
     * @param name 实体名称
     * @returns 找到的所有实体数组
     */
    findEntitiesByName(name: string): Entity[];
    /**
     * 根据ID查找实体（使用索引，O(1)复杂度）
     * @param id 实体ID
     * @returns 找到的实体或null
     */
    findEntityById(id: number): Entity | null;
    /**
     * 根据标签查找实体
     * @param tag 标签
     * @returns 找到的所有实体数组
     */
    findEntitiesByTag(tag: number): Entity[];
    /**
     * 根据组件类型查找实体
     * @param componentType 组件类型
     * @returns 找到的所有实体数组
     */
    findEntitiesWithComponent<T extends Component>(componentType: new (...args: unknown[]) => T): Entity[];
    /**
     * 批量操作：对所有实体执行指定操作
     * @param action 要执行的操作
     */
    forEach(action: (entity: Entity) => void): void;
    /**
     * 批量操作：对符合条件的实体执行指定操作
     * @param predicate 筛选条件
     * @param action 要执行的操作
     */
    forEachWhere(predicate: (entity: Entity) => boolean, action: (entity: Entity) => void): void;
    /**
     * 更新名称索引
     * @param entity 实体
     * @param isAdd 是否为添加操作
     */
    private updateNameIndex;
    /**
     * 获取实体列表的统计信息
     * @returns 统计信息
     */
    getStats(): {
        totalEntities: number;
        activeEntities: number;
        pendingAdd: number;
        pendingRemove: number;
        nameIndexSize: number;
    };
}

/**
 * 查询条件类型
 */
interface QueryCondition {
    all: ComponentType[];
    any: ComponentType[];
    none: ComponentType[];
    tag?: number;
    name?: string;
    component?: ComponentType;
}
/**
 * 实体匹配条件描述符
 *
 * 用于描述实体查询条件，不执行实际查询
 *
 * @example
 * ```typescript
 * const matcher = Matcher.all(Position, Velocity)
 *   .any(Health, Shield)
 *   .none(Dead);
 *
 * // 获取查询条件
 * const condition = matcher.getCondition();
 * ```
 */
declare class Matcher {
    private readonly condition;
    private constructor();
    /**
     * 创建匹配器，要求所有指定的组件
     * @param types 组件类型
     */
    static all(...types: ComponentType[]): Matcher;
    /**
     * 创建匹配器，要求至少一个指定的组件
     * @param types 组件类型
     */
    static any(...types: ComponentType[]): Matcher;
    /**
     * 创建匹配器，排除指定的组件
     * @param types 组件类型
     */
    static none(...types: ComponentType[]): Matcher;
    /**
     * 创建按标签查询的匙配器
     * @param tag 标签值
     */
    static byTag(tag: number): Matcher;
    /**
     * 创建按名称查询的匙配器
     * @param name 实体名称
     */
    static byName(name: string): Matcher;
    /**
     * 创建单组件查询的匙配器
     * @param componentType 组件类型
     */
    static byComponent(componentType: ComponentType): Matcher;
    /**
     * 创建复杂查询构建器
     */
    static complex(): Matcher;
    /**
     * 创建空匙配器（向后兼容）
     */
    static empty(): Matcher;
    /**
     * 必须包含所有指定组件
     * @param types 组件类型
     */
    all(...types: ComponentType[]): Matcher;
    /**
     * 必须包含至少一个指定组件
     * @param types 组件类型
     */
    any(...types: ComponentType[]): Matcher;
    /**
     * 不能包含任何指定组件
     * @param types 组件类型
     */
    none(...types: ComponentType[]): Matcher;
    /**
     * 排除指定组件（别名方法）
     * @param types 组件类型
     */
    exclude(...types: ComponentType[]): Matcher;
    /**
     * 至少包含其中之一（别名方法）
     * @param types 组件类型
     */
    one(...types: ComponentType[]): Matcher;
    /**
     * 按标签查询
     * @param tag 标签值
     */
    withTag(tag: number): Matcher;
    /**
     * 按名称查询
     * @param name 实体名称
     */
    withName(name: string): Matcher;
    /**
     * 单组件查询
     * @param componentType 组件类型
     */
    withComponent(componentType: ComponentType): Matcher;
    /**
     * 移除标签条件
     */
    withoutTag(): Matcher;
    /**
     * 移除名称条件
     */
    withoutName(): Matcher;
    /**
     * 移除单组件条件
     */
    withoutComponent(): Matcher;
    /**
     * 获取查询条件（只读）
     */
    getCondition(): Readonly<QueryCondition>;
    /**
     * 检查是否为空条件
     */
    isEmpty(): boolean;
    /**
     * 重置所有条件
     */
    reset(): Matcher;
    /**
     * 克隆匹配器