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(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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});