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): an exported game ships the systems it promised, and runs them
esenginedf8c1cf9826e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 401c7917a..aff67949b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,28 @@ published separately; it ships inside the editor.### Added+- **A system can promise to compile, and a shipped build keeps it.** Mark one+ `@compiled` in its JSDoc and the export lowers it to C, builds it with emcc,+ and ships a few-hundred-byte wasm module beside the bundle; the scheduler then+ calls that instead of the closure. The module imports the ENGINE's memory+ rather than owning one, so the engine wasm stays prebuilt and there is nothing+ to link — it reads the components where they already are.++ The marker is a promise, not a hint: in a `release` or `ship` export, anything+ the subset cannot lower is a build error naming the file and the line. A `dev`+ export never compiles, so the editor's preview keeps interpreting and a machine+ with no emsdk builds and runs every project. A project that marks nothing is+ unaffected — no toolchain, no build step, no file.++ Loading refuses rather than degrades. A module built against other engine+ offsets, or other `defineComponent` shapes, does not produce a wrong answer —+ it reads a different field — so the two digests it carries are checked before+ anything is registered, and the message says which one moved: rebuild the+ module, or rebuild the project.++ Hosts embedding the runtime themselves can do the same through+ `App.useCompiledSystems` (`@experimental`).+- **A playable ad now fits the networks it is made for.** The single-filetransport inlined its engine as plain base64 — a +33% tax on a payload that ismostly a 1.5MB wasm — and never minified the bundle, because the CLI had nodiff --git a/pipeline/src/bundle/aotArtifacts.ts b/pipeline/src/bundle/aotArtifacts.tsnew file mode 100644index 000000000..fd7d83eab--- /dev/null+++ b/pipeline/src/bundle/aotArtifacts.ts@@ -0,0 +1,16 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file aotArtifacts.ts+ * @brief What the AOT step's two files are called, for both ends of the wire.+ *+ * @details The export writes them and the game host fetches them, and a name+ * written twice fails in the worst way available: the fetch 404s, no+ * twin is installed, and the game runs the interpreter at full speed+ * with nothing to say. NO IMPORTS — the host bundles this.+ */++/** The compiled systems, as a module importing the engine's memory. */+export const AOT_WASM = 'systems.wasm';+/** How to call them: symbols, query order, and what the module baked in. */+export const AOT_MANIFEST = 'systems.json';diff --git a/pipeline/src/bundle/buildCompiledSystems.ts b/pipeline/src/bundle/buildCompiledSystems.tsindex 3902a86f6..d0d1865c5 100644--- a/pipeline/src/bundle/buildCompiledSystems.ts+++ b/pipeline/src/bundle/buildCompiledSystems.ts@@ -29,11 +29,12 @@ import { inlineSystem } from '../../../compiler/src/inline';import { builtinShapes } from '../../../compiler/src/builtins';import { packLayout, planFor } from '../../../compiler/src/abi';import { CFLAGS, WASM_LINK_FLAGS, cSymbol, emitC } from '../../../compiler/src/codegen';+import { AOT_MANIFEST, AOT_WASM } from './aotArtifacts';/** Where the C and the wasm land, beside the script bundle. */const CACHE_DIR = '.esengine/cache/aot';-const WASM = 'systems.wasm';-const MANIFEST = 'systems.json';+const WASM = AOT_WASM;+const MANIFEST = AOT_MANIFEST;/** What the runtime needs in order to call one compiled system. */export interface CompiledSystemInfo {diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex a41191aa6..08f8d6c72 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -21,6 +21,7 @@*/import type { BuildOptions, Plugin } from 'esbuild';import { loadEsbuild } from '../bundle/esbuildRuntime';+import { spawn } from 'node:child_process';import { writeFile, readFile, mkdir, cp, readdir, rm } from 'node:fs/promises';import { existsSync } from 'node:fs';import path from 'node:path';@@ -39,6 +40,9 @@ import { exportPlayable } from './exportPlayable';import { genericPlayableProfile, type PlayableAdProfile } from './playableAdProfile';import type { OnExportProgress } from './exportProgress';import { ESENGINE_EXTERNAL } from '../bundle/esengineResolve';+import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSystems';+import { AOT_MANIFEST, AOT_WASM } from '../bundle/aotArtifacts';+import { emccPath } from '../../../build-tools/utils/emscripten.js';import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';import { orientationCss, orientationOverlayHtml, orientationLockScript, orientationLockCspHash, type ScreenOrientation } from './orientationHtml';import { emitIosXcodeProject, type IosProjectSources } from '../../../build-tools/utils/iosProject.js';@@ -415,6 +419,9 @@ export interface ExportGameOptions {/** `packaging.sizeBudget[platform]` — the project's own package-size ceiling in* bytes, replacing whatever limit the target declares. See sizeBudget.ts. */sizeBudgetBytes?: number;+ /** Whether a `@compiled` marker is collected on. Default `release`, because an+ * export IS the shipping build; `dev` skips the toolchain entirely. */+ aot?: BuildMode;}/**@@ -493,6 +500,16 @@ async function attachSizeReport(result: ExportGameResult, opts: ExportGameOption}}+/** emcc, as buildCompiledSystems wants it: a .bat on Windows, so through a shell. */+function runEmcc(cmd: string, args: string[], cwd: string): Promise<{ code: number; stderr: string }> {+ return new Promise((done) => {+ const child = spawn(cmd, args, { cwd, shell: process.platform === 'win32' });+ let stderr = '';+ child.stderr.on('data', (d) => { stderr += String(d); });+ child.on('close', (code) => done({ code: code ?? 1, stderr }));+ });+}+async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult> {const platform = opts.platform ?? 'web';const title = opts.title ?? 'Game';@@ -703,6 +720,24 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>: await build({ ...common, entryPoints: [scriptsAbs], outfile: path.join(payloadDir, 'scripts.mjs') });errors.push(...explainBundleErrors(proj.errors));}++ // 3b. The systems the project PROMISED would compile, as wasm beside the+ // bundle: no marker is not a build step, a promise the subset cannot+ // keep is an error. The engine wasm stays prebuilt.+ if (!nativeContent) {+ const aot = await buildCompiledSystems(opts.root, {+ mode: opts.aot ?? 'release',+ emcc: emccPath(),+ run: runEmcc,+ });+ errors.push(...aot.errors);+ for (const note of aot.notes) warnings.push(note);+ if (aot.ok && aot.wasmPath && aot.manifest) {+ progress({ phase: 'Compiling promised systems' });+ await cp(aot.wasmPath, path.join(payloadDir, AOT_WASM));+ await writeFile(path.join(payloadDir, AOT_MANIFEST), JSON.stringify(aot.manifest));+ }+ }} catch (err) {const e = err as { errors?: BundleMessage[]; message?: string };errors.push(...(e.errors ? explainBundleErrors(e.errors) : [String(e.message ?? err)]));diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.tsindex 2cfda1261..949aaa4c9 100644--- a/pipeline/src/runtime/gameHost.ts+++ b/pipeline/src/runtime/gameHost.ts@@ -18,7 +18,8 @@ import {packagedAppOptions, packagedRuntimeInit, Transform, SceneManager, Nav, UINode,acquireWebGPUDevice,} from 'esengine';-import type { SceneData, AddressableManifest, PackagedGameConfig, RenderSurfaceSource } from 'esengine';+import type { SceneData, AddressableManifest, PackagedGameConfig, RenderSurfaceSource, AotManifest } from 'esengine';+import { AOT_MANIFEST, AOT_WASM } from '../bundle/aotArtifacts';import type { ESEngineModule } from 'esengine/wasm';async function boot(): Promise<void> {const canvas = document.getElementById('canvas') as HTMLCanvasElement;@@ -106,6 +107,20 @@ async function boot(): Promise<void> {});setEditorMode(false);setPlayMode(true);++ // The compiled twins, if the build made any. A project with no `@compiled`+ // marker ships neither file and interprets, which the 404 below detects.+ // Once the manifest IS there the wasm must be too.+ const aotManifest = await fetch(new URL(`./${AOT_MANIFEST}`, import.meta.url)).catch(() => null);+ if (aotManifest?.ok) {+ const wasm = await fetch(new URL(`./${AOT_WASM}`, import.meta.url));+ if (!wasm.ok) throw new Error(`${AOT_MANIFEST} shipped without ${AOT_WASM}`);+ await app.useCompiledSystems({+ host: module,+ manifest: await aotManifest.json() as AotManifest,+ wasm: await wasm.arrayBuffer(),+ });+ }if (headless) {(window as unknown as { __estellaCooked?: unknown }).__estellaCooked = {capture(): { width: number; height: number; rgba: Uint8Array } {diff --git a/pipeline/tests/export-aot.test.ts b/pipeline/tests/export-aot.test.tsnew file mode 100644index 000000000..649e7a85b--- /dev/null+++ b/pipeline/tests/export-aot.test.ts@@ -0,0 +1,137 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Whether a web package carries the systems the project promised would+ * compile, and whether the host it ships with goes looking for them.+ *+ * Two files and one name. If the export writes `systems.wasm` and the+ * host fetches something else, nothing fails: the fetch 404s, no twin is+ * installed, and the game runs the interpreter with nothing to say. So+ * the name is asserted in the BUNDLE, not just in the source.+ */+import { describe, it, expect } from 'vitest';+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { exportGame } from '../src/export/exportGame';+import { AOT_MANIFEST, AOT_WASM } from '../src/bundle/aotArtifacts';+import { emccPath } from '../../build-tools/utils/emscripten.js';++const HERE = path.dirname(fileURLToPath(import.meta.url));+const GAME_HOST = path.join(HERE, '..', 'src', 'runtime', 'gameHost.ts');+const EMCC = emccPath();++const SCN = 'ffffffff-ffff-ffff-ffff-ffffffffffff';+const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });++const COMPONENTS = `import { defineComponent } from 'esengine';+export const Mover = defineComponent('Mover', { speed: 100, directionX: 1, directionY: 0 });+`;++/** The shape the marker exists for: a promise the subset can keep. */+const PROMISED = `import { defineSystem, Query, Mut, Res, Time, Transform } from 'esengine';+import { Mover } from './components';++/**+ * @compiled+ */+export const moveSystem = defineSystem(+ [Query(Mut(Transform), Mover), Res(Time)],+ (query, time) => {+ for (const [, transform, mover] of query) {+ transform.position.x += mover.directionX * mover.speed * time.delta;+ transform.position.y += mover.directionY * mover.speed * time.delta;+ }+ },+ { name: 'MoveSystem' },+);+`;++const MAIN = `import './systems';+`;++function setup(files: Record<string, string>): { root: string; out: string } {+ const root = mkdtempSync(path.join(tmpdir(), 'estella-export-aot-'));+ 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: [] }] }));+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));+ for (const [rel, body] of Object.entries(files)) {+ const at = path.join(root, rel);+ mkdirSync(path.dirname(at), { recursive: true });+ writeFileSync(at, body);+ }+ mkdirSync(path.join(root, '_sdk'), { recursive: true });+ writeFileSync(path.join(root, '_sdk', 'index.js'), 'export const x = 1;\n');+ mkdirSync(path.join(root, '_wasm'), { recursive: true });+ writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'export default () => {};');+ writeFileSync(path.join(root, '_wasm', 'esengine.wasm'), 'ENGINE');+ return { root, out: path.join(root, 'dist') };+}++const run = (f: { root: string; out: string }, aot?: 'dev' | 'release' | 'ship') => 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, ...(aot === undefined ? {} : { aot }),+});++describe('the promised systems in a web package', () => {+ it('reports whether this gate could run at all', () => {+ if (!EMCC) console.warn('[export-aot] NO EMSDK — the compiling cases did NOT run.');+ });++ it('ships neither file for a project that promised nothing', async () => {+ const f = setup({ 'src/components.ts': COMPONENTS, 'src/main.ts': "export const n = 1;\n" });+ const res = await run(f);+ expect(res.errors).toEqual([]);+ expect(existsSync(path.join(f.out, AOT_WASM))).toBe(false);+ expect(existsSync(path.join(f.out, AOT_MANIFEST))).toBe(false);+ });++ it.skipIf(!EMCC)('ships both, and a manifest that says how to call them', async () => {+ const f = setup({ 'src/components.ts': COMPONENTS, 'src/systems.ts': PROMISED, 'src/main.ts': MAIN });+ const res = await run(f);+ expect(res.errors).toEqual([]);+ expect(existsSync(path.join(f.out, AOT_WASM))).toBe(true);++ const manifest = JSON.parse(readFileSync(path.join(f.out, AOT_MANIFEST), 'utf8')) as {+ engineAbi: string; projectShapes: string;+ systems: { name: string; symbol: string; queries: { comp: string; mut: boolean }[][]; resources: string[] }[];+ };+ expect(manifest.systems).toEqual([{+ name: 'MoveSystem',+ symbol: 'es_sys_MoveSystem',+ queries: [[{ comp: 'Transform', mut: true }, { comp: 'Mover', mut: false }]],+ resources: ['Time'],+ }]);+ expect(manifest.engineAbi).toMatch(/^[0-9a-f]{16}$/);++ // The shipped module is the one the runtime loads, so ask the artifact the+ // two questions a fake host cannot: it imports the engine's memory, and it+ // brought no data section to write over the engine's own bytes.+ const bytes = readFileSync(path.join(f.out, AOT_WASM));+ const mod = new WebAssembly.Module(bytes as unknown as BufferSource);+ expect(WebAssembly.Module.imports(mod)).toEqual([{ module: 'env', name: 'memory', kind: 'memory' }]);+ expect(WebAssembly.Module.exports(mod).map((e) => e.name)).toContain('es_sys_MoveSystem');+ });++ it.skipIf(!EMCC)('and the host it ships with asks for those exact names', async () => {+ const f = setup({ 'src/components.ts': COMPONENTS, 'src/systems.ts': PROMISED, 'src/main.ts': MAIN });+ await run(f);+ // In the BUNDLE: the constant is inlined by esbuild, so this is what the+ // shipped game will actually fetch — a source-level check would pass while+ // the two ends disagreed.+ const host = readFileSync(path.join(f.out, 'game.js'), 'utf8');+ expect(host).toContain(AOT_MANIFEST);+ expect(host).toContain(AOT_WASM);+ });++ it('a dev export never compiles, so it needs no toolchain', async () => {+ const f = setup({ 'src/components.ts': COMPONENTS, 'src/systems.ts': PROMISED, 'src/main.ts': MAIN });+ const res = await run(f, 'dev');+ expect(res.errors).toEqual([]);+ expect(existsSync(path.join(f.out, AOT_WASM))).toBe(false);+ });+});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 7aa9a32f7..bd3de97a9 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -586,6 +586,7 @@ stepFrame: () => voidstepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>waitForPhysics: () => Promise<void>world: Worldstatic new (): Appdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex df0bde3b3..f362137c8 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -586,6 +586,7 @@ stepFrame: () => voidstepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>waitForPhysics: () => Promise<void>world: Worldstatic new (): Appdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex e32d3ff8a..87a323a0a 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -581,6 +581,7 @@ stepFrame: () => voidstepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>waitForPhysics: () => Promise<void>world: Worldstatic new (): Appdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 8286848f1..012fd1c21 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -581,6 +581,7 @@ stepFrame: () => voidstepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>waitForPhysics: () => Promise<void>world: Worldstatic new (): Appdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex f7772d65c..562118e06 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -581,6 +581,7 @@ stepFrame: () => voidstepFrames: (frames?: number, dt?: number) => Promise<void>subsystems: SubsystemRegistrytick: (delta: number) => Promise<void>+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>waitForPhysics: () => Promise<void>world: Worldstatic new (): Appdiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 3ace190d8..ec02f8493 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -7,7 +7,10 @@import { World } from '../ecs/world';import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, rescopeSystem, type RunCondition } from '../ecs/system';-import { ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';+import { BUILTIN_RESOURCES, ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';+import { prepareAot, type AotHost } from '../ecs/aot/installAot';+import type { AotManifest } from '../ecs/aot/AotSystems';+import type { AotRuntime } from '../ecs/aot/AotRuntime';import { EventRegistry, type EventDef } from '../ecs/event';import type { ESEngineModule, CppRegistry } from '../wasm';import type { OutputTransform } from '../postprocess';@@ -610,6 +613,37 @@ export class App {return this.world_;}+ /**+ * Run the compiled twins a build produced instead of the systems' closures.+ * Call it BEFORE the world has any pooled component: the rows must be in the+ * memory the module reads. Refuses rather than degrades — a module built for+ * other offsets reads a different field, which is not an error.+ *+ * @experimental+ */+ async useCompiledSystems(opts: {+ readonly host: AotHost;+ readonly manifest: AotManifest;+ readonly wasm: BufferSource;+ }): Promise<void> {+ this.aot_ = await prepareAot({+ world: this.world_,+ host: opts.host,+ manifest: opts.manifest,+ wasm: opts.wasm,+ resources: (name) => {+ const def = BUILTIN_RESOURCES[name];+ return def !== undefined && this.resources_.has(def)+ ? this.resources_.get(def) as Readonly<Record<string, unknown>>+ : undefined;+ },+ });+ this.runner_?.useAot(this.aot_);+ }++ /** Held until there is a runner to give them to: one is made on the first frame. */+ private aot_: AotRuntime | null = null;+// =========================================================================// Configuration// =========================================================================@@ -1024,6 +1058,12 @@ export class App {private ensureRunner_(): SystemRunner {if (!this.runner_) {this.runner_ = new SystemRunner(this.world_, this.resources_, this.eventRegistry_);+ // Twins prepared before there was a runner. `useCompiledSystems` can be+ // called on a fresh App, and its `runner_?.useAot` would drop them for+ // good — a compiled build that silently runs its closures instead.+ if (this.aot_) {+ this.runner_.useAot(this.aot_);+ }if (this.statsEnabled_) {this.runner_.setTimingEnabled(true);}diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex b3ae759e7..c6d6bb8b4 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -368,3 +368,10 @@ export type { EngineApi } from './ecs/bridge/engineApi';// =============================================================================export { AppContext, getDefaultContext, setDefaultContext, type EditorBridge } from './ecs/context';++/** What `App.useCompiledSystems` takes: the engine module, and what a build+ * wrote beside the wasm it produced.+ *+ * @experimental */+export type { AotHost } from './ecs/aot/installAot';+export type { AotManifest, AotSystemDecl } from './ecs/aot/AotSystems';diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.tsindex ab4b364bf..b59423db3 100644--- a/sdk/src/ecs/aot/installAot.ts+++ b/sdk/src/ecs/aot/installAot.ts@@ -31,8 +31,12 @@ import { AotResources, type ResourceReader } from './AotResources';import { AotSystems, type AotManifest } from './AotSystems';import type { AotAddresses, AotRuntime } from './AotRuntime';-/** The engine module a compiled system shares memory with. */-export type AotHost = WasmHeap & { readonly memory: WebAssembly.Memory };+/**+ * The engine module a compiled system shares memory with. `wasmMemory` is+ * emscripten's own name for the Memory object, and the engine exports it for+ * exactly this — a HEAP view's buffer is an ArrayBuffer and cannot be imported.+ */+export type AotHost = WasmHeap & { readonly wasmMemory: WebAssembly.Memory };export interface InstallAotOptions {readonly world: World;@@ -56,6 +60,18 @@ export interface InstallAotOptions {* afterwards would leave half of them behind — so it refuses instead.*/export async function installAot(opts: InstallAotOptions): Promise<AotRuntime> {+ const runtime = await prepareAot(opts);+ opts.runner.useAot(runtime);+ return runtime;+}++/**+ * Everything install does except hand the twins to a runner, because the two+ * halves have different deadlines: the pool memory has to be in place before the+ * world's first pooled component, and a runner may not exist until the first+ * frame. A caller holding the result attaches it when it does.+ */+export async function prepareAot(opts: Omit<InstallAotOptions, 'runner'>): Promise<AotRuntime> {const memory = new WasmPoolMemory(opts.host);opts.world.useScriptPoolMemory(memory);@@ -69,13 +85,11 @@ export async function installAot(opts: InstallAotOptions): Promise<AotRuntime> {const systems = new AotSystems();systems.install(opts.manifest, exports, componentNamed);- const runtime: AotRuntime = {+ return {systems,addresses: worldAddresses(new AotResources(memory, opts.resources)),ctx: new AotContext(memory),};- opts.runner.useAot(runtime);- return runtime;}/**diff --git a/sdk/src/ecs/resource.ts b/sdk/src/ecs/resource.tsindex 71ffbb6da..3141e721b 100644--- a/sdk/src/ecs/resource.ts+++ b/sdk/src/ecs/resource.ts@@ -279,3 +279,15 @@ export interface TimeData {*/export const Time = defineResource<TimeData>({ ...RESOURCE_SHAPES.Time }, 'Time');+/**+ * The engine's own resources, by the name a compiled system names them with.+ * Not a general registry: `defineResource` identifies by REFERENCE, so a name+ * answers a resource only for the ones the engine itself declares — which is+ * exactly the set that has a layout to read at an address.+ *+ * @internal+ */+export const BUILTIN_RESOURCES: Readonly<Record<string, ResourceDef<unknown>>> = {+ Time: Time as ResourceDef<unknown>,+};+diff --git a/sdk/tests/aot-app.test.ts b/sdk/tests/aot-app.test.tsnew file mode 100644index 000000000..d9fbfdb5c--- /dev/null+++ b/sdk/tests/aot-app.test.ts@@ -0,0 +1,120 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file aot-app.test.ts+ * @brief The path a shipped game takes: install on the App, tick, get twins.+ *+ * @details The runner-level gates hand `useAot` a runtime directly. A game host+ * cannot: an App makes its runner on the FIRST FRAME, while the pool+ * memory has to be in place before the first pooled component. So the+ * install is split, and this is the gate on the halves meeting.+ */+import { describe, it, expect } from 'vitest';+import { bootMockApp } from './helpers/mockApp';+import { buildFadeModule, fadeManifest, FADE_PROBE_ALPHA, FADE_PROBE_C } from './helpers/aotFade';+import { FakeEngine } from './fakeEngine';+import { emccPath } from '../../build-tools/utils/emscripten.js';+import { defineComponent } from '../src/ecs/component';+import { defineSystem, Schedule } from '../src/ecs/system';+import { Query, Mut } from '../src/ecs/query';+import type { AnyComponentDef } from '../src/ecs/component';+import type { Entity } from '../src/types';++const EMCC = emccPath();+const N = 8;++/** The same author's system either way; only whether a twin exists differs. */+function fadeApp(): { app: ReturnType<typeof bootMockApp>['app']; Fade: AnyComponentDef } {+ const { app } = bootMockApp();+ const Fade = defineComponent('Fade', { alpha: 1, step: 0.1 }) as AnyComponentDef;+ app.addSystemToSchedule(Schedule.Update, defineSystem([Query(Mut(Fade))], (query) => {+ for (const [, fade] of query as Iterable<[Entity, { alpha: number; step: number }]>) {+ fade.alpha -= fade.step;+ }+ }, { name: 'Fade' }));+ return { app, Fade };+}++function seed(app: ReturnType<typeof bootMockApp>['app'], Fade: AnyComponentDef): Entity[] {+ const out: Entity[] = [];+ for (let i = 1; i <= N; i++) {+ const e = app.world.spawn();+ app.world.insert(e, Fade, { alpha: i * 0.1, step: 0.01 });+ out.push(e);+ }+ return out;+}++const alphas = (app: ReturnType<typeof bootMockApp>['app'], Fade: AnyComponentDef, es: Entity[]): number[] =>+ es.map((e) => (app.world.get(e, Fade) as { alpha: number }).alpha);++describe('an App told to run its compiled twins', () => {+ it('reports whether this gate could run at all', () => {+ if (!EMCC) console.warn('[aot-app] NO EMSDK — the App-level install did NOT run.');+ });++ it.skipIf(!EMCC)('installs before any runner exists, and the first frame uses the twin', async () => {+ const wasm = buildFadeModule(EMCC!);++ const plain = fadeApp();+ const plainEntities = seed(plain.app, plain.Fade);++ const compiled = fadeApp();+ // Before seeding AND before the first tick: no pooled component yet, and+ // no runner yet. Both deadlines are met by the same call.+ await compiled.app.useCompiledSystems({ host: new FakeEngine(), manifest: fadeManifest(), wasm });+ const compiledEntities = seed(compiled.app, compiled.Fade);++ for (let f = 0; f < 4; f++) {+ await plain.app.tick(1 / 60);+ await compiled.app.tick(1 / 60);+ }++ expect(alphas(compiled.app, compiled.Fade, compiledEntities))+ .toEqual(alphas(plain.app, plain.Fade, plainEntities));+ // Two untouched worlds would agree just as well.+ expect(alphas(compiled.app, compiled.Fade, compiledEntities)[0]).not.toBeCloseTo(0.1, 10);+ });++ /**+ * The differential above cannot see this one: with no twin the closure runs+ * and produces the same numbers, so it passes either way. Sabotage-verified+ * by removing the attach — this reddens, that one does not.+ */+ it.skipIf(!EMCC)('and the twin is what ran, not the closure that agrees with it', async () => {+ const { app, Fade } = fadeApp();+ await app.useCompiledSystems({+ host: new FakeEngine(), manifest: fadeManifest(),+ wasm: buildFadeModule(EMCC!, FADE_PROBE_C),+ });+ const entities = seed(app, Fade);+ await app.tick(1 / 60);+ expect(alphas(app, Fade, entities)).toEqual(entities.map(() => FADE_PROBE_ALPHA));+ });++ it.skipIf(!EMCC)('and installing after the runner exists attaches to it too', async () => {+ const { app, Fade } = fadeApp();+ // A frame first, so the runner is already made when the install lands.+ // The probe again: without it the closure's answer passes for the twin's.+ await app.tick(1 / 60);+ await app.useCompiledSystems({+ host: new FakeEngine(), manifest: fadeManifest(),+ wasm: buildFadeModule(EMCC!, FADE_PROBE_C),+ });+ const entities = seed(app, Fade);+ await app.tick(1 / 60);+ expect(alphas(app, Fade, entities)).toEqual(entities.map(() => FADE_PROBE_ALPHA));+ });++ it.skipIf(!EMCC)('refuses a module built for other shapes, and the App keeps interpreting', async () => {+ const { app, Fade } = fadeApp();+ await expect(app.useCompiledSystems({+ host: new FakeEngine(),+ manifest: fadeManifest(/* a shape digest from before `step` existed */ 'deadbeefdeadbeef'),+ wasm: buildFadeModule(EMCC!),+ })).rejects.toThrow(/Rebuild the project/);+ const entities = seed(app, Fade);+ await app.tick(1 / 60);+ expect(alphas(app, Fade, entities)[0]).toBeCloseTo(0.09, 10);+ });+});diff --git a/sdk/tests/aot-context.test.ts b/sdk/tests/aot-context.test.tsindex a81403db0..471dd2794 100644--- a/sdk/tests/aot-context.test.ts+++ b/sdk/tests/aot-context.test.ts@@ -132,7 +132,7 @@ describe('a compiled system, called by the SDK', () => {const memory = new WasmPoolMemory(engine);const instance = await WebAssembly.instantiate(new WebAssembly.Module(buildModule() as unknown as BufferSource),- { env: { memory: engine.memory } });+ { env: { memory: engine.wasmMemory } });const api = instance.exports as unknown as Record<string, unknown>;(api['_initialize'] as (() => void) | undefined)?.();const decay = api['es_sys_Decay'] as (ctx: number) => void;@@ -200,7 +200,7 @@ describe('a compiled system, called by the SDK', () => {const memory = new WasmPoolMemory(engine);const instance = await WebAssembly.instantiate(new WebAssembly.Module(buildModule() as unknown as BufferSource),- { env: { memory: engine.memory } });+ { env: { memory: engine.wasmMemory } });const api = instance.exports as unknown as Record<string, unknown>;(api['_initialize'] as (() => void) | undefined)?.();diff --git a/sdk/tests/aot-dispatch.test.ts b/sdk/tests/aot-dispatch.test.tsindex 9a3da519a..4b814ebf6 100644--- a/sdk/tests/aot-dispatch.test.ts+++ b/sdk/tests/aot-dispatch.test.ts@@ -163,7 +163,7 @@ describe('the scheduler and its compiled twin', () => {const instance = await WebAssembly.instantiate(new WebAssembly.Module(bytes as unknown as BufferSource),- { env: { memory: heap.memory } });+ { env: { memory: heap.wasmMemory } });const exports = instance.exports as unknown as Record<string, unknown>;(exports['_initialize'] as (() => void) | undefined)?.();@@ -219,7 +219,7 @@ describe('the scheduler and its compiled twin', () => {if (compiled) {const instance = await WebAssembly.instantiate(new WebAssembly.Module(bytes as unknown as BufferSource),- { env: { memory: heap.memory } });+ { env: { memory: heap.wasmMemory } });const exports = instance.exports as unknown as Record<string, unknown>;(exports['_initialize'] as (() => void) | undefined)?.();const systems = new AotSystems();diff --git a/sdk/tests/aot-install.test.ts b/sdk/tests/aot-install.test.tsindex 41309564b..0d0ef20c9 100644--- a/sdk/tests/aot-install.test.ts+++ b/sdk/tests/aot-install.test.ts@@ -39,7 +39,7 @@ import type { WasmHeap } from '../src/ecs/WasmPoolMemory';import type { Entity } from '../src/types';import { emccPath } from '../../build-tools/utils/emscripten.js';import { FakeEngine } from './fakeEngine';-import { WASM_LINK_FLAGS } from '../../compiler/src/codegen';+import { buildFadeModule, FADE_FIELDS, fadeManifest } from './helpers/aotFade';const N = 16;@@ -163,7 +163,7 @@ describe('installing a built module', () => {const engine = new FakeEngine();await installAot({world: compiled.world, runner: compiled.runner, host: engine,- manifest: manifestFor(), wasm, resources: () => undefined,+ manifest: fadeManifest(), wasm, resources: () => undefined,});const compiledEntities = seed(compiled.world, compiled.Fade);diff --git a/sdk/tests/fakeEngine.ts b/sdk/tests/fakeEngine.tsindex 5b15c0157..58fa2b0e2 100644--- a/sdk/tests/fakeEngine.ts+++ b/sdk/tests/fakeEngine.ts@@ -27,8 +27,8 @@ const STATICS_BYTE = 0xab;export class FakeEngine implements WasmHeap {/** 256 pages because that is the minimum a built module declares it needs. */- readonly memory = new WebAssembly.Memory({ initial: 256, maximum: 32768 });- HEAPU8 = new Uint8Array(this.memory.buffer);+ readonly wasmMemory = new WebAssembly.Memory({ initial: 256, maximum: 32768 });+ HEAPU8 = new Uint8Array(this.wasmMemory.buffer);private next = STATICS_AT + STATICS_LEN;constructor() { this.statics().fill(STATICS_BYTE); }@@ -37,8 +37,8 @@ export class FakeEngine implements WasmHeap {const at = this.next;this.next += (size + 15) & ~15;while (this.next > this.HEAPU8.byteLength) {- this.memory.grow(1);- this.HEAPU8 = new Uint8Array(this.memory.buffer);+ this.wasmMemory.grow(1);+ this.HEAPU8 = new Uint8Array(this.wasmMemory.buffer);}return at;}@@ -47,7 +47,7 @@ export class FakeEngine implements WasmHeap {/** The bytes the engine owns. Read after loading and after running. */statics(): Uint8Array {- return new Uint8Array(this.memory.buffer, STATICS_AT, STATICS_LEN);+ return new Uint8Array(this.wasmMemory.buffer, STATICS_AT, STATICS_LEN);}/** Whether anything wrote where the engine keeps its own data. */diff --git a/sdk/tests/helpers/aotFade.ts b/sdk/tests/helpers/aotFade.tsnew file mode 100644index 000000000..d4f0dc45f--- /dev/null+++ b/sdk/tests/helpers/aotFade.ts@@ -0,0 +1,82 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file aotFade.ts+ * @brief One compiled system, in the shape the compiler emits it.+ *+ * @details `Fade` is the smallest thing that exercises the whole path: an+ * all-scalar script component, so its rows live in the pool a module+ * can address, and a body that only reads and writes them. Shared so+ * the runner-level gate and the App-level one run the same artifact.+ */+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { spawnSync } from 'node:child_process';+import { WASM_LINK_FLAGS } from '../../../compiler/src/codegen';+import { engineAbiDigest, projectShapeDigest } from '../../src/ecs/aot/abiDigest';+import type { AotManifest } from '../../src/ecs/aot/AotSystems';++/** `Fade`: alpha -= step, addressed the way the ABI lays a call out. */+export const FADE_C = `#include <stdint.h>+#include <string.h>+typedef uint32_t es_addr_t;+#define ES_PTR(a) ((unsigned char *)(a))+typedef struct { es_addr_t rows, count; } EsQueryRows;+typedef struct { es_addr_t queries, resources, cmdBuf, cmdCap, cmdCount, events; } EsSysCtx;+static double ld(const unsigned char *p) { double v; memcpy(&v, p, 8); return v; }+static void st(unsigned char *p, double v) { memcpy(p, &v, 8); }++void es_sys_Fade(es_addr_t ctx) {+ const EsSysCtx *c = (const EsSysCtx *)ES_PTR(ctx);+ const EsQueryRows *q = (const EsQueryRows *)ES_PTR(c->queries);+ const es_addr_t *rows = (const es_addr_t *)ES_PTR(q[0].rows);+ for (es_addr_t i = 0; i < q[0].count; ++i) {+ unsigned char *f = ES_PTR(rows[i * 2u + 1u]);+ st(f, ld(f) - ld(f + 8)); /* alpha -= step */+ }+}+`;++/**+ * The same system, writing a value the author's closure cannot produce. A+ * differential proves a twin computes the right thing; it cannot prove the+ * twin RAN, because an interpreter that ran instead agrees with it. This can:+ * see the sentinel and dispatch happened.+ */+export const FADE_PROBE_C = FADE_C.replace(+ 'st(f, ld(f) - ld(f + 8)); /* alpha -= step */',+ 'st(f, -1.0); /* only a twin writes this */');++/** What the probe writes. No closure here produces a negative alpha. */+export const FADE_PROBE_ALPHA = -1;++export const FADE_FIELDS = ['alpha', 'step'];++export function buildFadeModule(emcc: string, source: string = FADE_C): Uint8Array {+ const dir = mkdtempSync(path.join(tmpdir(), 'estella-fade-'));+ mkdirSync(dir, { recursive: true });+ writeFileSync(path.join(dir, 'sys.c'), source);+ const out = path.join(dir, 'sys.wasm');+ const built = spawnSync(emcc, [+ '-std=c11', '-O2', '-ffp-contract=off', '-Wall', '-Wextra',+ ...WASM_LINK_FLAGS, '-sEXPORTED_FUNCTIONS=_es_sys_Fade',+ '-o', out, path.join(dir, 'sys.c'),+ ], { encoding: 'utf8', cwd: dir, shell: process.platform === 'win32' });+ if (built.status !== 0) throw new Error(`emcc failed:\n${built.stderr}`);+ return readFileSync(out);+}++/** What a build would have written beside that module, for THIS engine. */+export function fadeManifest(+ shapes = projectShapeDigest([{ name: 'Fade', fields: FADE_FIELDS }]),+): AotManifest {+ return {+ engineAbi: engineAbiDigest(4),+ projectShapes: shapes,+ systems: [{+ name: 'Fade', symbol: 'es_sys_Fade',+ queries: [[{ comp: 'Fade', mut: true }]], resources: [],+ }],+ };+}