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(sdk): Physics/Spine plugin cleanup() releases native module + listeners (audit A19)

esengine4bf28372755b
diff --git a/sdk/src/physics/PhysicsPlugin.ts b/sdk/src/physics/PhysicsPlugin.ts
index 5a223bfc5..b0c4b6e22 100644
--- a/sdk/src/physics/PhysicsPlugin.ts
+++ b/sdk/src/physics/PhysicsPlugin.ts
@@ -70,6 +70,7 @@ export class PhysicsPlugin implements Plugin {
private wasmUrl_: string;
private factory_?: PhysicsModuleFactory;
private bridge_ = new PhysicsBridge();
+ private module_: PhysicsWasmModule | null = null;
constructor(wasmUrl: string, config: PhysicsPluginConfig = {}, factory?: PhysicsModuleFactory) {
this.wasmUrl_ = wasmUrl;
@@ -96,6 +97,7 @@ export class PhysicsPlugin implements Plugin {
// abort safety without changing a single call.
this.bridge_.connect(loaded);
const module = this.bridge_.module;
+ this.module_ = module;
module._physics_init(
this.config_.gravity.x,
@@ -121,4 +123,15 @@ export class PhysicsPlugin implements Plugin {
});
app.getResource(PhysicsRuntime).initPromise = initPromise;
}
+
+ /**
+ * Shut the native Box2D world down on app teardown. Without this,
+ * `_physics_shutdown` was dead code and the C++ physics world (bodies,
+ * joints, contact state) leaked across an engine re-init. The bridge-guarded
+ * module makes the call abort-safe; null after so a double cleanup is a no-op.
+ */
+ cleanup(): void {
+ this.module_?._physics_shutdown();
+ this.module_ = null;
+ }
}
diff --git a/sdk/src/spine/SpineManager.ts b/sdk/src/spine/SpineManager.ts
index 4c294f1e2..5a9bb3de8 100644
--- a/sdk/src/spine/SpineManager.ts
+++ b/sdk/src/spine/SpineManager.ts
@@ -110,6 +110,21 @@ export class SpineManager {
this.entityVersions_.delete(entity);
}
+ /**
+ * Tear down every loaded runtime backend, freeing the native skeletons /
+ * atlases each holds. Idempotent — clearing the maps makes a second call a
+ * no-op. Called from SpinePlugin.cleanup() on app teardown so spine wasm
+ * resources don't leak across an engine re-init.
+ */
+ dispose(): void {
+ for (const backend of this.backends_.values()) {
+ backend.shutdown();
+ }
+ this.backends_.clear();
+ this.loadingBackends_.clear();
+ this.entityVersions_.clear();
+ }
+
getEntityVersion(entity: Entity): SpineVersion | undefined {
return this.entityVersions_.get(entity);
}
diff --git a/sdk/src/spine/SpinePlugin.ts b/sdk/src/spine/SpinePlugin.ts
index 7bdedd63c..31cbc635f 100644
--- a/sdk/src/spine/SpinePlugin.ts
+++ b/sdk/src/spine/SpinePlugin.ts
@@ -42,6 +42,7 @@ export class SpinePlugin implements Plugin {
private spineManager_: SpineManager | null;
private provider_: SpineWasmProvider | null;
private app_: App | null = null;
+ private despawnUnsub_: (() => void) | null = null;
constructor(managerOrProvider?: SpineManager | SpineWasmProvider) {
if (managerOrProvider instanceof SpineManager) {
@@ -80,7 +81,7 @@ export class SpinePlugin implements Plugin {
app.insertResource(SpineEvents, { events: [] });
- app.world.onDespawn((entity: Entity) => {
+ this.despawnUnsub_ = app.world.onDespawn((entity: Entity) => {
this.spineManager_?.removeEntity(entity);
});
@@ -129,6 +130,18 @@ export class SpinePlugin implements Plugin {
}
}
+ /**
+ * Drop the world.onDespawn subscription and dispose the spine manager's
+ * native backends. Without this, a re-init left a stale despawn listener
+ * pointing at a dead manager and leaked the wasm-side spine resources.
+ */
+ cleanup(): void {
+ this.despawnUnsub_?.();
+ this.despawnUnsub_ = null;
+ this.spineManager_?.dispose();
+ this.app_ = null;
+ }
+
private collectAndPublishEvents_(app: App): void {
const events: SpineEvent[] = [];
diff --git a/sdk/tests/plugin-cleanup.test.ts b/sdk/tests/plugin-cleanup.test.ts
new file mode 100644
index 000000000..f0739d613
--- /dev/null
+++ b/sdk/tests/plugin-cleanup.test.ts
@@ -0,0 +1,87 @@
+/**
+ * @file plugin-cleanup.test.ts
+ * @brief Regression net for audit A19 — Physics/Spine plugins must release
+ * their native module + world listeners on app teardown (App calls
+ * plugin.cleanup() at shutdown). Before this, `_physics_shutdown` was
+ * dead code, the spine backends were never disposed, and the
+ * world.onDespawn subscription was leaked, so re-init left a stale
+ * listener pointing at a dead manager.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { SpineManager } from '../src/spine/SpineManager';
+import { SpinePlugin } from '../src/spine/SpinePlugin';
+import { PhysicsPlugin } from '../src/physics/PhysicsPlugin';
+
+describe('SpineManager.dispose (A19)', () => {
+ it('shuts down every backend and clears all state, idempotently', () => {
+ const mgr = new SpineManager({} as any, new Map());
+ const backendA = { shutdown: vi.fn() };
+ const backendB = { shutdown: vi.fn() };
+ const m = mgr as any;
+ m.backends_.set('3.8', backendA);
+ m.backends_.set('4.1', backendB);
+ m.entityVersions_.set(1, '3.8');
+ m.loadingBackends_.set('4.2', Promise.resolve(null));
+
+ mgr.dispose();
+
+ expect(backendA.shutdown).toHaveBeenCalledTimes(1);
+ expect(backendB.shutdown).toHaveBeenCalledTimes(1);
+ expect(m.backends_.size).toBe(0);
+ expect(m.entityVersions_.size).toBe(0);
+ expect(m.loadingBackends_.size).toBe(0);
+
+ // Idempotent: a second dispose is a no-op, not a re-shutdown / throw.
+ expect(() => mgr.dispose()).not.toThrow();
+ expect(backendA.shutdown).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('SpinePlugin.cleanup (A19)', () => {
+ it('unsubscribes the despawn listener and disposes the spine manager', () => {
+ const plugin = new SpinePlugin();
+ const unsub = vi.fn();
+ const manager = { dispose: vi.fn() };
+ const p = plugin as any;
+ p.despawnUnsub_ = unsub;
+ p.spineManager_ = manager;
+
+ plugin.cleanup();
+
+ expect(unsub).toHaveBeenCalledTimes(1);
+ expect(manager.dispose).toHaveBeenCalledTimes(1);
+ expect(p.despawnUnsub_).toBeNull();
+
+ // A second cleanup must not re-fire the (now dropped) subscription.
+ plugin.cleanup();
+ expect(unsub).toHaveBeenCalledTimes(1);
+ });
+
+ it('is safe to call when build never ran (no subscription / manager)', () => {
+ const plugin = new SpinePlugin();
+ expect(() => plugin.cleanup()).not.toThrow();
+ });
+});
+
+describe('PhysicsPlugin.cleanup (A19)', () => {
+ it('shuts down the native physics world and nulls the module', () => {
+ const plugin = new PhysicsPlugin('fake://physics.wasm');
+ const shutdown = vi.fn();
+ const p = plugin as any;
+ p.module_ = { _physics_shutdown: shutdown };
+
+ plugin.cleanup();
+
+ expect(shutdown).toHaveBeenCalledTimes(1);
+ expect(p.module_).toBeNull();
+
+ // A second cleanup (module already released) must be a no-op.
+ plugin.cleanup();
+ expect(shutdown).toHaveBeenCalledTimes(1);
+ });
+
+ it('is safe to call before the async module load completed', () => {
+ const plugin = new PhysicsPlugin('fake://physics.wasm');
+ expect(() => plugin.cleanup()).not.toThrow();
+ });
+});