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(ecs): one call installs a built module and the scheduler runs it

yhh5df23b4420ef
diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.ts
new file mode 100644
index 000000000..1e278bc16
--- /dev/null
+++ b/sdk/src/ecs/aot/installAot.ts
@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file installAot.ts
+ * @brief Take a built module and let the scheduler call it.
+ *
+ * @details The one entry point a shipping runtime needs: instantiate the wasm a
+ * build produced, check what it baked in, and hand the runner the twins.
+ * Everything it assembles has been tested on its own — this is the
+ * wiring that was waiting for the handshake to be decided.
+ *
+ * The module IMPORTS the engine's memory, so there is nothing to link
+ * and no engine change: it reads the components where they already are
+ * (docs/REARCH_AOT.md §6.1).
+ *
+ * Refuses rather than degrades. A module built for other offsets does
+ * not produce a wrong answer, it produces a read of a different field,
+ * and a runtime that fell back to the interpreter on a mismatch would
+ * hide exactly the thing worth knowing.
+ */
+
+import { getComponent } from '../component';
+import type { AnyComponentDef } from '../component';
+import type { World } from '../world';
+import type { SystemRunner } from '../system';
+import type { Entity } from '../../types';
+import { WasmPoolMemory, type WasmHeap } from '../WasmPoolMemory';
+import { AotContext } from './AotContext';
+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 };
+
+export interface InstallAotOptions {
+ readonly world: World;
+ readonly runner: SystemRunner;
+ /** The engine's wasm module: its memory is the one the systems read. */
+ readonly host: AotHost;
+ /** What the build wrote beside the module. */
+ readonly manifest: AotManifest;
+ readonly wasm: BufferSource;
+ /** The live value of a named resource, for the mirror to copy in. */
+ readonly resources: ResourceReader;
+}
+
+/**
+ * Install the twins. Throws if the module disagrees with this engine or this
+ * project, and the message says which. Call it BEFORE the world has any pooled
+ * component: the rows must be in the memory the module reads, and moving them
+ * afterwards would leave half of them behind — so it refuses instead.
+ */
+export async function installAot(opts: InstallAotOptions): Promise<AotRuntime> {
+ const memory = new WasmPoolMemory(opts.host);
+ opts.world.useScriptPoolMemory(memory);
+
+ const instance = await WebAssembly.instantiate(
+ new WebAssembly.Module(opts.wasm), { env: { memory: opts.host.memory } });
+ const exports = instance.exports as unknown as Record<string, unknown>;
+ // A STANDALONE_WASM reactor runs its data setup here rather than at an entry
+ // point, and the module has none.
+ (exports['_initialize'] as (() => void) | undefined)?.();
+
+ const systems = new AotSystems();
+ systems.install(opts.manifest, exports, componentNamed);
+
+ const runtime: AotRuntime = {
+ systems,
+ addresses: worldAddresses(opts.world, new AotResources(memory, opts.resources)),
+ ctx: new AotContext(memory),
+ };
+ opts.runner.useAot(runtime);
+ return runtime;
+}
+
+/** What a manifest's component NAME means in this runtime. */
+function componentNamed(name: string): AnyComponentDef | undefined {
+ return getComponent(name);
+}
+
+/**
+ * Where things are, asked of the world. One question for both kinds of
+ * component, because a system may name an engine one and a script one in the
+ * same query and the runner has no business knowing which is which.
+ */
+export function worldAddresses(world: World, resources: AotResources): AotAddresses {
+ return {
+ componentNamed,
+ componentAt: (component: AnyComponentDef, entity: Entity) =>
+ world.addressOfComponent(component, entity),
+ resourceAt: (name: string) => resources.addressOf(name),
+ };
+}
diff --git a/sdk/tests/aot-install.test.ts b/sdk/tests/aot-install.test.ts
new file mode 100644
index 000000000..7acce23f9
--- /dev/null
+++ b/sdk/tests/aot-install.test.ts
@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file aot-install.test.ts
+ * @brief One call from a built module to a scheduler that runs it.
+ *
+ * @details The pieces each have their own test. This is the entry point a
+ * shipping runtime actually uses, and what it has to get right is the
+ * ORDER: pool memory before any component, module instantiated against
+ * the engine's memory, digests checked before anything is installed.
+ *
+ * Loud skip without emsdk — the module here is really compiled.
+ */
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { World } from '../src/ecs/world';
+import { defineComponent } from '../src/ecs/component';
+import { defineSystem, SystemRunner } from '../src/ecs/system';
+import { Query, Mut } from '../src/ecs/query';
+import { ResourceStorage } from '../src/ecs/resource';
+import { installAot } from '../src/ecs/aot/installAot';
+import { engineAbiDigest, projectShapeDigest } from '../src/ecs/aot/abiDigest';
+import type { AotManifest } from '../src/ecs/aot/AotSystems';
+import type { AnyComponentDef } from '../src/ecs/component';
+import type { WasmHeap } from '../src/ecs/WasmPoolMemory';
+import type { Entity } from '../src/types';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const N = 16;
+
+function findEmcc(): string | null {
+ const at = path.join(ROOT, 'tools/emsdk/upstream/emscripten',
+ process.platform === 'win32' ? 'emcc.bat' : 'emcc');
+ return existsSync(at) ? at : null;
+}
+const EMCC = findEmcc();
+
+/** The engine module, as far as a compiled system needs one. */
+class Host implements WasmHeap {
+ readonly memory = new WebAssembly.Memory({ initial: 256, maximum: 256 });
+ HEAPU8 = new Uint8Array(this.memory.buffer);
+ private next = 4096;
+ _malloc(size: number): number {
+ const at = this.next;
+ this.next += (size + 15) & ~15;
+ return at;
+ }
+ _free(): void { /* a bump allocator frees nothing */ }
+}
+
+/** `Fade`: alpha -= step, in the shape the compiler emits. */
+const SYSTEM_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 */
+ }
+}
+`;
+
+function buildModule(): Uint8Array {
+ const dir = mkdtempSync(path.join(tmpdir(), 'estella-install-'));
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(path.join(dir, 'sys.c'), SYSTEM_C);
+ const out = path.join(dir, 'sys.wasm');
+ const built = spawnSync(EMCC!, [
+ '-std=c11', '-O2', '-ffp-contract=off', '-Wall', '-Wextra',
+ '--no-entry', '-sSTANDALONE_WASM', '-sIMPORTED_MEMORY',
+ '-sERROR_ON_UNDEFINED_SYMBOLS=1', '-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);
+}
+
+const FADE_FIELDS = ['alpha', 'step'];
+
+function manifestFor(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: [],
+ }],
+ };
+}
+
+/** A world and the system the author wrote, before anything is installed. */
+function project(): {
+ world: World; runner: SystemRunner; Fade: AnyComponentDef;
+ system: ReturnType<typeof defineSystem>;
+} {
+ const world = new World();
+ const runner = new SystemRunner(world, new ResourceStorage());
+ const Fade = defineComponent('Fade', { alpha: 1, step: 0.1 }) as AnyComponentDef;
+ const system = defineSystem([Query(Mut(Fade))], (query) => {
+ for (const [, fade] of query as Iterable<[Entity, { alpha: number; step: number }]>) {
+ fade.alpha -= fade.step;
+ }
+ }, { name: 'Fade' });
+ return { world, runner, Fade, system };
+}
+
+function seed(world: World, Fade: AnyComponentDef): Entity[] {
+ const out: Entity[] = [];
+ for (let i = 1; i <= N; i++) {
+ const e = world.spawn();
+ world.insert(e, Fade, { alpha: i * 0.1, step: 0.01 });
+ out.push(e);
+ }
+ return out;
+}
+
+describe('installing a built module', () => {
+ it('reports whether this gate could run at all', () => {
+ if (EMCC) console.log('[aot-install] a built module was installed and run');
+ else console.warn('[aot-install] NO EMSDK — the install did NOT run (pnpm emsdk:setup).');
+ expect(true).toBe(true);
+ });
+
+ it.skipIf(!EMCC)('one call, and the scheduler runs the twin', async () => {
+ const wasm = buildModule();
+
+ const interpreted = project();
+ const interpretedEntities = seed(interpreted.world, interpreted.Fade);
+
+ const compiled = project();
+ await installAot({
+ world: compiled.world, runner: compiled.runner, host: new Host(),
+ manifest: manifestFor(), wasm, resources: () => undefined,
+ });
+ const compiledEntities = seed(compiled.world, compiled.Fade);
+
+ for (let f = 0; f < 6; f++) {
+ interpreted.runner.run(interpreted.system);
+ compiled.runner.run(compiled.system);
+ }
+
+ const alphas = (w: World, c: AnyComponentDef, es: Entity[]): number[] =>
+ es.map((e) => (w.get(e, c) as { alpha: number }).alpha);
+ expect(alphas(compiled.world, compiled.Fade, compiledEntities))
+ .toEqual(alphas(interpreted.world, interpreted.Fade, interpretedEntities));
+ // A world nothing touched would compare two untouched worlds.
+ expect(alphas(compiled.world, compiled.Fade, compiledEntities)[0]).not.toBeCloseTo(0.1, 10);
+ });
+
+ it.skipIf(!EMCC)('refuses a module built for other component shapes', async () => {
+ const p = project();
+ await expect(installAot({
+ world: p.world, runner: p.runner, host: new Host(),
+ // What a build would have written before `step` was added.
+ manifest: manifestFor(projectShapeDigest([{ name: 'Fade', fields: ['alpha'] }])),
+ wasm: buildModule(), resources: () => undefined,
+ })).rejects.toThrow(/Rebuild the project/);
+ });
+
+ it.skipIf(!EMCC)('and installs nothing when it refuses', async () => {
+ const p = project();
+ const entities = seed(p.world, p.Fade);
+ await installAot({
+ world: p.world, runner: p.runner, host: new Host(),
+ manifest: manifestFor(), wasm: buildModule(), resources: () => undefined,
+ }).catch(() => { /* the ordering check below is the point */ });
+ // Rows already existed, so pool memory could not move: the install threw
+ // before any twin was registered, and the closure still runs.
+ p.runner.run(p.system);
+ expect((p.world.get(entities[0]!, p.Fade) as { alpha: number }).alpha).toBeCloseTo(0.09, 10);
+ });
+});