@esengine/ecs-framework 2.1.16 → 2.1.17

package/README.md

@@ -104,18 +104,41 @@ scene.addEntityProcessor(new MovementSystem());
 
 ### 游戏循环
 
+ECS框架需要在游戏引擎的更新循环中调用：
+
 ```typescript
-function gameLoop() {
-    // 更新场景
-    scene.update();
-    
-    // 发送帧更新事件
-    Core.emitter.emit(CoreEvents.frameUpdated);
-    
-    requestAnimationFrame(gameLoop);
+// 统一的API：传入deltaTime
+Core.update(deltaTime);
+```
+
+**不同引擎的集成示例：**
+
+```typescript
+// Laya引擎
+Laya.timer.frameLoop(1, this, () => {
+    const deltaTime = Laya.timer.delta / 1000; // 转换为秒
+    Core.update(deltaTime);
+});
+
+// Cocos Creator
+update(deltaTime: number) {
+    Core.update(deltaTime);
+}
+
+// Unity (C#)
+void Update() {
+    Core.Update(Time.deltaTime);
 }
 
-gameLoop();
+// 原生浏览器环境
+let lastTime = 0;
+function gameLoop(currentTime: number) {
+    const deltaTime = lastTime > 0 ? (currentTime - lastTime) / 1000 : 0.016;
+    lastTime = currentTime;
+    Core.update(deltaTime);
+    requestAnimationFrame(gameLoop);
+}
+requestAnimationFrame(gameLoop);
 ```
 
 ## 实体管理器
@@ -312,7 +335,7 @@ ecs-framework/
 
 ### 🎯 新手入门
 - **[📖 新手教程完整指南](docs/beginner-tutorials.md)** - 完整学习路径，从零开始 ⭐ **强烈推荐**
-- [🚀 快速入门](docs/getting-started.md) - 详细的入门教程
+- **[🚀 快速入门](docs/getting-started.md)** - 详细的入门教程，包含Laya/Cocos/Node.js集成指南 ⭐ **平台集成必读**
 - [🧠 技术概念详解](docs/concepts-explained.md) - 通俗易懂的技术概念解释 ⭐ **推荐新手阅读**
 - [🎯 位掩码使用指南](docs/bitmask-guide.md) - 位掩码概念、原理和高级使用技巧
 - [💡 使用场景示例](docs/use-cases.md) - 不同类型游戏的具体应用案例

package/index.d.ts

@@ -1,204 +1,7 @@
 /**
- * @esengine/ecs-framework v2.1.16
+ * @esengine/ecs-framework v2.1.17
  * TypeScript definitions
  */
-/**
- * 用于包装事件的一个小类
- */
-declare class FuncPack {
-    /** 函数 */
-    func: Function;
-    /** 上下文 */
-    context: any;
-    constructor(func: Function, context: any);
-}
-/**
- * 用于事件管理
- */
-declare class Emitter<T> {
-    private _messageTable;
-    constructor();
-    /**
-     * 开始监听项
-     * @param eventType 监听类型
-     * @param handler 监听函数
-     * @param context 监听上下文
-     */
-    addObserver(eventType: T, handler: Function, context: any): void;
-    /**
-     * 移除监听项
-     * @param eventType 事件类型
-     * @param handler 事件函数
-     */
-    removeObserver(eventType: T, handler: Function): void;
-    /**
-     * 触发该事件
-     * @param eventType 事件类型
-     * @param data 事件数据
-     */
-    emit(eventType: T, ...data: any[]): void;
-    /**
-     * 判断是否存在该类型的观察者
-     * @param eventType 事件类型
-     * @param handler 事件函数
-     */
-    hasObserver(eventType: T, handler: Function): boolean;
-}
-
-/**
- * 核心事件枚举
- * 定义框架中的核心事件类型
- */
-declare enum CoreEvents {
-    /**
-     * 当场景发生变化时触发
-     */
-    sceneChanged = 0,
-    /**
-     * 每帧更新事件
-     */
-    frameUpdated = 1,
-    /**
-     * 当渲染发生时触发
-     */
-    renderChanged = 2
-}
-/**
- * ECS事件类型枚举
- * 定义实体组件系统中的所有事件类型
- */
-declare enum ECSEventType {
-    ENTITY_CREATED = "entity:created",
-    ENTITY_DESTROYED = "entity:destroyed",
-    ENTITY_ENABLED = "entity:enabled",
-    ENTITY_DISABLED = "entity:disabled",
-    ENTITY_TAG_ADDED = "entity:tag:added",
-    ENTITY_TAG_REMOVED = "entity:tag:removed",
-    ENTITY_NAME_CHANGED = "entity:name:changed",
-    COMPONENT_ADDED = "component:added",
-    COMPONENT_REMOVED = "component:removed",
-    COMPONENT_MODIFIED = "component:modified",
-    COMPONENT_ENABLED = "component:enabled",
-    COMPONENT_DISABLED = "component:disabled",
-    SYSTEM_ADDED = "system:added",
-    SYSTEM_REMOVED = "system:removed",
-    SYSTEM_ENABLED = "system:enabled",
-    SYSTEM_DISABLED = "system:disabled",
-    SYSTEM_PROCESSING_START = "system:processing:start",
-    SYSTEM_PROCESSING_END = "system:processing:end",
-    SYSTEM_ERROR = "system:error",
-    SCENE_CREATED = "scene:created",
-    SCENE_DESTROYED = "scene:destroyed",
-    SCENE_ACTIVATED = "scene:activated",
-    SCENE_DEACTIVATED = "scene:deactivated",
-    SCENE_PAUSED = "scene:paused",
-    SCENE_RESUMED = "scene:resumed",
-    QUERY_EXECUTED = "query:executed",
-    QUERY_CACHE_HIT = "query:cache:hit",
-    QUERY_CACHE_MISS = "query:cache:miss",
-    QUERY_OPTIMIZED = "query:optimized",
-    PERFORMANCE_WARNING = "performance:warning",
-    PERFORMANCE_CRITICAL = "performance:critical",
-    MEMORY_USAGE_HIGH = "memory:usage:high",
-    FRAME_RATE_DROP = "frame:rate:drop",
-    INDEX_CREATED = "index:created",
-    INDEX_UPDATED = "index:updated",
-    INDEX_OPTIMIZED = "index:optimized",
-    ARCHETYPE_CREATED = "archetype:created",
-    ARCHETYPE_ENTITY_ADDED = "archetype:entity:added",
-    ARCHETYPE_ENTITY_REMOVED = "archetype:entity:removed",
-    DIRTY_MARK_ADDED = "dirty:mark:added",
-    DIRTY_BATCH_PROCESSED = "dirty:batch:processed",
-    ERROR_OCCURRED = "error:occurred",
-    WARNING_ISSUED = "warning:issued",
-    FRAMEWORK_INITIALIZED = "framework:initialized",
-    FRAMEWORK_SHUTDOWN = "framework:shutdown",
-    DEBUG_INFO = "debug:info",
-    DEBUG_STATS_UPDATED = "debug:stats:updated"
-}
-/**
- * 事件优先级枚举
- * 定义事件处理的优先级级别
- */
-declare enum EventPriority {
-    LOWEST = 0,
-    LOW = 25,
-    NORMAL = 50,
-    HIGH = 75,
-    HIGHEST = 100,
-    CRITICAL = 200
-}
-/**
- * 预定义的事件类型常量
- * 提供类型安全的事件类型字符串
- */
-declare const EVENT_TYPES: {
-    readonly CORE: {
-        readonly SCENE_CHANGED: "core:scene:changed";
-        readonly FRAME_UPDATED: "core:frame:updated";
-        readonly RENDER_CHANGED: "core:render:changed";
-    };
-    readonly ENTITY: {
-        readonly CREATED: ECSEventType.ENTITY_CREATED;
-        readonly DESTROYED: ECSEventType.ENTITY_DESTROYED;
-        readonly ENABLED: ECSEventType.ENTITY_ENABLED;
-        readonly DISABLED: ECSEventType.ENTITY_DISABLED;
-        readonly TAG_ADDED: ECSEventType.ENTITY_TAG_ADDED;
-        readonly TAG_REMOVED: ECSEventType.ENTITY_TAG_REMOVED;
-        readonly NAME_CHANGED: ECSEventType.ENTITY_NAME_CHANGED;
-    };
-    readonly COMPONENT: {
-        readonly ADDED: ECSEventType.COMPONENT_ADDED;
-        readonly REMOVED: ECSEventType.COMPONENT_REMOVED;
-        readonly MODIFIED: ECSEventType.COMPONENT_MODIFIED;
-        readonly ENABLED: ECSEventType.COMPONENT_ENABLED;
-        readonly DISABLED: ECSEventType.COMPONENT_DISABLED;
-    };
-    readonly SYSTEM: {
-        readonly ADDED: ECSEventType.SYSTEM_ADDED;
-        readonly REMOVED: ECSEventType.SYSTEM_REMOVED;
-        readonly ENABLED: ECSEventType.SYSTEM_ENABLED;
-        readonly DISABLED: ECSEventType.SYSTEM_DISABLED;
-        readonly PROCESSING_START: ECSEventType.SYSTEM_PROCESSING_START;
-        readonly PROCESSING_END: ECSEventType.SYSTEM_PROCESSING_END;
-        readonly ERROR: ECSEventType.SYSTEM_ERROR;
-    };
-    readonly PERFORMANCE: {
-        readonly WARNING: ECSEventType.PERFORMANCE_WARNING;
-        readonly CRITICAL: ECSEventType.PERFORMANCE_CRITICAL;
-        readonly MEMORY_HIGH: ECSEventType.MEMORY_USAGE_HIGH;
-        readonly FRAME_DROP: ECSEventType.FRAME_RATE_DROP;
-    };
-};
-/**
- * 事件类型验证器
- * 验证事件类型是否有效
- */
-declare class EventTypeValidator {
-    private static validTypes;
-    /**
-     * 验证事件类型是否有效
-     * @param eventType 事件类型
-     * @returns 是否有效
-     */
-    static isValid(eventType: string): boolean;
-    /**
-     * 获取所有有效的事件类型
-     * @returns 事件类型数组
-     */
-    static getAllValidTypes(): string[];
-    /**
-     * 添加自定义事件类型
-     * @param eventType 事件类型
-     */
-    static addCustomType(eventType: string): void;
-    /**
-     * 移除自定义事件类型
-     * @param eventType 事件类型
-     */
-    static removeCustomType(eventType: string): void;
-}
-
 /**
  * 全局管理器的基类。所有全局管理器都应该从此类继承。
  */
@@ -3920,7 +3723,7 @@ declare function createECSAPI(scene: Scene, querySystem: QuerySystem, eventSyste
  * 游戏引擎核心类
  *
  * 负责管理游戏的生命周期、场景切换、全局管理器和定时器系统。
- * 提供统一的游戏循环和事件分发机制。
+ * 提供统一的游戏循环管理。
  *
  * @example
  * ```typescript
@@ -3930,6 +3733,12 @@ declare function createECSAPI(scene: Scene, querySystem: QuerySystem, eventSyste
  * // 设置场景
  * Core.scene = new MyScene();
  *
+ * // 在游戏循环中更新（Laya引擎示例）
+ * Laya.timer.frameLoop(1, this, () => {
+ *     const deltaTime = Laya.timer.delta / 1000;
+ *     Core.update(deltaTime);
+ * });
+ *
  * // 调度定时器
  * Core.schedule(1.0, false, null, (timer) => {
  *     console.log("1秒后执行");
@@ -3937,12 +3746,6 @@ declare function createECSAPI(scene: Scene, querySystem: QuerySystem, eventSyste
  * ```
  */
 declare class Core {
-    /**
-     * 核心事件发射器
-     *
-     * 用于发布和订阅核心级别的事件，如帧更新、场景切换等。
-     */
-    static emitter: Emitter<CoreEvents>;
     /**
      * 游戏暂停状态
      *
@@ -4039,10 +3842,36 @@ declare class Core {
      * 如果实例已存在，则返回现有实例。
      *
      * @param debug - 是否为调试模式，默认为true
-     * @param options - 额外的配置选项
      * @returns Core实例
      */
     static create(debug?: boolean): Core;
+    /**
+     * 更新游戏逻辑
+     *
+     * 此方法应该在游戏引擎的更新循环中调用。
+     *
+     * @param deltaTime - 外部引擎提供的帧时间间隔（秒）
+     *
+     * @example
+     * ```typescript
+     * // Laya引擎
+     * Laya.timer.frameLoop(1, this, () => {
+     *     const deltaTime = Laya.timer.delta / 1000;
+     *     Core.update(deltaTime);
+     * });
+     *
+     * // Cocos Creator
+     * update(deltaTime: number) {
+     *     Core.update(deltaTime);
+     * }
+     *
+     * // Unity (C#)
+     * void Update() {
+     *     Core.Update(Time.deltaTime);
+     * }
+     * ```
+     */
+    static update(deltaTime: number): void;
     /**
      * 注册全局管理器
      *
@@ -4097,13 +3926,185 @@ declare class Core {
      */
     protected initialize(): void;
     /**
-     * 游戏主循环更新
+     * 内部更新方法
      *
-     * 每帧调用，负责更新时间系统、全局管理器和当前场景。
-     *
-     * @param currentTime - 当前时间戳，默认为-1（使用系统时间）
+     * @param deltaTime - 帧时间间隔（秒）
+     */
+    private updateInternal;
+}
+
+/**
+ * 用于包装事件的一个小类
+ */
+declare class FuncPack {
+    /** 函数 */
+    func: Function;
+    /** 上下文 */
+    context: any;
+    constructor(func: Function, context: any);
+}
+/**
+ * 用于事件管理
+ */
+declare class Emitter<T> {
+    private _messageTable;
+    constructor();
+    /**
+     * 开始监听项
+     * @param eventType 监听类型
+     * @param handler 监听函数
+     * @param context 监听上下文
+     */
+    addObserver(eventType: T, handler: Function, context: any): void;
+    /**
+     * 移除监听项
+     * @param eventType 事件类型
+     * @param handler 事件函数
+     */
+    removeObserver(eventType: T, handler: Function): void;
+    /**
+     * 触发该事件
+     * @param eventType 事件类型
+     * @param data 事件数据
+     */
+    emit(eventType: T, ...data: any[]): void;
+    /**
+     * 判断是否存在该类型的观察者
+     * @param eventType 事件类型
+     * @param handler 事件函数
+     */
+    hasObserver(eventType: T, handler: Function): boolean;
+}
+
+/**
+ * ECS事件类型枚举
+ * 定义实体组件系统中的所有事件类型
+ */
+declare enum ECSEventType {
+    ENTITY_CREATED = "entity:created",
+    ENTITY_DESTROYED = "entity:destroyed",
+    ENTITY_ENABLED = "entity:enabled",
+    ENTITY_DISABLED = "entity:disabled",
+    ENTITY_TAG_ADDED = "entity:tag:added",
+    ENTITY_TAG_REMOVED = "entity:tag:removed",
+    ENTITY_NAME_CHANGED = "entity:name:changed",
+    COMPONENT_ADDED = "component:added",
+    COMPONENT_REMOVED = "component:removed",
+    COMPONENT_MODIFIED = "component:modified",
+    COMPONENT_ENABLED = "component:enabled",
+    COMPONENT_DISABLED = "component:disabled",
+    SYSTEM_ADDED = "system:added",
+    SYSTEM_REMOVED = "system:removed",
+    SYSTEM_ENABLED = "system:enabled",
+    SYSTEM_DISABLED = "system:disabled",
+    SYSTEM_PROCESSING_START = "system:processing:start",
+    SYSTEM_PROCESSING_END = "system:processing:end",
+    SYSTEM_ERROR = "system:error",
+    SCENE_CREATED = "scene:created",
+    SCENE_DESTROYED = "scene:destroyed",
+    SCENE_ACTIVATED = "scene:activated",
+    SCENE_DEACTIVATED = "scene:deactivated",
+    SCENE_PAUSED = "scene:paused",
+    SCENE_RESUMED = "scene:resumed",
+    QUERY_EXECUTED = "query:executed",
+    QUERY_CACHE_HIT = "query:cache:hit",
+    QUERY_CACHE_MISS = "query:cache:miss",
+    QUERY_OPTIMIZED = "query:optimized",
+    PERFORMANCE_WARNING = "performance:warning",
+    PERFORMANCE_CRITICAL = "performance:critical",
+    MEMORY_USAGE_HIGH = "memory:usage:high",
+    FRAME_RATE_DROP = "frame:rate:drop",
+    INDEX_CREATED = "index:created",
+    INDEX_UPDATED = "index:updated",
+    INDEX_OPTIMIZED = "index:optimized",
+    ARCHETYPE_CREATED = "archetype:created",
+    ARCHETYPE_ENTITY_ADDED = "archetype:entity:added",
+    ARCHETYPE_ENTITY_REMOVED = "archetype:entity:removed",
+    DIRTY_MARK_ADDED = "dirty:mark:added",
+    DIRTY_BATCH_PROCESSED = "dirty:batch:processed",
+    ERROR_OCCURRED = "error:occurred",
+    WARNING_ISSUED = "warning:issued",
+    FRAMEWORK_INITIALIZED = "framework:initialized",
+    FRAMEWORK_SHUTDOWN = "framework:shutdown",
+    DEBUG_INFO = "debug:info",
+    DEBUG_STATS_UPDATED = "debug:stats:updated"
+}
+/**
+ * 事件优先级枚举
+ * 定义事件处理的优先级级别
+ */
+declare enum EventPriority {
+    LOWEST = 0,
+    LOW = 25,
+    NORMAL = 50,
+    HIGH = 75,
+    HIGHEST = 100,
+    CRITICAL = 200
+}
+/**
+ * 预定义的事件类型常量
+ * 提供类型安全的事件类型字符串
+ */
+declare const EVENT_TYPES: {
+    readonly ENTITY: {
+        readonly CREATED: ECSEventType.ENTITY_CREATED;
+        readonly DESTROYED: ECSEventType.ENTITY_DESTROYED;
+        readonly ENABLED: ECSEventType.ENTITY_ENABLED;
+        readonly DISABLED: ECSEventType.ENTITY_DISABLED;
+        readonly TAG_ADDED: ECSEventType.ENTITY_TAG_ADDED;
+        readonly TAG_REMOVED: ECSEventType.ENTITY_TAG_REMOVED;
+        readonly NAME_CHANGED: ECSEventType.ENTITY_NAME_CHANGED;
+    };
+    readonly COMPONENT: {
+        readonly ADDED: ECSEventType.COMPONENT_ADDED;
+        readonly REMOVED: ECSEventType.COMPONENT_REMOVED;
+        readonly MODIFIED: ECSEventType.COMPONENT_MODIFIED;
+        readonly ENABLED: ECSEventType.COMPONENT_ENABLED;
+        readonly DISABLED: ECSEventType.COMPONENT_DISABLED;
+    };
+    readonly SYSTEM: {
+        readonly ADDED: ECSEventType.SYSTEM_ADDED;
+        readonly REMOVED: ECSEventType.SYSTEM_REMOVED;
+        readonly ENABLED: ECSEventType.SYSTEM_ENABLED;
+        readonly DISABLED: ECSEventType.SYSTEM_DISABLED;
+        readonly PROCESSING_START: ECSEventType.SYSTEM_PROCESSING_START;
+        readonly PROCESSING_END: ECSEventType.SYSTEM_PROCESSING_END;
+        readonly ERROR: ECSEventType.SYSTEM_ERROR;
+    };
+    readonly PERFORMANCE: {
+        readonly WARNING: ECSEventType.PERFORMANCE_WARNING;
+        readonly CRITICAL: ECSEventType.PERFORMANCE_CRITICAL;
+        readonly MEMORY_HIGH: ECSEventType.MEMORY_USAGE_HIGH;
+        readonly FRAME_DROP: ECSEventType.FRAME_RATE_DROP;
+    };
+};
+/**
+ * 事件类型验证器
+ * 验证事件类型是否有效
+ */
+declare class EventTypeValidator {
+    private static validTypes;
+    /**
+     * 验证事件类型是否有效
+     * @param eventType 事件类型
+     * @returns 是否有效
+     */
+    static isValid(eventType: string): boolean;
+    /**
+     * 获取所有有效的事件类型
+     * @returns 事件类型数组
      */
-    protected update(currentTime?: number): void;
+    static getAllValidTypes(): string[];
+    /**
+     * 添加自定义事件类型
+     * @param eventType 事件类型
+     */
+    static addCustomType(eventType: string): void;
+    /**
+     * 移除自定义事件类型
+     * @param eventType 事件类型
+     */
+    static removeCustomType(eventType: string): void;
 }
 
 /**
@@ -5043,18 +5044,10 @@ declare class Time {
      */
     static frameCount: number;
     /**
-     * 上一帧的时间戳
-     */
-    private static _lastTime;
-    /**
-     * 是否为第一次更新
-     */
-    private static _isFirstUpdate;
-    /**
-     * 更新时间信息
-     * @param currentTime 当前时间戳（毫秒）
+     * 使用外部引擎提供的deltaTime更新时间信息
+     * @param deltaTime 外部引擎提供的帧时间间隔（秒）
      */
-    static update(currentTime?: number): void;
+    static update(deltaTime: number): void;
     /**
      * 场景改变时重置时间
      */
@@ -5068,5 +5061,5 @@ declare class Time {
     static checkEvery(interval: number, lastTime: number): boolean;
 }
 
-export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentIndexManager, ComponentPool, ComponentStorage, ComponentTypeManager, Core, CoreEvents, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, createECSAPI };
+export { ArchetypeSystem, AsyncEventHandler$1 as AsyncEventHandler, BitMaskOptimizer, BitmapComponentIndex, Bits, Component, ComponentIndexManager, ComponentPool, ComponentStorage, ComponentTypeManager, Core, DirtyFlag, DirtyTrackingSystem, ECSEventType, ECSFluentAPI, EVENT_TYPES, Emitter, Entity, EntityList, EntityManager, EntityProcessorList, EntityQueryBuilder, EntitySystem, EventBus, EventHandler$1 as EventHandler, EventPriority, EventTypeValidator, FuncPack, GlobalEventBus, GlobalManager, HashComponentIndex, IdentifierPool, IndexType, IndexUpdateBatcher, IntervalSystem, Matcher, NumberExtension, PassiveSystem, PerformanceMonitor, PerformanceWarningType, Pool, PoolManager, ProcessingSystem, QuerySystem, Scene, TieredObjectPool, Time, Timer, TimerManager, TypeSafeEventSystem, TypeUtils, createECSAPI };
 export type { Archetype, ArchetypeQueryResult, ComponentType$1 as ComponentType, DirtyData, DirtyListener, EventListenerConfig, EventStats, IComponent, IComponentEventData, IEntityEventData, IEventBus, IEventData, IEventListenerConfig, IEventStats, IPerformanceEventData, IPoolable, ISceneEventData, ISystemBase, ISystemEventData, ITimer, PerformanceData, PerformanceStats, PerformanceThresholds, PerformanceWarning, PoolStats };