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): the scheduler runs the compiled twin
yhhf2c364327e21
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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) => voidclearTimings: () => voidevict: (systemId: symbol) => voidgetQueryCosts: () => 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) => voiddespawn: (entity: Entity) => voidentityCount: () => numberfindEntityByName: (name: string) => Entity | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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) => voidclearTimings: () => voidevict: (systemId: symbol) => voidgetQueryCosts: () => 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) => voiddespawn: (entity: Entity) => voidentityCount: () => numberfindEntityByName: (name: string) => Entity | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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) => voidclearTimings: () => voidevict: (systemId: symbol) => voidgetQueryCosts: () => 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) => voiddespawn: (entity: Entity) => voidentityCount: () => numberfindEntityByName: (name: string) => Entity | nulldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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) => voidclearTimings: () => voidevict: (systemId: symbol) => voidgetQueryCosts: () => 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) => voiddespawn: (entity: Entity) => voidentityCount: () => numberfindEntityByName: (name: string) => Entity | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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) => voidclearTimings: () => voidevict: (systemId: symbol) => voidgetQueryCosts: () => 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) => voiddespawn: (entity: Entity) => voidentityCount: () => numberfindEntityByName: (name: string) => Entity | nulldiff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.tsindex 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.tsindex 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 yetthis.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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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'/);+ });+});