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 packaged game runs its compiled systems

yhh9c05c19aa003
diff --git a/.gitignore b/.gitignore
index 1ff2a3a20..62bee218e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -61,6 +61,9 @@ compile_commands.json
# Cooked-build render-verify artifacts (regenerated by verify:render:cooked)
pipeline/.cooked-verify/
+# Projects the AOT end-to-end gate writes and compiles.
+pipeline/.aot-e2e/
+pipeline/.aot-e2e-probe/
pipeline/.cooked-src/
# Hot-update render-verify artifacts (regenerated by verify:render:hotupdate)
pipeline/.hotupdate-verify/
diff --git a/cmake/Emscripten.cmake b/cmake/Emscripten.cmake
index 1169731ac..192cd408f 100644
--- a/cmake/Emscripten.cmake
+++ b/cmake/Emscripten.cmake
@@ -45,7 +45,7 @@ set(ES_EMSCRIPTEN_LINK_FLAGS
"-sEXPORT_NAME='ESEngineModule'" # Module name
# Exported functions (EMSCRIPTEN_KEEPALIVE + stdlib)
"-sEXPORTED_FUNCTIONS=['_malloc','_free','_es_app_init']"
- "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32']"
+ "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','wasmMemory']"
# Embed assets (fonts, etc.)
"--embed-file=${CMAKE_SOURCE_DIR}/assets/fonts@/assets/fonts"
)
@@ -72,7 +72,7 @@ set(ES_EMSCRIPTEN_MAIN_MODULE_FLAGS
"-sEXPORTED_FUNCTIONS=['_malloc','_free']"
# 'GL' is required for the WebGL2 context binding (module.GL.registerContext);
# the monolithic web build exports it too — the main-module list had dropped it.
- "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS','addFunction','loadDynamicLibrary']"
+ "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS','addFunction','loadDynamicLibrary','wasmMemory']"
-O3
-flto
-Wl,--gc-sections
@@ -96,7 +96,7 @@ set(ES_EMSCRIPTEN_WXGAME_MAIN_MODULE_FLAGS
"--extern-pre-js=${CMAKE_SOURCE_DIR}/src/esengine/platform/web/wxgame-pre.js"
"-sEXPORT_NAME='ESEngineModule'"
"-sEXPORTED_FUNCTIONS=['_malloc','_free']"
- "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS','loadDynamicLibrary']"
+ "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS','loadDynamicLibrary','wasmMemory']"
-O3
-flto
-Wl,--gc-sections
@@ -153,7 +153,7 @@ set(ES_EMSCRIPTEN_WXGAME_SDK_FLAGS
"--extern-pre-js=${CMAKE_SOURCE_DIR}/src/esengine/platform/web/wxgame-pre.js"
"-sEXPORT_NAME='ESEngineModule'"
"-sEXPORTED_FUNCTIONS=['_malloc','_free']"
- "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS']"
+ "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS','wasmMemory']"
-O3
-flto
-Wl,--gc-sections
@@ -239,7 +239,11 @@ set(ES_EMSCRIPTEN_SDK_LINK_FLAGS
-sFORCE_FILESYSTEM=1
"-sEXPORT_NAME='ESEngineModule'"
"-sEXPORTED_FUNCTIONS=['_malloc','_free']"
- "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS','addFunction']"
+ # 'wasmMemory' is the AOT contract: a compiled system module IMPORTS this
+ # memory rather than owning one, so the game's own systems read the rows
+ # where they already are (docs/REARCH_AOT.md §6.1). The glue keeps it in a
+ # local otherwise, and an ArrayBuffer cannot be turned back into a Memory.
+ "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','HEAPF32','HEAPU8','HEAPU32','GL','FS','addFunction','wasmMemory']"
-O3
-flto
-Wl,--gc-sections
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index e349ac144..65eb4de36 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 71,
- "experimental": 1649,
+ "experimental": 1651,
"deprecated": 3
},
- "total": 1833,
+ "total": 1835,
"subsystems": [
{
"id": "ecs",
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index 3bc3e30c6..9a0fe279a 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -120,7 +120,10 @@ async function loadPipeline(entry, outName) {
format: 'esm',
platform: 'node',
target: 'node20',
- external: ['esbuild', 'electron', 'sharp', 'draco3dgltf',
+ // 'typescript' (the AOT step parses a project with it) reads `__filename` at
+ // load, which an ESM bundle has none of: inlined, the bundle dies before it
+ // exports anything.
+ external: ['esbuild', 'electron', 'sharp', 'draco3dgltf', 'typescript',
'../../../build-tools/basis/encoder.mjs', '../../../build-tools/ufbx/reader.mjs'],
logLevel: 'error',
banner: {
@@ -128,8 +131,16 @@ async function loadPipeline(entry, outName) {
+ `const require = __esCreateRequire('${fileUrl(path.join(PIPELINE, 'package.json'))}');\n`,
},
});
- const mod = await import(fileUrl(outfile));
- return { mod, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+ const cleanup = () => rmSync(dir, { recursive: true, force: true });
+ try {
+ // Cleaned up on the way out even when the bundle will not load: the temp dir
+ // lives inside `pipeline/src`, so one left behind is a copy of half the
+ // toolchain sitting where every source-scanning gate will read it.
+ return { mod: await import(fileUrl(outfile)), cleanup };
+ } catch (err) {
+ cleanup();
+ throw err;
+ }
}
const PROJECT_FILES = ['project.esproject', 'project.esproj', 'project.json'];
diff --git a/pipeline/package.json b/pipeline/package.json
index 50449b4c2..7bdcba8ea 100644
--- a/pipeline/package.json
+++ b/pipeline/package.json
@@ -20,12 +20,12 @@
"ffmpeg-static": "^5.3.0",
"meshoptimizer": "^1.2.0",
"pngjs": "^7.0.0",
+ "typescript": "^6.0.3",
"wasm-media-encoders": "^0.7.0"
},
"devDependencies": {
"@types/node": "^25.9.3",
"@types/pngjs": "^6.0.5",
- "typescript": "^6.0.3",
"vitest": "^2.1.9"
}
}
diff --git a/pipeline/src/bundle/buildCompiledSystems.ts b/pipeline/src/bundle/buildCompiledSystems.ts
index 8e0228d48..8e3e2e247 100644
--- a/pipeline/src/bundle/buildCompiledSystems.ts
+++ b/pipeline/src/bundle/buildCompiledSystems.ts
@@ -117,6 +117,12 @@ export async function buildCompiledSystems(
if (files.length === 0) {
return { ok: true, wasmPath: null, manifest: null, errors: [], notes: [] };
}
+ // A project with no `@compiled` anywhere promised nothing, so it must not pay
+ // for a TypeScript Program over its sources. Nothing is decided here: the parse
+ // below still decides, this only skips having nothing to decide.
+ if (!files.some((f) => readFileSync(f, 'utf8').includes('@compiled'))) {
+ return { ok: true, wasmPath: null, manifest: null, errors: [], notes: [] };
+ }
let lowered;
try {
@@ -160,7 +166,8 @@ export async function buildCompiledSystems(
return {
ok: false, wasmPath: null, manifest: null, notes,
errors: [`${chosen.length} system(s) are marked @compiled but there is no emcc`
- + ' — run `pnpm emsdk:setup`, or remove the marker'],
+ + ' — install the emscripten toolchain and point EMSDK at it (in this repo:'
+ + ' `pnpm emsdk:setup`), or remove the marker'],
};
}
@@ -182,6 +189,10 @@ export async function buildCompiledSystems(
// No entry point and no JS glue, so the module's only import is the memory
// it is given. §6.5 is a property of this command line as much as of the C.
'--no-entry', '-sSTANDALONE_WASM', '-sIMPORTED_MEMORY', '-sERROR_ON_UNDEFINED_SYMBOLS=1',
+ // An import may not declare a smaller maximum than the memory handed to it,
+ // and the engine's grows (2GB). Without this the module takes a hand-made
+ // 256-page test memory and REFUSES the real engine's.
+ '-sALLOW_MEMORY_GROWTH=1',
`-sEXPORTED_FUNCTIONS=${exported}`,
'-o', wasmPath, path.join(dir, 'systems.c'),
], dir);
diff --git a/pipeline/src/bundle/emccPath.ts b/pipeline/src/bundle/emccPath.ts
new file mode 100644
index 000000000..3a9b4cbaf
--- /dev/null
+++ b/pipeline/src/bundle/emccPath.ts
@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @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.
+ *
+ * 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 path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** `emcc` is a .bat on Windows, and spawning it needs the extension. */
+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)), '..', '..', '..');
+
+/**
+ * An absolute path to emcc, or null where this machine has none.
+ *
+ * `override` wins when given — the caller may know about a toolchain this has no
+ * way to find, and passing an explicit path must never be second-guessed.
+ */
+export function resolveEmcc(override?: string | null): string | null {
+ if (override) return existsSync(override) ? override : null;
+ const env = process.env['EMCC'];
+ if (env && existsSync(env)) return env;
+ const emsdk = process.env['EMSDK'];
+ if (emsdk) {
+ const at = path.join(emsdk, 'upstream', 'emscripten', EXE);
+ if (existsSync(at)) return at;
+ }
+ const local = path.join(REPO, 'tools', 'emsdk', 'upstream', 'emscripten', EXE);
+ return existsSync(local) ? local : null;
+}
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 678663fbe..f1a2e39e0 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -23,6 +23,7 @@ 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';
@@ -56,6 +57,8 @@ import { measureBuild, type BuildSizeReport } from './sizeReport';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
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';
export type { ExportPlatform };
/**
@@ -352,6 +355,12 @@ export interface ExportGameOptions {
orientation?: ScreenOrientation;
/** Per-phase progress (build log). */
onProgress?: OnExportProgress;
+ /**
+ * Where emcc is, for the step that compiles the systems a project marked
+ * `@compiled` (docs/REARCH_AOT.md). Absent ⇒ found from the environment or
+ * the repo's own submodule; a project that promised nothing never needs one.
+ */
+ emcc?: string | null;
/** Shipping config: minify the bundles, no sourcemap. Default off (dev). */
minify?: boolean;
sourcemap?: boolean;
@@ -477,6 +486,22 @@ 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';
@@ -689,6 +714,29 @@ 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.
+ 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,
+ });
+ if (!built.ok) {
+ errors.push(...built.errors);
+ return { ok: false, platform, outDir: absOut, included: cook.included.length, warnings, errors };
+ }
+ if (built.wasmPath && built.manifest) {
+ progress({ phase: 'Compiling systems', detail: `${built.manifest.systems.length} system(s)` });
+ await mkdir(path.join(payloadDir, 'aot'), { recursive: true });
+ await cp(built.wasmPath, path.join(payloadDir, 'aot', 'systems.wasm'));
+ aot = { wasm: 'aot/systems.wasm', manifest: built.manifest };
+ }
+ }
+
// 4. SDK (import-map target) + wasm runtime. The import map and the game
// host reference both unconditionally — a missing tree is not a degraded
// export but a package that cannot boot, so it fails the export.
@@ -740,6 +788,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
...(hotUpdate ? { hotUpdate } : {}),
...(sideModuleDeclarations(projectModules, platform).length > 0
? { sideModules: sideModuleDeclarations(projectModules, platform) } : {}),
+ ...(aot ? { aot } : {}),
};
await writeFile(path.join(payloadDir, 'game.config.json'), JSON.stringify(gameConfig, null, 2) + '\n');
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index 31c23d5f3..405f99fea 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -115,6 +115,14 @@ async function boot(): Promise<void> {
gl!.readPixels(0, 0, w, h, gl!.RGBA, gl!.UNSIGNED_BYTE, rgba);
return { width: w, height: h, rgba };
},
+ /**
+ * How many of this build's systems run as compiled code. Zero in an
+ * interpreted package, which is what tells the two apart from outside —
+ * the frames they produce are meant to be identical.
+ */
+ compiledSystems(): number {
+ return app.compiledSystemCount;
+ },
/**
* Where things are, for a driver that has to play rather than just look.
* Capture answers "did it draw"; walking a route needs "am I there yet",
@@ -193,10 +201,17 @@ 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 } : {}),
manifest: index.manifest,
catalog: index.catalog,
remoteRoot: cfg.hotUpdate?.remoteRoot,
diff --git a/pipeline/tests/aot-end-to-end.test.ts b/pipeline/tests/aot-end-to-end.test.ts
new file mode 100644
index 000000000..00eeda6e7
--- /dev/null
+++ b/pipeline/tests/aot-end-to-end.test.ts
@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The whole AOT road, in one test: a project's source becomes wasm, an
+ * App installs it, and the frames it produces are the frames the
+ * TypeScript produced (docs/REARCH_AOT.md).
+ *
+ * @details Every stage of this had its own gate already — the compiler against
+ * its interpreter, the module against a hand-built host, the scheduler
+ * against a closure. None of them answered the question a shipping
+ * build asks: does a project that marks a system `@compiled` end up
+ * RUNNING that system compiled, through the same doors a packaged game
+ * uses?
+ *
+ * The two worlds run the SAME module: the fixture project's file is
+ * what emcc compiled AND what the interpreted App imports. A retyped
+ * copy would only ever agree with its own mistakes.
+ *
+ * Loud skip without emsdk: a gate that never saw its subject is worse
+ * than a missing one.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { App, Schedule, type AotManifest, type ComponentDef, type SystemDef } from 'esengine';
+import type { CppRegistry, ESEngineModule } from 'esengine/wasm';
+
+import { buildCompiledSystems } from '../src/bundle/buildCompiledSystems';
+import { resolveEmcc } from '../src/bundle/emccPath';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** Inside the package, so the project's `import 'esengine'` resolves as a real one does. */
+const PROJECT = path.resolve(HERE, '..', '.aot-e2e');
+const PROBE = path.resolve(HERE, '..', '.aot-e2e-probe');
+const EMCC = resolveEmcc();
+const N = 24;
+const FRAMES = 5;
+const DT = 1 / 60;
+
+/**
+ * The project, as its author wrote it. One `@compiled` system over two script
+ * components and the clock — the shape `examples/ecs-basics` ships, minus the
+ * engine component, because an engine component's address comes from a built
+ * engine and this test is about the road, not the bridge.
+ */
+const SOURCE = `import { defineComponent, defineSystem, Query, Mut, Res, Time } from 'esengine';
+
+export const Pos = defineComponent('AotE2EPos', { x: 0, y: 0 });
+export const Mover = defineComponent('AotE2EMover', { dx: 0, dy: 0, speed: 0 });
+
+/**
+ * Moves every mover by its direction and speed, once per frame.
+ *
+ * @compiled
+ * A promise, not a hint: if the subset cannot lower this, the build fails here.
+ */
+export const moveSystem = defineSystem(
+ [Query(Mut(Pos), Mover), Res(Time)],
+ (query, time) => {
+ for (const [, pos, mover] of query) {
+ pos.x += mover.dx * mover.speed * time.delta;
+ pos.y += mover.dy * mover.speed * time.delta;
+ }
+ },
+ { name: 'AotE2EMoveSystem' },
+);
+`;
+
+/**
+ * The same project with the X step doubled (`replace` takes the first match).
+ * It is the discriminator: without a module that answers DIFFERENTLY from the
+ * closure it stands in for, this file passes with the dispatch deleted — both
+ * worlds would be interpreting, and would of course agree.
+ */
+const PROBE_SOURCE = SOURCE.replace('mover.speed * time.delta;', 'mover.speed * time.delta * 2;');
+
+/** The toolchain's runner, in miniature: emcc is a .bat on Windows. */
+const run = (cmd: string, args: string[], cwd: string): Promise<{ code: number; stderr: string }> =>
+ 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 }));
+ });
+
+/**
+ * The engine module, as far as a compiled system needs one: an allocator, a live
+ * heap view, and the memory the module imports. A bump allocator because nothing
+ * here frees, and freeing is not what is under test.
+ */
+function engineModule(): ESEngineModule {
+ const memory = new WebAssembly.Memory({ initial: 256, maximum: 256 });
+ let next = 4096;
+ const host = {
+ wasmMemory: memory,
+ get HEAPU8(): Uint8Array { return new Uint8Array(memory.buffer); },
+ _malloc(size: number): number {
+ const at = next;
+ next += (size + 15) & ~15;
+ return at;
+ },
+ _free(): void { /* a bump allocator frees nothing */ },
+ };
+ return host as unknown as ESEngineModule;
+}
+
+/**
+ * Enough of a CppRegistry to hand out entities. A packaged game has the real
+ * one; what this test is about lives entirely on the script side — the pools the
+ * rows come from and the addresses they answer with — so the registry only has
+ * to be a source of ids.
+ */
+function registry(): CppRegistry {
+ let next = 0;
+ return { create: () => ++next } as unknown as CppRegistry;
+}
+
+/** What the fixture project's module exports, as this test uses it. */
+interface Fixture {
+ Pos: ComponentDef<{ x: number; y: number }>;
+ Mover: ComponentDef<{ dx: number; dy: number; speed: number }>;
+ moveSystem: SystemDef;
+}
+
+/** One world, seeded the same way, with or without the compiled twin. */
+async function world(fixture: Fixture, module: ESEngineModule | null,
+ install?: { wasm: BufferSource; manifest: AotManifest }): Promise<{ app: App; ids: number[] }> {
+ const app = App.new();
+ if (module) app.connectCpp(registry(), module);
+ // Before any component exists — the rows a twin reads have to be in the memory
+ // it reads, and this is the only moment that is true.
+ if (install) await app.installCompiledSystems(install.wasm, install.manifest);
+
+ const ids: number[] = [];
+ for (let i = 1; i <= N; i++) {
+ const e = app.world.spawn();
+ app.world.insert(e, fixture.Pos, { x: i, y: -i });
+ app.world.insert(e, fixture.Mover, { dx: 1, dy: -0.5, speed: i * 3 });
+ ids.push(e as unknown as number);
+ }
+ app.addSystemToSchedule(Schedule.Update, fixture.moveSystem);
+ return { app, ids };
+}
+
+const positions = (app: App, fixture: Fixture, ids: number[]): number[] =>
+ ids.flatMap((id) => {
+ const p = app.world.get(id as never, fixture.Pos);
+ return [p.x, p.y];
+ });
+
+describe('a project that promised compilation gets it', () => {
+ let built: Awaited<ReturnType<typeof buildCompiledSystems>>;
+ let fixture: Fixture;
+ let wasm: Uint8Array<ArrayBuffer>;
+ let probe: Awaited<ReturnType<typeof buildCompiledSystems>>;
+ let probeWasm: Uint8Array<ArrayBuffer>;
+
+ beforeAll(async () => {
+ if (!EMCC) return;
+ rmSync(PROJECT, { recursive: true, force: true });
+ mkdirSync(path.join(PROJECT, 'src'), { recursive: true });
+ writeFileSync(path.join(PROJECT, 'src', 'move.ts'), SOURCE);
+ built = await buildCompiledSystems(PROJECT, { mode: 'release', emcc: EMCC, run });
+ if (built.wasmPath) wasm = Uint8Array.from(readFileSync(built.wasmPath));
+ // The same file the compiler read, as the runtime's own definitions — not a
+ // second copy that would only ever agree with its own mistakes.
+ fixture = await import(/* @vite-ignore */
+ pathToFileURL(path.join(PROJECT, 'src', 'move.ts')).href) as unknown as Fixture;
+
+ rmSync(PROBE, { recursive: true, force: true });
+ mkdirSync(path.join(PROBE, 'src'), { recursive: true });
+ writeFileSync(path.join(PROBE, 'src', 'move.ts'), PROBE_SOURCE);
+ probe = await buildCompiledSystems(PROBE, { mode: 'release', emcc: EMCC, run });
+ if (probe.wasmPath) probeWasm = Uint8Array.from(readFileSync(probe.wasmPath));
+ }, 180_000);
+
+ it('reports whether this gate could run at all', () => {
+ if (EMCC) console.log(`[aot-e2e] emcc at ${EMCC}`);
+ else console.warn('[aot-e2e] NO EMSDK — the end-to-end road did NOT run (pnpm emsdk:setup).');
+ expect(true).toBe(true);
+ });
+
+ it.skipIf(!EMCC)('builds the promised system and nothing else', () => {
+ expect(built.errors.join('; ')).toBe('');
+ expect(built.manifest?.systems.map((s) => s.name)).toEqual(['AotE2EMoveSystem']);
+ });
+
+ it.skipIf(!EMCC)('is what the runner calls — the module, not the closure', async () => {
+ // A world that shows the probe's doubled X ran the compiled code; one that
+ // shows the TypeScript's answer is a world where the install did nothing and
+ // nobody noticed.
+ const twin = await world(fixture, engineModule(), { wasm: probeWasm, manifest: probe.manifest! });
+ const interpreted = await world(fixture, null);
+ for (let f = 0; f < FRAMES; f++) {
+ await twin.app.tick(DT);
+ await interpreted.app.tick(DT);
+ }
+ const movedX = (w: { app: App; ids: number[] }, i: number): number =>
+ w.app.world.get(w.ids[i] as never, fixture.Pos).x - (i + 1);
+ const y = (w: { app: App; ids: number[] }, i: number): number =>
+ w.app.world.get(w.ids[i] as never, fixture.Pos).y;
+ for (let i = 0; i < N; i++) {
+ expect(movedX(interpreted, i)).toBeGreaterThan(0);
+ expect(movedX(twin, i)).toBeCloseTo(2 * movedX(interpreted, i), 10);
+ // Y is the line the probe did NOT touch: it agrees, so what ran was this
+ // module and not just anything that moves things.
+ expect(y(twin, i)).toBeCloseTo(y(interpreted, i), 10);
+ }
+ }, 60_000);
+
+ it.skipIf(!EMCC)('installs it, and the frames agree with the TypeScript', async () => {
+ const compiled = await world(fixture, engineModule(), { wasm, manifest: built.manifest! });
+ const interpreted = await world(fixture, null);
+ for (let f = 0; f < FRAMES; f++) {
+ await compiled.app.tick(DT);
+ await interpreted.app.tick(DT);
+ }
+
+ expect(positions(compiled.app, fixture, compiled.ids))
+ .toEqual(positions(interpreted.app, fixture, interpreted.ids));
+ // Two untouched worlds agree too. The clock has to have reached the compiled
+ // code for the agreement above to mean anything.
+ expect(compiled.app.world.get(compiled.ids[0] as never, fixture.Pos).x).toBeGreaterThan(1);
+ }, 60_000);
+
+ it.skipIf(!EMCC)('refuses a module built for other component shapes', async () => {
+ const app = App.new();
+ app.connectCpp(registry(), engineModule());
+ await expect(app.installCompiledSystems(wasm, {
+ ...built.manifest!, projectShapes: 'deadbeefdeadbeef',
+ })).rejects.toThrow(/Rebuild the project/);
+ });
+
+ it.skipIf(!EMCC)('refuses an engine that does not hand out its memory', async () => {
+ const app = App.new();
+ const module = engineModule() as unknown as { wasmMemory?: WebAssembly.Memory };
+ delete module.wasmMemory;
+ app.connectCpp(registry(), module as unknown as ESEngineModule);
+ await expect(app.installCompiledSystems(wasm, built.manifest!))
+ .rejects.toThrow(/wasmMemory/);
+ });
+});
diff --git a/pipeline/tests/cooked-verify-fixture.test.ts b/pipeline/tests/cooked-verify-fixture.test.ts
index ddfc1c8a6..67d1dbefc 100644
--- a/pipeline/tests/cooked-verify-fixture.test.ts
+++ b/pipeline/tests/cooked-verify-fixture.test.ts
@@ -41,6 +41,35 @@ void main() { fragColor = u_tint; }
#pragma end
`;
+/**
+ * The project's own code: one component, one system, and the promise that the
+ * system compiles. `Transform` is an ENGINE component, so the compiled code
+ * reads it at the offsets EHT generated, in the memory the engine already owns.
+ */
+const PROJECT_SCRIPTS = `import {
+ addSystem, defineComponent, defineSystem, Query, Mut, Res, Time, Transform,
+} from 'esengine';
+
+export const Drifter = defineComponent('Drifter', { speed: 0 });
+
+/**
+ * @compiled
+ * A promise, not a hint: what the subset cannot lower fails the export here
+ * rather than falling back to the interpreter with nothing to see.
+ */
+export const driftSystem = defineSystem(
+ [Query(Mut(Transform), Drifter), Res(Time)],
+ (query, time) => {
+ for (const [, transform, drifter] of query) {
+ transform.position.x += drifter.speed * time.delta;
+ }
+ },
+ { name: 'CookedDrift' },
+);
+
+addSystem(driftSystem);
+`;
+
describe.skipIf(!process.env.ESTELLA_COOK_FIXTURE)('cooked-verify fixture', () => {
it('cooks a content-addressed build: green KTX2 sprite + path-ref material chain', async () => {
rmSync(SRC, { recursive: true, force: true });
@@ -73,12 +102,21 @@ describe.skipIf(!process.env.ESTELLA_COOK_FIXTURE)('cooked-verify fixture', () =
{ type: 'Transform', data: { position: { x: 150, y: 0, z: 0 } } },
{ type: 'Sprite', data: { size: { x: 250, y: 250 }, color: { r: 1, g: 1, b: 1, a: 1 }, material: 'assets/red.esmaterial' } },
] },
+ // Nothing draws this one. It exists so the compiled system has a real
+ // engine component to move, and the driver a number to read.
+ { id: 3, name: 'Drifter', parent: null, children: [], visible: true, components: [
+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 0 } } },
+ { type: 'Drifter', data: { speed: 100 } },
+ ] },
],
}));
writeFileSync(path.join(SRC, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
mkdirSync(path.join(SRC, 'src'), { recursive: true });
- writeFileSync(path.join(SRC, 'src', 'main.ts'), 'export {};\n');
+ // A `@compiled` system, so this build also proves the AOT road end to end
+ // (docs/REARCH_AOT.md §9). What it moves carries no Sprite, so the pixel
+ // claims below keep sampling the same two quads.
+ writeFileSync(path.join(SRC, 'src', 'main.ts'), PROJECT_SCRIPTS);
const res = await exportGame({
root: SRC,
diff --git a/pipeline/tests/export-compiled-systems.test.ts b/pipeline/tests/export-compiled-systems.test.ts
new file mode 100644
index 000000000..053809c94
--- /dev/null
+++ b/pipeline/tests/export-compiled-systems.test.ts
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What a package carries for the systems a project marked `@compiled`.
+ *
+ * @details `build-compiled-systems.test.ts` proves the compile; this proves the
+ * EXPORT — that the module is staged where the runtime looks and named
+ * in `game.config.json`, because a module nothing points at is a module
+ * nothing loads, and the game would interpret with no sign anything
+ * went wrong (docs/REARCH_AOT.md §9).
+ *
+ * Stub sdk/wasm trees, like the other export tests: what is under test
+ * is the package's shape, not the engine in it.
+ */
+import { describe, it, expect } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { PackagedGameConfig } from 'esengine';
+import { exportGame } from '../src/export/exportGame';
+import { resolveEmcc } from '../src/bundle/emccPath';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const GAME_HOST = path.join(HERE, '..', 'src', 'runtime', 'gameHost.ts');
+const SCN = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
+const EMCC = resolveEmcc();
+
+/** A system the subset lowers, and its author says so. */
+const PROMISED = `import { defineComponent, defineSystem, Query, Mut } from 'esengine';
+
+export const Drift = defineComponent('ExportDrift', { x: 0, step: 0.5 });
+
+/**
+ * @compiled
+ */
+export const driftSystem = defineSystem(
+ [Query(Mut(Drift))],
+ (query) => {
+ for (const [, drift] of query) {
+ drift.x += drift.step;
+ }
+ },
+ { name: 'ExportDriftSystem' },
+);
+`;
+
+/** The same promise over something the subset refuses: a call it cannot lower. */
+const BROKEN = PROMISED.replace('drift.x += drift.step;', 'drift.x += Math.random();');
+
+/** A project with no marker at all — the state every project starts in. */
+const UNMARKED = PROMISED.replace(/\n \* @compiled\n/, '\n');
+
+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 });
+ writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({
+ version: '1.0', name: 'Main', entities: [{ id: 0, components: [{ type: 'Sprite', data: {} }] }],
+ }));
+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'),
+ JSON.stringify({ uuid: SCN, version: '2.0', type: 'scene', importer: {} }));
+
+ mkdirSync(path.join(root, 'src'), { recursive: true });
+ writeFileSync(path.join(root, 'src', 'main.ts'), source ?? 'export {};\n');
+
+ mkdirSync(path.join(root, '_sdk'), { recursive: true });
+ writeFileSync(path.join(root, '_sdk', 'index.js'), 'export const x = 1;');
+ mkdirSync(path.join(root, '_wasm'), { recursive: true });
+ writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'export default () => {};');
+ writeFileSync(path.join(root, '_wasm', 'esengine.wasm'), 'ENGINE');
+ writeFileSync(path.join(root, '_wasm', 'wasm.manifest.json'), JSON.stringify({ schema: 1 }));
+ return { root, out: path.join(root, 'dist') };
+}
+
+const run = (f: { root: string; out: string }) => exportGame({
+ root: f.root, entryScene: 'scenes/main.esscene', gameHostEntry: GAME_HOST,
+ scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(f.root, '_sdk'), wasmDir: path.join(f.root, '_wasm'),
+ outDir: f.out,
+});
+
+const config = (out: string): PackagedGameConfig =>
+ JSON.parse(readFileSync(path.join(out, 'game.config.json'), 'utf8')) as PackagedGameConfig;
+
+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}`);
+ else console.warn('[aot-export] NO EMSDK — the staged module was NOT built (pnpm emsdk:setup).');
+ expect(true).toBe(true);
+ });
+
+ it.skipIf(!EMCC)('stages the module and names it in the config', async () => {
+ const f = project(PROMISED);
+ try {
+ const res = await run(f);
+ expect(res.errors).toEqual([]);
+ const cfg = config(f.out);
+ expect(cfg.aot?.wasm).toBe('aot/systems.wasm');
+ // The path in the config is the path in the package, or the runtime 404s
+ // at boot and falls back to interpreting with nothing to see.
+ expect(existsSync(path.join(f.out, cfg.aot!.wasm))).toBe(true);
+ expect(cfg.aot?.manifest.systems.map((s) => s.name)).toEqual(['ExportDriftSystem']);
+ expect(cfg.aot?.manifest.engineAbi).toMatch(/^[0-9a-f]{16}$/);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 120_000);
+
+ it.skipIf(!EMCC)('fails the export when a promise cannot be kept, and says where', async () => {
+ const f = project(BROKEN);
+ try {
+ const res = await run(f);
+ expect(res.ok).toBe(false);
+ expect(res.errors.join('\n')).toMatch(/main\.ts:\d+:.*ExportDriftSystem is @compiled/);
+ expect(existsSync(path.join(f.out, 'aot', 'systems.wasm'))).toBe(false);
+ } 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 {
+ const res = await run(f);
+ expect(res.errors).toEqual([]);
+ // Not an empty module and not an empty key: a project that never asked for
+ // this pays nothing for it, on a machine that may have no toolchain at all.
+ expect(config(f.out).aot).toBeUndefined();
+ expect(existsSync(path.join(f.out, 'aot'))).toBe(false);
+ } finally { rmSync(f.root, { recursive: true, force: true }); }
+ }, 120_000);
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d8362928a..8987c34e4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -165,6 +165,9 @@ importers:
pngjs:
specifier: ^7.0.0
version: 7.0.0
+ typescript:
+ specifier: ^6.0.3
+ version: 6.0.3
wasm-media-encoders:
specifier: ^0.7.0
version: 0.7.0
@@ -175,9 +178,6 @@ importers:
'@types/pngjs':
specifier: ^6.0.5
version: 6.0.5
- typescript:
- specifier: ^6.0.3
- version: 6.0.3
vitest:
specifier: ^2.1.9
@@ -4647,14 +4647,6 @@ snapshots:
chai: 5.3.3
tinyrainbow: 1.2.0
- dependencies:
- '@vitest/spy': 2.1.9
- estree-walker: 3.0.3
- magic-string: 0.30.21
- optionalDependencies:
-
dependencies:
'@vitest/spy': 2.1.9
@@ -4691,7 +4683,7 @@ snapshots:
sirv: 3.0.2
tinyglobby: 0.2.15
tinyrainbow: 1.2.0
'@vitest/[email protected]':
dependencies:
@@ -7160,7 +7152,7 @@ snapshots:
dependencies:
'@vitest/expect': 2.1.9
'@vitest/pretty-format': 2.1.9
'@vitest/runner': 2.1.9
'@vitest/snapshot': 2.1.9
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 2d147257f..88791666b 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 64 beta · 1512 experimental · 3 deprecated
+Symbols: 113 public · 64 beta · 1514 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -510,6 +510,21 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotManifest — interface @experimental
+```
+engineAbi: string
+projectShapes: string
+systems: readonly AotSystemDecl[]
+```
+
+## AotSystemDecl — interface @experimental
+```
+name: string
+queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+resources: readonly string[]
+symbol: string
+```
+
## App — class @experimental
```
@internal addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
@@ -523,6 +538,7 @@ addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+compiledSystemCount: number
enableStats: () => App
getEntityCount: () => number
getFixedTimestep: () => number
@@ -540,6 +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>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5073,6 +5090,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6581,6 +6599,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: 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 f5f898af8..7027a1491 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 69 beta · 1531 experimental · 3 deprecated
+Symbols: 113 public · 69 beta · 1533 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -510,6 +510,21 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotManifest — interface @experimental
+```
+engineAbi: string
+projectShapes: string
+systems: readonly AotSystemDecl[]
+```
+
+## AotSystemDecl — interface @experimental
+```
+name: string
+queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+resources: readonly string[]
+symbol: string
+```
+
## App — class @experimental
```
@internal addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
@@ -523,6 +538,7 @@ addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+compiledSystemCount: number
enableStats: () => App
getEntityCount: () => number
getFixedTimestep: () => number
@@ -540,6 +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>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5256,6 +5273,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6774,6 +6792,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: 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 e2fa112ab..a6f0aa621 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1511 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1513 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -505,6 +505,21 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotManifest — interface @experimental
+```
+engineAbi: string
+projectShapes: string
+systems: readonly AotSystemDecl[]
+```
+
+## AotSystemDecl — interface @experimental
+```
+name: string
+queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+resources: readonly string[]
+symbol: string
+```
+
## App — class @experimental
```
@internal addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
@@ -518,6 +533,7 @@ addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+compiledSystemCount: number
enableStats: () => App
getEntityCount: () => number
getFixedTimestep: () => number
@@ -535,6 +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>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5068,6 +5085,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6576,6 +6594,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: 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 cfdd88551..700ddf732 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 64 beta · 1533 experimental · 3 deprecated
+Symbols: 113 public · 64 beta · 1535 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -505,6 +505,21 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotManifest — interface @experimental
+```
+engineAbi: string
+projectShapes: string
+systems: readonly AotSystemDecl[]
+```
+
+## AotSystemDecl — interface @experimental
+```
+name: string
+queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+resources: readonly string[]
+symbol: string
+```
+
## App — class @experimental
```
@internal addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
@@ -518,6 +533,7 @@ addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+compiledSystemCount: number
enableStats: () => App
getEntityCount: () => number
getFixedTimestep: () => number
@@ -535,6 +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>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5313,6 +5330,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6821,6 +6839,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 0be1d3c1c..97ff99573 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -423,6 +423,7 @@ uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
ui_getCullBit: ((registry: CppRegistry, entity: number) => number) | undefined
ui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined
+wasmMemory: WebAssembly.Memory | undefined
```
## EmscriptenFS — interface @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 46297af9c..4e7a4e1c1 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 64 beta · 1523 experimental · 3 deprecated
+Symbols: 113 public · 64 beta · 1525 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -505,6 +505,21 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotManifest — interface @experimental
+```
+engineAbi: string
+projectShapes: string
+systems: readonly AotSystemDecl[]
+```
+
+## AotSystemDecl — interface @experimental
+```
+name: string
+queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+resources: readonly string[]
+symbol: string
+```
+
## App — class @experimental
```
@internal addBundleSystems: (entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet; }>) => App
@@ -518,6 +533,7 @@ addSystem: (system: SystemDef) => App
addSystemSet: (set: SystemSet) => App
addSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => App
addSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App
+compiledSystemCount: number
enableStats: () => App
getEntityCount: () => number
getFixedTimestep: () => number
@@ -535,6 +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>
isPaused: () => boolean
isPhysicsReady: boolean
measureFrameScope: <T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder; }) => T
@@ -5075,6 +5092,7 @@ decodePixels: ((path: string, flip: boolean) => Promise<{ width: number; height:
## PackagedGameConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: string; manifest: AotManifest; } | undefined
audioConfig: AudioProjectConfig | undefined
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
@@ -6583,6 +6601,7 @@ textureCacheBudget: number | undefined
## RuntimeInitConfig — interface @experimental
```
achievements: string[] | undefined
+aot: { wasm: BufferSource; manifest: AotManifest; } | undefined
app: App
aspectRatio: number | undefined
audioConfig: AudioProjectConfig | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index c35adf6da..746d95c94 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -17,6 +17,9 @@ import { inputPlugin, Input } from '../input/input';
import { assetPlugin } from '../asset';
import { prefabsPlugin } from '../prefab/prefabServer';
import { setWasmErrorHandler } from '../wasm/wasmError';
+import { installAot, type AotHost } from '../ecs/aot/installAot';
+import type { AotRuntime } from '../ecs/aot/AotRuntime';
+import type { AotManifest } from '../ecs/aot/AotSystems';
import { corePlugin, DEFAULT_UI_CAMERA_INFO } from './corePlugin';
import {
ancestors,
@@ -126,6 +129,12 @@ export class App {
private readonly resources_: ResourceStorage;
private readonly systems_ = new Map<Schedule, SystemEntry[]>();
private runner_: SystemRunner | null = null;
+ /** Whether the once-per-app boot work has run. Not `runner_ !== null`: a
+ * compiled-systems install needs the runner BEFORE the first tick, and
+ * reading the boot from its existence would then skip that work forever. */
+ private booted_ = false;
+ /** The compiled twins a build installed, or null where it made none. */
+ private aot_: AotRuntime | null = null;
private systemCounter_ = 0;
private readonly templateToRuntime_ = new Map<symbol, symbol>();
/** Set name -> runtime system names registered under that set, for dep expansion. */
@@ -819,21 +828,63 @@ export class App {
return this;
}
+ // =========================================================================
+ // Compiled systems (AOT)
+ // =========================================================================
+
+ /**
+ * How many compiled twins this App runs. Zero unless a build installed some,
+ * which is the whole of the mode policy — and the one number that tells a
+ * shipped AOT build apart from a shipped interpreted one from outside.
+ */
+ get compiledSystemCount(): number {
+ return this.aot_?.systems.size ?? 0;
+ }
+
+ /**
+ * Install the compiled twins a build produced, and answer how many
+ * (docs/REARCH_AOT.md §9). Call it BEFORE any component exists — a twin reads
+ * 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> {
+ const module = this.module_;
+ if (!module) {
+ throw new Error('installCompiledSystems: this App has no engine module, and a compiled '
+ + 'system reads the memory of one');
+ }
+ const memory = module.wasmMemory;
+ if (!memory) {
+ throw new Error('installCompiledSystems: this engine artifact does not export '
+ + "'wasmMemory', so there is no memory for the module to import — rebuild the engine");
+ }
+ // Read through to the module rather than captured: emscripten REPLACES
+ // the heap view when the heap grows, and a snapshot taken here would be
+ // detached by the first allocation that grows it.
+ const host: AotHost = {
+ memory,
+ _malloc: (size: number) => module._malloc(size),
+ _free: (ptr: number) => module._free(ptr),
+ get HEAPU8(): Uint8Array { return module.HEAPU8; },
+ };
+ this.aot_ = await installAot({
+ world: this.world_,
+ runner: this.ensureRunner_(),
+ host,
+ manifest,
+ wasm,
+ resources: (name: string) => this.getResourceByName(name) as
+ Readonly<Record<string, unknown>> | undefined,
+ });
+ return this.aot_.systems.size;
+ }
+
// =========================================================================
// Run
// =========================================================================
async tick(delta: number): Promise<void> {
- if (!this.runner_) {
- this.runner_ = new SystemRunner(this.world_, this.resources_, this.eventRegistry_);
- if (this.statsEnabled_) {
- this.runner_.setTimingEnabled(true);
- }
- if (!this.resources_.has(Time)) {
- this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });
- }
- this.finishPlugins_();
- }
+ this.boot_();
await this.flushStartupSystems_();
await this.runFrame_(delta);
@@ -884,16 +935,7 @@ export class App {
}
this.running_ = true;
- if (!this.runner_) {
- this.runner_ = new SystemRunner(this.world_, this.resources_, this.eventRegistry_);
- if (this.statsEnabled_) {
- this.runner_.setTimingEnabled(true);
- }
- if (!this.resources_.has(Time)) {
- this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });
- }
- this.finishPlugins_();
- }
+ this.boot_();
await this.flushStartupSystems_();
this.lastTime_ = platformNow();
@@ -951,6 +993,8 @@ export class App {
this.pipeline_ = null;
this.runner_ = null;
+ this.booted_ = false;
+ this.aot_ = null;
// Tear down the C++ engine context too: previously quit() only cleared
// JS state and dropped the module reference, so the EstellaContext was
// never shut down — it leaked its GPU subsystems + WebGL context, and a
@@ -969,6 +1013,34 @@ export class App {
// Internal
// =========================================================================
+ /**
+ * The runner, made on demand. Making one is free and decides nothing — what
+ * has to happen exactly once before a frame is in `boot_`, so a caller that
+ * needs the runner early (a compiled-systems install) does not consume the
+ * boot by asking.
+ */
+ private ensureRunner_(): SystemRunner {
+ if (!this.runner_) {
+ this.runner_ = new SystemRunner(this.world_, this.resources_, this.eventRegistry_);
+ if (this.statsEnabled_) {
+ this.runner_.setTimingEnabled(true);
+ }
+ }
+ return this.runner_;
+ }
+
+ /** Once per app, on the way into the first frame: the clock every system
+ * reads, and the plugins' last chance to add one. */
+ private boot_(): void {
+ this.ensureRunner_();
+ if (this.booted_) return;
+ this.booted_ = true;
+ if (!this.resources_.has(Time)) {
+ this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });
+ }
+ this.finishPlugins_();
+ }
+
private async runFrame_(delta: number): Promise<void> {
this.runner_?.clearTimings();
this.phaseTimings_?.clear();
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 926b50ae4..43e530898 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -436,6 +436,17 @@ export {
type BehaviorContext,
} from './behavior';
+// =============================================================================
+// Compiled systems (AOT)
+// =============================================================================
+
+/**
+ * What a build wrote beside a compiled-systems module: which twins it holds, and
+ * the two digests that say what it was built against. A packaged runtime reads
+ * one and hands it to `App.installCompiledSystems` (docs/REARCH_AOT.md).
+ */
+export type { AotManifest, AotSystemDecl } from './ecs/aot/AotSystems';
+
// =============================================================================
// World
// =============================================================================
diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.ts
index aaa73d053..f5f1d58f9 100644
--- a/sdk/src/runtime/packagedRuntime.ts
+++ b/sdk/src/runtime/packagedRuntime.ts
@@ -27,6 +27,7 @@ import { VideoPlayer } from '../video/VideoAPI';
import type { App } from '../app/app';
import type { RuntimeAssetSource } from './runtimeAssets';
import { registerSideModule } from '../sideModules/registry';
+import type { AotManifest } from '../ecs/aot/AotSystems';
/**
* `game.config.json` — what an export bakes about the project, and the contract
@@ -87,6 +88,13 @@ export interface PackagedGameConfig {
* says so, and every transport resolves these ids exactly like a built-in.
*/
sideModules?: Array<{ id: string; file: string; globalName?: string }>;
+ /**
+ * The compiled twins this build produced (docs/REARCH_AOT.md). `wasm` is
+ * package-relative; the manifest rides here so there is not a second file to
+ * keep in step. Absent unless the project marked something `@compiled`, so a
+ * runtime reads presence and needs no mode flag.
+ */
+ aot?: { wasm: string; manifest: AotManifest };
}
/** The packaged realm's resolved asset index — manifest, catalog, resolution. */
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index f70597f73..4edaf0af4 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -40,6 +40,7 @@ import { flushPendingRegistrations } from '../app/app';
import { installHotUpdateRebind } from '../hotUpdateRebind';
import { requireResourceManager } from '../wasm/resourceManager';
import { log } from '../util/logger';
+import type { AotManifest } from '../ecs/aot/AotSystems';
import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';
import { loadSpineAssets, applySpineEntities, type SpineAssetInfo } from '../spine/loadSpineScene';
import { DragonBonesPlugin } from '../dragonbones/DragonBonesPlugin';
@@ -568,6 +569,13 @@ export interface RuntimeInitConfig {
* it answer for achievements. Absent or unavailable keeps the local one. */
steamAppId?: number;
aspectRatio?: number;
+ /**
+ * The compiled twins a build produced (docs/REARCH_AOT.md): bytes, because
+ * fetching them is the transport's job — http here, `wx` there. Installed
+ * 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 };
}
export async function initRuntime(config: RuntimeInitConfig): Promise<void> {
@@ -575,6 +583,14 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {
flushPendingRegistrations(app);
+ // After the project's components are registered (the manifest names them)
+ // and before any exists (its rows must be in the memory the module reads).
+ // A module that disagrees with this engine or project throws here.
+ if (config.aot) {
+ const installed = await app.installCompiledSystems(config.aot.wasm, config.aot.manifest);
+ log.info('runtime', `AOT: ${installed} compiled system(s) installed`);
+ }
+
// Install the per-App runtime Assets up front (scene loads reuse it) and
// hand it the manifest so on-demand loadGroup works from the first frame.
// The catalog rides the same first-creation moment (later ensure calls
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 02d3379d0..fdcb2a05a 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -157,6 +157,13 @@ export interface ESEngineModule {
HEAPU8: Uint8Array;
HEAPU32: Uint32Array;
HEAPF32: Float32Array;
+ /**
+ * The module's own linear memory, which a compiled system module IMPORTS
+ * rather than owning a second (docs/REARCH_AOT.md §6.1) — and only a
+ * `Memory` can be imported, a heap view's `buffer` cannot become one again.
+ * Optional because an artifact built before the link flag carries none.
+ */
+ wasmMemory?: WebAssembly.Memory;
FS: EmscriptenFS;
diff --git a/tools/launchers/headless-cooked-verify.mjs b/tools/launchers/headless-cooked-verify.mjs
index e59c64b22..f899f82a7 100644
--- a/tools/launchers/headless-cooked-verify.mjs
+++ b/tools/launchers/headless-cooked-verify.mjs
@@ -71,6 +71,17 @@ app.whenReady().then(async () => {
return { w, h, left: at(0.3, 0.5), right: at(0.7, 0.5), corner: at(0.04, 0.04) };
})()`);
+ // The AOT road in the shipped runtime: the module installed, and the entity
+ // only a compiled system touches is moving. Nothing draws it, so this claim
+ // and the pixel ones stay independent.
+ const compiledSystems = await exec('window.__estellaCooked.compiledSystems()');
+ const first = await exec("window.__estellaCooked.probe(['Drifter']).at.Drifter");
+ await sleep(500);
+ const second = await exec("window.__estellaCooked.probe(['Drifter']).at.Drifter");
+ // 100 units a second, so half a second is about 50. Twenty is clear of a
+ // stutter and nowhere near what a still entity would report.
+ const aotOk = compiledSystems >= 1 && !!first && !!second && second.x - first.x > 20;
+
// Left quad = the KTX2 texture (green); right quad = the PATH-referenced
// material chain (its shader paints u_tint red) — proving the cooked
// logical→staged resolution end to end, not just uuid refs.
@@ -79,9 +90,13 @@ app.whenReady().then(async () => {
const [rr, rg, rb] = cap.right;
const redOk = rr >= 180 && rg <= 70 && rb <= 70;
const cornerBlack = cap.corner[0] <= 40 && cap.corner[1] <= 40 && cap.corner[2] <= 40;
- const ok = greenOk && redOk && cornerBlack;
+ const ok = greenOk && redOk && cornerBlack && aotOk;
console.log(`\n[verify:render:cooked] ${ok ? 'PASS' : 'FAIL'}`);
- console.log('DRIVE_RESULT ' + JSON.stringify({ ...cap, greenOk, redOk, cornerBlack, diag: diag.slice(0, 6) }));
+ console.log('DRIVE_RESULT ' + JSON.stringify({
+ ...cap, greenOk, redOk, cornerBlack,
+ aotOk, compiledSystems, drift: [first?.x ?? null, second?.x ?? null],
+ diag: diag.slice(0, 6),
+ }));
failed = !ok;
} catch (e) {
console.log('\n[verify:render:cooked] FAIL — ' + (e?.message ?? e));