fix(editor): 修复 Play/Stop 循环中的场景管理器和动态实体问题 (#307)

问题修复：
1. RuntimeSceneManager 在 Stop 后失效
   - 根因：SceneLoadTriggerSystem 闭包缓存了 sceneManager 引用
   - 修复：每次点击时动态从 Core.services 获取服务

2. Play 期间创建的动态实体（如 ClickFx 粒子）Stop 后残留
   - 根因：EntityList.removeAllEntities() 只清空 _entitiesToAdd 队列但没有销毁实体
   - 修复：先销毁待添加队列中的实体再清空

3. 场景切换后动态实体残留
   - 根因：editorSceneLoader 中 saveSceneSnapshot() 覆盖了初始快照
   - 修复：移除该调用，保持 Play 开始时的快照不被覆盖

架构改进：
- RuntimeSceneManager 新增 reset() 方法，区分会话重置和完全销毁
- Viewport 复用 RuntimeSceneManager 实例而非每次创建
- IRuntimeSceneManager 接口补充 setSceneLoader/setBaseUrl 方法

packages/core/src/ECS/Utils/EntityList.ts

@@ -80,17 +80,30 @@ export class EntityList {
 
     /**
      * 移除所有实体
+     * Remove all entities
+     *
+     * 包括 buffer 中的实体和待添加队列中的实体。
+     * Includes entities in buffer and entities in pending add queue.
      */
     public removeAllEntities(): void {
-        // 收集所有实体ID用于回收
         const idsToRecycle: number[] = [];
 
+        // 销毁 buffer 中的实体
+        // Destroy entities in buffer
         for (let i = this.buffer.length - 1; i >= 0; i--) {
             idsToRecycle.push(this.buffer[i]!.id);
             this.buffer[i]!.destroy();
         }
 
-        // 批量回收ID
+        // 销毁待添加队列中的实体（这些实体已创建但尚未加入 buffer）
+        // Destroy entities in pending add queue (created but not yet in buffer)
+        for (const entity of this._entitiesToAdd) {
+            idsToRecycle.push(entity.id);
+            entity.destroy();
+        }
+
+        // 批量回收 ID
+        // Recycle IDs in batch
         if (this._scene && this._scene.identifierPool) {
             for (const id of idsToRecycle) {
                 this._scene.identifierPool.checkIn(id);

packages/editor-app/src/components/Viewport.tsx

@@ -841,54 +841,51 @@ export function Viewport({ locale = 'en', messageHub, commandManager }: Viewport
             // Switch to player camera
             syncPlayerCamera();
 
-            // Register RuntimeSceneManager for scene switching in play mode
+            // 设置 RuntimeSceneManager 用于 Play 模式场景切换
-            // 注册 RuntimeSceneManager 以支持 Play 模式下的场景切换
+            // Setup RuntimeSceneManager for scene switching in play mode
+            //
+            // 生命周期设计：
+            // - 首次 Play：创建新实例
+            // - 后续 Play：复用实例，只更新 sceneLoader
+            // - Stop：调用 reset() 清理会话状态，保留实例
+            //
+            // Lifecycle design:
+            // - First Play: Create new instance
+            // - Subsequent Plays: Reuse instance, only update sceneLoader
+            // - Stop: Call reset() to clear session state, keep instance
             const projectService = Core.services.tryResolve(ProjectService);
             const projectPath = projectService?.getCurrentProject()?.path;
             if (projectPath) {
-                // Create scene loader function that reads scene files using Tauri API
+                // 创建场景加载函数
-                // 创建使用 Tauri API 读取场景文件的场景加载器函数
+                // Create scene loader function
                 const editorSceneLoader = async (scenePath: string): Promise<void> => {
                     try {
-                        // Normalize path: handle both relative and absolute paths
-                        // 标准化路径：处理相对路径和绝对路径
                         let fullPath = scenePath;
                         if (!scenePath.includes(':') && !scenePath.startsWith('/')) {
-                            // Relative path - construct full path
-                            // 相对路径 - 构建完整路径
                             const normalizedPath = scenePath.replace(/^\.\//, '').replace(/\//g, '\\');
                             fullPath = `${projectPath}\\${normalizedPath}`;
                         } else {
-                            // Absolute path - normalize separators for Windows
-                            // 绝对路径 - 为 Windows 规范化分隔符
                             fullPath = scenePath.replace(/\//g, '\\');
                         }
 
-                        // Read scene file content
-                        // 读取场景文件内容
                         const sceneJson = await TauriAPI.readFileContent(fullPath);
-
-                        // Validate scene data
-                        // 验证场景数据
                         const validation = SceneSerializer.validate(sceneJson);
                         if (!validation.valid) {
                             throw new Error(`Invalid scene: ${validation.errors?.join(', ')}`);
                         }
 
-                        // Save current scene snapshot (so we can go back)
+                        // 注意：不要在这里保存快照！
-                        // 保存当前场景快照（以便返回）
+                        // 初始快照在 Play 开始时已保存，Stop 时应恢复到那个状态
-                        EngineService.getInstance().saveSceneSnapshot();
+                        // 如果在这里保存，会覆盖初始快照，导致动态创建的实体残留
+                        //
+                        // Note: Don't save snapshot here!
+                        // Initial snapshot was saved at Play start, Stop should restore to that state
+                        // Saving here would overwrite initial snapshot, causing dynamically created entities to remain
 
-                        // Load new scene by deserializing into current scene
-                        // 通过反序列化加载新场景到当前场景
                         const scene = Core.scene;
                         if (scene) {
                             scene.deserialize(sceneJson, { strategy: 'replace' });
 
-                            // Reset particle component textureIds after scene switch
-                            // 场景切换后重置粒子组件的 textureId
-                            // This ensures ParticleUpdateSystem will reload textures
-                            // 这确保 ParticleUpdateSystem 会重新加载纹理
                             for (const entity of scene.entities.buffer) {
                                 const particleComponent = entity.getComponent(ParticleSystemComponent);
                                 if (particleComponent) {
@@ -896,28 +893,17 @@ export function Viewport({ locale = 'en', messageHub, commandManager }: Viewport
                                 }
                             }
 
-                            // Re-register user code components and systems after scene switch
-                            // 场景切换后重新注册用户代码组件和系统
                             const userCodeService = Core.services.tryResolve(UserCodeService);
                             if (userCodeService) {
                                 const runtimeModule = userCodeService.getModule(UserCodeTarget.Runtime);
                                 if (runtimeModule) {
-                                    // Re-register components (ensures GlobalComponentRegistry has correct references)
-                                    // 重新注册组件（确保 GlobalComponentRegistry 有正确的引用）
                                     userCodeService.registerComponents(runtimeModule, GlobalComponentRegistry);
-
-                                    // Re-register systems (recreates systems with correct component references)
-                                    // 重新注册系统（使用正确的组件引用重建系统）
                                     userCodeService.registerSystems(runtimeModule, scene);
                                 }
                             }
 
-                            // Load scene resources (textures, etc.)
-                            // 加载场景资源（纹理等）
                             await EngineService.getInstance().loadSceneResources();
 
-                            // Sync entity store
-                            // 同步实体存储
                             const entityStore = Core.services.tryResolve(EntityStoreService);
                             entityStore?.syncFromScene();
                         }
@@ -929,22 +915,35 @@ export function Viewport({ locale = 'en', messageHub, commandManager }: Viewport
                     }
                 };
 
-                // Create and register RuntimeSceneManager
-                // 创建并注册 RuntimeSceneManager
-                const sceneManager = new RuntimeSceneManager(
-                    editorSceneLoader,
-                    `${projectPath}\\scenes`
-                );
-                runtimeSceneManagerRef.current = sceneManager;
-
-                // Register to Core.services with the global key
-                // 使用全局 key 注册到 Core.services
                 const GlobalSceneManagerKey = Symbol.for('@esengine/service:runtimeSceneManager');
-                if (!Core.services.isRegistered(GlobalSceneManagerKey)) {
-                    Core.services.registerInstance(GlobalSceneManagerKey, sceneManager);
-                }
 
-                console.log('[Viewport] RuntimeSceneManager registered for play mode');
+                if (runtimeSceneManagerRef.current) {
+                    // 复用已有实例：重置状态并更新 sceneLoader
+                    // Reuse existing instance: reset state and update sceneLoader
+                    runtimeSceneManagerRef.current.reset();
+                    runtimeSceneManagerRef.current.setSceneLoader(editorSceneLoader);
+                    runtimeSceneManagerRef.current.setBaseUrl(`${projectPath}\\scenes`);
+
+                    // 确保已注册到服务容器
+                    // Ensure registered to service container
+                    if (!Core.services.isRegistered(GlobalSceneManagerKey)) {
+                        Core.services.registerInstance(GlobalSceneManagerKey, runtimeSceneManagerRef.current);
+                    }
+                    console.log('[Viewport] RuntimeSceneManager reused for play mode');
+                } else {
+                    // 首次创建实例
+                    // First time: create new instance
+                    const sceneManager = new RuntimeSceneManager(
+                        editorSceneLoader,
+                        `${projectPath}\\scenes`
+                    );
+                    runtimeSceneManagerRef.current = sceneManager;
+
+                    if (!Core.services.isRegistered(GlobalSceneManagerKey)) {
+                        Core.services.registerInstance(GlobalSceneManagerKey, sceneManager);
+                    }
+                    console.log('[Viewport] RuntimeSceneManager created for play mode');
+                }
             }
 
             // Register user code components and systems before starting engine
@@ -984,16 +983,19 @@ export function Viewport({ locale = 'en', messageHub, commandManager }: Viewport
         setPlayState('stopped');
         engine.stop();
 
-        // Unregister RuntimeSceneManager
+        // 重置 RuntimeSceneManager 状态（但保留实例以便下次 Play 复用）
-        // 注销 RuntimeSceneManager
+        // Reset RuntimeSceneManager state (but keep instance for next Play reuse)
         if (runtimeSceneManagerRef.current) {
             const GlobalSceneManagerKey = Symbol.for('@esengine/service:runtimeSceneManager');
             if (Core.services.isRegistered(GlobalSceneManagerKey)) {
                 Core.services.unregister(GlobalSceneManagerKey);
             }
-            runtimeSceneManagerRef.current.dispose();
+            // 调用 reset() 而不是 dispose()，保留 sceneLoader 以便复用
-            runtimeSceneManagerRef.current = null;
+            // Call reset() instead of dispose(), keep sceneLoader for reuse
-            console.log('[Viewport] RuntimeSceneManager unregistered');
+            runtimeSceneManagerRef.current.reset();
+            // 注意：不设置 ref 为 null，保留实例
+            // Note: Don't set ref to null, keep the instance
+            console.log('[Viewport] RuntimeSceneManager reset (instance kept for reuse)');
         }
 
         // Restore scene snapshot

packages/runtime-core/src/services/RuntimeSceneManager.ts

@@ -2,8 +2,12 @@
  * 运行时场景管理器
  * Runtime Scene Manager
  *
- * 提供场景加载和切换 API，供用户脚本使用
+ * 提供场景加载和切换 API，供用户脚本使用。
- * Provides scene loading and transition API for user scripts
+ * Provides scene loading and transition API for user scripts.
+ *
+ * 生命周期设计 | Lifecycle Design:
+ * - reset(): 清理会话状态，保留核心功能（用于 Play/Stop 切换）
+ * - dispose(): 完全销毁，释放所有资源（用于编辑器关闭）
  *
  * @example
  * ```typescript
@@ -68,8 +72,9 @@ export type SceneLoader = (url: string) => Promise<void>;
  * 运行时场景管理器接口
  * Runtime Scene Manager Interface
  *
- * 继承 IService 的 dispose 模式以兼容 ServiceContainer。
+ * 生命周期方法 | Lifecycle Methods:
- * Follows IService dispose pattern for ServiceContainer compatibility.
+ * - reset(): 重置会话状态（Play/Stop 切换时调用）
+ * - dispose(): 完全销毁（编辑器关闭时调用）
  */
 export interface IRuntimeSceneManager {
     /**
@@ -133,8 +138,41 @@ export interface IRuntimeSceneManager {
     onLoadError(callback: (error: Error, sceneName: string) => void): () => void;
 
     /**
-     * 释放资源（IService 兼容）
+     * 设置场景加载器
-     * Dispose resources (IService compatible)
+     * Set scene loader
+     *
+     * 用于更新场景加载函数（如 Play 模式切换时）。
+     * Used to update scene loader function (e.g., during Play mode transitions).
+     */
+    setSceneLoader(loader: SceneLoader): void;
+
+    /**
+     * 设置基础 URL
+     * Set base URL
+     */
+    setBaseUrl(baseUrl: string): void;
+
+    /**
+     * 重置会话状态
+     * Reset session state
+     *
+     * 清理监听器和当前场景状态，但保留 sceneLoader。
+     * 用于 Play/Stop 切换时调用。
+     *
+     * Clears listeners and current scene state, but keeps sceneLoader.
+     * Called during Play/Stop transitions.
+     */
+    reset(): void;
+
+    /**
+     * 完全释放资源
+     * Dispose all resources
+     *
+     * 销毁实例，清理所有资源。
+     * 仅在编辑器关闭时调用。
+     *
+     * Destroys the instance, cleans up all resources.
+     * Only called when editor closes.
      */
     dispose(): void;
 }
@@ -367,25 +405,45 @@ export class RuntimeSceneManager implements IRuntimeSceneManager {
         }
     }
 
-    // ==================== IService 实现 | IService Implementation ====================
+    // ==================== 生命周期方法 | Lifecycle Methods ====================
 
     /**
-     * 释放资源
+     * 重置会话状态
-     * Dispose resources
+     * Reset session state
      *
-     * 实现 IService 接口，清理所有监听器和状态。
+     * 清理监听器和当前场景状态，但保留 sceneLoader 和 baseUrl。
-     * Implements IService interface, cleans up all listeners and state.
+     * 用于 Play/Stop 切换时调用，允许实例复用。
+     *
+     * Clears listeners and current scene state, but keeps sceneLoader and baseUrl.
+     * Called during Play/Stop transitions, allows instance reuse.
      */
-    dispose(): void {
+    reset(): void {
-        if (this._disposed) return;
-
         this._loadStartListeners.clear();
         this._loadCompleteListeners.clear();
         this._loadErrorListeners.clear();
         this._scenes.clear();
-        this._sceneLoader = null;
         this._currentSceneName = null;
         this._currentScenePath = null;
+        this._isLoading = false;
+        // 注意：保留 _sceneLoader 和 _baseUrl
+        // Note: Keep _sceneLoader and _baseUrl
+    }
+
+    /**
+     * 完全释放资源
+     * Dispose all resources
+     *
+     * 销毁实例，清理所有资源包括 sceneLoader。
+     * 仅在编辑器完全关闭时调用。
+     *
+     * Destroys the instance, cleans up all resources including sceneLoader.
+     * Only called when editor completely closes.
+     */
+    dispose(): void {
+        if (this._disposed) return;
+
+        this.reset();
+        this._sceneLoader = null;
         this._disposed = true;
     }
 }

packages/ui/src/systems/SceneLoadTriggerSystem.ts

@@ -4,24 +4,24 @@
  *
  * 处理 SceneLoadTriggerComponent，绑定 UIInteractable 点击事件到场景加载。
  * Processes SceneLoadTriggerComponent, binds UIInteractable click to scene loading.
+ *
+ * 设计说明 | Design Notes:
+ * - 每次点击时动态从服务容器获取 RuntimeSceneManager
+ * - 不缓存服务引用，避免 Play/Stop 切换时引用失效
+ * - Dynamically resolves RuntimeSceneManager from service container on each click
+ * - Avoids caching service references to handle Play/Stop lifecycle correctly
  */
 
 import { Entity, EntitySystem, Matcher, ECSSystem, Core } from '@esengine/ecs-framework';
 import { SceneLoadTriggerComponent } from '../components/SceneLoadTriggerComponent';
 import { UIInteractableComponent } from '../components/UIInteractableComponent';
 
-/**
- * 场景加载函数类型（与 RuntimeSceneManager.loadScene 兼容）
- * Scene load function type (compatible with RuntimeSceneManager.loadScene)
- */
-type SceneLoadFunction = (sceneName: string) => Promise<void>;
-
 /**
  * 场景管理器接口（最小化，避免循环依赖）
  * Scene manager interface (minimal, avoids circular dependency)
  *
- * 包含 IService 的 dispose 方法以兼容 ServiceContainer。
+ * 包含 IService 所需方法以满足 tryResolve 类型约束。
- * Includes IService's dispose method for ServiceContainer compatibility.
+ * Includes IService required methods to satisfy tryResolve type constraint.
  */
 interface ISceneManager {
     loadScene(sceneName: string): Promise<void>;
@@ -32,8 +32,8 @@ interface ISceneManager {
  * 全局场景管理器服务键
  * Global scene manager service key
  *
- * 使用 Symbol.for 确保与 BrowserRuntime 中注册的键一致。
+ * 使用 Symbol.for 确保与 BrowserRuntime/Viewport 中注册的键一致。
- * Uses Symbol.for to match the key registered in BrowserRuntime.
+ * Uses Symbol.for to match the key registered in BrowserRuntime/Viewport.
  */
 const GlobalSceneManagerKey = Symbol.for('@esengine/service:runtimeSceneManager');
 
@@ -46,30 +46,11 @@ const GlobalSceneManagerKey = Symbol.for('@esengine/service:runtimeSceneManager'
  */
 @ECSSystem('SceneLoadTrigger')
 export class SceneLoadTriggerSystem extends EntitySystem {
-    private _sceneLoader: SceneLoadFunction | null = null;
-
     constructor() {
         super(Matcher.empty().all(SceneLoadTriggerComponent, UIInteractableComponent));
     }
 
-    /**
-     * 设置场景加载函数
-     * Set scene load function
-     *
-     * 可以直接设置函数，或者系统会尝试从服务注册表获取 RuntimeSceneManager。
-     * Can set function directly, or system will try to get RuntimeSceneManager from service registry.
-     */
-    public setSceneLoader(loader: SceneLoadFunction): void {
-        this._sceneLoader = loader;
-    }
-
     protected override process(entities: readonly Entity[]): void {
-        // 如果没有设置场景加载器，尝试从服务注册表获取
-        // If no scene loader set, try to get from service registry
-        if (!this._sceneLoader) {
-            this._tryGetSceneManager();
-        }
-
         for (const entity of entities) {
             const trigger = entity.getComponent(SceneLoadTriggerComponent);
             const interactable = entity.getComponent(UIInteractableComponent);
@@ -77,84 +58,51 @@ export class SceneLoadTriggerSystem extends EntitySystem {
             if (!trigger || !interactable) continue;
             if (!trigger.enabled || !trigger.targetScene) continue;
 
-            // 只绑定一次回调
+            // 只绑定一次回调 | Only bind callback once
-            // Only bind callback once
             if (trigger._callbackBound) continue;
 
-            this._bindClickHandler(entity, trigger, interactable);
+            this._bindClickHandler(trigger, interactable);
-        }
-    }
-
-    /**
-     * 尝试从全局服务获取场景管理器
-     * Try to get scene manager from global services
-     */
-    private _tryGetSceneManager(): void {
-        try {
-            // 从 Core.services 获取场景管理器
-            // Get scene manager from Core.services
-            // RuntimeSceneManager 实现了 IService 接口
-            // RuntimeSceneManager implements IService interface
-            const sceneManager = Core.services.tryResolve<ISceneManager>(GlobalSceneManagerKey);
-            if (sceneManager?.loadScene) {
-                this._sceneLoader = (sceneName: string) => sceneManager.loadScene(sceneName);
-            }
-        } catch (e) {
-            // 忽略错误，保持 _sceneLoader 为 null
-            // Ignore error, keep _sceneLoader as null
         }
     }
 
     /**
      * 绑定点击处理器
      * Bind click handler
+     *
+     * 关键设计：不缓存 sceneManager 引用，每次点击时动态获取。
+     * Key design: Don't cache sceneManager reference, resolve dynamically on each click.
      */
     private _bindClickHandler(
-        entity: Entity,
         trigger: SceneLoadTriggerComponent,
         interactable: UIInteractableComponent
     ): void {
         const targetScene = trigger.targetScene;
-
-        // 保存原有的 onClick（如果有）
-        // Save original onClick (if any)
         const originalOnClick = interactable.onClick;
 
         interactable.onClick = () => {
-            // 调用原有回调
-            // Call original callback
             originalOnClick?.();
 
-            // 检查是否启用
-            // Check if enabled
             if (!trigger.enabled) return;
 
-            // 禁用（防止重复点击）
-            // Disable (prevent double clicks)
             if (trigger.disableOnClick) {
                 trigger.enabled = false;
             }
 
-            // 尝试获取场景加载器（可能在回调绑定后才注册）
+            // 每次点击时动态获取场景管理器
-            // Try to get scene loader (may be registered after callback binding)
+            // Resolve scene manager dynamically on each click
-            if (!this._sceneLoader) {
+            const sceneManager = Core.services.tryResolve<ISceneManager>(GlobalSceneManagerKey);
-                this._tryGetSceneManager();
+            if (!sceneManager?.loadScene) {
+                // 编辑器预览模式下可能未注册，静默处理
+                // May not be registered in editor preview mode, handle silently
+                return;
             }
 
-            // 加载场景
+            sceneManager.loadScene(targetScene).catch((error) => {
-            // Load scene
+                console.error(`[SceneLoadTriggerSystem] Failed to load scene "${targetScene}":`, error);
-            if (this._sceneLoader) {
+                if (trigger.disableOnClick) {
-                this._sceneLoader(targetScene).catch((error) => {
+                    trigger.enabled = true;
-                    console.error(`[SceneLoadTriggerSystem] Failed to load scene "${targetScene}":`, error);
+                }
-                    // 恢复启用状态
+            });
-                    // Restore enabled state
-                    if (trigger.disableOnClick) {
-                        trigger.enabled = true;
-                    }
-                });
-            }
-            // 静默处理：编辑器预览模式下场景切换不可用
-            // Silent handling: scene switching not available in editor preview mode
         };
 
         trigger._callbackBound = true;