@esengine/ecs-framework 2.2.19 → 2.2.21

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.19
+ * @esengine/ecs-framework v2.2.21
  * TypeScript definitions
  */
 /**
@@ -1323,6 +1323,13 @@ declare class ComponentRegistry {
     private static componentNameToId;
     private static maskCache;
     private static nextBitIndex;
+    /**
+     * 热更新模式标志，默认禁用
+     * Hot reload mode flag, disabled by default
+     * 编辑器环境应启用此选项以支持脚本热更新
+     * Editor environment should enable this to support script hot reload
+     */
+    private static hotReloadEnabled;
     /**
      * 注册组件类型并分配位掩码
      * @param componentType 组件类型
@@ -1402,6 +1409,23 @@ declare class ComponentRegistry {
      * 清除掩码缓存
      */
     static clearMaskCache(): void;
+    /**
+     * 启用热更新模式
+     * Enable hot reload mode
+     * 在编辑器环境中调用以支持脚本热更新
+     * Call in editor environment to support script hot reload
+     */
+    static enableHotReload(): void;
+    /**
+     * 禁用热更新模式
+     * Disable hot reload mode
+     */
+    static disableHotReload(): void;
+    /**
+     * 检查热更新模式是否启用
+     * Check if hot reload mode is enabled
+     */
+    static isHotReloadEnabled(): boolean;
     /**
      * 重置注册表（用于测试）
      */
@@ -4368,12 +4392,17 @@ declare class ComponentSerializer {
  */
 declare class HierarchySystem extends EntitySystem {
     private static readonly MAX_DEPTH;
+    /**
+     * 脏实体集合 - 只有这些实体需要在 process() 中更新缓存
+     * Dirty entity set - only these entities need cache update in process()
+     */
+    private dirtyEntities;
     constructor();
     /**
      * 系统优先级，确保在其他系统之前更新层级缓存
      */
     get updateOrder(): number;
-    protected process(): void;
+    protected process(_entities: readonly Entity[]): void;
     /**
      * 设置实体的父级
      *
@@ -4474,17 +4503,24 @@ declare class HierarchySystem extends EntitySystem {
         bIsExpanded: boolean;
     }>;
     /**
-     * 标记缓存为脏
+     * 标记缓存为脏，并添加到脏实体集合
+     * Mark cache as dirty and add to dirty entity set
      */
     private markCacheDirty;
     /**
      * 更新层级缓存
      */
     private updateHierarchyCache;
+    /**
+     * 当实体被添加到系统时，将其加入脏集合
+     * When entity is added to system, add it to dirty set
+     */
+    protected onAdded(entity: Entity): void;
     /**
      * 当实体被移除时清理层级关系
+     * When entity is removed, clean up hierarchy relationships
      */
-    protected onEntityRemoved(entity: Entity): void;
+    protected onRemoved(entity: Entity): void;
     dispose(): void;
 }
 
@@ -5137,6 +5173,28 @@ declare class Scene implements IScene {
      * 场景是否已开始运行
      */
     private _didSceneBegin;
+    /**
+     * 编辑器模式标志
+     *
+     * 当为 true 时，组件的生命周期回调（如 onAddedToEntity）会被延迟，
+     * 直到调用 begin() 开始运行场景时才会触发。
+     *
+     * Editor mode flag.
+     * When true, component lifecycle callbacks (like onAddedToEntity) are deferred
+     * until begin() is called to start running the scene.
+     */
+    isEditorMode: boolean;
+    /**
+     * 延迟的组件生命周期回调队列
+     *
+     * 在编辑器模式下，组件的 onAddedToEntity 回调会被加入此队列，
+     * 等到 begin() 调用时统一执行。
+     *
+     * Deferred component lifecycle callback queue.
+     * In editor mode, component's onAddedToEntity callbacks are queued here,
+     * and will be executed when begin() is called.
+     */
+    private _deferredComponentCallbacks;
     /**
      * 系统列表缓存
      */
@@ -5166,6 +5224,28 @@ declare class Scene implements IScene {
      * Counter for assigning unique add order to each system for stable sorting
      */
     private _systemAddCounter;
+    /**
+     * 组件ID到系统的索引映射
+     *
+     * 用于快速查找关心特定组件的系统，避免遍历所有系统。
+     * 使用组件ID（数字）而非ComponentType作为key，避免类引用问题。
+     *
+     * Component ID to systems index map.
+     * Used for fast lookup of systems that care about specific components.
+     * Uses component ID (number) instead of ComponentType as key to avoid class reference issues.
+     */
+    private _componentIdToSystems;
+    /**
+     * 需要接收所有组件变化通知的系统集合
+     *
+     * 包括使用 none 条件、tag/name 查询、或空匹配器的系统。
+     * 这些系统无法通过组件ID索引优化，需要在每次组件变化时都检查。
+     *
+     * Systems that need to receive all component change notifications.
+     * Includes systems using none conditions, tag/name queries, or empty matchers.
+     * These systems cannot be optimized via component ID indexing.
+     */
+    private _globalNotifySystems;
     /**
      * 获取场景中所有已注册的EntitySystem
      *
@@ -5253,10 +5333,25 @@ declare class Scene implements IScene {
      * 在场景被销毁时调用，可以在此方法中执行清理工作。
      */
     unload(): void;
+    /**
+     * 添加延迟的组件生命周期回调
+     *
+     * 在编辑器模式下，组件的 onAddedToEntity 回调会通过此方法加入队列。
+     *
+     * Queue a deferred component lifecycle callback.
+     * In editor mode, component's onAddedToEntity callbacks are queued via this method.
+     *
+     * @param callback 要延迟执行的回调 | The callback to defer
+     */
+    queueDeferredComponentCallback(callback: () => void): void;
     /**
      * 开始场景，启动实体处理器等
      *
      * 这个方法会启动场景。它将启动实体处理器等，并调用onStart方法。
+     * 在编辑器模式下，此方法还会执行所有延迟的组件生命周期回调。
+     *
+     * This method starts the scene. It will start entity processors and call onStart.
+     * In editor mode, this method also executes all deferred component lifecycle callbacks.
      */
     begin(): void;
     /**
@@ -5299,6 +5394,49 @@ declare class Scene implements IScene {
      * 当实体或组件发生变化时调用
      */
     clearSystemEntityCaches(): void;
+    /**
+     * 通知相关系统实体的组件发生了变化
+     *
+     * 这是事件驱动设计的核心：当组件被添加或移除时，立即通知相关系统检查该实体是否匹配，
+     * 并触发 onAdded/onRemoved 回调。通过组件ID索引优化，只通知关心该组件的系统。
+     *
+     * This is the core of event-driven design: when a component is added or removed,
+     * immediately notify relevant systems to check if the entity matches and trigger
+     * onAdded/onRemoved callbacks. Optimized via component ID indexing to only notify
+     * systems that care about the changed component.
+     *
+     * @param entity 组件发生变化的实体 | The entity whose components changed
+     * @param changedComponentType 变化的组件类型（可选） | The changed component type (optional)
+     */
+    notifyEntityComponentChanged(entity: Entity, changedComponentType?: ComponentType): void;
+    /**
+     * 将系统添加到组件索引
+     *
+     * 根据系统的 Matcher 条件，将系统注册到相应的组件ID索引中。
+     *
+     * Index a system by its interested component types.
+     * Registers the system to component ID indices based on its Matcher conditions.
+     *
+     * @param system 要索引的系统 | The system to index
+     */
+    private indexSystemByComponents;
+    /**
+     * 将系统添加到指定组件的索引
+     *
+     * Add system to the index for a specific component type.
+     *
+     * @param componentType 组件类型 | Component type
+     * @param system 系统 | System
+     */
+    private addSystemToComponentIndex;
+    /**
+     * 从组件索引中移除系统
+     *
+     * Remove a system from all component indices.
+     *
+     * @param system 要移除的系统 | The system to remove
+     */
+    private removeSystemFromIndex;
     /**
      * 在场景的实体列表中添加一个实体
      * @param entity 要添加的实体
@@ -5982,8 +6120,44 @@ declare abstract class EntitySystem implements ISystemBase, IService {
      * @returns 系统信息字符串
      */
     toString(): string;
+    /**
+     * 检查实体是否匹配当前系统的查询条件
+     * Check if an entity matches this system's query condition
+     *
+     * @param entity 要检查的实体 / The entity to check
+     * @returns 是否匹配 / Whether the entity matches
+     */
+    matchesEntity(entity: Entity): boolean;
+    /**
+     * 检查实体是否正在被此系统跟踪
+     * Check if an entity is being tracked by this system
+     *
+     * @param entity 要检查的实体 / The entity to check
+     * @returns 是否正在跟踪 / Whether the entity is being tracked
+     */
+    isTracking(entity: Entity): boolean;
+    /**
+     * 当实体的组件发生变化时由 Scene 调用
+     *
+     * 立即检查实体是否匹配并触发 onAdded/onRemoved 回调。
+     * 这是事件驱动设计的核心：组件变化时立即通知相关系统。
+     *
+     * Called by Scene when an entity's components change.
+     * Immediately checks if the entity matches and triggers onAdded/onRemoved callbacks.
+     * This is the core of event-driven design: notify relevant systems immediately when components change.
+     *
+     * @param entity 组件发生变化的实体 / The entity whose components changed
+     * @internal 由 Scene.notifyEntityComponentChanged 调用 / Called by Scene.notifyEntityComponentChanged
+     */
+    handleEntityComponentChanged(entity: Entity): void;
     /**
      * 更新实体跟踪，检查新增和移除的实体
+     *
+     * 由于采用了事件驱动设计，运行时的 onAdded/onRemoved 已在 handleEntityComponentChanged 中
+     * 立即触发。此方法不再触发回调，只同步跟踪状态。
+     *
+     * With event-driven design, runtime onAdded/onRemoved are triggered immediately in
+     * handleEntityComponentChanged. This method no longer triggers callbacks, only syncs tracking state.
      */
     private updateEntityTracking;
     /**
@@ -6273,6 +6447,17 @@ interface IScene {
      * 场景级别的依赖注入容器，用于管理服务的生命周期。
      */
     readonly services: ServiceContainer;
+    /**
+     * 编辑器模式标志
+     *
+     * 当为 true 时，组件的生命周期回调（如 onAddedToEntity）会被延迟，
+     * 直到调用 begin() 开始运行场景时才会触发。
+     *
+     * Editor mode flag.
+     * When true, component lifecycle callbacks (like onAddedToEntity) are deferred
+     * until begin() is called to start running the scene.
+     */
+    isEditorMode: boolean;
     /**
      * 获取系统列表
      */
@@ -6289,6 +6474,14 @@ interface IScene {
      * 场景卸载时的回调
      */
     unload(): void;
+    /**
+     * 添加延迟的组件生命周期回调
+     *
+     * Queue a deferred component lifecycle callback.
+     *
+     * @param callback 要延迟执行的回调 | The callback to defer
+     */
+    queueDeferredComponentCallback(callback: () => void): void;
     /**
      * 开始场景
      */
@@ -6307,8 +6500,24 @@ interface IScene {
     createEntity(name: string): Entity;
     /**
      * 清除所有EntitySystem的实体缓存
+     * Clear all EntitySystem entity caches
      */
     clearSystemEntityCaches(): void;
+    /**
+     * 通知相关系统实体的组件发生了变化
+     *
+     * 当组件被添加或移除时调用，立即通知相关系统检查该实体是否匹配，
+     * 并触发 onAdded/onRemoved 回调。通过组件ID索引优化，只通知关心该组件的系统。
+     *
+     * Notify relevant systems that an entity's components have changed.
+     * Called when a component is added or removed, immediately notifying
+     * relevant systems to check if the entity matches and trigger onAdded/onRemoved callbacks.
+     * Optimized via component ID indexing to only notify systems that care about the changed component.
+     *
+     * @param entity 组件发生变化的实体 | The entity whose components changed
+     * @param changedComponentType 变化的组件类型（可选） | The changed component type (optional)
+     */
+    notifyEntityComponentChanged(entity: Entity, changedComponentType?: ComponentType): void;
     /**
      * 添加实体
      */
@@ -6672,6 +6881,10 @@ declare class Entity {
     private addComponentInternal;
     /**
      * 通知Scene中的QuerySystem实体组件发生变动
+     *
+     * Notify the QuerySystem in Scene that entity components have changed
+     *
+     * @param changedComponentType 变化的组件类型（可选，用于优化通知） | Changed component type (optional, for optimized notification)
      */
     private notifyQuerySystems;
     /**
@@ -12825,6 +13038,22 @@ declare class PlatformDetector {
      * 检测是否为浏览器环境
      */
     private static isBrowser;
+    /**
+     * 检测是否在 Tauri 桌面环境中运行
+     * Check if running in Tauri desktop environment
+     *
+     * 同时支持 Tauri v1 (__TAURI__) 和 v2 (__TAURI_INTERNALS__)
+     * Supports both Tauri v1 (__TAURI__) and v2 (__TAURI_INTERNALS__)
+     */
+    static isTauriEnvironment(): boolean;
+    /**
+     * 检测是否在编辑器环境中运行
+     * Check if running in editor environment
+     *
+     * 包括 Tauri 桌面应用或带 __ESENGINE_EDITOR__ 标记的环境
+     * Includes Tauri desktop app or environments marked with __ESENGINE_EDITOR__
+     */
+    static isEditorEnvironment(): boolean;
     /**
      * 获取详细的环境信息（用于调试）
      */