Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(scene): runtime-loaded scene entities now unload with their scene

esengine03e1bea4a77e
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 2dce22756..2761e1dc8 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5243,6 +5243,7 @@ systems: { schedule: Schedule; system: SystemDef; }[] | undefined
## SceneContext — interface
```
+adopt: (entity: Entity) => void
bindPostProcess: (camera: Entity, stack: PostProcessStack) => void
despawn: (entity: Entity) => void
entities: ReadonlySet<number>
@@ -9505,7 +9506,7 @@ TrailPlugin
## transitionTo — function
```
-(app: App, targetScene: string, config: TransitionConfig): Promise<void>
+(host: App | SceneManagerState, targetScene: string, config: TransitionConfig): Promise<void>
```
## trimTextureCache — function
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 1150ddddd..1c75c2204 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5238,6 +5238,7 @@ systems: { schedule: Schedule; system: SystemDef; }[] | undefined
## SceneContext — interface
```
+adopt: (entity: Entity) => void
bindPostProcess: (camera: Entity, stack: PostProcessStack) => void
despawn: (entity: Entity) => void
entities: ReadonlySet<number>
@@ -9510,7 +9511,7 @@ TrailPlugin
## transitionTo — function
```
-(app: App, targetScene: string, config: TransitionConfig): Promise<void>
+(host: App | SceneManagerState, targetScene: string, config: TransitionConfig): Promise<void>
```
## trimTextureCache — function
diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.ts
index 4f8c4fbb2..530ac5600 100644
--- a/sdk/src/runtimeLoader.ts
+++ b/sdk/src/runtimeLoader.ts
@@ -351,8 +351,12 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
}
if (sceneName && app.hasResource(SceneManager)) {
+ // Adopt into the SceneManager's instance set so unload/switchTo actually
+ // despawns these entities — SceneOwner alone is only the persistence tag.
+ const ctx = app.getResource(SceneManager).getScene(sceneName);
for (const entity of entityMap.values()) {
- app.world.insert(entity, SceneOwner, { scene: sceneName, persistent: false });
+ if (ctx) ctx.adopt(entity);
+ else app.world.insert(entity, SceneOwner, { scene: sceneName, persistent: false });
}
}
}
diff --git a/sdk/src/sceneManager.ts b/sdk/src/sceneManager.ts
index 2141d0896..3a866242e 100644
--- a/sdk/src/sceneManager.ts
+++ b/sdk/src/sceneManager.ts
@@ -51,6 +51,8 @@ export interface SceneContext {
readonly name: string;
readonly entities: ReadonlySet<Entity>;
spawn(): Entity;
+ /** Track an externally-spawned entity as scene-owned (despawned on unload). */
+ adopt(entity: Entity): void;
despawn(entity: Entity): void;
registerDrawCallback(id: string, fn: DrawCallback): void;
bindPostProcess(camera: Entity, stack: PostProcessStack): void;
@@ -117,12 +119,16 @@ class SceneContextImpl implements SceneContext {
spawn(): Entity {
const entity = this.app_.world.spawn();
+ this.adopt(entity);
+ return entity;
+ }
+
+ adopt(entity: Entity): void {
this.instance_.entities.add(entity);
this.app_.world.insert(entity, SceneOwner, {
scene: this.instance_.config.name,
persistent: false,
});
- return entity;
}
despawn(entity: Entity): void {
diff --git a/sdk/src/sceneTransition.ts b/sdk/src/sceneTransition.ts
index 305207964..36118c935 100644
--- a/sdk/src/sceneTransition.ts
+++ b/sdk/src/sceneTransition.ts
@@ -7,7 +7,7 @@
import type { App } from './app';
import type { Color } from './types';
-import { SceneManager } from './sceneManager';
+import { SceneManager, SceneManagerState } from './sceneManager';
export interface TransitionConfig {
duration: number;
@@ -15,12 +15,16 @@ export interface TransitionConfig {
color?: Color;
}
+/**
+ * Pass the App from host code, or the `Res(SceneManager)` state from inside a
+ * system.
+ */
export async function transitionTo(
- app: App,
+ host: App | SceneManagerState,
targetScene: string,
config: TransitionConfig,
): Promise<void> {
- const manager = app.getResource(SceneManager);
+ const manager = host instanceof SceneManagerState ? host : host.getResource(SceneManager);
await manager.switchTo(targetScene, {
transition: config.type,
duration: config.duration,