Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(aot): an exported game ships the systems it promised, and runs them

esenginedf8c1cf9826e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-file
transport inlined its engine as plain base64 — a +33% tax on a payload that is
mostly a 1.5MB wasm — and never minified the bundle, because the CLI had no
diff --git a/pipeline/src/bundle/aotArtifacts.ts b/pipeline/src/bundle/aotArtifacts.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index 7aa9a32f7..bd3de97a9 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -586,6 +586,7 @@ stepFrame: () => void
stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>
waitForPhysics: () => Promise<void>
world: World
static new (): App
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index df0bde3b3..f362137c8 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -586,6 +586,7 @@ stepFrame: () => void
stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>
waitForPhysics: () => Promise<void>
world: World
static new (): App
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index e32d3ff8a..87a323a0a 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -581,6 +581,7 @@ stepFrame: () => void
stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>
waitForPhysics: () => Promise<void>
world: World
static new (): App
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 8286848f1..012fd1c21 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -581,6 +581,7 @@ stepFrame: () => void
stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>
waitForPhysics: () => Promise<void>
world: World
static new (): App
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f7772d65c..562118e06 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -581,6 +581,7 @@ stepFrame: () => void
stepFrames: (frames?: number, dt?: number) => Promise<void>
subsystems: SubsystemRegistry
tick: (delta: number) => Promise<void>
+useCompiledSystems: (opts: { readonly host: AotHost; readonly manifest: AotManifest; readonly wasm: BufferSource; }) => Promise<void>
waitForPhysics: () => Promise<void>
world: World
static new (): App
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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: [],
+ }],
+ };
+}