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(animation): isolate despawn subscriptions by app

yhha12af71c3069
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 826fd09fe..09a8143f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Animation despawn subscriptions belong to their App.** Shared animation plugins withdraw the quitting App's listener while preserving other Apps' tween cancellation, sprite-event cleanup, and animator removal callbacks. Repeated preview shutdowns no longer leave stale subscriptions on older worlds.
+
- **Sprite animation applies frames through direct component accessors.** Running animation resolves the sprite read/write path once per update, avoiding per-frame embind snapshots and full component marshalling for every animated entity. Component write journals still observe frame changes, while editor observers, speculative updates, and rebound worlds retain the full mutation path.
- **Native audio completion subscriptions are independent.** Multiple backends sharing one host bridge receive their own voice-end notifications, and preview shutdowns withdraw only their subscription. Dispatch skips listeners withdrawn during the event, defers new listeners to the next event, and notifies remaining listeners before propagating the first callback error.
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 8c2add121..a17ffb68a 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -415,7 +415,7 @@ type: "animFrames"
## AnimationPlugin — class @experimental
```
build: (app: App) => void
-cleanup: () => void
+cleanup: (app?: App) => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 940e767fc..bbeed92aa 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -415,7 +415,7 @@ type: "animFrames"
## AnimationPlugin — class @experimental
```
build: (app: App) => void
-cleanup: () => void
+cleanup: (app?: App) => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 284bddc22..1972c35e5 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -410,7 +410,7 @@ type: "animFrames"
## AnimationPlugin — class @experimental
```
build: (app: App) => void
-cleanup: () => void
+cleanup: (app?: App) => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 06acdfe1f..e13cf49db 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -410,7 +410,7 @@ type: "animFrames"
## AnimationPlugin — class @experimental
```
build: (app: App) => void
-cleanup: () => void
+cleanup: (app?: App) => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index c14b696ed..00fe42c3b 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -410,7 +410,7 @@ type: "animFrames"
## AnimationPlugin — class @experimental
```
build: (app: App) => void
-cleanup: () => void
+cleanup: (app?: App) => void
name: string
static new (): AnimationPlugin
static prototype: AnimationPlugin
diff --git a/sdk/src/animation/AnimationPlugin.ts b/sdk/src/animation/AnimationPlugin.ts
index 5381c89ea..cf5145283 100644
--- a/sdk/src/animation/AnimationPlugin.ts
+++ b/sdk/src/animation/AnimationPlugin.ts
@@ -26,9 +26,11 @@ import { SystemLabel } from '../ecs/systemLabels';
export class AnimationPlugin implements Plugin {
name = 'animation';
- private offDespawn_: (() => void) | null = null;
+ private readonly despawnCleanups_ = new WeakMap<App, () => void>();
+ private latestDespawnCleanup_: (() => void) | null = null;
build(app: App): void {
+ this.cleanup(app);
// Whichever core is present (see ecs/engineApi.ts). Sprite animation and the
// animator graph are pure TypeScript, but tweens live in the engine, so a core
// that compiles no tween system gets the rest of the plugin and says so.
@@ -45,11 +47,13 @@ export class AnimationPlugin implements Plugin {
app.insertResource(AnimatorController, animator);
const world = app.world;
- this.offDespawn_ = world.onDespawn((entity: Entity) => {
+ const offDespawn = world.onDespawn((entity: Entity) => {
tween.cancelAll(entity);
anim.removeEntityListeners(entity);
animator.removeEntity(entity);
});
+ this.despawnCleanups_.set(app, offDespawn);
+ this.latestDespawnCleanup_ = offDespawn;
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(Tween)],
@@ -90,11 +94,12 @@ export class AnimationPlugin implements Plugin {
), { runAfter: [SystemLabel.Tween, SystemLabel.Animator], runIf: playModeOnly });
}
- cleanup(): void {
- // Drop the despawn subscription so a warm re-Play with a reused world
- // doesn't stack a second (stale) closure.
- this.offDespawn_?.();
- this.offDespawn_ = null;
+ cleanup(app?: App): void {
+ const release = app ? this.despawnCleanups_.get(app) : this.latestDespawnCleanup_;
+ if (!release) return;
+ if (app) this.despawnCleanups_.delete(app);
+ if (release === this.latestDespawnCleanup_) this.latestDespawnCleanup_ = null;
+ release();
}
}
diff --git a/sdk/tests/animation-plugin-lifecycle.test.ts b/sdk/tests/animation-plugin-lifecycle.test.ts
new file mode 100644
index 000000000..9a5929221
--- /dev/null
+++ b/sdk/tests/animation-plugin-lifecycle.test.ts
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, expect, it, vi } from 'vitest';
+import { App } from '../src/app/app';
+import { AnimationPlugin } from '../src/animation/AnimationPlugin';
+import { Tween } from '../src/animation/Tween';
+import { SpriteAnimation, SpriteAnimator } from '../src/animation/SpriteAnimator';
+const apps: App[] = [];
+function build(plugin: AnimationPlugin) { const app = App.new(); apps.push(app); app.addPlugin(plugin); return app; }
+afterEach(() => { for (const app of apps.splice(0)) app.quit(); });
+it('quitting an older app releases only its animation despawn subscription', () => {
+ const plugin = new AnimationPlugin(), first = build(plugin), second = build(plugin);
+ expect(first.world.getStorageSizes().despawnCallbacks).toBe(1);
+ expect(second.world.getStorageSizes().despawnCallbacks).toBe(1);
+ first.quit();
+ expect(first.world.getStorageSizes().despawnCallbacks).toBe(0);
+ expect(second.world.getStorageSizes().despawnCallbacks).toBe(1);
+ const entity = second.world.spawn(), cancel = vi.spyOn(second.getResource(Tween), 'cancelAll');
+ const remove = vi.spyOn(second.getResource(SpriteAnimation), 'removeEntityListeners');
+ second.world.despawn(entity); expect(cancel).toHaveBeenCalledWith(entity); expect(remove).toHaveBeenCalledWith(entity);
+ second.quit(); expect(second.world.getStorageSizes().despawnCallbacks).toBe(0);
+});
+it('preview shutdowns leave the main animation listener active without accumulating old subscriptions', () => {
+ const plugin = new AnimationPlugin(), main = build(plugin);
+ for (let cycle = 0; cycle < 100; cycle++) {
+ const preview = build(plugin); preview.quit();
+ expect(preview.world.getStorageSizes().despawnCallbacks).toBe(0);
+ expect(main.world.getStorageSizes().despawnCallbacks).toBe(1);
+ }
+ main.quit(); expect(main.world.getStorageSizes().despawnCallbacks).toBe(0);
+});
+it('parameterless cleanup withdraws only the latest subscription and stays idempotent', () => {
+ const plugin = new AnimationPlugin(), first = build(plugin), second = build(plugin);
+ plugin.cleanup(); plugin.cleanup();
+ expect(first.world.getStorageSizes().despawnCallbacks).toBe(1);
+ expect(second.world.getStorageSizes().despawnCallbacks).toBe(0);
+ first.quit(); second.quit(); expect(first.world.getStorageSizes().despawnCallbacks).toBe(0);
+});
+it('quitting a newer app preserves older sprite animation playback', async () => {
+ const plugin = new AnimationPlugin(), first = build(plugin), second = build(plugin);
+ const animation = first.getResource(SpriteAnimation);
+ animation.registerClip({ name: 'walk', fps: 10, loop: true, frames: [{ texture: 0 }, { texture: 0 }] });
+ const entity = first.world.spawn(); first.world.insert(entity, SpriteAnimator, { clip: 'walk' });
+ second.quit(); await first.tick(.1);
+ expect(first.world.get(entity, SpriteAnimator).currentFrame).toBe(1);
+ first.quit(); expect(first.world.getStorageSizes().despawnCallbacks).toBe(0);
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index d5f676702..7445f4556 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(animation): isolate despawn subscriptions by app':
+ { note: 'Animation despawn subscriptions belong to their App.' },
'perf(animation): apply sprite frames through direct storage accessors':
{ note: 'Sprite animation applies frames through direct component accessors.' },
'fix(audio): share native completion events across backend subscribers':