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
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.tsindex 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.tsindex 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 } fromimport { 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.tsindex 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/bundleDiagnosimport { 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.tsindex 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.tsindex 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.mdindex 88791666b..d296ba3f8 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -556,7 +556,7 @@ getTargetFrameRate: () => numberhasResource: <T>(resource: ResourceDef<T>) => booleanhotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => booleaninsertResource: <T>(resource: ResourceDef<T>, value: T) => App-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 7027a1491..a9e8112d4 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -556,7 +556,7 @@ getTargetFrameRate: () => numberhasResource: <T>(resource: ResourceDef<T>) => booleanhotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => booleaninsertResource: <T>(resource: ResourceDef<T>, value: T) => App-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex a6f0aa621..b5a7083ae 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -551,7 +551,7 @@ getTargetFrameRate: () => numberhasResource: <T>(resource: ResourceDef<T>) => booleanhotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => booleaninsertResource: <T>(resource: ResourceDef<T>, value: T) => App-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 700ddf732..b4859b7a4 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -551,7 +551,7 @@ getTargetFrameRate: () => numberhasResource: <T>(resource: ResourceDef<T>) => booleanhotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => booleaninsertResource: <T>(resource: ResourceDef<T>, value: T) => App-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T@@ -4807,6 +4807,7 @@ url: string## MiniGameRuntimeConfig — interface @experimental```+aot: { wasm: string; manifest: AotManifest; } | undefinedaudioConfig: AudioProjectConfig | undefinedcolorSpace: "gamma" | "linear" | undefineddepthLayers: 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; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 4e7a4e1c1..21df5f6ee 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -551,7 +551,7 @@ getTargetFrameRate: () => numberhasResource: <T>(resource: ResourceDef<T>) => booleanhotSwapSystems: (incoming: ReadonlyArray<{ schedule: number; system: SystemDef; }>) => booleaninsertResource: <T>(resource: ResourceDef<T>, value: T) => App-installCompiledSystems: (wasm: BufferSource, manifest: AotManifest) => Promise<number>+installCompiledSystems: (wasm: string | BufferSource, manifest: AotManifest) => Promise<number>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefined@@ -9213,6 +9213,7 @@ tileTerrain: Map<number, number>## WeChatRuntimeConfig — interface @experimental```+aot: { wasm: string; manifest: AotManifest; } | undefinedaudioConfig: AudioProjectConfig | undefinedcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefineddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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.tsindex 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): PromisuiThemeOverrides: 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.tsindex 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.tsindex 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.