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 packaged game runs its compiled systems
yhh9c05c19aa003
diff --git a/.gitignore b/.gitignoreindex 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.cmakeindex 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-sectionsdiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.mjsindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.yamlindex d8362928a..8987c34e4 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -165,6 +165,9 @@ importers:pngjs:specifier: ^7.0.0version: 7.0.0+ typescript:+ specifier: ^6.0.3+ version: 6.0.3wasm-media-encoders:specifier: ^0.7.0version: 0.7.0@@ -175,9 +178,6 @@ importers:'@types/pngjs':specifier: ^6.0.5version: 6.0.5- typescript:- specifier: ^6.0.3- version: 6.0.3vitest:specifier: ^2.1.9version: 2.1.9(@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected])@@ -4647,14 +4647,6 @@ snapshots:chai: 5.3.3tinyrainbow: 1.2.0- '@vitest/[email protected]([email protected](@types/[email protected])([email protected])([email protected]))':- dependencies:- '@vitest/spy': 2.1.9- estree-walker: 3.0.3- magic-string: 0.30.21- optionalDependencies:-'@vitest/[email protected]([email protected](@types/[email protected])([email protected])([email protected]))':dependencies:'@vitest/spy': 2.1.9@@ -4691,7 +4683,7 @@ snapshots:sirv: 3.0.2tinyglobby: 0.2.15tinyrainbow: 1.2.0- vitest: 2.1.9(@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected])+ vitest: 2.1.9(@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected])'@vitest/[email protected]':dependencies:@@ -7160,7 +7152,7 @@ snapshots:[email protected](@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected]):dependencies:'@vitest/expect': 2.1.9- '@vitest/mocker': 2.1.9([email protected](@types/[email protected])([email protected])([email protected]))+ '@vitest/mocker': 2.1.9([email protected](@types/[email protected])([email protected])([email protected]))'@vitest/pretty-format': 2.1.9'@vitest/runner': 2.1.9'@vitest/snapshot': 2.1.9diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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: stringComponentDef<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) => AppaddSystemSet: (set: SystemSet) => AppaddSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => AppaddSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App+compiledSystemCount: numberenableStats: () => AppgetEntityCount: () => numbergetFixedTimestep: () => number@@ -540,6 +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>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedaudioConfig: AudioProjectConfig | undefinedcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefined@@ -6581,6 +6599,7 @@ textureCacheBudget: number | undefined## RuntimeInitConfig — interface @experimental```achievements: string[] | undefined+aot: { wasm: BufferSource; manifest: AotManifest; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: stringComponentDef<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) => AppaddSystemSet: (set: SystemSet) => AppaddSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => AppaddSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App+compiledSystemCount: numberenableStats: () => AppgetEntityCount: () => numbergetFixedTimestep: () => number@@ -540,6 +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>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedaudioConfig: AudioProjectConfig | undefinedcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefined@@ -6774,6 +6792,7 @@ textureCacheBudget: number | undefined## RuntimeInitConfig — interface @experimental```achievements: string[] | undefined+aot: { wasm: BufferSource; manifest: AotManifest; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: stringComponentDef<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) => AppaddSystemSet: (set: SystemSet) => AppaddSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => AppaddSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App+compiledSystemCount: numberenableStats: () => AppgetEntityCount: () => numbergetFixedTimestep: () => number@@ -535,6 +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>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedaudioConfig: AudioProjectConfig | undefinedcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefined@@ -6576,6 +6594,7 @@ textureCacheBudget: number | undefined## RuntimeInitConfig — interface @experimental```achievements: string[] | undefined+aot: { wasm: BufferSource; manifest: AotManifest; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: stringComponentDef<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) => AppaddSystemSet: (set: SystemSet) => AppaddSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => AppaddSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App+compiledSystemCount: numberenableStats: () => AppgetEntityCount: () => numbergetFixedTimestep: () => number@@ -535,6 +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>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedaudioConfig: AudioProjectConfig | undefinedcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefined@@ -6821,6 +6839,7 @@ textureCacheBudget: number | undefined## RuntimeInitConfig — interface @experimental```achievements: string[] | undefined+aot: { wasm: BufferSource; manifest: AotManifest; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => numberuiRenderOrder_update: (registry: CppRegistry) => voidui_getCullBit: ((registry: CppRegistry, entity: number) => number) | undefinedui_getRenderOrder: ((registry: CppRegistry, entity: number) => number) | undefined+wasmMemory: WebAssembly.Memory | undefined```## EmscriptenFS — interface @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: stringComponentDef<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) => AppaddSystemSet: (set: SystemSet) => AppaddSystemSetToSchedule: (schedule: Schedule, set: SystemSet) => AppaddSystemToSchedule: (schedule: Schedule, system: SystemDef, options?: { runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; }) => App+compiledSystemCount: numberenableStats: () => AppgetEntityCount: () => numbergetFixedTimestep: () => number@@ -535,6 +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>isPaused: () => booleanisPhysicsReady: booleanmeasureFrameScope: <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; } | undefinedaudioConfig: AudioProjectConfig | undefinedcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefined@@ -6583,6 +6601,7 @@ textureCacheBudget: number | undefined## RuntimeInitConfig — interface @experimental```achievements: string[] | undefined+aot: { wasm: BufferSource; manifest: AotManifest; } | undefinedapp: AppaspectRatio: number | undefinedaudioConfig: AudioProjectConfig | undefineddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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.tsindex 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.tsindex 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 callsdiff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 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.mjsindex 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));