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): the runtime says how its twins are called, not the runner

yhhf0d2b2f6dc24
diff --git a/sdk/src/ecs/aot/AotRuntime.ts b/sdk/src/ecs/aot/AotRuntime.ts
index da60f4049..5d720059e 100644
--- a/sdk/src/ecs/aot/AotRuntime.ts
+++ b/sdk/src/ecs/aot/AotRuntime.ts
@@ -15,8 +15,9 @@
*/
import type { AnyComponentDef } from '../component';
+import type { World } from '../world';
import type { AotContext } from './AotContext';
-import type { AotSystems } from './AotSystems';
+import type { AotSystems, AotTwin } from './AotSystems';
/** Where the bytes are, in the memory the compiled code reads. */
export interface AotAddresses {
@@ -42,6 +43,17 @@ export interface AotAddresses {
componentNamed(name: string): AnyComponentDef | undefined;
}
+/**
+ * One twin's frame, whoever lays the rows out.
+ *
+ * A wasm module shares the engine's memory, so they go HERE and the call takes
+ * their address. A host loading a library has 64-bit addresses nothing here can
+ * hold, so it packs them itself and takes only which system to run.
+ */
+export interface AotDispatcher {
+ run(twin: AotTwin): void;
+}
+
/**
* Installed by a shipping build, absent everywhere else. That absence is the
* whole of the mode policy: with no twins there is nothing to dispatch to, so
@@ -51,4 +63,10 @@ export interface AotRuntime {
readonly systems: AotSystems;
readonly addresses: AotAddresses;
readonly ctx: AotContext;
+ /**
+ * How this runtime's twins are called, for the world that will call them.
+ * The runtime decides, because it is what knows where the rows can live —
+ * the runner asking would be the runner knowing which host it is on.
+ */
+ dispatcherFor(world: World): AotDispatcher;
}
diff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.ts
index ace07c91e..d497dab0c 100644
--- a/sdk/src/ecs/aot/AotSystems.ts
+++ b/sdk/src/ecs/aot/AotSystems.ts
@@ -105,10 +105,17 @@ export class AotSystems {
* from the manifest: a manifest compared against itself always agrees.
*/
resourceFields: (name: string) => readonly string[] | undefined = () => [],
+ /**
+ * `sizeof(es_addr_t)` where this module will run: 4 in a wasm module
+ * addressing the engine's memory by offset, 8 in a library the host
+ * loaded into its own process. The digest carries it, so asking for
+ * the wrong one is the refusal it is supposed to be.
+ */
+ addressBytes: 4 | 8 = 4,
): void {
// Two questions with two fixes, so two answers rather than one that can
// only say "something moved".
- const engine = engineAbiDigest(4);
+ const engine = engineAbiDigest(addressBytes);
if (manifest.engineAbi !== engine) {
throw new Error(
`AOT module refused: built for engine ${manifest.engineAbi}, this is ${engine}. `
diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.ts
index 9c02faec1..8ee314c9d 100644
--- a/sdk/src/ecs/aot/installAot.ts
+++ b/sdk/src/ecs/aot/installAot.ts
@@ -31,6 +31,7 @@ import { AotResources, type ResourceReader } from './AotResources';
import { AotEvents, type EventBusAccess } from './AotEvents';
import { AotSystems, type AotManifest } from './AotSystems';
import type { AotAddresses, AotRuntime } from './AotRuntime';
+import { AotDispatch } from './AotDispatch';
/**
* The engine module a compiled system shares memory with. The Memory OBJECT,
@@ -99,13 +100,17 @@ export async function prepareAot(opts: Omit<InstallAotOptions, 'runner'>): Promi
return value === undefined ? undefined : Object.keys(value);
}));
- return {
+ const runtime: AotRuntime = {
systems,
addresses: worldAddresses(
new AotResources(memory, opts.resources, declaredLayouts(opts.manifest)),
new AotEvents(memory, opts.events ?? (() => undefined))),
ctx: new AotContext(memory),
+ // This module shares the engine's memory, so the rows go there and the
+ // call takes their address.
+ dispatcherFor: (world) => new AotDispatch(world, runtime),
};
+ return runtime;
}
/**
diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.ts
index 71a48193c..a04fe7caa 100644
--- a/sdk/src/ecs/system.ts
+++ b/sdk/src/ecs/system.ts
@@ -17,8 +17,7 @@ import {
} from './event';
import type { Entity } from '../types';
import type { World } from './world';
-import { AotDispatch } from './aot/AotDispatch';
-import type { AotRuntime } from './aot/AotRuntime';
+import type { AotDispatcher, AotRuntime } from './aot/AotRuntime';
import type { AotTwin } from './aot/AotSystems';
// =============================================================================
@@ -417,9 +416,9 @@ export class SystemRunner {
* there is nothing to dispatch to.
*/
private aot_: AotRuntime | null = null;
- /** The compiled half of this runner: everything a twin needs around its call
- * (docs/REARCH_AOT_ABI.md §2.1), and the plans that keep it off the frame. */
- private aotDispatch_: AotDispatch | null = null;
+ /** The compiled half of this runner: everything a twin needs around its
+ * call, from whichever side of the contract can lay the rows out. */
+ private aotDispatch_: AotDispatcher | null = null;
constructor(world: World, resources: ResourceStorage, eventRegistry?: EventRegistry) {
this.world_ = world;
@@ -430,7 +429,7 @@ export class SystemRunner {
/** @internal Install the twins a build produced. */
useAot(runtime: AotRuntime | null): void {
this.aot_ = runtime;
- this.aotDispatch_ = runtime ? new AotDispatch(this.world_, runtime) : null;
+ this.aotDispatch_ = runtime ? runtime.dispatcherFor(this.world_) : null;
}
setTimingEnabled(enabled: boolean): void {
diff --git a/sdk/tests/aot-dispatch.test.ts b/sdk/tests/aot-dispatch.test.ts
index 9a3da519a..95798c05f 100644
--- a/sdk/tests/aot-dispatch.test.ts
+++ b/sdk/tests/aot-dispatch.test.ts
@@ -28,6 +28,7 @@ import { WasmPoolMemory, type WasmHeap } from '../src/ecs/WasmPoolMemory';
import { AotContext } from '../src/ecs/aot/AotContext';
import { AotSystems, type AotManifest } from '../src/ecs/aot/AotSystems';
import type { AotAddresses, AotRuntime } from '../src/ecs/aot/AotRuntime';
+import { AotDispatch } from '../src/ecs/aot/AotDispatch';
import type { AnyComponentDef } from '../src/ecs/component';
import { engineAbiDigest, projectShapeDigest } from '../src/ecs/aot/abiDigest';
import type { Entity } from '../src/types';
@@ -182,7 +183,10 @@ describe('the scheduler and its compiled twin', () => {
componentNamed: (name) => (name === 'Decay' ? b.Decay : undefined),
resourceAt: () => undefined,
};
- const runtime: AotRuntime = { systems, addresses, ctx: new AotContext(memory) };
+ const runtime: AotRuntime = {
+ systems, addresses, ctx: new AotContext(memory),
+ dispatcherFor: (w) => new AotDispatch(w, runtime),
+ };
b.runner.useAot(runtime);
for (let f = 0; f < FRAMES; f++) b.runner.run(b.system);
@@ -231,14 +235,16 @@ describe('the scheduler and its compiled twin', () => {
queries: [[{ comp: 'Decay', mut: true }]], resources: [],
}],
}, exports, (name) => (name === 'Decay' ? w.Decay : undefined));
- w.runner.useAot({
+ const runtime: AotRuntime = {
systems,
addresses: {
componentNamed: (name) => (name === 'Decay' ? w.Decay : undefined),
resourceAt: () => undefined,
},
ctx: new AotContext(memory),
- });
+ dispatcherFor: (world) => new AotDispatch(world, runtime),
+ };
+ w.runner.useAot(runtime);
}
for (let f = 0; f < 4; f++) {
w.world.advanceTick();
diff --git a/sdk/tests/aot-dispatcher-seam.test.ts b/sdk/tests/aot-dispatcher-seam.test.ts
new file mode 100644
index 000000000..c4246f817
--- /dev/null
+++ b/sdk/tests/aot-dispatcher-seam.test.ts
@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file aot-dispatcher-seam.test.ts
+ * @brief The runner drives a twin whose rows were laid out somewhere else.
+ *
+ * @details A wasm module shares the engine's memory, so `AotDispatch` packs the
+ * rows here and hands the call their address. A host that loads a
+ * library has 64-bit addresses and a heap nothing here can see, so it
+ * packs them itself and takes only which system to run.
+ *
+ * One interface either way, and this is what says so: a runtime whose
+ * dispatcher is neither `AotDispatch` nor backed by any wasm memory,
+ * driven by the same scheduler. Without it the seam is an interface
+ * with one implementation, which is a decision nobody has made yet.
+ */
+import { describe, it, expect } from 'vitest';
+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 { AotSystems, type AotManifest, type AotTwin } from '../src/ecs/aot/AotSystems';
+import { engineAbiDigest, projectShapeDigest } from '../src/ecs/aot/abiDigest';
+import type { AotContext, AotRuntime } from '../src/ecs/aot/AotRuntime';
+
+const Drift = defineComponent('Drift', { x: 0 });
+
+/** A library in the host's own process, so an address is a pointer. The JS
+ * side still checks the handshake — it just checks the OTHER width. */
+const NATIVE_ADDR = 8;
+
+const MANIFEST: AotManifest = {
+ engineAbi: engineAbiDigest(NATIVE_ADDR),
+ projectShapes: projectShapeDigest([{ name: 'Drift', fields: ['x'] }]),
+ systems: [{
+ name: 'DriftSystem',
+ symbol: 'es_sys_Drift',
+ queries: [[{ comp: 'Drift', mut: true }]],
+ resources: [],
+ }],
+};
+
+/**
+ * A host that owns the row table. It never touches the twin's `call`, because
+ * on that side the export is a native function pointer and calling it is the
+ * host's job — here it stands in for one and moves the world directly.
+ */
+class HostPackedDispatcher {
+ readonly ran: string[] = [];
+ constructor(private readonly world: World) {}
+ run(twin: AotTwin): void {
+ this.ran.push(twin.decl.name);
+ for (const e of this.world.queryEntities([Drift])) {
+ this.world.set(e, Drift, { x: this.world.get(e, Drift).x + 1 });
+ }
+ }
+}
+
+/** A runtime with no wasm anything: what a native install would hand the runner. */
+function hostRuntime(world: World, seen: { dispatcher?: HostPackedDispatcher }): AotRuntime {
+ const systems = new AotSystems();
+ // The export table is what a loader resolved. A native one holds function
+ // pointers; the shape the runner sees is the same either way.
+ systems.install(
+ MANIFEST,
+ { es_sys_Drift: () => { throw new Error('the host calls it, not the runner'); } },
+ (name) => (name === 'Drift' ? Drift : undefined),
+ () => [],
+ NATIVE_ADDR,
+ );
+ return {
+ systems,
+ addresses: { componentNamed: () => Drift, resourceAt: () => undefined } as AotRuntime['addresses'],
+ // Never read: the ctx is where JS lays a call out, and this host lays it
+ // out on its own side. Typed rather than optional, because a runtime that
+ // could omit it would let the wasm path omit it too.
+ ctx: null as unknown as AotContext,
+ dispatcherFor: (w) => {
+ const d = new HostPackedDispatcher(w);
+ seen.dispatcher = d;
+ return d;
+ },
+ };
+}
+
+describe('the scheduler and a host that packs its own rows', () => {
+ it('asks the runtime which dispatcher, and drives the twin through it', () => {
+ const world = new World();
+ const runner = new SystemRunner(world, new ResourceStorage());
+ const system = defineSystem([Query(Mut(Drift))], () => {
+ throw new Error('the closure must not run when a twin exists');
+ }, { name: 'DriftSystem' });
+
+ const entity = world.spawn();
+ world.insert(entity, Drift, { x: 0 });
+
+ const seen: { dispatcher?: HostPackedDispatcher } = {};
+ runner.useAot(hostRuntime(world, seen));
+ runner.run(system);
+
+ expect(seen.dispatcher, 'the runner never asked for a dispatcher').toBeDefined();
+ expect(seen.dispatcher!.ran).toEqual(['DriftSystem']);
+ // The world moved, and it moved because the DISPATCHER moved it — the
+ // interpreted closure throws and the export throws.
+ expect(world.get(entity, Drift).x).toBe(1);
+ });
+
+ it('and stops when the twins are taken away, without a wasm heap ever existing', () => {
+ const world = new World();
+ const runner = new SystemRunner(world, new ResourceStorage());
+ let ran = 0;
+ const system = defineSystem([Query(Mut(Drift))], () => { ran++; }, { name: 'DriftSystem' });
+
+ const entity = world.spawn();
+ world.insert(entity, Drift, { x: 0 });
+
+ runner.useAot(hostRuntime(world, {}));
+ runner.run(system);
+ expect(world.get(entity, Drift).x).toBe(1);
+ expect(ran).toBe(0);
+
+ // Uninstalled, the same system is an ordinary closure again. This is the
+ // fallback the whole design rests on, on the side that has no module.
+ runner.useAot(null);
+ runner.run(system);
+ expect(ran).toBe(1);
+ expect(world.get(entity, Drift).x).toBe(1);
+ });
+});
diff --git a/sdk/tests/aot-row-cache.test.ts b/sdk/tests/aot-row-cache.test.ts
index f31b3e4ac..40e72c104 100644
--- a/sdk/tests/aot-row-cache.test.ts
+++ b/sdk/tests/aot-row-cache.test.ts
@@ -124,9 +124,11 @@ function harness(options: { epochBinding?: boolean } = {}) {
systems,
addresses: { componentNamed: () => Transform as unknown as AnyComponentDef, resourceAt: () => undefined },
ctx,
+ // The wasm side of the contract: the rows go in the memory the module
+ // shares, which is what this file is about.
+ dispatcherFor: (w) => new AotDispatch(w, runtime),
};
runner.useAot(runtime);
- void new AotDispatch(world, runtime);
const spawn = (): Entity => {
const entity = world.spawn();