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): 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.ts
index 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.ts
index 0f137a203..fd5e3d011 100644
--- a/sdk/src/sideModules/embeddedHost.ts
+++ b/sdk/src/sideModules/embeddedHost.ts
@@ -31,5 +31,5 @@ export function createEmbeddedSideModuleHost(registry: EmbeddedSideModuleRegistr
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
+ }
+ });
+
});