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

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

/**
 * @esengine/ecs-framework v2.1.22
 * 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 {
    context: any;
    /**
     * 调用stop以停止此计时器再次运行。这对非重复计时器没有影响。
     */
    stop(): void;
    /**
     * 将计时器的运行时间重置为0
     */
    reset(): void;
    /**
     * 返回投向T的上下文，作为方便
     */
    getContext<T>(): T;
}

/**
 * 私有类隐藏ITimer的实现
 */
declare class Timer implements ITimer {
    context: any;
    _timeInSeconds: number;
    _repeats: boolean;
    _onTime: (timer: ITimer) => 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: any, onTime: (timer: ITimer) => void): void;
    /**
     * 空出对象引用，以便在js需要时GC可以清理它们的引用
     */
    unload(): void;
}

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

/**
 * 性能监控数据
 */
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: any[]) => T, maxSize?: number, estimatedObjectSize?: number): Pool<T>;
    /**
     * 从池中获取对象
     * @returns 对象实例
     */
    obtain(): T;
    /**
     * 将对象归还到池中
     * @param obj 要归还的对象
     */
    free(obj: T): void;
    /**
     * 预热池，创建指定数量的对象
     * @param count 要创建的对象数量
     */
    warmUp(count: number): void;
    /**
     * 清空池
     */
    clear(): void;
    /**
     * 获取池中对象数量
     */
    get size(): number;
    /**
     * 获取池的最大大小
     */
    get maxSize(): number;
    /**
     * 设置池的最大大小
     */
    set maxSize(value: number);
    /**
     * 获取池的统计信息
     */
    getStats(): PoolStats;
    /**
     * 重置统计信息
     */
    resetStats(): void;
    /**
     * 更新命中率
     */
    private _updateHitRate;
    /**
     * 更新内存使用估算
     */
    private _updateMemoryUsage;
    /**
     * 静态方法：从指定类型的池中获取对象
     * @param type 对象类型
     * @returns 对象实例
     */
    static obtain<T extends IPoolable>(type: new (...args: any[]) => T): T;
    /**
     * 静态方法：将对象归还到对应类型的池中
     * @param type 对象类型
     * @param obj 要归还的对象
     */
    static free<T extends IPoolable>(type: new (...args: any[]) => T, obj: T): void;
    /**
     * 静态方法：预热指定类型的池
     * @param type 对象类型
     * @param count 要创建的对象数量
     */
    static warmUp<T extends IPoolable>(type: new (...args: any[]) => T, count: number): void;
    /**
     * 静态方法：清空指定类型的池
     * @param type 对象类型
     */
    static clearPool<T extends IPoolable>(type: new (...args: any[]) => T): 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;
    /**
     * 清空所有池
     */
    clear(): void;
    /**
     * 获取统计信息
     */
    getStats(): {
        totalSize: number;
        totalMaxSize: number;
        totalMemoryUsage: number;
        tierStats: PoolStats[];
        hitRate: number;
    };
    /**
     * 获取总创建数量
     */
    private getTotalCreated;
}
/**
 * 池管理器
 * 统一管理所有对象池
 */
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> | TieredObjectPool<T>): void;
    /**
     * 获取池
     * @param name 池名称
     * @returns 池实例
     */
    getPool<T extends IPoolable>(name: string): Pool<T> | TieredObjectPool<T> | null;
    /**
     * 更新池管理器（应在游戏循环中调用）
     */
    update(): void;
    /**
     * 压缩所有池（清理碎片）
     */
    compactAllPools(): void;
    /**
     * 获取所有池的统计信息
     */
    getAllStats(): Map<string, any>;
    /**
     * 生成性能报告
     */
    generateReport(): string;
}

/**
 * 框架核心类型定义
 */
/**
 * 组件接口
 *
 * 定义组件的基本契约，所有组件都应该实现此接口
 */
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;
    /** 系统处理的实体列表 */
    readonly entities: readonly any[];
    /** 更新顺序/优先级 */
    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?: any;
}
/**
 * 事件统计信息接口
 */
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, 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;
}

/**
 * 游戏组件基类
 *
 * 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;
}

/**
 * 组件类型定义
 */
type ComponentType<T extends Component = Component> = new (...args: any[]) => T;
/**
 * 高性能组件存储器
 * 使用SoA（Structure of Arrays）模式存储组件
 */
declare class ComponentStorage<T extends Component> {
    private components;
    private entityToIndex;
    private indexToEntity;
    private freeIndices;
    private componentType;
    private _size;
    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>;
    /**
     * 压缩存储（移除空洞）
     */
    compact(): void;
    /**
     * 获取存储统计信息
     */
    getStats(): {
        totalSlots: number;
        usedSlots: number;
        freeSlots: number;
        fragmentation: number;
    };
}
/**
 * 组件存储管理器
 * 管理所有组件类型的存储器
 */
declare class ComponentStorageManager {
    private storages;
    /**
     * 获取或创建组件存储器
     * @param componentType 组件类型
     * @returns 组件存储器
     */
    getStorage<T extends Component>(componentType: ComponentType<T>): ComponentStorage<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): bigint;
    /**
     * 压缩所有存储器
     */
    compactAll(): void;
    /**
     * 获取所有存储器的统计信息
     */
    getAllStats(): Map<string, any>;
    /**
     * 清空所有存储器
     */
    clear(): void;
}

/**
 * 增强的事件总线实现
 * 基于TypeSafeEventSystem，提供类型安全的事件发布订阅机制
 */
declare class EventBus implements IEventBus {
    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;

/**
 * 实体比较器
 *
 * 用于比较两个实体的优先级，首先按更新顺序比较，然后按ID比较。
 */
declare class EntityComparer {
    /**
     * 比较两个实体
     *
     * @param self - 第一个实体
     * @param other - 第二个实体
     * @returns 比较结果，负数表示self优先级更高，正数表示other优先级更高，0表示相等
     */
    compare(self: Entity, other: Entity): number;
}
/**
 * 组件缓存配置
 */
interface ComponentCacheConfig {
    maxSize: number;
    ttl: number;
    enableLRU: boolean;
}
/**
 * 高性能组件缓存
 */
declare class ComponentCache {
    private cache;
    private accessOrder;
    private config;
    constructor(config?: ComponentCacheConfig);
    get<T extends Component>(type: ComponentType<T>): T | null;
    set<T extends Component>(type: ComponentType<T>, component: T): void;
    delete(type: ComponentType): boolean;
    clear(): void;
    has(type: ComponentType): boolean;
    private evictLeastRecentlyUsed;
    private updateAccessOrder;
    private removeFromAccessOrder;
    getStats(): {
        size: number;
        maxSize: number;
        hitRate: number;
        averageAccessCount: number;
    };
}
/**
 * 游戏实体类
 *
 * ECS架构中的实体（Entity），作为组件的容器。
 * 实体本身不包含游戏逻辑，所有功能都通过组件来实现。
 * 支持父子关系，可以构建实体层次结构。
 *
 * @example
 * ```typescript
 * // 创建实体
 * const entity = new Entity("Player", 1);
 *
 * // 添加组件
 * const healthComponent = entity.addComponent(new HealthComponent(100));
 *
 * // 获取组件
 * const health = entity.getComponent(HealthComponent);
 *
 * // 添加位置组件
 * entity.addComponent(new PositionComponent(100, 200));
 *
 * // 添加子实体
 * const weapon = new Entity("Weapon", 2);
 * entity.addChild(weapon);
 * ```
 */
declare class Entity {
    /**
     * 实体比较器实例
     */
    static entityComparer: EntityComparer;
    /**
     * 全局事件总线实例
     * 用于发射组件相关事件
     */
    static eventBus: EventBus | null;
    /**
     * 实体名称
     *
     * 用于标识和调试的友好名称。
     */
    name: string;
    /**
     * 实体唯一标识符
     *
     * 在场景中唯一的数字标识符。
     */
    readonly id: number;
    /**
     * 组件集合
     *
     * 存储实体拥有的所有组件。
     */
    readonly components: Component[];
    /**
     * 所属场景引用
     *
     * 指向实体所在的场景实例。
     */
    scene: any;
    /**
     * 更新间隔
     *
     * 控制实体更新的频率，值越大更新越不频繁。
     */
    updateInterval: number;
    /**
     * 销毁状态标志
     *
     * 标记实体是否已被销毁。
     */
    _isDestroyed: boolean;
    /**
     * 父实体引用
     *
     * 指向父级实体，用于构建实体层次结构。
     */
    private _parent;
    /**
     * 子实体集合
     *
     * 存储所有子级实体的数组。
     */
    private _children;
    /**
     * 激活状态
     *
     * 控制实体是否处于激活状态。
     */
    private _active;
    /**
     * 实体标签
     *
     * 用于分类和查询的数字标签。
     */
    private _tag;
    /**
     * 启用状态
     *
     * 控制实体是否启用更新和处理。
     */
    private _enabled;
    /**
     * 更新顺序
     *
     * 控制实体在系统中的更新优先级。
     */
    private _updateOrder;
    /**
     * 组件位掩码
     *
     * 用于快速查询实体拥有的组件类型。
     */
    private _componentMask;
    /**
     * 组件类型到索引的映射
     *
     * 用于快速定位组件在数组中的位置。
     */
    private _componentTypeToIndex;
    /**
     * 组件缓存
     *
     * 高性能组件访问缓存。
     */
    private _componentCache;
    /**
     * 组件访问统计
     *
     * 记录组件访问的性能统计信息。
     */
    private _componentAccessStats;
    /**
     * 构造函数
     *
     * @param name - 实体名称
     * @param id - 实体唯一标识符
     */
    constructor(name: string, id: number);
    /**
     * 获取销毁状态
     *
     * @returns 如果实体已被销毁则返回true
     */
    get isDestroyed(): boolean;
    /**
     * 获取父实体
     *
     * @returns 父实体，如果没有父实体则返回null
     */
    get parent(): Entity | null;
    /**
     * 获取子实体数组的只读副本
     *
     * @returns 子实体数组的副本
     */
    get children(): readonly Entity[];
    /**
     * 获取子实体数量
     *
     * @returns 子实体的数量
     */
    get childCount(): number;
    /**
     * 获取活跃状态
     *
     * @returns 如果实体处于活跃状态则返回true
     */
    get active(): boolean;
    /**
     * 设置活跃状态
     *
     * 设置实体的活跃状态，会影响子实体的有效活跃状态。
     *
     * @param value - 新的活跃状态
     */
    set active(value: boolean);
    /**
     * 获取实体的有效活跃状态
     *
     * 考虑父实体的活跃状态，只有当实体本身和所有父实体都处于活跃状态时才返回true。
     *
     * @returns 有效的活跃状态
     */
    get activeInHierarchy(): boolean;
    /**
     * 获取实体标签
     *
     * @returns 实体的数字标签
     */
    get tag(): number;
    /**
     * 设置实体标签
     *
     * @param value - 新的标签值
     */
    set tag(value: number);
    /**
     * 获取启用状态
     *
     * @returns 如果实体已启用则返回true
     */
    get enabled(): boolean;
    /**
     * 设置启用状态
     *
     * @param value - 新的启用状态
     */
    set enabled(value: boolean);
    /**
     * 获取更新顺序
     *
     * @returns 实体的更新顺序值
     */
    get updateOrder(): number;
    /**
     * 设置更新顺序
     *
     * @param value - 新的更新顺序值
     */
    set updateOrder(value: number);
    /**
     * 获取组件位掩码
     *
     * @returns 实体的组件位掩码
     */
    get componentMask(): bigint;
    /**
     * 创建并添加组件
     *
     * @param componentType - 组件类型
     * @param args - 组件构造函数参数
     * @returns 创建的组件实例
     */
    createComponent<T extends Component>(componentType: ComponentType<T>, ...args: any[]): T;
    /**
     * 内部添加组件方法（不进行重复检查，用于初始化）
     *
     * @param component - 要添加的组件实例
     * @returns 添加的组件实例
     */
    private addComponentInternal;
    /**
     * 添加组件到实体
     *
     * @param component - 要添加的组件实例
     * @returns 添加的组件实例
     * @throws {Error} 如果组件类型已存在
     */
    addComponent<T extends Component>(component: T): T;
    /**
     * 获取指定类型的组件
     *
     * @param type - 组件类型
     * @returns 组件实例或null
     */
    getComponent<T extends Component>(type: ComponentType<T>): T | null;
    /**
     * 更新组件访问统计
     *
     * @param type - 组件类型
     */
    private updateComponentAccessStats;
    /**
     * 记录缓存命中
     *
     * @param type - 组件类型
     */
    private recordCacheHit;
    /**
     * 记录缓存未命中
     *
     * @param type - 组件类型
     */
    private recordCacheMiss;
    /**
     * 重建组件索引映射
     */
    private rebuildComponentIndex;
    /**
     * 检查实体是否有指定类型的组件
     *
     * @param type - 组件类型
     * @returns 如果有该组件则返回true
     */
    hasComponent<T extends Component>(type: ComponentType<T>): boolean;
    /**
     * 获取或创建指定类型的组件
     *
     * @param type - 组件类型
     * @param args - 组件构造函数参数（仅在创建时使用）
     * @returns 组件实例
     */
    getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: any[]): T;
    /**
     * 移除指定的组件
     *
     * @param component - 要移除的组件实例
     */
    removeComponent(component: Component): void;
    /**
     * 移除指定类型的组件
     *
     * @param type - 组件类型
     * @returns 被移除的组件实例或null
     */
    removeComponentByType<T extends Component>(type: ComponentType<T>): T | null;
    /**
     * 移除所有组件
     */
    removeAllComponents(): void;
    /**
     * 批量添加组件
     *
     * @param components - 要添加的组件数组
     * @returns 添加的组件数组
     */
    addComponents<T extends Component>(components: T[]): T[];
    /**
     * 批量移除组件类型
     *
     * @param componentTypes - 要移除的组件类型数组
     * @returns 被移除的组件数组
     */
    removeComponentsByTypes<T extends Component>(componentTypes: ComponentType<T>[]): (T | null)[];
    /**
     * 获取组件缓存统计信息
     *
     * @returns 缓存统计信息
     */
    getComponentCacheStats(): {
        cacheStats: ReturnType<ComponentCache['getStats']>;
        accessStats: Map<string, {
            accessCount: number;
            lastAccessed: number;
            cacheHits: number;
            cacheMisses: number;
            hitRate: number;
        }>;
        indexMappingSize: number;
        totalComponents: number;
    };
    /**
     * 预热组件缓存
     *
     * 将所有组件添加到缓存中，提升后续访问性能
     */
    warmUpComponentCache(): void;
    /**
     * 清理组件缓存
     *
     * 清除过期的缓存项，释放内存
     */
    cleanupComponentCache(): void;
    /**
     * 获取所有指定类型的组件
     *
     * @param type - 组件类型
     * @returns 组件实例数组
     */
    getComponents<T extends Component>(type: ComponentType<T>): T[];
    /**
     * 添加子实体
     *
     * @param child - 要添加的子实体
     * @returns 添加的子实体
     */
    addChild(child: Entity): Entity;
    /**
     * 移除子实体
     *
     * @param child - 要移除的子实体
     * @returns 是否成功移除
     */
    removeChild(child: Entity): boolean;
    /**
     * 移除所有子实体
     */
    removeAllChildren(): void;
    /**
     * 根据名称查找子实体
     *
     * @param name - 子实体名称
     * @param recursive - 是否递归查找
     * @returns 找到的子实体或null
     */
    findChild(name: string, recursive?: boolean): Entity | null;
    /**
     * 根据标签查找子实体
     *
     * @param tag - 标签
     * @param recursive - 是否递归查找
     * @returns 找到的子实体数组
     */
    findChildrenByTag(tag: number, recursive?: boolean): Entity[];
    /**
     * 获取根实体
     *
     * @returns 层次结构的根实体
     */
    getRoot(): Entity;
    /**
     * 检查是否是指定实体的祖先
     *
     * @param entity - 要检查的实体
     * @returns 如果是祖先则返回true
     */
    isAncestorOf(entity: Entity): boolean;
    /**
     * 检查是否是指定实体的后代
     *
     * @param entity - 要检查的实体
     * @returns 如果是后代则返回true
     */
    isDescendantOf(entity: Entity): boolean;
    /**
     * 获取层次深度
     *
     * @returns 在层次结构中的深度（根实体为0）
     */
    getDepth(): number;
    /**
     * 遍历所有子实体（深度优先）
     *
     * @param callback - 对每个子实体执行的回调函数
     * @param recursive - 是否递归遍历
     */
    forEachChild(callback: (child: Entity, index: number) => void, recursive?: boolean): void;
    /**
     * 活跃状态改变时的回调
     */
    private onActiveChanged;
    /**
     * 更新实体
     *
     * 调用所有组件的更新方法，并更新子实体。
     */
    update(): void;
    /**
     * 销毁实体
     *
     * 移除所有组件、子实体并标记为已销毁。
     */
    destroy(): void;
    /**
     * 比较实体
     *
     * @param other - 另一个实体
     * @returns 比较结果
     */
    compareTo(other: Entity): number;
    /**
     * 获取实体的字符串表示
     *
     * @returns 实体的字符串描述
     */
    toString(): string;
    /**
     * 获取实体的调试信息（包含组件缓存信息）
     *
     * @returns 包含实体详细信息的对象
     */
    getDebugInfo(): {
        name: string;
        id: number;
        enabled: boolean;
        active: boolean;
        activeInHierarchy: boolean;
        destroyed: boolean;
        componentCount: number;
        componentTypes: string[];
        componentMask: string;
        parentId: number | null;
        childCount: number;
        childIds: number[];
        depth: number;
        componentCache: {
            size: number;
            maxSize: number;
            hitRate: number;
            averageAccessCount: number;
        };
        componentAccessStats: Array<{
            componentType: string;
            accessCount: number;
            cacheHits: number;
            cacheMisses: number;
            hitRate: number;
            lastAccessed: string;
        }>;
        indexMappingSize: number;
    };
}

/**
 * 高性能实体列表管理器
 * 管理场景中的所有实体，支持快速查找和批量操作
 */
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: any[]) => 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;
    };
}

/**
 * 高性能位操作类
 * 基于BigInt实现，支持任意数量的位操作
 */
declare class Bits {
    private _value;
    constructor(initialValue?: bigint);
    /**
     * 设置指定位置的位为1
     */
    set(index: number): void;
    /**
     * 清除指定位置的位（设为0）
     */
    clear(index: number): void;
    /**
     * 获取指定位置的位值
     */
    get(index: number): boolean;
    /**
     * 检查是否包含所有指定的位
     */
    containsAll(other: Bits): boolean;
    /**
     * 检查是否包含任意一个指定的位
     */
    intersects(other: Bits): boolean;
    /**
     * 检查是否不包含任何指定的位
     */
    excludes(other: Bits): boolean;
    /**
     * 清空所有位
     */
    clearAll(): void;
    /**
     * 检查是否为空（没有设置任何位）
     */
    isEmpty(): boolean;
    /**
     * 获取设置的位数量
     */
    cardinality(): number;
    /**
     * 位运算：与
     */
    and(other: Bits): Bits;
    /**
     * 位运算：或
     */
    or(other: Bits): Bits;
    /**
     * 位运算：异或
     */
    xor(other: Bits): Bits;
    /**
     * 位运算：非
     */
    not(maxBits?: number): Bits;
    /**
     * 复制另一个Bits对象
     */
    copyFrom(other: Bits): void;
    /**
     * 创建当前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;
}

/**
 * 高性能实体匹配器
 * 用于快速匹配符合条件的实体
 */
declare class Matcher {
    protected allSet: (new (...args: any[]) => Component)[];
    protected exclusionSet: (new (...args: any[]) => Component)[];
    protected oneSet: (new (...args: any[]) => Component)[];
    private _allBits?;
    private _exclusionBits?;
    private _oneBits?;
    private _isDirty;
    static empty(): Matcher;
    getAllSet(): (new (...args: any[]) => Component)[];
    getExclusionSet(): (new (...args: any[]) => Component)[];
    getOneSet(): (new (...args: any[]) => Component)[];
    /**
     * 检查实体是否匹配条件
     * @param entity 要检查的实体
     * @returns 是否匹配
     */
    isInterestedEntity(entity: Entity): boolean;
    /**
     * 检查组件位掩码是否匹配条件
     * @param componentBits 组件位掩码
     * @returns 是否匹配
     */
    isInterested(componentBits: Bits): boolean;
    /**
     * 添加所有包含的组件类型
     * @param types 所有包含的组件类型列表
     */
    all(...types: (new (...args: any[]) => Component)[]): Matcher;
    /**
     * 添加排除包含的组件类型
     * @param types 排除包含的组件类型列表
     */
    exclude(...types: (new (...args: any[]) => Component)[]): Matcher;
    /**
     * 添加至少包含其中之一的组件类型
     * @param types 至少包含其中之一的组件类型列表
     */
    one(...types: (new (...args: any[]) => Component)[]): Matcher;
    /**
     * 获取实体的组件位掩码
     * @param entity 实体
     * @returns 组件位掩码
     */
    private getEntityBits;
    /**
     * 如果位掩码已过期，则更新它们
     */
    private updateBitsIfDirty;
    /**
     * 创建匹配器的字符串表示（用于调试）
     * @returns 字符串表示
     */
    toString(): string;
}

/**
 * 实体系统的基类
 *
 * 用于处理一组符合特定条件的实体。系统是ECS架构中的逻辑处理单元，
 * 负责对拥有特定组件组合的实体执行业务逻辑。
 *
 * @example
 * ```typescript
 * class MovementSystem extends EntitySystem {
 *     constructor() {
 *         super(Matcher.empty().all(Transform, Velocity));
 *     }
 *
 *     protected process(entities: Entity[]): void {
 *         for (const entity of entities) {
 *             const transform = entity.getComponent(Transform);
 *             const velocity = entity.getComponent(Velocity);
 *             transform.position.add(velocity.value);
 *         }
 *     }
 * }
 * ```
 */
declare abstract class EntitySystem implements ISystemBase {
    private _entities;
    private _updateOrder;
    private _enabled;
    private _performanceMonitor;
    private _systemName;
    /**
     * 获取系统处理的实体列表
     */
    get entities(): readonly Entity[];
    /**
     * 获取系统的更新时序
     */
    get updateOrder(): number;
    set updateOrder(value: number);
    /**
     * 获取系统的启用状态
     */
    get enabled(): boolean;
    /**
     * 设置系统的启用状态
     */
    set enabled(value: boolean);
    /**
     * 获取系统名称
     */
    get systemName(): string;
    constructor(matcher?: Matcher);
    private _scene;
    /**
     * 这个系统所属的场景
     */
    get scene(): Scene;
    set scene(value: Scene);
    private _matcher;
    /**
     * 获取实体匹配器
     */
    get matcher(): Matcher;
    /**
     * 设置更新时序
     * @param order 更新时序
     */
    setUpdateOrder(order: number): void;
    /**
     * 系统初始化
     *
     * 在系统创建时调用，自动检查场景中已存在的实体是否匹配此系统。
     * 子类可以重写此方法进行额外的初始化操作。
     */
    initialize(): void;
    /**
     * 当实体的组件发生变化时调用
     *
     * 检查实体是否仍然符合系统的匹配条件，并相应地添加或移除实体。
     *
     * @param entity 发生变化的实体
     */
    onChanged(entity: Entity): void;
    /**
     * 添加实体到系统
     *
     * @param entity 要添加的实体
     */
    add(entity: Entity): void;
    /**
     * 当实体被添加到系统时调用
     *
     * 子类可以重写此方法来处理实体添加事件。
     *
     * @param entity 被添加的实体
     */
    protected onAdded(entity: Entity): void;
    /**
     * 从系统中移除实体
     *
     * @param entity 要移除的实体
     */
    remove(entity: Entity): void;
    /**
     * 当实体从系统中移除时调用
     *
     * 子类可以重写此方法来处理实体移除事件。
     *
     * @param entity 被移除的实体
     */
    protected onRemoved(entity: Entity): void;
    /**
     * 更新系统
     *
     * 在每帧调用，处理系统的主要逻辑。
     */
    update(): void;
    /**
     * 后期更新系统
     *
     * 在所有系统的update方法执行完毕后调用。
     */
    lateUpdate(): void;
    /**
     * 在系统处理开始前调用
     *
     * 子类可以重写此方法进行预处理操作。
     */
    protected begin(): void;
    /**
     * 处理实体列表
     *
     * 系统的核心逻辑，子类必须实现此方法来定义具体的处理逻辑。
     *
     * @param entities 要处理的实体列表
     */
    protected process(entities: Entity[]): void;
    /**
     * 后期处理实体列表
     *
     * 在主要处理逻辑之后执行，子类可以重写此方法。
     *
     * @param entities 要处理的实体列表
     */
    protected lateProcess(entities: Entity[]): void;
    /**
     * 系统处理完毕后调用
     *
     * 子类可以重写此方法进行后处理操作。
     */
    protected end(): void;
    /**
     * 检查系统是否需要处理
     *
     * 在启用系统时有用，但仅偶尔需要处理。
     * 这只影响处理，不影响事件或订阅列表。
     *
     * @returns 如果系统应该处理，则为true，如果不处理则为false
     */
    protected checkProcessing(): boolean;
    /**
     * 获取系统的性能数据
     *
     * @returns 性能数据或undefined
     */
    getPerformanceData(): PerformanceData | undefined;
    /**
     * 获取系统的性能统计
     *
     * @returns 性能统计或undefined
     */
    getPerformanceStats(): PerformanceStats | undefined;
    /**
     * 重置系统的性能数据
     */
    resetPerformanceData(): void;
    /**
     * 获取系统信息的字符串表示
     *
     * @returns 系统信息字符串
     */
    toString(): string;
}

/**
 * 实体处理器列表管理器
 * 管理场景中的所有实体系统
 */
declare class EntityProcessorList {
    private _processors;
    private _isDirty;
    /**
     * 设置为脏状态，需要重新排序
     */
    setDirty(): void;
    /**
     * 添加实体处理器
     * @param processor 要添加的处理器
     */
    add(processor: EntitySystem): void;
    /**
     * 移除实体处理器
     * @param processor 要移除的处理器
     */
    remove(proce