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): the scheduler runs the compiled twin

yhhf2c364327e21
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index e439d0b91..b79b2db58 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -7657,6 +7657,7 @@ touches: SystemTouches | (() => SystemTouches) | undefined
## SystemRunner — class @experimental
```
+@internal useAot: (runtime: AotRuntime | null) => void
clearTimings: () => void
evict: (systemId: symbol) => void
getQueryCosts: () => ReadonlyMap<string, QueryCost> | null
@@ -9250,6 +9251,7 @@ tabIndex: number | undefined
## World — class @public
```
+@internal addressOfScriptComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@@ -9270,6 +9272,7 @@ tabIndex: number | undefined
@internal getWorldVersion: () => number
@internal hasCpp: boolean
@internal isAddedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
+@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@@ -9285,6 +9288,7 @@ tabIndex: number | undefined
@internal resumeIteration: (depth: number) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
+@internal useScriptPoolMemory: (memory: PoolMemory) => void
despawn: (entity: Entity) => void
entityCount: () => number
findEntityByName: (name: string) => Entity | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 2a4b292ba..03218d1d6 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -7850,6 +7850,7 @@ touches: SystemTouches | (() => SystemTouches) | undefined
## SystemRunner — class @experimental
```
+@internal useAot: (runtime: AotRuntime | null) => void
clearTimings: () => void
evict: (systemId: symbol) => void
getQueryCosts: () => ReadonlyMap<string, QueryCost> | null
@@ -9443,6 +9444,7 @@ tabIndex: number | undefined
## World — class @public
```
+@internal addressOfScriptComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@@ -9463,6 +9465,7 @@ tabIndex: number | undefined
@internal getWorldVersion: () => number
@internal hasCpp: boolean
@internal isAddedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
+@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@@ -9478,6 +9481,7 @@ tabIndex: number | undefined
@internal resumeIteration: (depth: number) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
+@internal useScriptPoolMemory: (memory: PoolMemory) => void
despawn: (entity: Entity) => void
entityCount: () => number
findEntityByName: (name: string) => Entity | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 04b80ad34..ba913dacf 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -7652,6 +7652,7 @@ touches: SystemTouches | (() => SystemTouches) | undefined
## SystemRunner — class @experimental
```
+@internal useAot: (runtime: AotRuntime | null) => void
clearTimings: () => void
evict: (systemId: symbol) => void
getQueryCosts: () => ReadonlyMap<string, QueryCost> | null
@@ -9245,6 +9246,7 @@ tabIndex: number | undefined
## World — class @public
```
+@internal addressOfScriptComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@@ -9265,6 +9267,7 @@ tabIndex: number | undefined
@internal getWorldVersion: () => number
@internal hasCpp: boolean
@internal isAddedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
+@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@@ -9280,6 +9283,7 @@ tabIndex: number | undefined
@internal resumeIteration: (depth: number) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
+@internal useScriptPoolMemory: (memory: PoolMemory) => void
despawn: (entity: Entity) => void
entityCount: () => number
findEntityByName: (name: string) => Entity | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index a4d9a517e..e68c81f7f 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -7897,6 +7897,7 @@ touches: SystemTouches | (() => SystemTouches) | undefined
## SystemRunner — class @experimental
```
+@internal useAot: (runtime: AotRuntime | null) => void
clearTimings: () => void
evict: (systemId: symbol) => void
getQueryCosts: () => ReadonlyMap<string, QueryCost> | null
@@ -9496,6 +9497,7 @@ tabIndex: number | undefined
## World — class @public
```
+@internal addressOfScriptComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@@ -9516,6 +9518,7 @@ tabIndex: number | undefined
@internal getWorldVersion: () => number
@internal hasCpp: boolean
@internal isAddedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
+@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@@ -9531,6 +9534,7 @@ tabIndex: number | undefined
@internal resumeIteration: (depth: number) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
+@internal useScriptPoolMemory: (memory: PoolMemory) => void
despawn: (entity: Entity) => void
entityCount: () => number
findEntityByName: (name: string) => Entity | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d1dc89eed..a3f2320a3 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -7659,6 +7659,7 @@ touches: SystemTouches | (() => SystemTouches) | undefined
## SystemRunner — class @experimental
```
+@internal useAot: (runtime: AotRuntime | null) => void
clearTimings: () => void
evict: (systemId: symbol) => void
getQueryCosts: () => ReadonlyMap<string, QueryCost> | null
@@ -9272,6 +9273,7 @@ tabIndex: number | undefined
## World — class @public
```
+@internal addressOfScriptComponent: (component: AnyComponentDef, entity: Entity) => number | undefined
@internal advanceTick: () => void
@internal anyChangedSince: (component: AnyComponentDef, sinceTick: number) => boolean
@internal applyEntityOrder: (entities: readonly Entity[]) => void
@@ -9292,6 +9294,7 @@ tabIndex: number | undefined
@internal getWorldVersion: () => number
@internal hasCpp: boolean
@internal isAddedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
+@internal isChangeTracked: (component: AnyComponentDef) => boolean
@internal isChangedSince: (entity: Entity, component: AnyComponentDef, sinceTick: number) => boolean
@internal isIterating: () => boolean
@internal markChanged: (entity: Entity, component: AnyComponentDef) => void
@@ -9307,6 +9310,7 @@ tabIndex: number | undefined
@internal resumeIteration: (depth: number) => void
@internal setQueryCostEnabled: (enabled: boolean) => void
@internal suspendIteration: () => number
+@internal useScriptPoolMemory: (memory: PoolMemory) => void
despawn: (entity: Entity) => void
entityCount: () => number
findEntityByName: (name: string) => Entity | null
diff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.ts
index 3a9ac2c63..0bdc1fc69 100644
--- a/sdk/src/ecs/ChangeTracker.ts
+++ b/sdk/src/ecs/ChangeTracker.ts
@@ -87,6 +87,15 @@ export class ChangeTracker {
map.set(entity, this.worldTick_);
}
+ /**
+ * Whether anything is asking about this component's changes. `recordChanged`
+ * self-gates on the same answer; this exists so a caller marking a whole
+ * query's worth of entities can ask ONCE instead of per entity.
+ */
+ isTracked(component: AnyComponentDef): boolean {
+ return this.trackedComponents_.has(component._id);
+ }
+
recordChanged(component: AnyComponentDef, entity: Entity): void {
if (!this.trackedComponents_.has(component._id)) return;
let map = this.componentChangedTicks_.get(component._id);
diff --git a/sdk/src/ecs/aot/AotContext.ts b/sdk/src/ecs/aot/AotContext.ts
index 08899ae0c..1fdc4669c 100644
--- a/sdk/src/ecs/aot/AotContext.ts
+++ b/sdk/src/ecs/aot/AotContext.ts
@@ -112,6 +112,7 @@ export class AotContext {
w[5] = 0; // events: no channel carries one yet
this.countAt_ = countAt;
this.cmdAt_ = cmdBuf;
+ this.address_ = base;
return base;
}
@@ -130,6 +131,12 @@ export class AotContext {
private countAt_ = 0;
private cmdAt_ = 0;
+ private address_ = 0;
+
+ /** The ctx `build` last laid out. */
+ get address(): number {
+ return this.address_;
+ }
private reserve_(words: number): void {
if (this.block !== null && words * 4 <= this.block.byteLength) {
diff --git a/sdk/src/ecs/aot/AotRuntime.ts b/sdk/src/ecs/aot/AotRuntime.ts
new file mode 100644
index 000000000..c67b72248
--- /dev/null
+++ b/sdk/src/ecs/aot/AotRuntime.ts
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AotRuntime.ts
+ * @brief What the runner needs to call a twin instead of a closure.
+ *
+ * @details Three things, and no more: which twins exist, where a component's and
+ * a resource's bytes are, and one arena to lay a call out in.
+ *
+ * Addresses are asked for by DEFINITION and by NAME rather than
+ * resolved here, because where a component lives depends on which kind
+ * it is — an engine component is at an EHT offset in the C++ pools, a
+ * `defineComponent` one is a row in a `ScriptPool` — and that is the
+ * storage layer's knowledge, not this one's.
+ */
+
+import type { AnyComponentDef } from '../component';
+import type { Entity } from '../../types';
+import type { AotContext } from './AotContext';
+import type { AotSystems } from './AotSystems';
+
+/** Where the bytes are, in the memory the compiled code reads. */
+export interface AotAddresses {
+ /** `component`'s bytes for `entity`, or undefined when it has none. */
+ componentAt(component: AnyComponentDef, entity: Entity): number | undefined;
+ /**
+ * The named resource's bytes, ready for THIS call. A resource is a host
+ * record with no address of its own, so an implementation mirrors it — and
+ * doing that per call rather than per row is why it is one call.
+ */
+ resourceAt(name: string): number | undefined;
+ /** The definition a manifest's component NAME refers to in this world. */
+ componentNamed(name: string): AnyComponentDef | undefined;
+}
+
+/**
+ * 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
+ * the editor and dev builds need no flag and take no branch worth measuring
+ * (docs/REARCH_AOT.md §9).
+ */
+export interface AotRuntime {
+ readonly systems: AotSystems;
+ readonly addresses: AotAddresses;
+ readonly ctx: AotContext;
+}
diff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.ts
new file mode 100644
index 000000000..836413290
--- /dev/null
+++ b/sdk/src/ecs/aot/AotSystems.ts
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AotSystems.ts
+ * @brief The compiled twins a build produced, and how a system finds its own.
+ *
+ * @details `REARCH_AOT.md` §9 settles when a twin is used: the editor's preview
+ * always interprets, and AOT is a shipping mode. So the runner has one
+ * rule — call the twin if there IS one — and the decision lives in who
+ * installs, which is the build, once, at load.
+ *
+ * Installing verifies the handshake first (§2.5). A module whose
+ * contract hash disagrees is REFUSED, not warned about: mismatched
+ * offsets do not produce an error, they produce a read of a different
+ * field.
+ */
+
+import type { AnyComponentDef } from '../component';
+
+/** One system's declaration, as the build wrote it beside the module. */
+export interface AotSystemDecl {
+ readonly name: string;
+ readonly symbol: string;
+ /** One entry per declared Query, in the order the system names them. */
+ readonly queries: readonly (readonly { comp: string; mut: boolean }[])[];
+ readonly resources: readonly string[];
+}
+
+export interface AotManifest {
+ readonly contractHash: string;
+ readonly systems: readonly AotSystemDecl[];
+}
+
+/** A twin, resolved: its declaration and the function that runs it. */
+export interface AotTwin {
+ readonly decl: AotSystemDecl;
+ readonly call: (ctx: number) => void;
+ /** The components this system may write, for the Changed bookkeeping the
+ * compiled code cannot do — it never calls back. */
+ readonly mutated: readonly (readonly AnyComponentDef[])[];
+}
+
+/**
+ * The twins available to a world. Empty in the editor and in dev, which is why
+ * dispatch needs no mode flag: there is simply nothing to find.
+ */
+export class AotSystems {
+ private readonly byName = new Map<string, AotTwin>();
+
+ get size(): number {
+ return this.byName.size;
+ }
+
+ /**
+ * Take a built module. `expectedHash` is what this SDK's own contract
+ * computes; a module that disagrees is refused.
+ *
+ * `resolve` turns a component NAME into the definition this world uses,
+ * because the manifest carries names — a build cannot know a runtime's ids.
+ */
+ install(
+ manifest: AotManifest,
+ exports: Readonly<Record<string, unknown>>,
+ expectedHash: string,
+ resolve: (name: string) => AnyComponentDef | undefined,
+ ): void {
+ if (manifest.contractHash !== expectedHash) {
+ throw new Error(
+ `AOT module refused: contract ${manifest.contractHash} but this engine has `
+ + `${expectedHash}. The offsets would not line up, and a wrong offset reads a `
+ + 'different field rather than failing.');
+ }
+ for (const decl of manifest.systems) {
+ const call = exports[decl.symbol];
+ if (typeof call !== 'function') {
+ throw new Error(`AOT module refused: it declares '${decl.name}' but exports no `
+ + `'${decl.symbol}'`);
+ }
+ const mutated = decl.queries.map((q) => q
+ .filter((a) => a.mut)
+ .map((a) => resolve(a.comp))
+ .filter((c): c is AnyComponentDef => c !== undefined));
+ this.byName.set(decl.name, {
+ decl, mutated, call: call as (ctx: number) => void,
+ });
+ }
+ }
+
+ get(name: string): AotTwin | undefined {
+ return this.byName.get(name);
+ }
+
+ clear(): void {
+ this.byName.clear();
+ }
+}
diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.ts
index cd4dd3913..6958fb7d7 100644
--- a/sdk/src/ecs/system.ts
+++ b/sdk/src/ecs/system.ts
@@ -15,7 +15,11 @@ import {
EventWriterInstance, EventReaderInstance,
EventRegistry,
} from './event';
+import type { Entity } from '../types';
import type { World } from './world';
+import { CMD_DESPAWN, type AotRow } from './aot/AotContext';
+import type { AotRuntime } from './aot/AotRuntime';
+import type { AotTwin } from './aot/AotSystems';
// =============================================================================
// Schedule Phases
@@ -401,12 +405,24 @@ export class SystemRunner {
private timings_: Map<string, number> | null = null;
private queryCosts_: Map<string, QueryCost> | null = null;
+ /**
+ * Compiled twins, when a shipping build installed them. Absent in the editor
+ * and in dev, which is the whole of the mode policy — with nothing installed
+ * there is nothing to dispatch to (docs/REARCH_AOT.md §9).
+ */
+ private aot_: AotRuntime | null = null;
+
constructor(world: World, resources: ResourceStorage, eventRegistry?: EventRegistry) {
this.world_ = world;
this.resources_ = resources;
this.eventRegistry_ = eventRegistry ?? null;
}
+ /** @internal Install the twins a build produced. */
+ useAot(runtime: AotRuntime | null): void {
+ this.aot_ = runtime;
+ }
+
setTimingEnabled(enabled: boolean): void {
this.timings_ = enabled ? new Map() : null;
this.queryCosts_ = enabled ? new Map() : null;
@@ -449,6 +465,11 @@ export class SystemRunner {
}
run(system: SystemDef): void | Promise<void> {
+ const twin = this.aot_?.systems.get(system._name);
+ if (twin) {
+ this.runCompiled_(system, twin);
+ return;
+ }
let args = this.argsCache_.get(system._id);
if (!args) {
args = new Array(system._params.length);
@@ -533,6 +554,75 @@ export class SystemRunner {
this.flushSystem_(system, args, t0);
}
+ /**
+ * One call of the contract in place of the closure: materialise the rows,
+ * lay out a SysCtx, call the compiled symbol, apply what it recorded. The
+ * compiled code calls nothing, so everything it could not do is here — the
+ * commands it appended, and the Changed ticks a `Mut` implies.
+ */
+ private runCompiled_(system: SystemDef, twin: AotTwin): void {
+ const aot = this.aot_!;
+ const t0 = this.timings_ ? performance.now() : 0;
+
+ const queries: AotRow[][] = [];
+ for (const args of twin.decl.queries) {
+ const comps: AnyComponentDef[] = [];
+ for (const a of args) {
+ const def = aot.addresses.componentNamed(a.comp);
+ if (def) comps.push(def);
+ }
+ const rows: AotRow[] = [];
+ if (comps.length === args.length) {
+ for (const entity of this.world_.getEntitiesWithComponents(comps)) {
+ const row: number[] = [entity as unknown as number];
+ let whole = true;
+ for (const def of comps) {
+ const at = aot.addresses.componentAt(def, entity);
+ // A query that matched but whose storage cannot answer is
+ // not a row. Reading zero would be a read of address zero.
+ if (at === undefined) { whole = false; break; }
+ row.push(at);
+ }
+ if (whole) rows.push(row);
+ }
+ }
+ queries.push(rows);
+ }
+
+ const resources = twin.decl.resources.map((name) => aot.addresses.resourceAt(name) ?? 0);
+ aot.ctx.build(queries, resources);
+ twin.call(aot.ctx.address);
+
+ for (const cmd of aot.ctx.commands()) {
+ // Only despawn is in the v1 record set (REARCH_AOT_ABI.md §2.3).
+ if (cmd.kind === CMD_DESPAWN) this.world_.despawn(cmd.a as unknown as Entity);
+ }
+ this.markCompiledChanges_(twin, queries);
+
+ if (this.timings_) {
+ const name = system._name;
+ this.timings_.set(name, (this.timings_.get(name) ?? 0) + (performance.now() - t0));
+ }
+ this.systemTicks_.set(system._id, this.world_.getWorldTick());
+ }
+
+ /**
+ * The Changed ticks the compiled code could not record. Asked ONCE per
+ * component rather than per entity: `recordChanged` self-gates on the same
+ * answer, and on the hot path with nothing listening this is where a
+ * per-row loop would have been spent for nothing.
+ */
+ private markCompiledChanges_(twin: AotTwin, queries: readonly AotRow[][]): void {
+ twin.mutated.forEach((comps, k) => {
+ const rows = queries[k];
+ if (!rows || rows.length === 0) return;
+ for (const def of comps) {
+ if (!this.world_.isChangeTracked(def)) continue;
+ for (const row of rows) this.world_.markChanged(row[0] as unknown as Entity, def);
+ }
+ });
+ }
+
private flushSystem_(system: SystemDef, args: unknown[], t0: number): void {
for (let i = 0; i < args.length; i++) {
if (args[i] instanceof CommandsInstance) {
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index 3236a94aa..ccc4a1938 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -11,6 +11,7 @@ import type { CppRegistry, ESEngineModule } from '../wasm';
import { handleWasmError } from '../wasm/wasmError';
import { BuiltinBridge, convertFromWasm, convertForWasm, type BridgeConnectOptions, type BuiltinMethods } from './bridge/BuiltinBridge';
import { ScriptStorage } from './ScriptStorage';
+import type { PoolMemory } from './ScriptPool';
import { NameIndex } from './NameIndex';
import { ChangeTracker } from './ChangeTracker';
import { QueryCache, type QueryCacheStats } from './QueryCache';
@@ -1156,4 +1157,28 @@ export class World {
markChanged(entity: Entity, component: AnyComponentDef): void {
this.changes_.recordChanged(component, entity);
}
+
+ /** @internal Whether any query is asking about `component`'s changes. */
+ isChangeTracked(component: AnyComponentDef): boolean {
+ return this.changes_.isTracked(component);
+ }
+
+ /**
+ * @internal Where script-component rows are allocated from. A wasm runtime
+ * installs linear memory here BEFORE any component is added, because
+ * compiled code cannot reach a JS-heap array (docs/REARCH_AOT_ABI.md §2.4).
+ */
+ useScriptPoolMemory(memory: PoolMemory): void {
+ this.scripts_.usePoolMemory(memory);
+ }
+
+ /**
+ * @internal `component`'s bytes for `entity`, in the memory the pool was
+ * allocated from — what a compiled system is handed. Undefined for a
+ * component with no flat rows, which is a component no system compiles
+ * against.
+ */
+ addressOfScriptComponent(component: AnyComponentDef, entity: Entity): number | undefined {
+ return this.scripts_.poolFor(component._id as symbol)?.address(entity);
+ }
}
diff --git a/sdk/tests/aot-dispatch.test.ts b/sdk/tests/aot-dispatch.test.ts
new file mode 100644
index 000000000..7f44135b1
--- /dev/null
+++ b/sdk/tests/aot-dispatch.test.ts
@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file aot-dispatch.test.ts
+ * @brief The scheduler runs a compiled twin, and the world comes out the same.
+ *
+ * @details The differential moved up one level. Everything before compared a
+ * compiled system against an oracle by hand; this schedules the SAME
+ * system twice — once as the TypeScript closure the author wrote, once
+ * as the twin a build produced — and requires the two worlds to agree.
+ *
+ * That is the shape of the pixel gate the roadmap ends at, minus the
+ * pixels: same project, two runs, and nothing may differ.
+ */
+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, Changed } from '../src/ecs/query';
+import { ResourceStorage } from '../src/ecs/resource';
+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 type { AnyComponentDef } from '../src/ecs/component';
+import type { Entity } from '../src/types';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const N = 20;
+const FRAMES = 10;
+const HASH = 'aabbccdd00112233';
+
+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();
+
+/** A linear memory and a bump allocator: the engine, as far as rows care. */
+class Heap 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 */ }
+}
+
+/** `Decay`: remaining -= rate, and despawn once it reaches zero. */
+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 { uint32_t kind, a, b, c; } EsCmd;
+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_Decay(es_addr_t ctx) {
+ const EsSysCtx *c = (const EsSysCtx *)ES_PTR(ctx);
+ const EsQueryRows *q = (const EsQueryRows *)ES_PTR(c->queries);
+ EsCmd *cmds = (EsCmd *)ES_PTR(c->cmdBuf);
+ uint32_t *count = (uint32_t *)ES_PTR(c->cmdCount);
+ uint32_t n = *count;
+ 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) {
+ const es_addr_t *row = rows + i * 2u;
+ unsigned char *m = ES_PTR(row[1]);
+ st(m, ld(m) - ld(m + 8)); /* remaining -= rate */
+ if (ld(m) <= 0.0 && n < (uint32_t)c->cmdCap) {
+ cmds[n].kind = 1u; cmds[n].a = (uint32_t)row[0];
+ cmds[n].b = 0u; cmds[n].c = 0u; n += 1u;
+ }
+ }
+ *count = n;
+}
+`;
+
+function buildModule(): Uint8Array {
+ const dir = mkdtempSync(path.join(tmpdir(), 'estella-dispatch-'));
+ 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_Decay',
+ '-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);
+}
+
+/**
+ * The system the author wrote. The twin is held against THIS, so the C above is
+ * the compiler's job to produce — here it stands in for what it produced.
+ */
+function makeWorld(): {
+ world: World; runner: SystemRunner; Decay: AnyComponentDef; system: ReturnType<typeof defineSystem>;
+} {
+ const world = new World();
+ const resources = new ResourceStorage();
+ const runner = new SystemRunner(world, resources);
+ const Decay = defineComponent('Decay', { remaining: 1, rate: 0.1 }) as AnyComponentDef;
+ const system = defineSystem([Query(Mut(Decay))], (query) => {
+ const doomed: Entity[] = [];
+ for (const [entity, decay] of query as Iterable<[Entity, { remaining: number; rate: number }]>) {
+ decay.remaining -= decay.rate;
+ if (decay.remaining <= 0) doomed.push(entity);
+ }
+ for (const entity of doomed) world.despawn(entity);
+ }, { name: 'Decay' });
+ return { world, runner, Decay, system };
+}
+
+function seed(world: World, Decay: AnyComponentDef): Entity[] {
+ const out: Entity[] = [];
+ for (let i = 1; i <= N; i++) {
+ const entity = world.spawn();
+ world.insert(entity, Decay, { remaining: i * 0.1, rate: 0.1 });
+ out.push(entity);
+ }
+ return out;
+}
+
+function snapshot(world: World, Decay: AnyComponentDef, entities: readonly Entity[]): string {
+ return entities
+ .filter((e) => world.valid(e) && world.has(e, Decay))
+ .map((e) => `${e}:${(world.get(e, Decay) as { remaining: number }).remaining}`)
+ .join(',');
+}
+
+describe('the scheduler and its compiled twin', () => {
+ it('reports whether this gate could run at all', () => {
+ if (EMCC) console.log('[aot-dispatch] the twin ran under the real runner');
+ else console.warn('[aot-dispatch] NO EMSDK — the dispatch did NOT run (pnpm emsdk:setup).');
+ expect(true).toBe(true);
+ });
+
+ it('with nothing installed there is nothing to dispatch to', () => {
+ const { runner, Decay, system, world } = makeWorld();
+ const entities = seed(world, Decay);
+ runner.useAot(null);
+ runner.run(system);
+ // The closure ran: this is the path every editor preview takes, and it
+ // must not have noticed that AOT exists.
+ expect((world.get(entities[9]!, Decay) as { remaining: number }).remaining)
+ .toBeCloseTo(0.9, 10);
+ });
+
+ it.skipIf(!EMCC)('the twin leaves the world the closure would have', async () => {
+ const bytes = buildModule();
+
+ // Interpreted.
+ const a = makeWorld();
+ const aEntities = seed(a.world, a.Decay);
+ for (let f = 0; f < FRAMES; f++) a.runner.run(a.system);
+
+ // Compiled, over rows in a linear memory the module shares.
+ const b = makeWorld();
+ const heap = new Heap();
+ const memory = new WasmPoolMemory(heap);
+ b.world.useScriptPoolMemory(memory);
+ const bEntities = seed(b.world, b.Decay);
+
+ const instance = await WebAssembly.instantiate(
+ new WebAssembly.Module(bytes as unknown as BufferSource),
+ { env: { memory: heap.memory } });
+ const exports = instance.exports as unknown as Record<string, unknown>;
+ (exports['_initialize'] as (() => void) | undefined)?.();
+
+ const manifest: AotManifest = {
+ contractHash: HASH,
+ systems: [{
+ name: 'Decay', symbol: 'es_sys_Decay',
+ queries: [[{ comp: 'Decay', mut: true }]], resources: [],
+ }],
+ };
+ const systems = new AotSystems();
+ systems.install(manifest, exports, HASH, (name) => (name === 'Decay' ? b.Decay : undefined));
+
+ const addresses: AotAddresses = {
+ componentNamed: (name) => (name === 'Decay' ? b.Decay : undefined),
+ componentAt: (comp, entity) => b.world.addressOfScriptComponent(comp, entity),
+ resourceAt: () => undefined,
+ };
+ const runtime: AotRuntime = { systems, addresses, ctx: new AotContext(memory) };
+ b.runner.useAot(runtime);
+
+ for (let f = 0; f < FRAMES; f++) b.runner.run(b.system);
+
+ expect(snapshot(b.world, b.Decay, bEntities)).toBe(snapshot(a.world, a.Decay, aEntities));
+ // A run where nothing despawned would compare two full worlds and prove
+ // only that neither moved.
+ expect(aEntities.filter((e) => a.world.valid(e)).length).toBeLessThan(N);
+ expect(aEntities.filter((e) => a.world.valid(e)).length).toBeGreaterThan(0);
+ });
+
+ it.skipIf(!EMCC)('a twin marks Changed, which it cannot do for itself', async () => {
+ // The compiled code calls nothing, so a `Mut` it honoured is invisible
+ // unless the host records it. A watcher is the only thing that can tell.
+ const bytes = buildModule();
+ const seen: number[] = [];
+
+ const build = async (compiled: boolean): Promise<number[]> => {
+ const w = makeWorld();
+ const watched: number[] = [];
+ const watcher = defineSystem([Query(Changed(w.Decay))], (query) => {
+ let n = 0;
+ for (const _ of query as Iterable<unknown>) n++;
+ watched.push(n);
+ }, { name: 'Watcher' });
+ const heap = new Heap();
+ const memory = new WasmPoolMemory(heap);
+ if (compiled) w.world.useScriptPoolMemory(memory);
+ seed(w.world, w.Decay);
+
+ if (compiled) {
+ const instance = await WebAssembly.instantiate(
+ new WebAssembly.Module(bytes as unknown as BufferSource),
+ { env: { memory: heap.memory } });
+ const exports = instance.exports as unknown as Record<string, unknown>;
+ (exports['_initialize'] as (() => void) | undefined)?.();
+ const systems = new AotSystems();
+ systems.install({
+ contractHash: HASH,
+ systems: [{
+ name: 'Decay', symbol: 'es_sys_Decay',
+ queries: [[{ comp: 'Decay', mut: true }]], resources: [],
+ }],
+ }, exports, HASH, (name) => (name === 'Decay' ? w.Decay : undefined));
+ w.runner.useAot({
+ systems,
+ addresses: {
+ componentNamed: (name) => (name === 'Decay' ? w.Decay : undefined),
+ componentAt: (c, e) => w.world.addressOfScriptComponent(c, e),
+ resourceAt: () => undefined,
+ },
+ ctx: new AotContext(memory),
+ });
+ }
+ for (let f = 0; f < 4; f++) {
+ w.world.advanceTick();
+ w.runner.run(w.system);
+ w.runner.run(watcher);
+ }
+ return watched;
+ };
+
+ const interpreted = await build(false);
+ const compiled = await build(true);
+ seen.push(...compiled);
+ expect(interpreted.some((n) => n > 0), 'the watcher never saw a change either way')
+ .toBe(true);
+ expect(compiled).toEqual(interpreted);
+ });
+
+ it('a module whose contract disagrees is refused, not warned about', () => {
+ const systems = new AotSystems();
+ const manifest: AotManifest = { contractHash: 'deadbeefdeadbeef', systems: [] };
+ expect(() => systems.install(manifest, {}, HASH, () => undefined))
+ .toThrow(/contract deadbeefdeadbeef but this engine has/);
+ expect(systems.size).toBe(0);
+ });
+
+ it('a manifest naming a symbol the module lacks is refused too', () => {
+ const systems = new AotSystems();
+ const manifest: AotManifest = {
+ contractHash: HASH,
+ systems: [{ name: 'Ghost', symbol: 'es_sys_Ghost', queries: [], resources: [] }],
+ };
+ expect(() => systems.install(manifest, {}, HASH, () => undefined))
+ .toThrow(/exports no 'es_sys_Ghost'/);
+ });
+});