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(sidemodules): a game started over and over in one page no longer runs out of WebAssembly memory - the module host has an end, the App that made it disposes it on quit, and the KTX2 transcode workers stop with it
yhh1915e10d11a9
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 16ee77208..490e51282 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -823,7 +823,7 @@ setPaused: (paused: boolean) => voidsetPipeline: (pipeline: RenderPipeline) => voidsetPlaySpeed: (speed: number) => voidsetRunInBackground: (on: boolean) => void-setSideModules: (host: SideModuleHost) => void+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => voidsetTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefined@@ -3127,6 +3127,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefined@@ -10076,6 +10077,8 @@ globalName: string | undefined## SideModuleHost — interface @experimental```acquire: (id: SideModuleId) => Promise<SideModule | null>+dispose: (() => void) | undefined+onDispose: ((release: () => void) => void) | undefinedsource: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined```@@ -13900,6 +13903,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex eb69efdc8..c90c1f059 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -823,7 +823,7 @@ setPaused: (paused: boolean) => voidsetPipeline: (pipeline: RenderPipeline) => voidsetPlaySpeed: (speed: number) => voidsetRunInBackground: (on: boolean) => void-setSideModules: (host: SideModuleHost) => void+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => voidsetTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefined@@ -3135,6 +3135,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefined@@ -10298,6 +10299,8 @@ globalName: string | undefined## SideModuleHost — interface @experimental```acquire: (id: SideModuleId) => Promise<SideModule | null>+dispose: (() => void) | undefined+onDispose: ((release: () => void) => void) | undefinedsource: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined```@@ -14122,6 +14125,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 41e8c772e..e26384ea4 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -818,7 +818,7 @@ setPaused: (paused: boolean) => voidsetPipeline: (pipeline: RenderPipeline) => voidsetPlaySpeed: (speed: number) => voidsetRunInBackground: (on: boolean) => void-setSideModules: (host: SideModuleHost) => void+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => voidsetTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefined@@ -3122,6 +3122,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefined@@ -10071,6 +10072,8 @@ globalName: string | undefined## SideModuleHost — interface @experimental```acquire: (id: SideModuleId) => Promise<SideModule | null>+dispose: (() => void) | undefined+onDispose: ((release: () => void) => void) | undefinedsource: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined```@@ -13895,6 +13898,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 606702c60..814d8d3c8 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -818,7 +818,7 @@ setPaused: (paused: boolean) => voidsetPipeline: (pipeline: RenderPipeline) => voidsetPlaySpeed: (speed: number) => voidsetRunInBackground: (on: boolean) => void-setSideModules: (host: SideModuleHost) => void+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => voidsetTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefined@@ -3122,6 +3122,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefined@@ -10368,6 +10369,8 @@ globalName: string | undefined## SideModuleHost — interface @experimental```acquire: (id: SideModuleId) => Promise<SideModule | null>+dispose: (() => void) | undefined+onDispose: ((release: () => void) => void) | undefinedsource: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined```@@ -14198,6 +14201,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 7680b1cc5..49bc67cd7 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -818,7 +818,7 @@ setPaused: (paused: boolean) => voidsetPipeline: (pipeline: RenderPipeline) => voidsetPlaySpeed: (speed: number) => voidsetRunInBackground: (on: boolean) => void-setSideModules: (host: SideModuleHost) => void+setSideModules: (host: SideModuleHost, options?: { owned?: boolean; }) => voidsetTargetFrameRate: (fps: number) => voidsideModules: SideModuleHost | nullspineInitPromise: Promise<unknown> | undefined@@ -3122,6 +3122,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefined@@ -10078,6 +10079,8 @@ globalName: string | undefined## SideModuleHost — interface @experimental```acquire: (id: SideModuleId) => Promise<SideModule | null>+dispose: (() => void) | undefined+onDispose: ((release: () => void) => void) | undefinedsource: ((id: SideModuleId) => Promise<SideModuleSource | null>) | undefined```@@ -13929,6 +13932,7 @@ depthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedmsaaSamples: number | undefinedoutputTransform: OutputTransform | undefined+ownsSideModules: boolean | undefinedplugins: Plugin[] | undefinedquality: QualityConfig | undefinedrandomSeed: number | undefineddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 25955f044..843a14caf 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -251,6 +251,8 @@ export class App {// The realm's acquirer for optional native modules (physics, spine). Set once// at app creation; physics/spine self-gate off it. Null in headless/test apps.private sideModules_: SideModuleHost | null = null;+ /** This App made the host, so quitting disposes it; one handed in is its maker's to end. */+ private ownsSideModules_ = false;private pluginsFinished_ = false;private readonly eventRegistry_ = new EventRegistry();private readonly sortedSystemsCache_ = new Map<Schedule, SystemEntry[]>();@@ -312,8 +314,14 @@ export class App {return this.sideModules_;}- setSideModules(host: SideModuleHost): void {+ /**+ * `owned` says the host was made for this App alone: quitting then disposes+ * it, with the workers and module instances tied to it. A host shared with+ * anything else is left as it is, and whoever made it disposes it.+ */+ setSideModules(host: SideModuleHost, options?: { owned?: boolean }): void {this.sideModules_ = host;+ this.ownsSideModules_ = options?.owned === true;}addPlugins(plugins: Plugin[]): this {@@ -1556,6 +1564,11 @@ export class App {this.ownedCppRegistry_ = null;try { ownedRegistry?.delete(); }catch (e) { log.warn('app', 'Shutdown registry release error', e); }+ // After the plugins, which may still have asked it for something on their way out.+ const modules = this.ownsSideModules_ ? this.sideModules_ : null;+ this.ownsSideModules_ = false;+ try { modules?.dispose?.(); }+ catch (e) { log.warn('app', 'Shutdown module-host release error', e); }for (const [, entries] of this.systems_) {entries.length = 0;@@ -2099,6 +2112,8 @@ export interface WebAppOptions {/** The realm's optional-native-module acquirer; set before plugins build so* SpinePlugin (and later physics) can pull from it. See {@link App.sideModules}. */sideModules?: SideModuleHost;+ /** `sideModules` was made for this App alone, so quitting disposes it. See {@link App.setSideModules}. */+ ownsSideModules?: boolean;/*** Bitmask of render layers (bits 0..31) that sort by world Y within the* layer — top-down occlusion (lower on screen draws on top). Project-level@@ -2192,7 +2207,7 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A// entry snapshots the baseline — e.g. in unit tests that never load it).seedEngineComponents();const app = App.new();- if (options?.sideModules) app.setSideModules(options.sideModules);+ if (options?.sideModules) app.setSideModules(options.sideModules, { owned: options.ownsSideModules });const cppRegistry = new module.Registry() as unknown as CppRegistry;try {diff --git a/sdk/src/asset/basisWorkers.ts b/sdk/src/asset/basisWorkers.tsindex 64ee8dcf7..2fff2ef92 100644--- a/sdk/src/asset/basisWorkers.ts+++ b/sdk/src/asset/basisWorkers.ts@@ -55,11 +55,20 @@ self.onmessage = (e) => {`;}+/** A transcoder that owns threads, and so has to be told when it is done with. */+export interface WorkerBasisTranscoder extends BasisTranscoder {+ /** Stop the workers. What is still in flight settles as "no result"; later calls do too. Idempotent. */+ dispose(): void;+}+/*** A transcoder whose work runs on `count` workers, or null where this realm has* no `Worker` (mini-game hosts, node) — the caller then transcodes in place.+ *+ * The caller owns the workers: each holds its own instance of the module, and a+ * running worker is never collected, so they last until {@link WorkerBasisTranscoder.dispose}.*/-export function createWorkerBasisTranscoder(source: SideModuleSource, count: number): BasisTranscoder | null {+export function createWorkerBasisTranscoder(source: SideModuleSource, count: number): WorkerBasisTranscoder | null {if (typeof Worker === 'undefined' || typeof Blob === 'undefined' || typeof URL?.createObjectURL !== 'function') {return null;}@@ -77,6 +86,11 @@ export function createWorkerBasisTranscoder(source: SideModuleSource, count: numif (e.data.error !== undefined) p.reject(new Error(`transcode worker: ${e.data.error}`));else p.resolve(e.data.result ?? null);};+ // A worker whose script will not even start answers nothing; without this its loads wait for good.+ w.onerror = (e: ErrorEvent) => {+ const failed = new Error(`transcode worker: ${e.message || 'the worker stopped'}`);+ for (const [id, p] of pending) { pending.delete(id); p.reject(failed); }+ };// Each worker gets its own copy: a transferred buffer would leave the next one empty.w.postMessage({ init: true, glueText: source.glueText, globalName: source.globalName, wasmBytes: source.wasmBytes.slice(0) });workers.push(w);@@ -86,7 +100,9 @@ export function createWorkerBasisTranscoder(source: SideModuleSource, count: num}// Least-loaded, so one slow 4K texture does not queue the small ones behind it.const inFlight = new Array<number>(workers.length).fill(0);+ let disposed = false;const run = (ktx2: Uint8Array, code: number): Promise<TranscodeResult | null> => {+ if (disposed) return Promise.resolve(null);const i = inFlight.indexOf(Math.min(...inFlight));const id = nextId++;inFlight[i]++;@@ -100,6 +116,13 @@ export function createWorkerBasisTranscoder(source: SideModuleSource, count: numreturn {transcode: (ktx2: Uint8Array, target: CompressedTextureFormat) => run(ktx2, FORMAT_CODE[target]),transcodeToRgba: (ktx2: Uint8Array) => run(ktx2, RGBA_CODE) as Promise<RgbaResult | null>,+ dispose(): void {+ if (disposed) return;+ disposed = true;+ for (const w of workers) w.terminate();+ // Whoever is still waiting is being torn down with the realm: no result, and no error to report.+ for (const [id, p] of pending) { pending.delete(id); p.resolve(null); }+ },};}@@ -114,6 +137,10 @@ function workerCount(): number {* in front of it where the host can hand over the module's source and the realm* has `Worker`. A worker that fails once (a CSP refusing blob workers, a module* that will not start) sends that load and every later one to the main thread.+ *+ * The workers are the host's: they stop when it is disposed, which is what an App+ * does on quit. A realm that starts a game over and over would otherwise keep+ * every earlier game's workers, each with a WebAssembly memory of its own.*/export function basisTranscoderFor(host: SideModuleHost | null | undefined): Promise<BasisTranscoder | null> {if (!host) return Promise.resolve(null);@@ -135,11 +162,14 @@ async function makeTranscoder(host: SideModuleHost): Promise<BasisTranscoder | nconst source = host.source ? await host.source('basis').catch(() => null) : null;const workers = source ? createWorkerBasisTranscoder(source, workerCount()) : null;if (!workers) return main;+ host.onDispose?.(() => workers.dispose());let broken = false;const either = <R>(off: () => R | Promise<R>, on: () => R | Promise<R>): Promise<R> => {if (broken) return Promise.resolve(on());return Promise.resolve(off()).catch((e: unknown) => {broken = true;+ // Not coming back, so they do not keep their memory either.+ workers.dispose();log.warn('asset', 'KTX2 transcoding moved back to the main thread: the transcode workers failed', e);return on();});diff --git a/sdk/src/runtime/webAppFactory.ts b/sdk/src/runtime/webAppFactory.tsindex e8446f45d..6abc566ae 100644--- a/sdk/src/runtime/webAppFactory.ts+++ b/sdk/src/runtime/webAppFactory.ts@@ -34,6 +34,8 @@ const basePlugins = webBasePlugins();export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {+ // A host built here is this App's alone and ends with it; one passed in may serve others.+ const ownsSideModules = !options?.sideModules && Boolean(options?.wasmBaseUrl);const sideModules: SideModuleHost | undefined = options?.sideModules?? (options?.wasmBaseUrl ? createFetchSideModuleHost(options.wasmBaseUrl) : undefined);// Spine and DragonBones each fetch their wasm only when asked, so installing@@ -43,7 +45,7 @@ export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptio// Ordered, not concatenated: where a plugin came from is not where it goes.const plugins = [...uiPlugins, ...inBuildOrder([...basePlugins, ...entryPlugins()]),...(options?.plugins ?? [])];- return _createWebApp(module, { ...options, sideModules, plugins });+ return _createWebApp(module, { ...options, sideModules, ownsSideModules, plugins });}export interface HeadlessAppOptions {diff --git a/sdk/src/sideModules/fetchHost.ts b/sdk/src/sideModules/fetchHost.tsindex a6fcda2de..42e716774 100644--- a/sdk/src/sideModules/fetchHost.ts+++ b/sdk/src/sideModules/fetchHost.ts@@ -40,6 +40,8 @@ export function createFetchSideModuleHost(baseUrl: string): SideModuleHost {// Instantiation may detach the buffer it is given; the kept one stays whole.return instantiateFromGlueText(glueText, wasmBytes.slice(0), descriptor);}, { requiresWebAssembly: true });+ // The bytes go with the host: a worker pool tied to it has made its copies by then.+ host.onDispose?.(() => fetched.clear());return {...host,async source(id: SideModuleId): Promise<SideModuleSource | null> {diff --git a/sdk/src/sideModules/host.ts b/sdk/src/sideModules/host.tsindex 6c84f4f18..81ac38c8c 100644--- a/sdk/src/sideModules/host.ts+++ b/sdk/src/sideModules/host.ts@@ -24,6 +24,23 @@ export interface SideModuleHost {/** The glue and binary `id` is instantiated from, for a worker to instantiate* its own copy; absent where the realm has none to hand over. */source?(id: SideModuleId): Promise<SideModuleSource | null>;+ /**+ * Tie something to this host's life: a pool of workers that each instantiated+ * one of its modules. `release` runs once, when the host is disposed — or at+ * once, if it already has been.+ */+ onDispose?(release: () => void): void;+ /**+ * Let go of everything the host holds: the instances it cached and whatever+ * was tied to it. Whoever made the host calls this when the realm it served+ * is over; an App does it on quit for a host it created itself. Idempotent,+ * and a disposed host answers every later `acquire` with null.+ *+ * Nothing else ends these. A worker is never collected while it runs, and+ * each one holds a WebAssembly memory, so a host dropped without this leaks+ * them for as long as the page lives.+ */+ dispose?(): void;}export interface SideModuleSource {@@ -68,8 +85,25 @@ export interface SideModuleHostOptions {export function createSideModuleHost(instantiate: SideModuleInstantiator, options: SideModuleHostOptions = {}): SideModuleHost {const cache = new Map<SideModuleId, Promise<SideModule | null>>();+ const releases: Array<() => void> = [];+ let disposed = false;+ const run = (release: () => void): void => {+ try { release(); } catch (e) { log.warn('sidemodule', 'a release tied to the module host failed', e); }+ };return {+ onDispose(release: () => void): void {+ if (disposed) run(release);+ else releases.push(release);+ },+ dispose(): void {+ if (disposed) return;+ disposed = true;+ // Last tied, first released: what was built on a module goes before the module's own entry.+ for (const release of releases.splice(0).reverse()) run(release);+ cache.clear();+ },acquire(id: SideModuleId): Promise<SideModule | null> {+ if (disposed) return Promise.resolve(null);const cached = cache.get(id);if (cached) return cached;const descriptor = sideModuleDescriptor(id);@@ -88,7 +122,7 @@ export function createSideModuleHost(instantiate: SideModuleInstantiator, option// Absent BY DESIGN is the answer null already means; only a// module that was meant to be here is a failure to report.if (e instanceof SideModuleAbsent) log.info('sidemodule', e.message);- else log.error('sidemodule', `failed to load "${id}" (${descriptor.file}) — ${howToFix(id)}`, e);+ else log.error('sidemodule', `failed to load "${id}" (${descriptor.file}) — ${howToFix(id, e)}`, e);return null;})// Unknown ids used to be impossible (the type was closed) and so@@ -103,6 +137,12 @@ export function createSideModuleHost(instantiate: SideModuleInstantiator, option};}+/** The engine refused the memory: the artifact was found and compiled, so this is not a missing build. */+export function isOutOfWasmMemory(error: unknown): boolean {+ const message = error instanceof Error ? error.message : String(error);+ return /out of memory|cannot allocate wasm memory/i.test(message);+}+/*** What to do about a module that would not load, which differs by who built it.*@@ -110,8 +150,15 @@ export function createSideModuleHost(instantiate: SideModuleInstantiator, option* the advice is the build command. For a project's own module the engine has no* idea how it is produced — pointing someone at `pnpm build -t rive` would be a* command that does not exist — so it says where the export looked instead.+ *+ * Neither applies when the process had no WebAssembly memory left to give: the+ * module is there, and telling someone to rebuild it sends them the wrong way.*/-function howToFix(id: SideModuleId): string {+function howToFix(id: SideModuleId, error: unknown): string {+ if (isOutOfWasmMemory(error)) {+ return 'the module is present, but this process has no WebAssembly memory left to start it: '+ + 'something is holding earlier instances (in the editor, restart it and report this)';+ }if (id in SIDE_MODULES) {return 'likely not built locally: run the matching wasm build (spine 4.2 = '+ '`pnpm build -t spine`, others match their file name, `-t all` builds 'diff --git a/sdk/tests/basis-workers.test.ts b/sdk/tests/basis-workers.test.tsindex ec0df21d5..91de17fb9 100644--- a/sdk/tests/basis-workers.test.ts+++ b/sdk/tests/basis-workers.test.ts@@ -15,7 +15,7 @@ import { WASM_DIR, hasSideModule, loadSideModule } from './helpers/loadWasm';import { basisTranscoderFor, createWorkerBasisTranscoder } from '../src/asset/basisWorkers';import { transcoderFromModule, type BasisWasmModule } from '../src/asset/basisTranscoder';import { CompressedTextureFormat, type TranscodeResult } from '../src/asset/compressed';-import type { SideModuleHost, SideModuleSource } from '../src/sideModules/host';+import { createSideModuleHost, type SideModuleHost, type SideModuleSource } from '../src/sideModules/host';import { log } from '../src/util/logger';const ROOT = path.resolve(__dirname, '../..');@@ -24,6 +24,9 @@ const blobs = new Map<string, string>();const saved = { Worker: globalThis.Worker, createObjectURL: URL.createObjectURL, revokeObjectURL: URL.revokeObjectURL };class StandInWorker {+ /** Workers started and not yet terminated: each one is a thread and a WebAssembly memory the page keeps. */+ static live = 0;+ private stopped = false;onmessage: ((e: { data: unknown }) => void) | null = null;private readonly scope: { onmessage: ((e: { data: unknown }) => void) | null; postMessage(d: unknown): void } & Record<string, unknown>;constructor(url: string) {@@ -49,11 +52,18 @@ class StandInWorker {)(scope, shadow, importScripts);};new Function('self', 'importScripts', text)(scope, importScripts);+ StandInWorker.live++;}postMessage(d: unknown): void {setTimeout(() => this.scope.onmessage?.({ data: structuredClone(d) }), 0);}- terminate(): void {}+ terminate(): void {+ if (this.stopped) return;+ this.stopped = true;+ StandInWorker.live--;+ this.onmessage = null;+ this.scope.onmessage = null;+ }}beforeAll(() => {@@ -103,10 +113,46 @@ describe.skipIf(!hasSideModule('basis'))('KTX2 transcoding on workers', () => {same(await workers.transcode(ktx2, CompressedTextureFormat.ASTC_4x4),await main.transcode(ktx2, CompressedTextureFormat.ASTC_4x4));same(await workers.transcodeToRgba(ktx2), await main.transcodeToRgba(ktx2));+ workers.dispose();+ });++ const realmHost = (): SideModuleHost => ({+ ...createSideModuleHost(async () => (main as unknown as { mod: unknown }).mod as never),+ source: async () => source,+ });++ it('stops its workers with the host that made them, and answers nothing after', async () => {+ const before = StandInWorker.live;+ const host = realmHost();+ const t = (await basisTranscoderFor(host))!;+ expect(StandInWorker.live).toBeGreaterThan(before);+ const inFlight = t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4);+ host.dispose!();+ expect(StandInWorker.live).toBe(before);+ // Torn down mid-load: no result and no error, and no fall back to a module that is going away too.+ const warn = vi.spyOn(log, 'warn');+ expect(await inFlight).toBeNull();+ expect(await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4)).toBeNull();+ expect(warn).not.toHaveBeenCalled();+ warn.mockRestore();+ });++ // The editor starts a game, stops it and starts it again in one page. Each start made a host and up to four+ // workers and nothing ended them: a dozen starts later the page had no WebAssembly memory left (#121).+ it('leaves no worker behind however many times a realm is started and stopped', async () => {+ const before = StandInWorker.live;+ for (let play = 0; play < 20; play++) {+ const host = realmHost();+ const t = (await basisTranscoderFor(host))!;+ same(await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4), await main.transcode(ktx2, CompressedTextureFormat.ASTC_4x4));+ host.dispose!();+ }+ expect(StandInWorker.live).toBe(before);});it('goes back to the main thread, once and for good, when the workers fail', async () => {const warn = vi.spyOn(log, 'warn');+ const before = StandInWorker.live;const host: SideModuleHost = {acquire: async () => (main as unknown as { mod: unknown }).mod as never,source: async () => ({ ...source, glueText: 'throw new Error("no glue")' }),@@ -115,6 +161,8 @@ describe.skipIf(!hasSideModule('basis'))('KTX2 transcoding on workers', () => {same(await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4), await main.transcode(ktx2, CompressedTextureFormat.ASTC_4x4));await t.transcode(ktx2, CompressedTextureFormat.ASTC_4x4);expect(warn.mock.calls.filter((c) => String(c[1]).includes('main thread'))).toHaveLength(1);+ // Workers that will never answer do not keep their threads.+ expect(StandInWorker.live).toBe(before);warn.mockRestore();});diff --git a/sdk/tests/sideModuleHost.test.ts b/sdk/tests/sideModuleHost.test.tsindex dcf85cdea..3077577b2 100644--- a/sdk/tests/sideModuleHost.test.ts+++ b/sdk/tests/sideModuleHost.test.ts@@ -6,7 +6,9 @@* WeChat) is exercised by the per-realm export + runtime paths.*/import { describe, it, expect, vi } from 'vitest';-import { createSideModuleHost, SideModuleAbsent } from '../src/sideModules/host';+import { createSideModuleHost, isOutOfWasmMemory, SideModuleAbsent } from '../src/sideModules/host';+import { App } from '../src/app/app';+import { log } from '../src/util/logger';import { SIDE_MODULES, SPINE_VERSIONS, spineModuleId } from '../src/sideModules/registry';describe('side-module registry', () => {@@ -114,3 +116,63 @@ describe('createSideModuleHost', () => {});});++describe('a module host ends', () => {+ it('releases what was tied to it, newest first and once', () => {+ const host = createSideModuleHost(vi.fn());+ const order: string[] = [];+ host.onDispose!(() => order.push('first'));+ host.onDispose!(() => { throw new Error('one bad release'); });+ host.onDispose!(() => order.push('last'));+ const warn = vi.spyOn(log, 'warn').mockImplementation(() => {});+ host.dispose!();+ host.dispose!();+ warn.mockRestore();+ // One that throws does not keep the others from running.+ expect(order).toEqual(['last', 'first']);+ // Tied too late: there is no later moment to wait for.+ host.onDispose!(() => order.push('late'));+ expect(order).toEqual(['last', 'first', 'late']);+ });++ it('gives nothing once disposed, and does not ask the transport', async () => {+ const instantiate = vi.fn().mockResolvedValue({});+ const host = createSideModuleHost(instantiate);+ await host.acquire('physics');+ host.dispose!();+ expect(await host.acquire('physics')).toBeNull();+ expect(await host.acquire('basis')).toBeNull();+ expect(instantiate).toHaveBeenCalledTimes(1);+ });++ it('is disposed by the App it was made for, and left alone by one it was lent to', () => {+ const owned = createSideModuleHost(vi.fn());+ const lent = createSideModuleHost(vi.fn());+ const ended: string[] = [];+ owned.onDispose!(() => ended.push('owned'));+ lent.onDispose!(() => ended.push('lent'));+ const a = App.new();+ a.setSideModules(owned, { owned: true });+ const b = App.new();+ b.setSideModules(lent);+ a.quit();+ b.quit();+ expect(ended).toEqual(['owned']);+ });+});++describe('a module that would not load', () => {+ it('is not called a missing build when the process had no memory for it', async () => {+ const oom = new RangeError('WebAssembly.instantiate(): Out of memory: Cannot allocate Wasm memory for new instance');+ expect(isOutOfWasmMemory(oom)).toBe(true);+ expect(isOutOfWasmMemory(new Error('fetch /wasm/basis.js → 404'))).toBe(false);+ const error = vi.spyOn(log, 'error').mockImplementation(() => {});+ expect(await createSideModuleHost(vi.fn().mockRejectedValue(oom)).acquire('basis')).toBeNull();+ expect(await createSideModuleHost(vi.fn().mockRejectedValue(new Error('404'))).acquire('basis')).toBeNull();+ const said = error.mock.calls.map((c) => String(c[1]));+ error.mockRestore();+ expect(said[0]).toMatch(/no WebAssembly memory left/);+ expect(said[0]).not.toMatch(/not built locally/);+ expect(said[1]).toMatch(/not built locally/);+ });+});