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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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();+ });+});