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.

feat(aot): a mini-game installs its compiled systems, by path

yhh3f28837e53db
diff --git a/pipeline/src/bundle/emccPath.ts b/pipeline/src/bundle/emccPath.ts
index 3a9b4cbaf..849b8a062 100644
--- a/pipeline/src/bundle/emccPath.ts
+++ b/pipeline/src/bundle/emccPath.ts
@@ -4,15 +4,17 @@
* @file Where emcc is, for the one build step that needs a C compiler.
*
* Only the AOT step asks (docs/REARCH_AOT.md): everything else the pipeline
- * builds is JavaScript. A machine without emscripten still exports every project
- * that promised nothing, so this answers `null` rather than throwing — the
- * refusal belongs to the step that knows whether anything was promised.
+ * builds is JavaScript, and this is the one place an export spawns a process. A
+ * machine without emscripten still exports every project that promised nothing,
+ * so this answers `null` rather than throwing — the refusal belongs to the step
+ * that knows whether anything was promised.
*
* Three places, in the order they are authoritative: what the caller was told
* (an editor that installed its own toolchain), the environment an emsdk shell
* exports, and the repo's own submodule for anyone working in the tree.
*/
import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -22,6 +24,23 @@ const EXE = process.platform === 'win32' ? 'emcc.bat' : 'emcc';
/** The repo root, from this file's own location (pipeline/src/bundle). */
const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+/**
+ * Run it. Never rejects: a missing binary is a code and a message, so the step
+ * that called it decides what that means. A shell on Windows because emcc is a
+ * `.bat` there and nothing else in an export shells out at all.
+ */
+export function runEmcc(
+ cmd: string, args: string[], cwd: string,
+): Promise<{ code: number; stderr: string }> {
+ return new Promise((done) => {
+ const child = spawn(cmd, args, { cwd, shell: process.platform === 'win32' });
+ let stderr = '';
+ child.stderr.on('data', (d) => { stderr += String(d); });
+ child.on('error', (e) => done({ code: 1, stderr: `${stderr}${e.message}` }));
+ child.on('close', (code) => done({ code: code ?? 1, stderr }));
+ });
+}
+
/**
* An absolute path to emcc, or null where this machine has none.
*
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index f1a2e39e0..d3849c82c 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -23,7 +23,6 @@ import type { BuildOptions, Plugin } from 'esbuild';
import { loadEsbuild } from '../bundle/esbuildRuntime';
import { writeFile, readFile, mkdir, cp, readdir, rm } from 'node:fs/promises';
import { existsSync } from 'node:fs';
-import { spawn } from 'node:child_process';
import path from 'node:path';
import { cookAssets, loadAssetGroups, type CookManifest } from '../assets/cookAssets';
import { buildAddressableManifest } from '../assets/addressableManifest';
@@ -58,7 +57,7 @@ import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from
import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../project/targetSupport';
import { scanSideModuleIds, sideModuleFiles, shipsSideModule } from '../bundle/sideModuleScan';
import { buildCompiledSystems } from '../bundle/buildCompiledSystems';
-import { resolveEmcc } from '../bundle/emccPath';
+import { resolveEmcc, runEmcc } from '../bundle/emccPath';
export type { ExportPlatform };
/**
@@ -486,22 +485,6 @@ async function attachSizeReport(result: ExportGameResult, opts: ExportGameOption
}
}
-/**
- * Run a build tool. The AOT step is the only part of an export that shells out,
- * and emcc is a `.bat` on Windows — which is why this asks for a shell there and
- * nowhere else. Never rejects: a missing binary is a code and a message, so the
- * step that called it decides what that means.
- */
-function runCommand(cmd: string, args: string[], cwd: string): Promise<{ code: number; stderr: string }> {
- return new Promise((done) => {
- const child = spawn(cmd, args, { cwd, shell: process.platform === 'win32' });
- let stderr = '';
- child.stderr.on('data', (d) => { stderr += String(d); });
- child.on('error', (e) => done({ code: 1, stderr: `${stderr}${e.message}` }));
- child.on('close', (code) => done({ code: code ?? 1, stderr }));
- });
-}
-
async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult> {
const platform = opts.platform ?? 'web';
const title = opts.title ?? 'Game';
@@ -533,6 +516,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
orientation,
runtime,
minify: opts.minify,
+ emcc: opts.emcc,
contentAddressed: opts.contentAddressed,
compressTextures: opts.compressTextures,
compressAudio: opts.compressAudio,
@@ -556,6 +540,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
orientation,
runtime,
minify: opts.minify,
+ emcc: opts.emcc,
contentAddressed: opts.contentAddressed,
compressTextures: opts.compressTextures,
compressAudio: opts.compressAudio,
@@ -714,16 +699,16 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
return { ok: false, platform, outDir: absOut, included: cook.included.length, warnings, errors };
}
- // 3b. Compiled systems (docs/REARCH_AOT.md), only where a runtime installs one:
- // the web page host. A mini-game and a playable have their own transports
- // and do not ask yet; QuickJS cannot instantiate a module at all.
+ // 3b. Compiled systems (docs/REARCH_AOT.md), for the page host. A mini-game
+ // stages its own above and takes a path; a playable inlines everything and
+ // has nowhere to put a module, and QuickJS cannot instantiate one at all.
let aot: PackagedGameConfig['aot'];
if (platform === 'web') {
// An export is not the editor's preview: here a `@compiled` marker is a
// promise someone is collecting on, so a promise the subset cannot keep
// fails the build rather than quietly falling back to the interpreter.
const built = await buildCompiledSystems(opts.root, {
- mode: 'release', emcc: resolveEmcc(opts.emcc), run: runCommand,
+ mode: 'release', emcc: resolveEmcc(opts.emcc), run: runEmcc,
});
if (!built.ok) {
errors.push(...built.errors);
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index 47b8f89e6..3934572f1 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -44,6 +44,8 @@ import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnos
import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';
import { OPEN_DATA_DIR } from './miniGameExportProfile';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
+import { buildCompiledSystems } from '../bundle/buildCompiledSystems';
+import { resolveEmcc, runEmcc } from '../bundle/emccPath';
import type { MiniGameExportProfile, MiniGameVendor } from './miniGameExportProfile';
export interface ExportMiniGameResult {
@@ -156,6 +158,12 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
* generated boot passes the packaged slice of them to the vendor runtime. */
runtime?: RuntimeProjectConfig;
minify?: boolean;
+ /**
+ * Where emcc is, for the systems a project marked `@compiled`
+ * (docs/REARCH_AOT.md). Absent ⇒ found from the environment; a project that
+ * promised nothing never needs one.
+ */
+ emcc?: string | null;
/** Emit content-addressed asset filenames (<hash><ext>) for dedup + immutable caching. */
contentAddressed?: boolean;
/** Encode raster textures to GPU-compressed KTX2 at cook time. */
@@ -312,13 +320,31 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
// factories arrive separately (game.js require()s the glue); this is what tells
// the runtime where each binary sits in the package.
const projectDeclarations = sideModuleDeclarations(projectModules, profile.id);
+
+ // The compiled twins, staged as a package file and named in the boot call —
+ // the target AOT exists for (docs/REARCH_AOT.md §1.1: iOS mini-games have no
+ // JIT). A PATH, because WXWebAssembly cannot compile bytes.
+ const built = await buildCompiledSystems(opts.root, {
+ mode: 'release', emcc: resolveEmcc(opts.emcc), run: runEmcc,
+ });
+ if (!built.ok) {
+ errors.push(...built.errors);
+ return { ok: false, platform: profile.id, outDir: absOut, included: cook.included.length, warnings, errors };
+ }
+ let aotArg = '';
+ if (built.wasmPath && built.manifest) {
+ progress({ phase: 'Compiling systems', detail: `${built.manifest.systems.length} system(s)` });
+ await mkdir(path.join(absOut, 'aot'), { recursive: true });
+ await cp(built.wasmPath, path.join(absOut, 'aot', 'systems.wasm'));
+ aotArg = `, aot: ${JSON.stringify({ wasm: 'aot/systems.wasm', manifest: built.manifest })}`;
+ }
const entrySrc =
`import { ${profile.runtimeInit}${installsPlatform ? ', installMiniGamePlatform' : ''}${themeColors ? ', parseThemeOverrides' : ''} } from 'esengine';\n` +
(installsPlatform ? `import __platformProfile from ${JSON.stringify(profile.runtimeProfileModule)};\n` : '') +
(scriptsAbs && existsSync(scriptsAbs) ? `import ${JSON.stringify(scriptsAbs)};\n` : '') +
`export function boot(engineFactory, sideModuleFactories) {\n` +
(installsPlatform ? ` installMiniGamePlatform(__platformProfile);\n` : '') +
- ` return ${profile.runtimeInit}({ engineFactory, engineWasmPath: ${JSON.stringify(engineWasmPath)}, sideModuleFactories, sceneNames: ${JSON.stringify(scenes.map((s) => s.name))}, firstScene: ${JSON.stringify(sceneName)}${runtimeArgs}${projectDeclarations.length > 0 ? `, sideModules: ${JSON.stringify(projectDeclarations)}` : ''} });\n` +
+ ` return ${profile.runtimeInit}({ engineFactory, engineWasmPath: ${JSON.stringify(engineWasmPath)}, sideModuleFactories, sceneNames: ${JSON.stringify(scenes.map((s) => s.name))}, firstScene: ${JSON.stringify(sceneName)}${runtimeArgs}${projectDeclarations.length > 0 ? `, sideModules: ${JSON.stringify(projectDeclarations)}` : ''}${aotArg} });\n` +
`}\n`;
progress({ phase: 'Bundling game' });
try {
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index 405f99fea..2cfda1261 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -201,17 +201,14 @@ async function boot(): Promise<void> {
decodePixels: (path) => fetchDecodePixels(path),
});
applyAssetRefResolvers(app, index.resolvePath);
- // The compiled twins this build produced, if it produced any. Fetched here
- // rather than inside initRuntime because fetching is what a transport does and
- // initRuntime serves every one of them (docs/REARCH_AOT.md §9).
- const aot = cfg.aot
- ? { wasm: await (await fetch(`./${cfg.aot.wasm}`)).arrayBuffer(), manifest: cfg.aot.manifest }
- : undefined;
await initRuntime({
app,
module,
source,
- ...(aot ? { aot } : {}),
+ // The compiled twins this build produced, if any. The path, not the bytes:
+ // reading it is the platform seam's job, and on a mini-game only the seam
+ // knows how (docs/REARCH_AOT.md §9).
+ ...(cfg.aot ? { aot: cfg.aot } : {}),
manifest: index.manifest,
catalog: index.catalog,
remoteRoot: cfg.hotUpdate?.remoteRoot,
diff --git a/pipeline/tests/export-compiled-systems.test.ts b/pipeline/tests/export-compiled-systems.test.ts
index 053809c94..00719de60 100644
--- a/pipeline/tests/export-compiled-systems.test.ts
+++ b/pipeline/tests/export-compiled-systems.test.ts
@@ -51,6 +51,18 @@ const BROKEN = PROMISED.replace('drift.x += drift.step;', 'drift.x += Math.rando
/** A project with no marker at all — the state every project starts in. */
const UNMARKED = PROMISED.replace(/\n \* @compiled\n/, '\n');
+/** A mini-game package needs the vendor SDK entry and its own glue staged. */
+function miniGameStubs(root: string): void {
+ // The names the fixture project imports: a stub entry missing one fails the
+ // bundle, and the bundle is what carries the boot call under test.
+ writeFileSync(path.join(root, '_sdk', 'index.wechat.js'),
+ 'export function initWeChatRuntime(){return Promise.resolve();}\n'
+ + 'export const defineComponent = () => {};\nexport const defineSystem = () => {};\n'
+ + 'export const Query = () => {};\nexport const Mut = () => {};\n');
+ writeFileSync(path.join(root, '_wasm', 'esengine.wxgame.js'), 'module.exports = () => Promise.resolve({});');
+ writeFileSync(path.join(root, '_wasm', 'esengine.wxgame.wasm'), 'wasmbytes');
+}
+
function project(source: string | null): { root: string; out: string } {
const root = mkdtempSync(path.join(tmpdir(), 'estella-aot-export-'));
mkdirSync(path.join(root, 'scenes'), { recursive: true });
@@ -82,6 +94,13 @@ const run = (f: { root: string; out: string }) => exportGame({
const config = (out: string): PackagedGameConfig =>
JSON.parse(readFileSync(path.join(out, 'game.config.json'), 'utf8')) as PackagedGameConfig;
+const runWeChat = (f: { root: string; out: string }) => exportGame({
+ root: f.root, entryScene: 'scenes/main.esscene', gameHostEntry: 'unused-for-wechat',
+ scriptsEntry: 'src/main.ts', platform: 'wechat', wechatAppid: 'wxTEST0123456789',
+ sdkDistDir: path.join(f.root, '_sdk'), wasmDir: path.join(f.root, '_wasm'),
+ outDir: f.out,
+});
+
describe('what a package carries for a compiled system', () => {
it('reports whether this gate could run at all', () => {
if (EMCC) console.log(`[aot-export] emcc at ${EMCC}`);
@@ -114,6 +133,21 @@ describe('what a package carries for a compiled system', () => {
} finally { rmSync(f.root, { recursive: true, force: true }); }
}, 120_000);
+ it.skipIf(!EMCC)('a mini-game carries it too, and boots from the path', async () => {
+ const f = project(PROMISED);
+ miniGameStubs(f.root);
+ try {
+ const res = await runWeChat(f);
+ expect(res.errors).toEqual([]);
+ expect(existsSync(path.join(f.out, 'aot', 'systems.wasm'))).toBe(true);
+ // A mini-game has no game.config.json — its configuration IS the generated
+ // boot call, and WXWebAssembly takes the PATH, never the bytes.
+ const boot = readFileSync(path.join(f.out, 'game-bundle.js'), 'utf8');
+ expect(boot).toContain('aot/systems.wasm');
+ expect(boot).toContain('ExportDriftSystem');
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 120_000);
+
it('carries nothing for a project that promised nothing', async () => {
const f = project(UNMARKED);
try {
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 88791666b..d296ba3f8 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -556,7 +556,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -6599,7 +6599,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: BufferSource; manifest: AotManifest; } | undefined
+aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 7027a1491..a9e8112d4 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -556,7 +556,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -6792,7 +6792,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: BufferSource; manifest: AotManifest; } | undefined
+aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a6f0aa621..b5a7083ae 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -551,7 +551,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -6594,7 +6594,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: BufferSource; manifest: AotManifest; } | undefined
+aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 700ddf732..b4859b7a4 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -551,7 +551,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -4807,6 +4807,7 @@ url: string
## MiniGameRuntimeConfig — interface @experimental
```
+aot: { wasm: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6839,7 +6840,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: BufferSource; manifest: AotManifest; } | undefined
+aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 4e7a4e1c1..21df5f6ee 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -551,7 +551,7 @@ getTargetFrameRate: () => number
hasResource: <T>(resource: ResourceDef<T>) => boolean
hotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => boolean
insertResource: <T>(resource: ResourceDef<T>, value: T) => App
-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>
+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -6601,7 +6601,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
-aot: { wasm: BufferSource; manifest: AotManifest; } | undefined
+aot: { wasm: string | BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
@@ -9213,6 +9213,7 @@ tileTerrain: Map<number, number>
## WeChatRuntimeConfig — interface @experimental
```
+aot: { wasm: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 746d95c94..3ace190d8 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -847,7 +847,9 @@ export class App {
* rows in the ENGINE's memory, and refuses rather than move rows already
* allocated elsewhere, or trust a module built for other offsets.
*/
- async installCompiledSystems(wasm: BufferSource, manifest: AotManifest): Promise<number> {
+ async installCompiledSystems(
+ wasm: string | BufferSource, manifest: AotManifest,
+ ): Promise<number> {
const module = this.module_;
if (!module) {
throw new Error('installCompiledSystems: this App has no engine module, and a compiled '
diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.ts
index 1e278bc16..57434cf43 100644
--- a/sdk/src/ecs/aot/installAot.ts
+++ b/sdk/src/ecs/aot/installAot.ts
@@ -19,6 +19,7 @@
* hide exactly the thing worth knowing.
*/
+import { platformInstantiateWasm } from '../../platform';
import { getComponent } from '../component';
import type { AnyComponentDef } from '../component';
import type { World } from '../world';
@@ -40,7 +41,10 @@ export interface InstallAotOptions {
readonly host: AotHost;
/** What the build wrote beside the module. */
readonly manifest: AotManifest;
- readonly wasm: BufferSource;
+ /** The module: a package-relative path, or its bytes. A path is the only
+ * form WeChat takes (WXWebAssembly cannot compile a buffer), so the
+ * platform seam is what instantiates rather than this. */
+ readonly wasm: string | BufferSource;
/** The live value of a named resource, for the mirror to copy in. */
readonly resources: ResourceReader;
}
@@ -55,8 +59,8 @@ export async function installAot(opts: InstallAotOptions): Promise<AotRuntime> {
const memory = new WasmPoolMemory(opts.host);
opts.world.useScriptPoolMemory(memory);
- const instance = await WebAssembly.instantiate(
- new WebAssembly.Module(opts.wasm), { env: { memory: opts.host.memory } });
+ const { instance } = await platformInstantiateWasm(
+ wasmSource(opts.wasm), { env: { memory: opts.host.memory } });
const exports = instance.exports as unknown as Record<string, unknown>;
// A STANDALONE_WASM reactor runs its data setup here rather than at an entry
// point, and the module has none.
@@ -74,6 +78,16 @@ export async function installAot(opts: InstallAotOptions): Promise<AotRuntime> {
return runtime;
}
+/**
+ * The module as the platform seam takes it. A view over a pooled buffer (what
+ * node hands back for a file read) is a window onto other bytes, so it gives up
+ * its own rather than the pool's.
+ */
+function wasmSource(wasm: string | BufferSource): string | ArrayBuffer {
+ if (typeof wasm === 'string' || wasm instanceof ArrayBuffer) return wasm;
+ return wasm.buffer.slice(wasm.byteOffset, wasm.byteOffset + wasm.byteLength) as ArrayBuffer;
+}
+
/** What a manifest's component NAME means in this runtime. */
function componentNamed(name: string): AnyComponentDef | undefined {
return getComponent(name);
diff --git a/sdk/src/runtime/miniGameRuntime.ts b/sdk/src/runtime/miniGameRuntime.ts
index 0eeecf33a..59e411d0d 100644
--- a/sdk/src/runtime/miniGameRuntime.ts
+++ b/sdk/src/runtime/miniGameRuntime.ts
@@ -29,6 +29,7 @@ import {
import { createMiniGameSideModuleHost, type MiniGameSideModuleFactories } from '../sideModules';
import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { SceneData } from '../scene/scene';
+import type { AotManifest } from '../ecs/aot/AotSystems';
import { log } from '../util/logger';
// =============================================================================
@@ -118,6 +119,12 @@ export interface MiniGameRuntimeConfig {
* need no entry; the engine's table already has them.
*/
sideModules?: Array<{ id: string; file: string; globalName?: string }>;
+ /**
+ * The compiled twins this build produced (docs/REARCH_AOT.md), as the path
+ * the export staged them at. A path and never bytes: WXWebAssembly compiles
+ * a package file and nothing else, which is also why the seam instantiates.
+ */
+ aot?: { wasm: string; manifest: AotManifest };
}
export async function initMiniGameRuntime(config: MiniGameRuntimeConfig): Promise<void> {
@@ -213,6 +220,7 @@ export async function initMiniGameRuntime(config: MiniGameRuntimeConfig): Promis
uiThemeOverrides: config.uiThemeOverrides,
audioConfig: config.audioConfig,
aspectRatio: canvas.width / canvas.height,
+ ...(config.aot ? { aot: config.aot } : {}),
});
app.run();
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index 4edaf0af4..e10475013 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -575,7 +575,7 @@ export interface RuntimeInitConfig {
* before the first scene registers, the only moment where no component
* exists yet to be left behind in the wrong memory.
*/
- aot?: { wasm: BufferSource; manifest: AotManifest };
+ aot?: { wasm: string | BufferSource; manifest: AotManifest };
}
export async function initRuntime(config: RuntimeInitConfig): Promise<void> {
diff --git a/sdk/tests/aot-install.test.ts b/sdk/tests/aot-install.test.ts
index 7acce23f9..e64dad691 100644
--- a/sdk/tests/aot-install.test.ts
+++ b/sdk/tests/aot-install.test.ts
@@ -9,6 +9,12 @@
* ORDER: pool memory before any component, module instantiated against
* the engine's memory, digests checked before anything is installed.
*
+ * It runs on both shapes of host, because they are not interchangeable:
+ * a browser takes the bytes, and WeChat's WXWebAssembly takes ONLY a
+ * package path and cannot compile a buffer at all. Instantiating
+ * through the platform seam is what makes one road serve both, and a
+ * host here refuses the form it would refuse on a device.
+ *
* Loud skip without emsdk — the module here is really compiled.
*/
import { describe, it, expect } from 'vitest';
@@ -18,6 +24,8 @@ import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { setPlatform } from '../src/platform/base';
+import type { PlatformAdapter, WasmInstantiateResult } from '../src/platform/types';
import { World } from '../src/ecs/world';
import { defineComponent } from '../src/ecs/component';
import { defineSystem, SystemRunner } from '../src/ecs/system';
@@ -74,7 +82,32 @@ void es_sys_Fade(es_addr_t ctx) {
}
`;
-function buildModule(): Uint8Array {
+/**
+ * The two hosts, each refusing what it refuses on a device. Nothing else of a
+ * platform is reached by an install, so nothing else is here.
+ */
+const HOSTS = {
+ 'a host that takes bytes': {
+ instantiateWasm(src: string | ArrayBuffer, imports: WebAssembly.Imports) {
+ if (typeof src === 'string') throw new Error('this host was handed a path');
+ return WebAssembly.instantiate(src, imports) as Promise<WasmInstantiateResult>;
+ },
+ },
+ 'a host that takes only a path': {
+ instantiateWasm(src: string | ArrayBuffer, imports: WebAssembly.Imports) {
+ if (typeof src !== 'string') throw new Error('WXWebAssembly requires a file path string');
+ return WebAssembly.instantiate(readFileSync(src), imports) as Promise<WasmInstantiateResult>;
+ },
+ },
+} as const;
+
+/** What that host is given: the same module, in the form it accepts. */
+function moduleFor(kind: keyof typeof HOSTS, built: { bytes: Uint8Array; path: string }): string | BufferSource {
+ setPlatform(HOSTS[kind] as unknown as PlatformAdapter);
+ return kind === 'a host that takes only a path' ? built.path : built.bytes;
+}
+
+function buildModule(): { bytes: Uint8Array; path: string } {
const dir = mkdtempSync(path.join(tmpdir(), 'estella-install-'));
mkdirSync(dir, { recursive: true });
writeFileSync(path.join(dir, 'sys.c'), SYSTEM_C);
@@ -86,7 +119,7 @@ function buildModule(): Uint8Array {
'-o', out, path.join(dir, 'sys.c'),
], { encoding: 'utf8', cwd: dir, shell: process.platform === 'win32' });
if (built.status !== 0) throw new Error(`emcc failed:\n${built.stderr}`);
- return readFileSync(out);
+ return { bytes: readFileSync(out), path: out };
}
const FADE_FIELDS = ['alpha', 'step'];
@@ -135,8 +168,9 @@ describe('installing a built module', () => {
expect(true).toBe(true);
});
- it.skipIf(!EMCC)('one call, and the scheduler runs the twin', async () => {
- const wasm = buildModule();
+ it.skipIf(!EMCC).each(Object.keys(HOSTS) as (keyof typeof HOSTS)[])(
+ 'one call, and the scheduler runs the twin — on %s', async (kind) => {
+ const wasm = moduleFor(kind, buildModule());
const interpreted = project();
const interpretedEntities = seed(interpreted.world, interpreted.Fade);
@@ -167,7 +201,8 @@ describe('installing a built module', () => {
world: p.world, runner: p.runner, host: new Host(),
// What a build would have written before `step` was added.
manifest: manifestFor(projectShapeDigest([{ name: 'Fade', fields: ['alpha'] }])),
- wasm: buildModule(), resources: () => undefined,
+ wasm: moduleFor('a host that takes bytes', buildModule()),
+ resources: () => undefined,
})).rejects.toThrow(/Rebuild the project/);
});
@@ -176,7 +211,8 @@ describe('installing a built module', () => {
const entities = seed(p.world, p.Fade);
await installAot({
world: p.world, runner: p.runner, host: new Host(),
- manifest: manifestFor(), wasm: buildModule(), resources: () => undefined,
+ manifest: manifestFor(), wasm: moduleFor('a host that takes bytes', buildModule()),
+ resources: () => undefined,
}).catch(() => { /* the ordering check below is the point */ });
// Rows already existed, so pool memory could not move: the install threw
// before any twin was registered, and the closure still runs.