@esengine/ecs-framework 2.1.33 → 2.1.35

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.1.33
+ * @esengine/ecs-framework v2.1.35
  * TypeScript definitions
  */
 /**
@@ -583,8 +583,9 @@ interface ISystemBase {
  * 组件类型定义
  *
  * 用于类型安全的组件操作
+ * 支持任意构造函数签名，提供更好的类型安全性
  */
-type ComponentType$1<T extends IComponent = IComponent> = new (...args: unknown[]) => T;
+type ComponentType$1<T extends IComponent = IComponent> = new (...args: any[]) => T;
 /**
  * 事件总线接口
  * 提供类型安全的事件发布订阅机制
@@ -1850,8 +1851,9 @@ declare class SoAStorage<T extends Component> {
 
 /**
  * 组件类型定义
+ * 支持任意构造函数签名，提供更好的类型安全性
  */
-type ComponentType<T extends Component = Component> = new (...args: unknown[]) => T;
+type ComponentType<T extends Component = Component> = new (...args: any[]) => T;
 /**
  * 组件注册表
  * 管理组件类型的位掩码分配
@@ -2954,7 +2956,7 @@ declare function EventHandler(eventType: string, config?: IEventListenerConfig):
  */
 declare function AsyncEventHandler(eventType: string, config?: IEventListenerConfig): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 
-interface IScene {
+interface IScene$1 {
     readonly name: string;
     readonly componentStorageManager: ComponentStorageManager;
     readonly querySystem: QuerySystem;
@@ -3042,7 +3044,7 @@ declare class Entity {
      *
      * 指向实体所在的场景实例。
      */
-    scene: IScene | null;
+    scene: IScene$1 | null;
     /**
      * 更新间隔
      *
@@ -3205,7 +3207,7 @@ declare class Entity {
      * @param args - 组件构造函数参数
      * @returns 创建的组件实例
      */
-    createComponent<T extends Component>(componentType: ComponentType<T>, ...args: unknown[]): T;
+    createComponent<T extends Component>(componentType: ComponentType<T>, ...args: any[]): T;
     /**
      * 内部添加组件方法（不进行重复检查，用于初始化）
      *
@@ -3246,7 +3248,7 @@ declare class Entity {
      * @param args - 组件构造函数参数（仅在创建时使用）
      * @returns 组件实例
      */
-    getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: unknown[]): T;
+    getOrCreateComponent<T extends Component>(type: ComponentType<T>, ...args: any[]): T;
     /**
      * 移除指定的组件
      *
@@ -3545,257 +3547,6 @@ declare class Matcher {
     toString(): string;
 }
 
-/**
- * 实体系统的基类
- *
- * 用于处理一组符合特定条件的实体。系统是ECS架构中的逻辑处理单元，
- * 负责对拥有特定组件组合的实体执行业务逻辑。
- *
- * @example
- * ```typescript
- * class MovementSystem extends EntitySystem {
- *     constructor() {
- *         super(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 _updateOrder;
-    private _enabled;
-    private _performanceMonitor;
-    private _systemName;
-    private _initialized;
-    private _matcher;
-    private _trackedEntities;
-    private _lastQueryResult;
-    /**
-     * 获取系统处理的实体列表（动态查询）
-     */
-    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 | null;
-    set scene(value: Scene | null);
-    /**
-     * 获取实体匹配器
-     */
-    get matcher(): Matcher;
-    /**
-     * 设置更新时序
-     * @param order 更新时序
-     */
-    setUpdateOrder(order: number): void;
-    /**
-     * 系统初始化（框架调用）
-     *
-     * 在系统创建时调用。框架内部使用，用户不应直接调用。
-     */
-    initialize(): void;
-    /**
-     * 系统初始化回调
-     *
-     * 子类可以重写此方法进行初始化操作。
-     */
-    protected onInitialize(): void;
-    /**
-     * 重置系统状态
-     *
-     * 当系统从场景中移除时调用，重置初始化状态以便重新添加时能正确初始化。
-     */
-    reset(): void;
-    /**
-     * 查询匹配的实体
-     */
-    private queryEntities;
-    /**
-     * 检查是否为单一条件查询
-     */
-    private isSingleCondition;
-    /**
-     * 执行单一条件查询
-     */
-    private executeSingleConditionQuery;
-    /**
-     * 执行复合查询
-     */
-    private executeComplexQuery;
-    /**
-     * 更新系统
-     *
-     * 在每帧调用，处理系统的主要逻辑。
-     */
-    update(): void;
-    /**
-     * 后期更新系统
-     *
-     * 在所有系统的update方法执行完毕后调用。
-     */
-    lateUpdate(): void;
-    /**
-     * 在系统处理开始前调用
-     *
-     * 子类可以重写此方法进行预处理操作。
-     */
-    protected onBegin(): void;
-    /**
-     * 处理实体列表
-     *
-     * 系统的核心逻辑，子类必须实现此方法来定义具体的处理逻辑。
-     *
-     * @param entities 要处理的实体列表
-     */
-    protected process(entities: Entity[]): void;
-    /**
-     * 后期处理实体列表
-     *
-     * 在主要处理逻辑之后执行，子类可以重写此方法。
-     *
-     * @param entities 要处理的实体列表
-     */
-    protected lateProcess(entities: Entity[]): void;
-    /**
-     * 系统处理完毕后调用
-     *
-     * 子类可以重写此方法进行后处理操作。
-     */
-    protected onEnd(): void;
-    /**
-     * 检查系统是否需要处理
-     *
-     * 在启用系统时有用，但仅偶尔需要处理。
-     * 这只影响处理，不影响事件或订阅列表。
-     *
-     * @returns 如果系统应该处理，则为true，如果不处理则为false
-     */
-    protected onCheckProcessing(): boolean;
-    /**
-     * 获取系统的性能数据
-     *
-     * @returns 性能数据或undefined
-     */
-    getPerformanceData(): PerformanceData | undefined;
-    /**
-     * 获取系统的性能统计
-     *
-     * @returns 性能统计或undefined
-     */
-    getPerformanceStats(): PerformanceStats | undefined;
-    /**
-     * 重置系统的性能数据
-     */
-    resetPerformanceData(): void;
-    /**
-     * 获取系统信息的字符串表示
-     *
-     * @returns 系统信息字符串
-     */
-    toString(): string;
-    /**
-     * 更新实体跟踪，检查新增和移除的实体
-     */
-    private updateEntityTracking;
-    /**
-     * 当实体被添加到系统时调用
-     *
-     * 子类可以重写此方法来处理实体添加事件。
-     *
-     * @param entity 被添加的实体
-     */
-    protected onAdded(_entity: Entity): void;
-    /**
-     * 当实体从系统中移除时调用
-     *
-     * 子类可以重写此方法来处理实体移除事件。
-     *
-     * @param entity 被移除的实体
-     */
-    protected onRemoved(_entity: Entity): void;
-}
-
-/**
- * 实体处理器列表管理器
- * 管理场景中的所有实体系统
- */
-declare class EntityProcessorList {
-    private static readonly _logger;
-    private _processors;
-    private _isDirty;
-    /**
-     * 设置为脏状态，需要重新排序
-     */
-    setDirty(): void;
-    /**
-     * 添加实体处理器
-     * @param processor 要添加的处理器
-     */
-    add(processor: EntitySystem): void;
-    /**
-     * 移除实体处理器
-     * @param processor 要移除的处理器
-     */
-    remove(processor: EntitySystem): void;
-    /**
-     * 获取指定类型的处理器
-     * @param type 处理器类型
-     */
-    getProcessor<T extends EntitySystem>(type: new (...args: unknown[]) => T): T | null;
-    /**
-     * 开始处理
-     *
-     * 对所有处理器进行排序以确保正确的执行顺序。
-     */
-    begin(): void;
-    /**
-     * 结束处理
-     */
-    end(): void;
-    /**
-     * 更新所有处理器
-     */
-    update(): void;
-    /**
-     * 后期更新所有处理器
-     */
-    lateUpdate(): void;
-    /**
-     * 排序处理器
-     */
-    private sortProcessors;
-    /** 获取处理器列表 */
-    get processors(): EntitySystem[];
-    /** 获取处理器数量 */
-    get count(): number;
-}
-
 /**
  * 世代式ID池管理器
  *
@@ -3928,296 +3679,645 @@ declare class IdentifierPool {
     /**
      * 强制执行延迟回收处理
      *
-     * 在某些情况下可能需要立即处理延迟回收队列，
-     * 比如内存压力大或者需要精确的统计信息时。
+     * 在某些情况下可能需要立即处理延迟回收队列，
+     * 比如内存压力大或者需要精确的统计信息时。
+     */
+    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;
+}
+
+/**
+ * 游戏场景默认实现类
+ *
+ * 实现IScene接口，提供场景的基础功能。
+ * 推荐使用组合而非继承的方式来构建自定义场景。
+ */
+declare class Scene implements IScene {
+    /**
+     * 场景名称
+     *
+     * 用于标识和调试的友好名称。
+     */
+    name: string;
+    /**
+     * 场景中的实体集合
+     *
+     * 管理场景内所有实体的生命周期。
+     */
+    readonly entities: EntityList;
+    /**
+     * 实体系统处理器集合
+     *
+     * 管理场景内所有实体系统的执行。
+     */
+    readonly entityProcessors: EntityProcessorList;
+    /**
+     * 实体ID池
+     *
+     * 用于分配和回收实体的唯一标识符。
+     */
+    readonly identifierPool: IdentifierPool;
+    /**
+     * 组件存储管理器
+     *
+     * 高性能的组件存储和查询系统。
+     */
+    readonly componentStorageManager: ComponentStorageManager;
+    /**
+     * 查询系统
+     *
+     * 基于位掩码的高性能实体查询系统。
+     */
+    readonly querySystem: QuerySystem;
+    /**
+     * 事件系统
+     *
+     * 类型安全的事件系统。
+     */
+    readonly eventSystem: TypeSafeEventSystem;
+    /**
+     * 场景是否已开始运行
+     */
+    private _didSceneBegin;
+    /**
+     * 获取系统列表（兼容性属性）
+     */
+    get systems(): EntitySystem[];
+    /**
+     * 创建场景实例
+     */
+    constructor(config?: ISceneConfig);
+    /**
+     * 初始化场景
+     *
+     * 在场景创建时调用，子类可以重写此方法来设置初始实体和组件。
+     */
+    initialize(): void;
+    /**
+     * 场景开始运行时的回调
+     *
+     * 在场景开始运行时调用，可以在此方法中执行场景启动逻辑。
+     */
+    onStart(): void;
+    /**
+     * 场景卸载时的回调
+     *
+     * 在场景被销毁时调用，可以在此方法中执行清理工作。
+     */
+    unload(): void;
+    /**
+     * 开始场景，启动实体处理器等
+     *
+     * 这个方法会启动场景。它将启动实体处理器等，并调用onStart方法。
+     */
+    begin(): void;
+    /**
+     * 结束场景，清除实体、实体处理器等
+     *
+     * 这个方法会结束场景。它将移除所有实体，结束实体处理器等，并调用unload方法。
+     */
+    end(): void;
+    /**
+     * 更新场景，更新实体组件、实体处理器等
+     */
+    update(): void;
+    /**
+     * 将实体添加到此场景，并返回它
+     * @param name 实体名称
+     */
+    createEntity(name: string): Entity;
+    /**
+     * 在场景的实体列表中添加一个实体
+     * @param entity 要添加的实体
+     * @param deferCacheClear 是否延迟缓存清理（用于批量操作）
+     */
+    addEntity(entity: Entity, deferCacheClear?: boolean): Entity;
+    /**
+     * 批量创建实体（高性能版本）
+     * @param count 要创建的实体数量
+     * @param namePrefix 实体名称前缀
+     * @returns 创建的实体列表
+     */
+    createEntities(count: number, namePrefix?: string): Entity[];
+    /**
+     * 从场景中删除所有实体
+     */
+    destroyAllEntities(): void;
+    /**
+     * 搜索并返回第一个具有名称的实体
+     * @param name 实体名称
+     */
+    findEntity(name: string): Entity | null;
+    /**
+     * 根据ID查找实体
+     * @param id 实体ID
+     */
+    findEntityById(id: number): Entity | null;
+    /**
+     * 根据标签查找实体
+     * @param tag 实体标签
+     */
+    findEntitiesByTag(tag: number): Entity[];
+    /**
+     * 根据名称查找实体（别名方法）
+     * @param name 实体名称
+     */
+    getEntityByName(name: string): Entity | null;
+    /**
+     * 根据标签查找实体（别名方法）
+     * @param tag 实体标签
+     */
+    getEntitiesByTag(tag: number): Entity[];
+    /**
+     * 在场景中添加一个EntitySystem处理器
+     * @param processor 处理器
+     */
+    addEntityProcessor(processor: EntitySystem): EntitySystem;
+    /**
+     * 添加系统到场景（addEntityProcessor的别名）
+     * @param system 系统
+     */
+    addSystem(system: EntitySystem): EntitySystem;
+    /**
+     * 从场景中删除EntitySystem处理器
+     * @param processor 要删除的处理器
+     */
+    removeEntityProcessor(processor: EntitySystem): void;
+    /**
+     * 获取指定类型的EntitySystem处理器
+     * @param type 处理器类型
+     */
+    getEntityProcessor<T extends EntitySystem>(type: new (...args: unknown[]) => T): T | null;
+    /**
+     * 获取场景统计信息
+     */
+    getStats(): {
+        entityCount: number;
+        processorCount: number;
+        componentStorageStats: Map<string, any>;
+    };
+    /**
+     * 压缩组件存储（清理碎片）
+     */
+    compactComponentStorage(): void;
+    /**
+     * 获取场景的调试信息
+     */
+    getDebugInfo(): {
+        name: string;
+        entityCount: number;
+        processorCount: number;
+        isRunning: boolean;
+        entities: Array<{
+            name: string;
+            id: number;
+            componentCount: number;
+            componentTypes: string[];
+        }>;
+        processors: Array<{
+            name: string;
+            updateOrder: number;
+            entityCount: number;
+        }>;
+        componentStats: Map<string, any>;
+    };
+}
+
+/**
+ * 实体系统的基类
+ *
+ * 用于处理一组符合特定条件的实体。系统是ECS架构中的逻辑处理单元，
+ * 负责对拥有特定组件组合的实体执行业务逻辑。
+ *
+ * @example
+ * ```typescript
+ * class MovementSystem extends EntitySystem {
+ *     constructor() {
+ *         super(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 _updateOrder;
+    private _enabled;
+    private _performanceMonitor;
+    private _systemName;
+    private _initialized;
+    private _matcher;
+    private _trackedEntities;
+    private _lastQueryResult;
+    /**
+     * 获取系统处理的实体列表（动态查询）
+     */
+    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 | null;
+    set scene(value: Scene | null);
+    /**
+     * 获取实体匹配器
+     */
+    get matcher(): Matcher;
+    /**
+     * 设置更新时序
+     * @param order 更新时序
+     */
+    setUpdateOrder(order: number): void;
+    /**
+     * 系统初始化（框架调用）
+     *
+     * 在系统创建时调用。框架内部使用，用户不应直接调用。
+     */
+    initialize(): void;
+    /**
+     * 系统初始化回调
+     *
+     * 子类可以重写此方法进行初始化操作。
+     */
+    protected onInitialize(): void;
+    /**
+     * 重置系统状态
+     *
+     * 当系统从场景中移除时调用，重置初始化状态以便重新添加时能正确初始化。
+     */
+    reset(): void;
+    /**
+     * 查询匹配的实体
+     */
+    private queryEntities;
+    /**
+     * 检查是否为单一条件查询
+     */
+    private isSingleCondition;
+    /**
+     * 执行单一条件查询
+     */
+    private executeSingleConditionQuery;
+    /**
+     * 执行复合查询
+     */
+    private executeComplexQuery;
+    /**
+     * 更新系统
+     *
+     * 在每帧调用，处理系统的主要逻辑。
+     */
+    update(): void;
+    /**
+     * 后期更新系统
+     *
+     * 在所有系统的update方法执行完毕后调用。
+     */
+    lateUpdate(): void;
+    /**
+     * 在系统处理开始前调用
+     *
+     * 子类可以重写此方法进行预处理操作。
+     */
+    protected onBegin(): void;
+    /**
+     * 处理实体列表
+     *
+     * 系统的核心逻辑，子类必须实现此方法来定义具体的处理逻辑。
+     *
+     * @param entities 要处理的实体列表
+     */
+    protected process(entities: Entity[]): void;
+    /**
+     * 后期处理实体列表
+     *
+     * 在主要处理逻辑之后执行，子类可以重写此方法。
+     *
+     * @param entities 要处理的实体列表
+     */
+    protected lateProcess(entities: Entity[]): void;
+    /**
+     * 系统处理完毕后调用
+     *
+     * 子类可以重写此方法进行后处理操作。
+     */
+    protected onEnd(): void;
+    /**
+     * 检查系统是否需要处理
+     *
+     * 在启用系统时有用，但仅偶尔需要处理。
+     * 这只影响处理，不影响事件或订阅列表。
+     *
+     * @returns 如果系统应该处理，则为true，如果不处理则为false
+     */
+    protected onCheckProcessing(): boolean;
+    /**
+     * 获取系统的性能数据
+     *
+     * @returns 性能数据或undefined
+     */
+    getPerformanceData(): PerformanceData | undefined;
+    /**
+     * 获取系统的性能统计
+     *
+     * @returns 性能统计或undefined
+     */
+    getPerformanceStats(): PerformanceStats | undefined;
+    /**
+     * 重置系统的性能数据
+     */
+    resetPerformanceData(): void;
+    /**
+     * 获取系统信息的字符串表示
+     *
+     * @returns 系统信息字符串
+     */
+    toString(): string;
+    /**
+     * 更新实体跟踪，检查新增和移除的实体
+     */
+    private updateEntityTracking;
+    /**
+     * 当实体被添加到系统时调用
+     *
+     * 子类可以重写此方法来处理实体添加事件。
+     *
+     * @param entity 被添加的实体
      */
-    forceProcessDelayedRecycle(): void;
+    protected onAdded(_entity: Entity): void;
     /**
-     * 清理过期的延迟回收项
+     * 当实体从系统中移除时调用
      *
-     * 将超过延迟时间的回收项真正回收到空闲列表中。
+     * 子类可以重写此方法来处理实体移除事件。
      *
-     * @param forceAll 是否强制处理所有延迟回收项
-     * @private
+     * @param entity 被移除的实体
      */
-    private _processDelayedRecycle;
+    protected onRemoved(_entity: Entity): void;
+}
+
+/**
+ * 实体处理器列表管理器
+ * 管理场景中的所有实体系统
+ */
+declare class EntityProcessorList {
+    private static readonly _logger;
+    private _processors;
+    private _isDirty;
     /**
-     * 预分配世代信息
-     *
-     * @param startIndex 起始索引
-     * @param count 分配数量
-     * @private
+     * 设置为脏状态，需要重新排序
      */
-    private _preAllocateGenerations;
+    setDirty(): void;
     /**
-     * 确保指定索引的世代信息存在
-     *
-     * @param index 索引
-     * @private
+     * 添加实体处理器
+     * @param processor 要添加的处理器
      */
-    private _ensureGenerationCapacity;
+    add(processor: EntitySystem): void;
     /**
-     * 计算内存使用量
-     *
-     * @returns 内存使用字节数
-     * @private
+     * 移除实体处理器
+     * @param processor 要移除的处理器
      */
-    private _calculateMemoryUsage;
+    remove(processor: EntitySystem): void;
     /**
-     * 打包索引和世代为32位ID
-     *
-     * @param index 索引（16位）
-     * @param generation 世代版本（16位）
-     * @returns 打包后的32位ID
-     * @private
+     * 获取指定类型的处理器
+     * @param type 处理器类型
      */
-    private _packId;
+    getProcessor<T extends EntitySystem>(type: new (...args: unknown[]) => T): T | null;
     /**
-     * 从ID中解包索引
+     * 开始处理
      *
-     * @param id 32位ID
-     * @returns 索引部分（16位）
-     * @private
+     * 对所有处理器进行排序以确保正确的执行顺序。
      */
-    private _unpackIndex;
+    begin(): void;
     /**
-     * 从ID中解包世代版本
-     *
-     * @param id 32位ID
-     * @returns 世代版本部分（16位）
-     * @private
+     * 结束处理
      */
-    private _unpackGeneration;
+    end(): void;
     /**
-     * 内部ID有效性检查
-     *
-     * @param index 索引
-     * @param generation 世代版本
-     * @returns 是否有效
-     * @private
+     * 更新所有处理器
      */
-    private _isValidId;
+    update(): void;
+    /**
+     * 后期更新所有处理器
+     */
+    lateUpdate(): void;
+    /**
+     * 排序处理器
+     */
+    private sortProcessors;
+    /** 获取处理器列表 */
+    get processors(): EntitySystem[];
+    /** 获取处理器数量 */
+    get count(): number;
 }
 
 /**
- * 游戏场景类
+ * 场景接口定义
  *
- * 管理游戏场景中的所有实体和系统，提供场景生命周期管理。
- * 场景是游戏世界的容器，负责协调实体和系统的运行。
- *
- * @example
- * ```typescript
- * class GameScene extends Scene {
- *     public initialize(): void {
- *         // 创建游戏实体
- *         const player = this.createEntity("Player");
- *
- *         // 添加系统
- *         this.addEntityProcessor(new MovementSystem());
- *     }
- * }
- * ```
+ * 定义场景应该实现的核心功能和属性，使用接口而非继承提供更灵活的实现方式。
  */
-declare class Scene {
+interface IScene {
     /**
      * 场景名称
-     *
-     * 用于标识和调试的友好名称。
      */
     name: string;
     /**
      * 场景中的实体集合
-     *
-     * 管理场景内所有实体的生命周期。
      */
     readonly entities: EntityList;
     /**
      * 实体系统处理器集合
-     *
-     * 管理场景内所有实体系统的执行。
      */
     readonly entityProcessors: EntityProcessorList;
     /**
-     * 实体ID池
-     *
-     * 用于分配和回收实体的唯一标识符。
+     * 标识符池
      */
     readonly identifierPool: IdentifierPool;
     /**
      * 组件存储管理器
-     *
-     * 高性能的组件存储和查询系统。
      */
     readonly componentStorageManager: ComponentStorageManager;
     /**
      * 查询系统
-     *
-     * 基于位掩码的高性能实体查询系统。
      */
     readonly querySystem: QuerySystem;
     /**
      * 事件系统
-     *
-     * 类型安全的事件系统。
      */
     readonly eventSystem: TypeSafeEventSystem;
     /**
-     * 场景是否已开始运行
-     */
-    private _didSceneBegin;
-    /**
-     * 场景是否已初始化
-     */
-    private _isInitialized;
-    /**
-     * 获取系统列表（兼容性属性）
-     */
-    get systems(): EntitySystem[];
-    /**
-     * 创建场景实例
+     * 获取系统列表
      */
-    constructor();
+    readonly systems: EntitySystem[];
     /**
      * 初始化场景
-     *
-     * 在场景创建时调用，子类可以重写此方法来设置初始实体和组件。
      */
     initialize(): void;
     /**
      * 场景开始运行时的回调
-     *
-     * 在场景开始运行时调用，可以在此方法中执行场景启动逻辑。
      */
     onStart(): void;
     /**
      * 场景卸载时的回调
-     *
-     * 在场景被销毁时调用，可以在此方法中执行清理工作。
      */
     unload(): void;
     /**
-     * 开始场景，启动实体处理器等
-     *
-     * 这个方法会启动场景。它将启动实体处理器等，并调用onStart方法。
+     * 开始场景
      */
     begin(): void;
     /**
-     * 结束场景，清除实体、实体处理器等
-     *
-     * 这个方法会结束场景。它将移除所有实体，结束实体处理器等，并调用unload方法。
+     * 结束场景
      */
     end(): void;
     /**
-     * 更新场景，更新实体组件、实体处理器等
+     * 更新场景
      */
     update(): void;
     /**
-     * 将实体添加到此场景，并返回它
-     * @param name 实体名称
+     * 创建实体
      */
     createEntity(name: string): Entity;
     /**
-     * 在场景的实体列表中添加一个实体
-     * @param entity 要添加的实体
-     * @param deferCacheClear 是否延迟缓存清理（用于批量操作）
+     * 添加实体
      */
     addEntity(entity: Entity, deferCacheClear?: boolean): Entity;
-    /**
-     * 批量创建实体（高性能版本）
-     * @param count 要创建的实体数量
-     * @param namePrefix 实体名称前缀
-     * @returns 创建的实体列表
-     */
-    createEntities(count: number, namePrefix?: string): Entity[];
     /**
      * 批量创建实体
-     * @param count 要创建的实体数量
-     * @param namePrefix 实体名称前缀
-     * @returns 创建的实体列表
      */
-    createEntitiesOld(count: number, namePrefix?: string): Entity[];
+    createEntities(count: number, namePrefix?: string): Entity[];
     /**
-     * 从场景中删除所有实体
+     * 销毁所有实体
      */
     destroyAllEntities(): void;
     /**
-     * 搜索并返回第一个具有名称的实体
-     * @param name 实体名称
+     * 查找实体
      */
     findEntity(name: string): Entity | null;
-    /**
-     * 根据ID查找实体
-     * @param id 实体ID
-     */
-    findEntityById(id: number): Entity | null;
     /**
      * 根据标签查找实体
-     * @param tag 实体标签
      */
     findEntitiesByTag(tag: number): Entity[];
     /**
-     * 根据名称查找实体（别名方法）
-     * @param name 实体名称
-     */
-    getEntityByName(name: string): Entity | null;
-    /**
-     * 根据标签查找实体（别名方法）
-     * @param tag 实体标签
-     */
-    getEntitiesByTag(tag: number): Entity[];
-    /**
-     * 在场景中添加一个EntitySystem处理器
-     * @param processor 处理器
+     * 添加实体处理器
      */
     addEntityProcessor(processor: EntitySystem): EntitySystem;
     /**
-     * 添加系统到场景（addEntityProcessor的别名）
-     * @param system 系统
-     */
-    addSystem(system: EntitySystem): EntitySystem;
-    /**
-     * 从场景中删除EntitySystem处理器
-     * @param processor 要删除的处理器
+     * 移除实体处理器
      */
     removeEntityProcessor(processor: EntitySystem): void;
     /**
-     * 获取指定类型的EntitySystem处理器
-     * @param type 处理器类型
+     * 获取实体处理器
      */
-    getEntityProcessor<T extends EntitySystem>(type: new (...args: unknown[]) => T): T | null;
+    getEntityProcessor<T extends EntitySystem>(type: new (...args: any[]) => T): T | null;
+}
+/**
+ * 场景工厂接口
+ */
+interface ISceneFactory<T extends IScene> {
     /**
-     * 获取场景统计信息
+     * 创建场景实例
      */
-    getStats(): {
-        entityCount: number;
-        processorCount: number;
-        componentStorageStats: Map<string, any>;
-    };
+    createScene(): T;
+}
+/**
+ * 场景配置接口
+ */
+interface ISceneConfig {
     /**
-     * 压缩组件存储（清理碎片）
+     * 场景名称
      */
-    compactComponentStorage(): void;
+    name?: string;
     /**
-     * 获取场景的调试信息
+     * 调试配置
      */
-    getDebugInfo(): {
-        name: string;
-        entityCount: number;
-        processorCount: number;
-        isRunning: boolean;
-        entities: Array<{
-            name: string;
-            id: number;
-            componentCount: number;
-            componentTypes: string[];
-        }>;
-        processors: Array<{
-            name: string;
-            updateOrder: number;
-            entityCount: number;
-        }>;
-        componentStats: Map<string, any>;
-    };
+    debug?: boolean;
 }
 
 /**
@@ -4227,7 +4327,7 @@ declare class EntityBuilder {
     private entity;
     private scene;
     private storageManager;
-    constructor(scene: Scene, storageManager: ComponentStorageManager);
+    constructor(scene: IScene, storageManager: ComponentStorageManager);
     /**
      * 设置实体名称
      * @param name 实体名称
@@ -4472,7 +4572,7 @@ declare class ECSFluentAPI {
     private scene;
     private querySystem;
     private eventSystem;
-    constructor(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem);
+    constructor(scene: IScene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem);
     /**
      * 创建实体构建器
      * @returns 实体构建器
@@ -4564,9 +4664,9 @@ declare class ECSFluentAPI {
     getStats(): {
         entityCount: number;
         systemCount: number;
-        componentStats: Map<string, any>;
+        componentStats: Map<string, unknown>;
         queryStats: unknown;
-        eventStats: Map<string, any>;
+        eventStats: Map<string, unknown>;
     };
 }
 /**
@@ -4576,7 +4676,7 @@ declare class ECSFluentAPI {
  * @param eventSystem 事件系统
  * @returns ECS流式API实例
  */
-declare function createECSAPI(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem): ECSFluentAPI;
+declare function createECSAPI(scene: IScene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem): ECSFluentAPI;
 
 /**
  * 实体数据收集器
@@ -4894,10 +4994,6 @@ declare class DebugManager {
      * 收集性能统计信息
      */
     private collectPerformanceStats;
-    /**
-     * 获取内存大小分类
-     */
-    private getMemorySizeCategory;
     /**
      * 获取调试数据
      */
@@ -4970,7 +5066,7 @@ declare class Core {
      *
      * 存储下一帧要切换到的场景实例。
      */
-    _nextScene: Scene | null;
+    _nextScene: IScene | null;
     /**
      * 全局管理器集合
      *
@@ -5004,7 +5100,7 @@ declare class Core {
     /**
      * 当前活动场景
      */
-    _scene?: Scene;
+    _scene?: IScene;
     /**
      * 调试管理器
      *
@@ -5036,16 +5132,54 @@ declare class Core {
      *
      * @returns 当前场景实例，如果没有则返回null
      */
-    static get scene(): Scene | null;
+    static get scene(): IScene | null;
+    /**
+     * 设置当前场景（已废弃）
+     *
+     * @deprecated 请使用 Core.setScene() 方法代替。scene setter 可能导致场景延迟激活的时序问题，
+     * 而 setScene() 提供更好的类型安全性和可预测的激活时序。
+     *
+     * 迁移示例：
+     * ```typescript
+     * // 旧方式（已废弃）
+     * Core.scene = myScene;
+     *
+     * // 新方式（推荐）
+     * Core.setScene(myScene);
+     * ```
+     *
+     * 如果当前没有场景，会立即切换；否则会在下一帧切换。
+     *
+     * @param value - 场景实例
+     */
+    static set scene(value: IScene | null);
     /**
-     * 设置当前活动的场景
+     * 类型安全的场景设置方法（推荐）
+     *
+     * 这是设置场景的推荐方法，提供更好的类型安全性和可预测的激活时序。
+     * 相比于 scene setter，此方法能确保场景正确初始化和激活。
      *
      * 如果当前没有场景，会立即切换；否则会在下一帧切换。
      *
-     * @param value - 要设置的场景实例
-     * @throws {Error} 当场景为空时抛出错误
+     * @param scene - 要设置的场景实例
+     * @returns 设置的场景实例，便于链式调用
+     *
+     * @example
+     * ```typescript
+     * const myScene = new MyScene();
+     * Core.setScene(myScene);
+     *
+     * // 链式调用
+     * const scene = Core.setScene(new MyScene()).addSystem(new MySystem());
+     * ```
+     */
+    static setScene<T extends IScene>(scene: T): T;
+    /**
+     * 类型安全的场景获取方法
+     *
+     * @returns 当前场景实例
      */
-    static set scene(value: Scene | null);
+    static getScene<T extends IScene>(): T | null;
     /**
      * 创建Core实例
      *
@@ -5113,7 +5247,7 @@ declare class Core {
      * @param onTime - 定时器触发时的回调函数
      * @returns 创建的定时器实例
      */
-    static schedule<TContext = unknown>(timeInSeconds: number, repeats: boolean | undefined, context: TContext | undefined, onTime: (timer: ITimer<TContext>) => void): Timer<TContext>;
+    static schedule<TContext = unknown>(timeInSeconds: number, repeats?: boolean, context?: TContext, onTime?: (timer: ITimer<TContext>) => void): Timer<TContext>;
     /**
      * 获取ECS流式API
      *
@@ -5135,7 +5269,7 @@ declare class Core {
      *
      * @returns 当前调试数据，如果调试未启用则返回null
      */
-    static getDebugData(): any;
+    static getDebugData(): unknown;
     /**
      * 检查调试是否启用
      *
@@ -5154,6 +5288,12 @@ declare class Core {
      * @returns 是否支持BigInt
      */
     static get supportsBigInt(): boolean;
+    /**
+     * 内部场景设置方法
+     *
+     * @param scene - 要设置的场景实例
+     */
+    private setSceneInternal;
     /**
      * 场景切换回调
      *
@@ -6358,4 +6498,4 @@ declare class Time {
 }
 
 export { ArchetypeSystem, AsyncEventHandler, BigIntFactory, BitmapComponentIndex, Bits, Component, ComponentDataCollector, ComponentIndexManager, ComponentPool, ComponentPoolManager, ComponentRegistry, ComponentStorage, ComponentTypeManager, ConsoleLogger, Core, DebugManager, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, EnableSoA, Entity, EntityDataCollector, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler, EventPriority, EventTypeValidator, Float32, Float64, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, HighPrecision, IdentifierPool, IndexType, Int32, IntervalSystem, LogLevel, Logger, LoggerManager, Matcher, NumberExtension, PassiveSystem, PerformanceDataCollector, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, SceneDataCollector, SerializeMap, SoAStorage, SystemDataCollector, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, WebSocketManager, createECSAPI, createLogger, setGlobalLogLevel };
-export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, ISceneDebugData, ISceneEventData, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };
+export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentDebugData, IComponentEventData, ICoreConfig, IECSDebugConfig, IECSDebugData, IEntityDebugData, IEntityEventData, IEntityHierarchyNode, IEventBus, IEventData, IEventListenerConfig, IEventStats, ILogger, IPerformanceDebugData, IPerformanceEventData, IPoolable, IScene, ISceneConfig, ISceneDebugData, ISceneEventData, ISceneFactory, ISystemBase, ISystemDebugData, ISystemEventData, ITimer, LoggerConfig, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };