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): side modules load on a native host with no WebAssembly global, and a video's audio-track probe is not a missing asset
yhh18eab4fe6c87
diff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.tsindex 8702f63f5..8f0b971d1 100644--- a/sdk/src/asset/AddressableManifest.ts+++ b/sdk/src/asset/AddressableManifest.ts@@ -7,6 +7,23 @@ import { contentHashOf } from './contentHash';import { log } from '../util/logger';const warnedNotPackaged = new Set<string>();+let probing = 0;++/**+ * Run `fn` asking about refs that may well not be packaged, without the warning+ * for each one that is not. A video asks whether the cook demuxed an audio track+ * beside it (`<video>.m4a`), and a target that plays the video whole, as the+ * mobile hosts do, has none: said as a missing asset, the question failed every+ * video example's boot on Android and iOS. Synchronous, so the window closes with it.+ */+export function probeRefs<T>(fn: () => T): T {+ probing++;+ try {+ return fn();+ } finally {+ probing--;+ }+}/*** A project file the package does not carry, said once and with the reason —@@ -14,7 +31,7 @@ const warnedNotPackaged = new Set<string>();* that look like files: `builtin:` meshes, URLs and blobs are not the cook's.*/function warnNotPackaged(ref: string): void {- if (warnedNotPackaged.has(ref) || ref.includes(':') || !/\.[a-z0-9]{2,8}$/i.test(ref)) return;+ if (probing > 0 || warnedNotPackaged.has(ref) || ref.includes(':') || !/\.[a-z0-9]{2,8}$/i.test(ref)) return;warnedNotPackaged.add(ref);log.warn('asset', `"${ref}" is not in this package. A build ships what its scenes reference, what the `+ 'scripts name as a whole path in a string literal, and the folders asset-groups.json marks 'diff --git a/sdk/src/sideModules/embeddedHost.ts b/sdk/src/sideModules/embeddedHost.tsindex 0f137a203..fd5e3d011 100644--- a/sdk/src/sideModules/embeddedHost.ts+++ b/sdk/src/sideModules/embeddedHost.ts@@ -31,5 +31,5 @@ export function createEmbeddedSideModuleHost(registry: EmbeddedSideModuleRegistrconst entry = registry[id];if (!entry) throw new Error(`side module "${id}" (${descriptor.file}) not embedded in this playable`);return instantiateFromGlueText(entry.glue, entry.wasm.buffer as ArrayBuffer, descriptor);- });+ }, { requiresWebAssembly: true });}diff --git a/sdk/src/sideModules/fetchHost.ts b/sdk/src/sideModules/fetchHost.tsindex df8b88762..a6fcda2de 100644--- a/sdk/src/sideModules/fetchHost.ts+++ b/sdk/src/sideModules/fetchHost.ts@@ -39,7 +39,7 @@ export function createFetchSideModuleHost(baseUrl: string): SideModuleHost {const { glueText, wasmBytes } = await fetchPair(descriptor);// Instantiation may detach the buffer it is given; the kept one stays whole.return instantiateFromGlueText(glueText, wasmBytes.slice(0), descriptor);- });+ }, { requiresWebAssembly: true });return {...host,async source(id: SideModuleId): Promise<SideModuleSource | null> {diff --git a/sdk/src/sideModules/host.ts b/sdk/src/sideModules/host.tsindex 29d4e4e97..6c84f4f18 100644--- a/sdk/src/sideModules/host.ts+++ b/sdk/src/sideModules/host.ts@@ -54,17 +54,29 @@ export class SideModuleAbsent extends Error {* missing artifact isn't refetched every frame). The transport is the only* realm-specific part; everything above it — gating, plugin install — is shared.*/-export function createSideModuleHost(instantiate: SideModuleInstantiator): SideModuleHost {+export interface SideModuleHostOptions {+ /**+ * The transport instantiates a WebAssembly binary through the realm's own+ * `WebAssembly` (the web's fetch and embedded hosts). A native host links its+ * modules in C++, and a mini-game host instantiates through the vendor's+ * WXWebAssembly, so neither needs the global, and iOS (QuickJS) and WeChat have+ * none: asking every host for it turned off physics, Spine and DragonBones on+ * every iOS build.+ */+ requiresWebAssembly?: boolean;+}++export function createSideModuleHost(instantiate: SideModuleInstantiator, options: SideModuleHostOptions = {}): SideModuleHost {const cache = new Map<SideModuleId, Promise<SideModule | null>>();return {acquire(id: SideModuleId): Promise<SideModule | null> {const cached = cache.get(id);if (cached) return cached;const descriptor = sideModuleDescriptor(id);- // A side module is a WebAssembly module; a host with none runs the- // engine's JavaScript build, which carries the core and nothing beside+ // On the web a side module is a WebAssembly binary; a page with none runs+ // the engine's JavaScript build, which carries the core and nothing beside// it. Said once, by name, instead of "WebAssembly is not defined".- if (descriptor && typeof WebAssembly === 'undefined') {+ if (descriptor && options.requiresWebAssembly && typeof WebAssembly === 'undefined') {log.error('sidemodule', `"${id}" is a WebAssembly module and this host has no WebAssembly: `+ 'the engine runs as JavaScript here, and the features it provides are unavailable');const none = Promise.resolve(null);diff --git a/sdk/src/video/VideoAPI.ts b/sdk/src/video/VideoAPI.tsindex c07ca2e18..f799a3aae 100644--- a/sdk/src/video/VideoAPI.ts+++ b/sdk/src/video/VideoAPI.ts@@ -6,6 +6,7 @@ import type { ESEngineModule } from '../wasm';import type { PlatformVideoBackend, VideoStreamHandle, VideoStreamOptions } from './PlatformVideoBackend';import { defineResource } from '../ecs/resource';import { log } from '../util/logger';+import { probeRefs } from '../asset/AddressableManifest';import { getPlatform, isPlatformInitialized } from '../platform/base';export type VideoHandle = VideoStreamHandle;@@ -119,7 +120,9 @@ export class VideoAPI {private resolveAudioTrack_(source: string): string | undefined {if (!this.refResolver_) return undefined;const siblingRef = source.startsWith('@uuid:') ? `${source}-audio` : `${source}.m4a`;- const resolved = this.refResolver_(siblingRef);+ // A question, not a reference: most targets have no cooked sibling.+ const resolver = this.refResolver_;+ const resolved = probeRefs(() => resolver(siblingRef));return resolved !== siblingRef ? resolved : undefined;}diff --git a/sdk/tests/manifest-model.test.ts b/sdk/tests/manifest-model.test.tsindex 0e16b0c10..ed0e9f726 100644--- a/sdk/tests/manifest-model.test.ts+++ b/sdk/tests/manifest-model.test.ts@@ -4,6 +4,7 @@ import { describe, it, expect, vi } from 'vitest';import {ManifestModel,normalizeBundleMode,+ probeRefs,type AddressableManifest,} from '../src/asset/AddressableManifest';@@ -153,6 +154,19 @@ describe('ManifestModel resolution', () => {expect(said[0]).toContain('alwaysInclude');});+ // A video asks whether a demuxed audio track was packaged beside it; on a target+ // that plays the video whole there is none, and that is an answer, not a fault.+ it('resolvePath: a probe that misses says nothing, and a miss after it still does', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);+ const m = model();+ expect(probeRefs(() => m.resolvePath('assets/video/probe-only.mp4.m4a'))).toBe('assets/video/probe-only.mp4.m4a');+ m.resolvePath('assets/video/really-missing.mp4');+ const said = warn.mock.calls.map((c) => c.join(' ')).filter((t) => t.includes('not in this package'));+ warn.mockRestore();+ expect(said).toHaveLength(1);+ expect(said[0]).toContain('really-missing.mp4');+ });+it('resolvePath: miss returns the ref verbatim', () => {expect(model().resolvePath('assets/hero.esprefab')).toBe('assets/hero.esprefab');});diff --git a/sdk/tests/native-side-modules.test.ts b/sdk/tests/native-side-modules.test.tsindex 58775da9e..27482c8ee 100644--- a/sdk/tests/native-side-modules.test.ts+++ b/sdk/tests/native-side-modules.test.ts@@ -69,6 +69,20 @@ describe('createNativeSideModules', () => {expect(mod).not.toBeNull();});+ // iOS runs the game's JS on QuickJS, which has no WebAssembly global. The host's modules+ // are linked in C++, so that must not matter: the release boot of every iOS template+ // found physics, Spine and DragonBones all turned off by a check meant for the web.+ it('answers physics on a host with no WebAssembly global', async () => {+ const { scope } = mockNativeHost();+ const saved = globalThis.WebAssembly;+ try {+ delete (globalThis as { WebAssembly?: unknown }).WebAssembly;+ expect(await createNativeSideModules(scope).acquire('physics')).not.toBeNull();+ } finally {+ globalThis.WebAssembly = saved;+ }+ });+it('answers null when the host did not — not an object that throws on first call', async () => {const { scope } = mockNativeHost({ physics: false });expect(await createNativeSideModules(scope).acquire('physics')).toBeNull();diff --git a/sdk/tests/sideModuleHost.test.ts b/sdk/tests/sideModuleHost.test.tsindex 014609576..dcf85cdea 100644--- a/sdk/tests/sideModuleHost.test.ts+++ b/sdk/tests/sideModuleHost.test.ts@@ -85,7 +85,7 @@ describe('createSideModuleHost', () => {try {delete (globalThis as { WebAssembly?: unknown }).WebAssembly;const instantiate = vi.fn().mockResolvedValue({});- const host = createSideModuleHost(instantiate);+ const host = createSideModuleHost(instantiate, { requiresWebAssembly: true });expect(await host.acquire('physics')).toBeNull();expect(await host.acquire('physics')).toBeNull();expect(instantiate).not.toHaveBeenCalled();@@ -96,4 +96,21 @@ describe('createSideModuleHost', () => {spy.mockRestore();}});++ // iOS runs QuickJS and WeChat has WXWebAssembly: neither realm has the global, and+ // neither transport needs it. A native host's modules are linked in C++.+ it('still loads through a transport that does not need WebAssembly, on a host without it', async () => {+ const saved = globalThis.WebAssembly;+ try {+ delete (globalThis as { WebAssembly?: unknown }).WebAssembly;+ const module = { tag: 'linked' };+ const instantiate = vi.fn().mockResolvedValue(module);+ const host = createSideModuleHost(instantiate);+ expect(await host.acquire('physics')).toBe(module);+ expect(instantiate).toHaveBeenCalledTimes(1);+ } finally {+ globalThis.WebAssembly = saved;+ }+ });+});