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 方法
This commit is contained in:
YHH
2025-12-16 15:07:11 +08:00
committed by GitHub
parent a18eb5aa3c
commit 9e195ae3fd
4 changed files with 172 additions and 151 deletions

View File

@@ -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();
}
// 销毁待添加队列中的实体(这些实体已创建但尚未加入 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);

View File

@@ -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)
// 保存当前场景快照(以便返回)
EngineService.getInstance().saveSceneSnapshot();
// 注意:不要在这里保存快照!
// 初始快照在 Play 开始时已保存Stop 时应恢复到那个状态
// 如果在这里保存,会覆盖初始快照,导致动态创建的实体残留
//
// 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 GlobalSceneManagerKey = Symbol.for('@esengine/service:runtimeSceneManager');
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;
// 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');
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
// 重置 RuntimeSceneManager 状态(但保留实例以便下次 Play 复用)
// 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();
runtimeSceneManagerRef.current = null;
console.log('[Viewport] RuntimeSceneManager unregistered');
// 调用 reset() 而不是 dispose(),保留 sceneLoader 以便复用
// Call reset() instead of dispose(), keep sceneLoader for reuse
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

View File

@@ -2,8 +2,12 @@
* 运行时场景管理器
* Runtime Scene Manager
*
* 提供场景加载和切换 API供用户脚本使用
* Provides scene loading and transition API for user scripts
* 提供场景加载和切换 API供用户脚本使用
* 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。
* Follows IService dispose pattern for ServiceContainer compatibility.
* 生命周期方法 | Lifecycle Methods:
* - 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 接口,清理所有监听器和状态
* Implements IService interface, cleans up all listeners and state.
* 清理监听器和当前场景状态,但保留 sceneLoader 和 baseUrl
* 用于 Play/Stop 切换时调用,允许实例复用。
*
* Clears listeners and current scene state, but keeps sceneLoader and baseUrl.
* Called during Play/Stop transitions, allows instance reuse.
*/
dispose(): void {
if (this._disposed) return;
reset(): void {
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;
}
}

View File

@@ -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
* Includes IService's dispose method for ServiceContainer compatibility.
* 包含 IService 所需方法以满足 tryResolve 类型约束
* 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 中注册的键一致。
* Uses Symbol.for to match the key registered in BrowserRuntime.
* 使用 Symbol.for 确保与 BrowserRuntime/Viewport 中注册的键一致。
* 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);
}
}
/**
* 尝试从全局服务获取场景管理器
* 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
this._bindClickHandler(trigger, interactable);
}
}
/**
* 绑定点击处理器
* 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)
if (!this._sceneLoader) {
this._tryGetSceneManager();
// 每次点击时动态获取场景管理器
// Resolve scene manager dynamically on each click
const sceneManager = Core.services.tryResolve<ISceneManager>(GlobalSceneManagerKey);
if (!sceneManager?.loadScene) {
// 编辑器预览模式下可能未注册,静默处理
// May not be registered in editor preview mode, handle silently
return;
}
// 加载场景
// Load scene
if (this._sceneLoader) {
this._sceneLoader(targetScene).catch((error) => {
sceneManager.loadScene(targetScene).catch((error) => {
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;