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): retire ownership records on world despawn

yhhfa58aac02a70
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7335a8f9d..0e4c7074f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Scenes forget runtime entities when the World destroys them.** Scene ownership collections and saved render state now retire an entity on despawn, including runtime prefab copies destroyed through Commands or World. Repeated bullet spawning no longer accumulates dead scene entries for later unloads. Scene reset and plugin cleanup detach the observer, and subsequent loads restore tracking with one observer per manager.
+
- **Old audio asset leases do not release replacement clips.** Each loaded audio result releases the buffer generation and audio device it actually retained. Releasing an outgoing scene's asset after a clip update no longer unpins or evicts the current clip under the same path, including when the warm-cache budget is zero. Final release still retires the current buffer normally.
- **Audio source updates retire pending decodes.** Invalidating a clip starts a new load instead of joining its outdated request. Late results release their buffers without overwriting current audio or deleting the newer request's deduplication record. Web Audio also tracks source revisions across file reads and decode completion so old requests cannot restore stale URL-cache entries.
diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.ts
index 3ae0d3794..fca8c47fa 100644
--- a/sdk/src/scene/sceneManager.ts
+++ b/sdk/src/scene/sceneManager.ts
@@ -278,11 +278,22 @@ export class SceneManagerState {
private readonly transitionController_ = new SceneTransitionController();
private switching_ = false;
private loadPromises_ = new Map<string, Promise<SceneContext>>();
+ private stopEntityTracking_: (() => void) | null = null;
constructor(app: App) {
this.app_ = app;
}
+ private trackEntityDestruction_(): void {
+ if (this.stopEntityTracking_) return;
+ this.stopEntityTracking_ = this.app_.world.onDespawn?.(entity => {
+ for (const instance of this.scenes_.values()) {
+ instance.entities.delete(entity);
+ instance.savedEnabled.delete(entity);
+ }
+ }) ?? null;
+ }
+
/**
* Forget the scenes while the caller keeps the World.
*
@@ -291,6 +302,8 @@ export class SceneManagerState {
* keeps its receipts and systems. No caller in this repo says if that is right.
*/
reset(): void {
+ this.stopEntityTracking_?.();
+ this.stopEntityTracking_ = null;
for (const instance of this.scenes_.values()) {
for (const id of instance.drawCallbacks.keys()) {
unregisterDrawCallback(id);
@@ -478,6 +491,7 @@ export class SceneManagerState {
}
const instance = new SceneInstance(config);
+ this.trackEntityDestruction_();
this.scenes_.set(name, instance);
const ctx = new SceneContextImpl(instance, this.app_);
diff --git a/sdk/src/scene/scenePlugin.ts b/sdk/src/scene/scenePlugin.ts
index 7ee47d45f..663eb10dc 100644
--- a/sdk/src/scene/scenePlugin.ts
+++ b/sdk/src/scene/scenePlugin.ts
@@ -49,6 +49,9 @@ export const sceneStreamingSystem = defineSystem(
export const sceneManagerPlugin: Plugin = {
name: 'sceneManager',
profileDomain: 'scene',
+ cleanup(app: App): void {
+ if (app.hasResource(SceneManager)) app.getResource(SceneManager).reset();
+ },
build(app: App): void {
ensureSceneAiRegistrations();
const state = new SceneManagerState(app);
diff --git a/sdk/tests/sceneManager.test.ts b/sdk/tests/sceneManager.test.ts
index 30b0830ea..f2c5d89f3 100644
--- a/sdk/tests/sceneManager.test.ts
+++ b/sdk/tests/sceneManager.test.ts
@@ -85,6 +85,7 @@ import { Material } from '../src/render/material';
function createMockApp() {
const entities = new Map<number, Map<symbol, any>>();
+ const despawnListeners = new Set<(entity: number) => void>();
let nextEntity = 1;
const resources = new Map<any, any>();
// PostProcess is now a per-App resource; register the mock so sceneManager's
@@ -97,7 +98,14 @@ function createMockApp() {
entities.set(e, new Map());
return e;
}),
- despawn: vi.fn((e: number) => entities.delete(e)),
+ despawn: vi.fn((e: number) => {
+ for (const listener of [...despawnListeners]) listener(e);
+ return entities.delete(e);
+ }),
+ onDespawn: vi.fn((listener: (entity: number) => void) => {
+ despawnListeners.add(listener);
+ return () => { despawnListeners.delete(listener); };
+ }),
valid: vi.fn((e: number) => entities.has(e)),
has: vi.fn((e: number, comp: symbol) => entities.get(e)?.has(comp) ?? false),
get: vi.fn((e: number, comp: symbol) => entities.get(e)?.get(comp)),
@@ -122,6 +130,7 @@ function createMockApp() {
addSystemToSchedule: vi.fn(),
_entities: entities,
_resources: resources,
+ _despawnListeners: despawnListeners,
};
}
@@ -143,6 +152,23 @@ describe('SceneManager', () => {
manager = new SceneManagerState(app as any);
});
+ it('forgets entities destroyed through the World and reattaches tracking after reset', async () => {
+ for (let round = 0; round < 2; round++) {
+ manager.register({ name: 'tracked' });
+ const context = await manager.load('tracked');
+ for (let i = 0; i < 100; i++) {
+ const entity = context.spawn();
+ context.adopt(entity);
+ app.world.despawn(entity);
+ expect(context.entities.size).toBe(0);
+ }
+ expect(app._despawnListeners.size).toBe(1);
+ await manager.unload('tracked');
+ manager.reset();
+ expect(app._despawnListeners.size).toBe(0);
+ }
+ });
+
// =========================================================================
// Registration & initial scene
// =========================================================================
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 8c2a0d07b..84751dca9 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(scene): retire ownership records on world despawn':
+ { note: 'Scenes forget runtime entities when the World destroys them.' },
'fix(audio): bind asset releases to retained buffer generations':
{ note: 'Old audio asset leases do not release replacement clips.' },
'fix(audio): retire pending loads when clip sources change':