@esengine/ecs-framework 2.2.18 → 2.2.20

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.2.18
+ * @esengine/ecs-framework v2.2.20
  * TypeScript definitions
  */
 /**
@@ -5159,6 +5159,35 @@ declare class Scene implements IScene {
      * 系统错误次数超过此阈值后将被自动禁用
      */
     private _maxErrorCount;
+    /**
+     * 系统添加计数器
+     *
+     * 用于为每个添加的系统分配唯一的添加顺序，保证排序稳定性
+     * 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
      *
@@ -5178,7 +5207,8 @@ declare class Scene implements IScene {
      */
     private _filterEntitySystems;
     /**
-     * 按updateOrder排序系统
+     * 按 updateOrder 排序系统，相同时按 addOrder 保证稳定性
+     * Sort systems by updateOrder, use addOrder as secondary key for stability
      */
     private _sortSystemsByUpdateOrder;
     /**
@@ -5291,6 +5321,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 要添加的实体
@@ -5740,6 +5813,12 @@ declare class Scene implements IScene {
  */
 declare abstract class EntitySystem implements ISystemBase, IService {
     private _updateOrder;
+    /**
+     * 添加顺序，用于 updateOrder 相同时的稳定排序
+     * Add order for stable sorting when updateOrder is the same
+     * @internal
+     */
+    private _addOrder;
     private _enabled;
     private _performanceMonitor;
     private _systemName;
@@ -5767,6 +5846,18 @@ declare abstract class EntitySystem implements ISystemBase, IService {
      */
     get updateOrder(): number;
     set updateOrder(value: number);
+    /**
+     * 获取系统的添加顺序
+     * Get the add order of the system
+     * @internal
+     */
+    get addOrder(): number;
+    /**
+     * 设置系统的添加顺序（由 Scene 在添加时设置）
+     * Set the add order of the system (set by Scene when adding)
+     * @internal
+     */
+    set addOrder(value: number);
     /**
      * 获取系统的启用状态
      */
@@ -5956,8 +6047,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;
     /**
@@ -6281,8 +6408,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;
     /**
      * 添加实体
      */
@@ -6646,6 +6789,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;
     /**