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

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

/**
 * @esengine/ecs-framework v2.2.12
 * TypeScript definitions
 */
/**
 * TypeScript类型工具集
 *
 * 提供高级类型推断和类型安全的工具类型
 */

/**
 * 组件类型提取器
 * 从组件构造函数中提取实例类型
 */
type ComponentInstance<T> = T extends new (...args: any[]) => infer R ? R : never;
/**
 * 组件构造函数类型
 *
 * 与 ComponentType 保持一致，避免类型转换
 */
type ComponentConstructor<T extends IComponent = IComponent> = new (...args: any[]) => T;
/**
 * 组件类型的通用约束
 *
 * 用于确保类型参数是有效的组件构造函数
 */
type AnyComponentConstructor = ComponentConstructor<any>;
/**
 * 多组件类型提取
 * 从组件构造函数数组中提取所有实例类型的联合
 */
type ExtractComponents<T extends readonly ComponentConstructor[]> = {
    [K in keyof T]: ComponentInstance<T[K]>;
};
/**
 * 组件类型映射
 * 将组件构造函数数组转换为实例类型的元组
 */
type ComponentTypeMap<T extends readonly ComponentConstructor[]> = {
    [K in keyof T]: T[K] extends ComponentConstructor<infer C> ? C : never;
};
/**
 * 实体with组件的类型
 * 表示一个实体确定拥有某些组件
 */
interface EntityWithComponents<T extends readonly ComponentConstructor[]> {
    readonly id: number;
    readonly name: string;
    /**
     * 类型安全的组件获取
     * 确保返回非空的组件实例
     */
    getComponent<C extends ComponentConstructor>(componentType: C): ComponentInstance<C>;
    /**
     * 检查是否拥有组件
     */
    hasComponent<C extends ComponentConstructor>(componentType: C): boolean;
    /**
     * 获取所有组件
     */
    readonly components: ComponentTypeMap<T>;
}
/**
 * 查询结果类型
 * 根据查询条件推断实体必定拥有的组件
 */
type QueryResult$1<All extends readonly ComponentConstructor[] = [], Any extends readonly ComponentConstructor[] = [], None extends readonly ComponentConstructor[] = []> = {
    /**
     * 实体列表，确保拥有All中的所有组件
     */
    readonly entities: ReadonlyArray<EntityWithComponents<All>>;
    /**
     * 实体数量
     */
    readonly length: number;
    /**
     * 遍历实体
     */
    forEach(callback: (entity: EntityWithComponents<All>, index: number) => void): void;
    /**
     * 映射转换
     */
    map<R>(callback: (entity: EntityWithComponents<All>, index: number) => R): R[];
    /**
     * 过滤实体
     */
    filter(predicate: (entity: EntityWithComponents<All>, index: number) => boolean): QueryResult$1<All, Any, None>;
};
/**
 * System处理的实体类型
 * 根据Matcher推断System处理的实体类型
 */
type SystemEntityType<M> = M extends {
    getCondition(): {
        all: infer All extends readonly ComponentConstructor[];
    };
} ? EntityWithComponents<All> : never;
/**
 * 组件字段类型提取
 * 提取组件中所有可序列化的字段
 */
type SerializableFields<T> = {
    [K in keyof T]: T[K] extends Function ? never : K;
}[keyof T];
/**
 * 只读组件类型
 * 将组件的所有字段转为只读
 */
type ReadonlyComponent<T extends IComponent> = {
    readonly [K in keyof T]: T[K];
};
/**
 * 部分组件类型
 * 用于组件更新操作
 */
type PartialComponent<T extends IComponent> = {
    [K in SerializableFields<T>]?: T[K];
};
/**
 * 组件类型约束
 * 确保类型参数是有效的组件
 */
type ValidComponent<T> = T extends Component ? T : never;
/**
 * 组件数组约束
 * 确保数组中的所有元素都是组件构造函数
 */
type ValidComponentArray<T extends readonly any[]> = T extends readonly ComponentConstructor[] ? T : never;
/**
 * 事件处理器类型
 * 提供类型安全的事件处理
 */
type TypedEventHandler<T> = (data: T) => void | Promise<void>;
/**
 * 系统生命周期钩子类型
 */
interface SystemLifecycleHooks<T extends readonly ComponentConstructor[]> {
    /**
     * 实体添加到系统时调用
     */
    onAdded?: (entity: EntityWithComponents<T>) => void;
    /**
     * 实体从系统移除时调用
     */
    onRemoved?: (entity: EntityWithComponents<T>) => void;
    /**
     * 系统初始化时调用
     */
    onInitialize?: () => void;
    /**
     * 系统销毁时调用
     */
    onDestroy?: () => void;
}
/**
 * Fluent API构建器类型
 */
interface TypeSafeBuilder<T> {
    /**
     * 完成构建
     */
    build(): T;
}
/**
 * 实体查询条件类型
 */
interface TypedQueryCondition<All extends readonly ComponentConstructor[] = [], Any extends readonly ComponentConstructor[] = [], None extends readonly ComponentConstructor[] = []> {
    all: All;
    any: Any;
    none: None;
    tag?: number;
    name?: string;
}
/**
 * 组件类型守卫
 */
declare function isComponentType<T extends IComponent>(value: any): value is ComponentConstructor<T>;
/**
 * 类型安全的组件数组守卫
 */
declare function isComponentArray(value: any[]): value is ComponentConstructor[];
/**
 * 提取组件类型名称（编译时）
 */
type ComponentTypeName<T extends ComponentConstructor> = T extends {
    prototype: {
        constructor: {
            name: infer N;
        };
    };
} ? N : string;
/**
 * 多组件类型名称联合
 */
type ComponentTypeNames<T extends readonly ComponentConstructor[]> = {
    [K in keyof T]: ComponentTypeName<T[K]>;
}[number];
/**
 * 深度只读类型
 */
type DeepReadonly<T> = {
    readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};
/**
 * 深度可选类型
 */
type DeepPartial<T> = {
    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};
/**
 * 排除方法的类型
 */
type DataOnly<T> = {
    [K in keyof T as T[K] extends Function ? never : K]: T[K];
};
/**
 * 可序列化的组件数据
 */
type SerializableComponent<T extends IComponent> = DeepPartial<DataOnly<T>>;

/**
 * 可更新接口
 *
 * 实现此接口的服务将在每帧被Core自动调用update方法
 */
interface IUpdatable {
    /**
     * 每帧更新方法
     *
     * @param deltaTime - 帧时间间隔（秒），可选参数
     */
    update(deltaTime?: number): void;
}

/**
 * 框架核心类型定义
 */

/**
 * 组件接口
 *
 * 定义组件的基本契约。
 * 在 ECS 架构中，组件应该是纯数据容器，不包含业务逻辑。
 */
interface IComponent {
    /** 组件唯一标识符 */
    readonly id: number;
    /** 组件所属的实体ID */
    entityId: number | null;
    /** 组件添加到实体时的回调 */
    onAddedToEntity(): void;
    /** 组件从实体移除时的回调 */
    onRemovedFromEntity(): 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;
    /** 事件处理函数的 this 绑定对象 */
    thisArg?: object;
}
/**
 * 事件统计信息接口
 */
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;
    /** WorldManager配置 */
    worldManagerConfig?: IWorldManagerConfig;
}
/**
 * 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）应该是纯数据容器。
 * 所有游戏逻辑应该在 EntitySystem 中实现，而不是在组件内部。
 *
 * @example
 * 推荐做法：纯数据组件
 * ```typescript
 * class HealthComponent extends Component {
 *     public health: number = 100;
 *     public maxHealth: number = 100;
 * }
 * ```
 *
 * @example
 * 推荐做法：在 System 中处理逻辑
 * ```typescript
 * class HealthSystem extends EntitySystem {
 *     process(entities: Entity[]): void {
 *         for (const entity of entities) {
 *             const health = entity.getComponent(HealthComponent);
 *             if (health && health.health <= 0) {
 *                 entity.destroy();
 *             }
 *         }
 *     }
 * }
 * ```
 */
declare abstract class Component implements IComponent {
    /**
     * 组件ID生成器
     *
     * 用于为每个组件分配唯一的ID。
     */
    private static idGenerator;
    /**
     * 组件唯一标识符
     *
     * 在整个游戏生命周期中唯一的数字ID。
     */
    readonly id: number;
    /**
     * 所属实体ID
     *
     * 存储实体ID而非引用，避免循环引用，符合ECS数据导向设计。
     */
    entityId: number | null;
    /**
     * 创建组件实例
     *
     * 自动分配唯一ID给组件。
     */
    constructor();
    /**
     * 组件添加到实体时的回调
     *
     * 当组件被添加到实体时调用，可以在此方法中进行初始化操作。
     *
     * @remarks
     * 这是一个生命周期钩子，用于组件的初始化逻辑。
     * 虽然保留此方法，但建议将复杂的初始化逻辑放在 System 中处理。
     */
    onAddedToEntity(): void;
    /**
     * 组件从实体移除时的回调
     *
     * 当组件从实体中移除时调用，可以在此方法中进行清理操作。
     *
     * @remarks
     * 这是一个生命周期钩子，用于组件的清理逻辑。
     * 虽然保留此方法，但建议将复杂的清理逻辑放在 System 中处理。
     */
    onRemovedFromEntity(): void;
}

/**
 * 基础 64 位段结构
 * [低32位，高32位]
 */
type BitMask64Segment = [number, number];
/**
 * 位掩码数据结构
 * 基础模式（64位）：使用 base[lo , hi] 存储 64 位，segments 为空
 * 扩展模式（128+位）：base[lo , hi] 作为第一段，segments 存储额外的 64 位段
 * segments[0] 对应 bit 64-127，segments[1] 对应 bit 128-191，以此类推
 */
interface BitMask64Data {
    base: BitMask64Segment;
    /** 扩展段数组，每个元素是一个 64 位段，用于超过 64 位的场景 */
    segments?: BitMask64Segment[];
}
declare class BitMask64Utils {
    /** 零掩码常量，所有位都为0 */
    static readonly ZERO: Readonly<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 位索引，不小于零
     * @throws 当位索引超出范围时抛出错误
     */
    static setBit(mask: BitMask64Data, bitIndex: number): void;
    /**
     * 获取掩码中指定位，如果位超出当前掩码的区段长度，则直接返回0
     * @param mask 掩码
     * @param bitIndex 位索引，不小于零
     */
    static getBit(mask: BitMask64Data, bitIndex: number): boolean;
    /**
     * 清除掩码中指定位为0，如果位超出当前掩码的区段长度，则什么也不做
     * @param mask 要修改的掩码（原地修改）
     * @param bitIndex 位索引，不小于0
     */
    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;
    /**
     * 将源掩码的值复制到目标掩码，如果source包含扩展段，则target也会至少扩展到source扩展段的长度
     * @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，其他的值被视为2
     * @param printHead 打印头
     * @returns 掩码的字符串表示，二进制不带前缀，十六进制带0x前缀
     */
    static toString(mask: BitMask64Data, radix?: 2 | 16, printHead?: boolean): string;
    /**
     * 计算掩码中设置为1的位数
     * @param mask 要计算的掩码
     * @returns 掩码中1的位数
     */
    static popCount(mask: BitMask64Data): number;
    /**
     * 获取包含目标位的BitMask64Segment
     * @param mask 要操作的掩码
     * @param bitIndex 目标位
     * @param createNewSegment 如果bitIndex超过了当前范围，是否自动补充扩展区域，默认为真
     * @private
     */
    private static getSegmentByBitIndex;
}

/**
 * 启用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;
/**
 * 32位无符号整数装饰器
 * 标记字段使用Uint32Array存储（适用于无符号整数，如ID、标志位等）
 */
declare function Uint32(target: any, propertyKey: string | symbol): void;
/**
 * 16位整数装饰器
 * 标记字段使用Int16Array存储（适用于小范围整数）
 */
declare function Int16(target: any, propertyKey: string | symbol): void;
/**
 * 16位无符号整数装饰器
 * 标记字段使用Uint16Array存储（适用于小范围无符号整数）
 */
declare function Uint16(target: any, propertyKey: string | symbol): void;
/**
 * 8位整数装饰器
 * 标记字段使用Int8Array存储（适用于很小的整数值）
 */
declare function Int8(target: any, propertyKey: string | symbol): void;
/**
 * 8位无符号整数装饰器
 * 标记字段使用Uint8Array存储（适用于字节值、布尔标志等）
 */
declare function Uint8(target: any, propertyKey: string | symbol): void;
/**
 * 8位夹紧整数装饰器
 * 标记字段使用Uint8ClampedArray存储（适用于颜色值等需要夹紧的数据）
 */
declare function Uint8Clamped(target: any, propertyKey: string | symbol): void;
/**
 * 序列化Map装饰器
 * 标记Map字段需要序列化/反序列化存储
 */
declare function SerializeMap(target: any, propertyKey: string | symbol): void;
/**
 * 序列化Set装饰器
 * 标记Set字段需要序列化/反序列化存储
 */
declare function SerializeSet(target: any, propertyKey: string | symbol): void;
/**
 * 序列化Array装饰器
 * 标记Array字段需要序列化/反序列化存储
 */
declare function SerializeArray(target: any, propertyKey: string | symbol): void;
/**
 * 深拷贝装饰器
 * 标记字段需要深拷贝处理（适用于嵌套对象）
 */
declare function DeepCopy(target: any, propertyKey: string | symbol): void;
/**
 * 自动类型推断装饰器
 * 根据字段的默认值和数值范围自动选择最优的TypedArray类型
 *
 * @param options 类型推断选项
 * @param options.minValue 数值的最小值（用于范围优化）
 * @param options.maxValue 数值的最大值（用于范围优化）
 * @param options.precision 是否需要浮点精度（true: 使用浮点数组, false: 使用整数数组）
 * @param options.signed 是否需要符号位（仅在整数模式下有效）
 */
declare function AutoTyped(options?: {
    minValue?: number;
    maxValue?: number;
    precision?: boolean;
    signed?: boolean;
}): (target: any, propertyKey: string | symbol) => void;
/**
 * 自动类型推断器
 * 根据数值类型和范围自动选择最优的TypedArray类型
 */
declare class TypeInference {
    /**
     * 根据数值范围推断最优的TypedArray类型
     */
    static inferOptimalType(value: any, options?: {
        minValue?: number;
        maxValue?: number;
        precision?: boolean;
        signed?: boolean;
    }): string;
    /**
     * 根据推断的类型名创建对应的TypedArray构造函数
     */
    static getTypedArrayConstructor(typeName: string): typeof Float32Array | typeof Float64Array | typeof Int32Array | typeof Uint32Array | typeof Int16Array | typeof Uint16Array | typeof Int8Array | typeof Uint8Array | typeof Uint8ClampedArray;
}
/**
 * SoA存储器支持的TypedArray类型
 */
type SupportedTypedArray = Float32Array | Float64Array | Int32Array | Uint32Array | Int16Array | Uint16Array | Int8Array | Uint8Array | Uint8ClampedArray;
/**
 * 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): SupportedTypedArray | null;
    getTypedFieldArray<K extends keyof T>(fieldName: K): SupportedTypedArray | 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, SupportedTypedArray>, activeIndices: number[]) => void): void;
}

/**
 * 日志级别
 */
declare enum LogLevel {
    Debug = 0,
    Info = 1,
    Warn = 2,
    Error = 3,
    Fatal = 4,
    None = 5
}
/**
 * 预定义的颜色常量
 */
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 ILogger {
    debug(...args: unknown[]): void;
    info(...args: unknown[]): void;
    warn(...args: unknown[]): void;
    error(...args: unknown[]): void;
    fatal(...args: unknown[]): void;
}
/**
 * 日志颜色配置接口
 */
interface LoggerColorConfig {
    debug?: string;
    info?: string;
    warn?: string;
    error?: string;
    fatal?: string;
    reset?: string;
}
/**
 * 日志配置
 */
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 _defaultLevel;
    private _loggerFactory?;
    private constructor();
    private get defaultLogger();
    private createDefaultLogger;
    /**
     * 获取日志管理器实例
     * @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;
    /**
     * 设置日志器工厂方法
     * @param factory 日志器工厂方法
     */
    setLoggerFactory(factory: (name?: string) => ILogger): 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;
/**
 * 设置日志器工厂方法
 * @param factory 日志器工厂方法
 */
declare function setLoggerFactory(factory: (name?: string) => ILogger): void;

/**
 * 组件类型定义
 */
type ComponentType<T extends Component = Component> = new (...args: any[]) => T;
/**
 * 组件注册表
 * 管理组件类型的位掩码分配
 */
declare class ComponentRegistry {
    protected static readonly _logger: ILogger;
    private static componentTypes;
    private static bitIndexToType;
    private static componentNameToType;
    private static componentNameToId;
    private static maskCache;
    private static nextBitIndex;
    /**
     * 注册组件类型并分配位掩码
     * @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 bitIndex 位索引
     * @returns 组件类型构造函数或null
     */
    static getTypeByBitIndex(bitIndex: number): ComponentType | null;
    /**
     * 获取当前已注册的组件类型数量
     * @returns 已注册数量
     */
    static getRegisteredCount(): number;
    /**
     * 通过名称获取组件类型
     * @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): SupportedTypedArray | null;
    /**
     * 直接获取SoA字段数组（类型安全，带字段名检查）
     * @param componentType 组件类型
     * @param fieldName 字段名（类型检查）
     * @returns TypedArray或null
     */
    getTypedFieldArray<T extends Component, K extends keyof T>(componentType: ComponentType<T>, fieldName: K): SupportedTypedArray | 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, {
        totalSlots: number;
        usedSlots: number;
        freeSlots: number;
        fragmentation: number;
    }>;
    /**
     * 清空所有存储器
     */
    clear(): void;
}

/**
 * 高性能实体列表管理器
 * 管理场景中的所有实体，支持快速查找和批量操作
 */
declare class EntityList {
    buffer: Entity[];
    private _scene;
    private _idToEntity;
    private _nameToEntities;
    private _entitiesToAdd;
    private _entitiesToRemove;
    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;
    };
}

/**
 * 世代式ID池管理器
 *
 * 用于管理实体ID的分配和回收，支持世代版本控制以防止悬空引用问题。
 * 世代式ID由索引和版本组成，当ID被回收时版本会递增，确保旧引用失效。
 *
 * 支持动态扩展，理论上可以支持到65535个索引（16位），每个索引65535个版本（16位）。
 * 总计可以处理超过42亿个独特的ID组合，完全满足ECS大规模实体需求。
 *
 * @example
 * ```typescript
 * const pool = new IdentifierPool();
 *
 * // 分配ID
 * const id = pool.checkOut(); // 例如: 65536 (版本1，索引0)
 *
 * // 回收ID
 * pool.checkIn(id);
 *
 * // 验证ID是否有效
 * const isValid = pool.isValid(id); // false，因为版本已递增
 * ```
 */
declare class IdentifierPool {
    /**
     * 下一个可用的索引
     */
    private _nextAvailableIndex;
    /**
     * 空闲的索引列表
     */
    private _freeIndices;
    /**
     * 每个索引对应的世代版本
     * 动态扩展的Map，按需分配内存
     */
    private _generations;
    /**
     * 延迟回收队列
     * 防止在同一帧内立即重用ID，避免时序问题
     */
    private _pendingRecycle;
    /**
     * 延迟回收时间（毫秒）
     */
    private _recycleDelay;
    /**
     * 最大索引限制（16位）
     * 这是框架设计选择：16位索引 + 16位版本 = 32位ID，确保高效位操作
     * 不是硬件限制，而是性能和内存效率的权衡
     */
    private static readonly MAX_INDEX;
    /**
     * 最大世代限制（16位）
     */
    private static readonly MAX_GENERATION;
    /**
     * 内存扩展块大小
     * 当需要更多内存时，一次性预分配的索引数量
     */
    private _expansionBlockSize;
    /**
     * 统计信息
     */
    private _stats;
    /**
     * 构造函数
     *
     * @param recycleDelay 延迟回收时间（毫秒），默认为100ms
     * @param expansionBlockSize 内存扩展块大小，默认为1024
     */
    constructor(recycleDelay?: number, expansionBlockSize?: number);
    /**
     * 获取一个可用的ID
     *
     * 返回一个32位ID，高16位为世代版本，低16位为索引。
     *
     * @returns 新分配的实体ID
     * @throws {Error} 当达到索引限制时抛出错误
     */
    checkOut(): number;
    /**
     * 回收一个ID
     *
     * 验证ID的有效性后，将其加入延迟回收队列。
     * ID不会立即可重用，而是在延迟时间后才真正回收。
     *
     * @param id 要回收的实体ID
     * @returns 是否成功回收（ID是否有效且未被重复回收）
     */
    checkIn(id: number): boolean;
    /**
     * 验证ID是否有效
     *
     * 检查ID的索引和世代版本是否匹配当前状态。
     *
     * @param id 要验证的实体ID
     * @returns ID是否有效
     */
    isValid(id: number): boolean;
    /**
     * 获取统计信息
     *
     * @returns 池的当前状态统计
     */
    getStats(): {
        /** 已分配的总索引数 */
        totalAllocated: number;
        /** 总计回收次数 */
        totalRecycled: number;
        /** 当前活跃实体数 */
        currentActive: number;
        /** 当前空闲的索引数 */
        currentlyFree: number;
        /** 等待回收的ID数 */
        pendingRecycle: number;
        /** 理论最大实体数（设计限制） */
        maxPossibleEntities: number;
        /** 当前使用的最大索引 */
        maxUsedIndex: number;
        /** 内存使用（字节） */
        memoryUsage: number;
        /** 内存扩展次数 */
        memoryExpansions: number;
        /** 平均世代版本 */
        averageGeneration: number;
        /** 世代存储大小 */
        generationStorageSize: number;
    };
    /**
     * 强制执行延迟回收处理
     *
     * 在某些情况下可能需要立即处理延迟回收队列，
     * 比如内存压力大或者需要精确的统计信息时。
     */
    forceProcessDelayedRecycle(): void;
    /**
     * 清理过期的延迟回收项
     *
     * 将超过延迟时间的回收项真正回收到空闲列表中。
     *
     * @param forceAll 是否强制处理所有延迟回收项
     * @private
     */
    private _processDelayedRecycle;
    /**
     * 预分配世代信息
     *
     * @param startIndex 起始索引
     * @param count 分配数量
     * @private
     */
    private _preAllocateGenerations;
    /**
     * 确保指定索引的世代信息存在
     *
     * @param index 索引
     * @private
     */
    private _ensureGenerationCapacity;
    /**
     * 计算内存使用量
     *
     * @returns 内存使用字节数
     * @private
     */
    private _calculateMemoryUsage;
    /**
     * 打包索引和世代为32位ID
     *
     * @param index 索引（16位）
     * @param generation 世代版本（16位）
     * @returns 打包后的32位ID
     * @private
     */
    private _packId;
    /**
     * 从ID中解包索引
     *
     * @param id 32位ID
     * @returns 索引部分（16位）
     * @private
     */
    private _unpackIndex;
    /**
     * 从ID中解包世代版本
     *
     * @param id 32位ID
     * @returns 世代版本部分（16位）
     * @private
     */
    private _unpackGeneration;
    /**
     * 内部ID有效性检查
     *
     * @param index 索引
     * @param generation 世代版本
     * @returns 是否有效
     * @private
     */
    private _isValidId;
}

/**
 * 服务基础接口
 * 所有通过 ServiceContainer 管理的服务都应该实现此接口
 */
interface IService {
    /**
     * 释放服务占用的资源
     * 当服务被注销或容器被清空时调用
     */
    dispose(): void;
}
/**
 * 服务类型
 *
 * 支持任意构造函数签名，以便与依赖注入装饰器配合使用
 * 使用 any[] 以允许任意参数类型的构造函数
 */
type ServiceType<T extends IService> = new (...args: any[]) => T;
/**
 * 服务生命周期
 */
declare enum ServiceLifetime {
    /**
     * 单例模式 - 整个应用生命周期内只有一个实例
     */
    Singleton = "singleton",
    /**
     * 瞬时模式 - 每次请求都创建新实例
     */
    Transient = "transient"
}
/**
 * 服务容器
 *
 * 负责管理所有服务的注册、解析和生命周期。
 * 支持依赖注入和服务定位模式。
 *
 * 特点：
 * - 单例和瞬时两种生命周期
 * - 支持工厂函数注册
 * - 支持实例注册
 * - 类型安全的服务解析
 *
 * @example
 * ```typescript
 * const container = new ServiceContainer();
 *
 * // 注册单例服务
 * container.registerSingleton(TimerManager);
 *
 * // 注册工厂函数
 * container.registerSingleton(Logger, (c) => createLogger('App'));
 *
 * // 注册实例
 * container.registerInstance(Config, new Config());
 *
 * // 解析服务
 * const timer = container.resolve(TimerManager);
 * ```
 */
declare class ServiceContainer {
    /**
     * 服务注册表
     */
    private _services;
    /**
     * 正在解析的服务栈（用于循环依赖检测）
     */
    private _resolving;
    /**
     * 可更新的服务列表
     *
     * 自动收集所有使用@Updatable装饰器标记的服务，供Core统一更新
     * 按优先级排序（数值越小越先执行）
     */
    private _updatableServices;
    /**
     * 注册单例服务
     *
     * @param type - 服务类型
     * @param factory - 可选的工厂函数
     *
     * @example
     * ```typescript
     * // 直接注册类型
     * container.registerSingleton(TimerManager);
     *
     * // 使用工厂函数
     * container.registerSingleton(Logger, (c) => {
     *     return createLogger('App');
     * });
     * ```
     */
    registerSingleton<T extends IService>(type: ServiceType<T>, factory?: (container: ServiceContainer) => T): void;
    /**
     * 注册瞬时服务
     *
     * 每次解析都会创建新实例。
     *
     * @param type - 服务类型
     * @param factory - 可选的工厂函数
     *
     * @example
     * ```typescript
     * // 每次解析都创建新实例
     * container.registerTransient(Command);
     * ```
     */
    registerTransient<T extends IService>(type: ServiceType<T>, factory?: (container: ServiceContainer) => T): void;
    /**
     * 注册服务实例
     *
     * 直接注册已创建的实例，自动视为单例。
     *
     * @param type - 服务类型（构造函数，仅用作标识）
     * @param instance - 服务实例
     *
     * @example
     * ```typescript
     * const config = new Config();
     * container.registerInstance(Config, config);
     * ```
     */
    registerInstance<T extends IService>(type: ServiceType<T>, instance: T): void;
    /**
     * 解析服务
     *
     * @param type - 服务类型
     * @returns 服务实例
     * @throws 如果服务未注册或存在循环依赖
     *
     * @example
     * ```typescript
     * const timer = container.resolve(TimerManager);
     * ```
     */
    resolve<T extends IService>(type: ServiceType<T>): T;
    /**
     * 尝试解析服务
     *
     * 如果服务未注册，返回null而不是抛出异常。
     *
     * @param type - 服务类型
     * @returns 服务实例或null
     *
     * @example
     * ```typescript
     * const timer = container.tryResolve(TimerManager);
     * if (timer) {
     *     timer.schedule(...);
     * }
     * ```
     */
    tryResolve<T extends IService>(type: ServiceType<T>): T | null;
    /**
     * 检查服务是否已注册
     *
     * @param type - 服务类型
     * @returns 是否已注册
     */
    isRegistered<T extends IService>(type: ServiceType<T>): boolean;
    /**
     * 注销服务
     *
     * @param type - 服务类型
     * @returns 是否成功注销
     */
    unregister<T extends IService>(type: ServiceType<T>): boolean;
    /**
     * 清空所有服务
     */
    clear(): void;
    /**
     * 获取所有已注册的服务类型
     *
     * @returns 服务类型数组
     */
    getRegisteredServices(): ServiceType<IService>[];
    /**
     * 更新所有使用@Updatable装饰器标记的服务
     *
     * 此方法会按优先级顺序遍历所有可更新的服务并调用它们的update方法。
     * 所有服务在注册时已经由@Updatable装饰器验证过必须实现IUpdatable接口。
     * 通常在Core的主更新循环中调用。
     *
     * @param deltaTime - 可选的帧时间间隔（秒）
     *
     * @example
     * ```typescript
     * // 在Core的update方法中
     * this._serviceContainer.updateAll(deltaTime);
     * ```
     */
    updateAll(deltaTime?: number): void;
    /**
     * 获取所有可更新的服务数量
     *
     * @returns 可更新服务的数量
     */
    getUpdatableCount(): number;
    /**
     * 获取所有已实例化的服务实例
     *
     * @returns 所有服务实例的数组
     */
    getAll(): IService[];
}

/**
 * 性能监控数据
 */
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 implements IService {
    private _systemData;
    private _systemStats;
    private _isEnabled;
    private _maxRecentSamples;
    constructor();
    /**
     * 启用性能监控
     */
    enable(): void;
    /**
     * 禁用性能监控
     */
    disable(): void;
    /**
     * 检查是否启用了性能监控
     */
    get isEnabled(): boolean;
    /**
     * 开始监控系统性能
     * @param systemName 系统名称
     * @returns 开始时间戳
     */
    startMonitoring(_systemName: string): number;
    /**
     * 结束监控并记录性能数据
     * @param systemName 系统名称
     * @param start