From 64ea53eba1dcd0fcb80f87ea3fd294d51ed40bc5 Mon Sep 17 00:00:00 2001
From: YHH <359807859@qq.com>
Date: Fri, 26 Sep 2025 10:50:31 +0800
Subject: [PATCH] =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E6=B7=BB=E5=8A=A0=E7=BC=93?=
 =?UTF-8?q?=E5=AD=98=E5=AE=9E=E4=BD=93=E6=9C=BA=E5=88=B6=E9=81=BF=E5=85=8D?=
 =?UTF-8?q?=E9=A2=91=E7=B9=81=E5=BC=80=E9=94=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/core/src/ECS/Entity.ts               |  2 ++
 packages/core/src/ECS/IScene.ts               |  5 +++
 packages/core/src/ECS/Scene.ts                | 21 +++++++++--
 packages/core/src/ECS/Systems/EntitySystem.ts | 35 +++++++++++++++++--
 4 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/ECS/Entity.ts b/packages/core/src/ECS/Entity.ts
index a4cbc927..9dcfbbe0 100644
--- a/packages/core/src/ECS/Entity.ts
+++ b/packages/core/src/ECS/Entity.ts
@@ -373,6 +373,7 @@ export class Entity {
         if (this.scene && this.scene.querySystem) {
             this.scene.querySystem.removeEntity(this);
             this.scene.querySystem.addEntity(this);
+            this.scene.clearSystemEntityCaches();
         }
 
         return component;
@@ -523,6 +524,7 @@ export class Entity {
         if (this.scene && this.scene.querySystem) {
             this.scene.querySystem.removeEntity(this);
             this.scene.querySystem.addEntity(this);
+            this.scene.clearSystemEntityCaches();
         }
     }
 
diff --git a/packages/core/src/ECS/IScene.ts b/packages/core/src/ECS/IScene.ts
index 19a68e3c..8ea21b28 100644
--- a/packages/core/src/ECS/IScene.ts
+++ b/packages/core/src/ECS/IScene.ts
@@ -88,6 +88,11 @@ export interface IScene {
      */
     createEntity(name: string): Entity;
 
+    /**
+     * 清除所有EntitySystem的实体缓存
+     */
+    clearSystemEntityCaches(): void;
+
     /**
      * 添加实体
      */
diff --git a/packages/core/src/ECS/Scene.ts b/packages/core/src/ECS/Scene.ts
index d7ad85fe..55ad6efc 100644
--- a/packages/core/src/ECS/Scene.ts
+++ b/packages/core/src/ECS/Scene.ts
@@ -207,6 +207,16 @@ export class Scene implements IScene {
         return this.addEntity(entity);
     }
 
+    /**
+     * 清除所有EntitySystem的实体缓存
+     * 当实体或组件发生变化时调用
+     */
+    public clearSystemEntityCaches(): void {
+        for (const system of this.entityProcessors.processors) {
+            system.clearEntityCache();
+        }
+    }
+
     /**
      * 在场景的实体列表中添加一个实体
      * @param entity 要添加的实体
@@ -215,13 +225,18 @@ export class Scene implements IScene {
     public addEntity(entity: Entity, deferCacheClear: boolean = false) {
         this.entities.add(entity);
         entity.scene = this;
-        
+
         // 将实体添加到查询系统（可延迟缓存清理）
         this.querySystem.addEntity(entity, deferCacheClear);
-        
+
+        // 清除系统缓存以确保系统能及时发现新实体
+        if (!deferCacheClear) {
+            this.clearSystemEntityCaches();
+        }
+
         // 触发实体添加事件
         this.eventSystem.emitSync('entity:added', { entity, scene: this });
-        
+
         return entity;
     }
 
diff --git a/packages/core/src/ECS/Systems/EntitySystem.ts b/packages/core/src/ECS/Systems/EntitySystem.ts
index 3aacae2e..cc79936a 100644
--- a/packages/core/src/ECS/Systems/EntitySystem.ts
+++ b/packages/core/src/ECS/Systems/EntitySystem.ts
@@ -50,12 +50,23 @@ export abstract class EntitySystem implements ISystemBase {
     private _trackedEntities: Set<Entity> = new Set();
     private _eventListeners: EventListenerRecord[] = [];
     private _frameEntities: Entity[] | null = null;
+    private _cachedEntities: Entity[] | null = null;
 
     /**
      * 获取系统处理的实体列表
      */
     public get entities(): readonly Entity[] {
-        return this._frameEntities || [];
+        // 如果在update周期内，优先使用_frameEntities
+        if (this._frameEntities !== null) {
+            return this._frameEntities;
+        }
+
+        // 否则使用持久缓存
+        if (this._cachedEntities === null) {
+            this._cachedEntities = this.queryEntities();
+        }
+
+        return this._cachedEntities;
     }
 
     /**
@@ -128,7 +139,7 @@ export abstract class EntitySystem implements ISystemBase {
 
     /**
      * 系统初始化（框架调用）
-     * 
+     *
      * 在系统创建时调用。框架内部使用，用户不应直接调用。
      */
     public initialize(): void {
@@ -141,6 +152,8 @@ export abstract class EntitySystem implements ISystemBase {
 
         // 框架内部初始化：触发一次实体查询，以便正确跟踪现有实体
         if (this.scene) {
+            // 清理缓存确保初始化时重新查询
+            this._cachedEntities = null;
             this.queryEntities();
         }
 
@@ -157,6 +170,14 @@ export abstract class EntitySystem implements ISystemBase {
         // 子类可以重写此方法进行初始化
     }
 
+    /**
+     * 清除实体缓存（内部使用）
+     * 当Scene中的实体发生变化时调用
+     */
+    public clearEntityCache(): void {
+        this._cachedEntities = null;
+    }
+
     /**
      * 重置系统状态
      *
@@ -166,6 +187,8 @@ export abstract class EntitySystem implements ISystemBase {
         this.scene = null;
         this._initialized = false;
         this._trackedEntities.clear();
+        this._cachedEntities = null;
+        this._frameEntities = null;
 
         // 清理所有事件监听器
         this.cleanupEventListeners();
@@ -522,12 +545,14 @@ export abstract class EntitySystem implements ISystemBase {
      */
     private updateEntityTracking(currentEntities: Entity[]): void {
         const currentSet = new Set(currentEntities);
+        let hasChanged = false;
 
         // 检查新增的实体
         for (const entity of currentEntities) {
             if (!this._trackedEntities.has(entity)) {
                 this._trackedEntities.add(entity);
                 this.onAdded(entity);
+                hasChanged = true;
             }
         }
 
@@ -536,8 +561,14 @@ export abstract class EntitySystem implements ISystemBase {
             if (!currentSet.has(entity)) {
                 this._trackedEntities.delete(entity);
                 this.onRemoved(entity);
+                hasChanged = true;
             }
         }
+
+        // 如果实体发生了变化，使缓存失效
+        if (hasChanged) {
+            this._cachedEntities = null;
+        }
     }
 
     /**