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): 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.tsindex 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.tsindex 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.tsindex 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'>): Promireturn 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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();