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
fix(aot): the compiler's reach and the dispatcher's speed become one road
esengine0065c6e0cc73
diff --git a/compiler/tests/codegen.test.ts b/compiler/tests/codegen.test.tsindex 58dfcadf7..b6cf08bed 100644--- a/compiler/tests/codegen.test.ts+++ b/compiler/tests/codegen.test.ts@@ -39,6 +39,7 @@ import { inlineSystem } from '../src/inline';import { builtinShapes } from '../src/builtins';import { AbiMemory, flushCommands, materialize, packLayout, planFor, runOnAbi } from '../src/abi';import { CFLAGS, cSymbol, emitC, type CModule } from '../src/codegen';+import { findCC } from './hostCC';import { abiHashFor } from '../src/abi';import type { AbiLayout } from '../src/abi';import { F64, type EirSystem } from '../src/eir';@@ -57,32 +58,6 @@ const FRAMES = 12;/** Small enough that a frame is one cheap pipe, big enough for the world above. */const IMAGE = 1 << 16;-// =============================================================================-// finding a C compiler-// =============================================================================--/**- * clang first because it is what Stage 2 ships with — emcc is clang and the- * aarch64 path is clang. gcc is accepted, and is arguably the better witness:- * agreeing with a SECOND independent implementation of C says more than- * agreeing with the one the lowering was written against.- *- * The candidate has to BUILD something, not merely answer `--version`. emsdk's- * clang shadows the system one on PATH, reports `Target: unknown`, and answers- * `--version` with 0 while refusing every host compile — so the wrong probe- * reddens this differential on exactly the machines that can run AOT.- */-function findCC(): string | null {- const dir = mkdtempSync(join(tmpdir(), 'estella-cc-'));- const src = join(dir, 'probe.c');- writeFileSync(src, 'int main(void) { return 0; }\n');- for (const cc of ['clang', 'gcc', 'cc']) {- const out = spawnSync(cc, ['-std=c11', '-o', join(dir, `probe-${cc}`), src], { encoding: 'utf8' });- if (out.status === 0) return cc;- }- return null;-}-const CC = findCC();/** The harness: linear memory in on stdin, linear memory out on stdout. */diff --git a/compiler/tests/exact-trig.test.ts b/compiler/tests/exact-trig.test.tsindex b74623823..4154aa667 100644--- a/compiler/tests/exact-trig.test.ts+++ b/compiler/tests/exact-trig.test.ts@@ -22,13 +22,8 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import { CFLAGS, RUNTIME_H } from '../src/codegen';import { exact } from '../../sdk/src/math/exact';+import { findCC } from './hostCC';-function findCC(): string | null {- for (const cc of ['clang', 'gcc', 'cc']) {- if (spawnSync(cc, ['--version'], { encoding: 'utf8' }).status === 0) return cc;- }- return null;-}const CC = findCC();/** Where a range reduction, a quadrant choice or a polynomial could differ. */diff --git a/compiler/tests/hostCC.ts b/compiler/tests/hostCC.tsnew file mode 100644index 000000000..6cacb9114--- /dev/null+++ b/compiler/tests/hostCC.ts@@ -0,0 +1,33 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file hostCC.ts+ * @brief The host C compiler a differential needs, or nothing.+ *+ * @details clang first because it is what Stage 2 ships with — emcc is clang and+ * the aarch64 path is clang. gcc is accepted, and is arguably the better+ * witness: agreeing with a SECOND independent implementation of C says+ * more than agreeing with the one the lowering was written against.+ *+ * The candidate has to BUILD something, not merely answer `--version`.+ * emsdk's clang shadows the system one on PATH, reports `Target:+ * unknown`, and answers `--version` with 0 while refusing every host+ * compile — so the wrong probe reddens these differentials on exactly+ * the machines that can run AOT.+ */+import { spawnSync } from 'node:child_process';+import { mkdtempSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';++export function findCC(): string | null {+ const dir = mkdtempSync(join(tmpdir(), 'estella-cc-'));+ const src = join(dir, 'probe.c');+ writeFileSync(src, 'int main(void) { return 0; }\n');+ for (const cc of ['clang', 'gcc', 'cc']) {+ if (spawnSync(cc, ['-std=c11', '-o', join(dir, `probe-${cc}`), src], { encoding: 'utf8' }).status === 0) {+ return cc;+ }+ }+ return null;+}diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 65eb4de36..2cf06495b 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -2,11 +2,11 @@"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {"public": 113,- "beta": 71,- "experimental": 1651,+ "beta": 72,+ "experimental": 1652,"deprecated": 3},- "total": 1835,+ "total": 1837,"subsystems": [{"id": "ecs",@@ -2448,6 +2448,18 @@"minigame"]},+ {+ "name": "exact",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "installNativePlatform","kind": "function",diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 08f8d6c72..719c4ab09 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -21,7 +21,6 @@*/import type { BuildOptions, Plugin } from 'esbuild';import { loadEsbuild } from '../bundle/esbuildRuntime';-import { spawn } from 'node:child_process';import { writeFile, readFile, mkdir, cp, readdir, rm } from 'node:fs/promises';import { existsSync } from 'node:fs';import path from 'node:path';@@ -41,8 +40,7 @@ import { genericPlayableProfile, type PlayableAdProfile } from './playableAdProfimport type { OnExportProgress } from './exportProgress';import { ESENGINE_EXTERNAL } from '../bundle/esengineResolve';import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSystems';-import { AOT_MANIFEST, AOT_WASM } from '../bundle/aotArtifacts';-import { emccPath } from '../../../build-tools/utils/emscripten.js';+import { resolveEmcc, runEmcc } from '../bundle/emccPath';import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';import { orientationCss, orientationOverlayHtml, orientationLockScript, orientationLockCspHash, type ScreenOrientation } from './orientationHtml';import { emitIosXcodeProject, type IosProjectSources } from '../../../build-tools/utils/iosProject.js';@@ -60,8 +58,6 @@ import { measureBuild, type BuildSizeReport } from './sizeReport';import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';import { collectSubsystems, subsystemGapWarnings, targetGaps, type Subsystem } from '../project/targetSupport';import { scanSideModuleIds, sideModuleFiles, shipsSideModule } from '../bundle/sideModuleScan';-import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSystems';-import { resolveEmcc, runEmcc } from '../bundle/emccPath';export type { ExportPlatform };/**@@ -419,9 +415,6 @@ export interface ExportGameOptions {/** `packaging.sizeBudget[platform]` — the project's own package-size ceiling in* bytes, replacing whatever limit the target declares. See sizeBudget.ts. */sizeBudgetBytes?: number;- /** Whether a `@compiled` marker is collected on. Default `release`, because an- * export IS the shipping build; `dev` skips the toolchain entirely. */- aot?: BuildMode;}/**@@ -500,16 +493,6 @@ async function attachSizeReport(result: ExportGameResult, opts: ExportGameOption}}-/** emcc, as buildCompiledSystems wants it: a .bat on Windows, so through a shell. */-function runEmcc(cmd: string, args: string[], cwd: string): Promise<{ code: number; stderr: string }> {- return new Promise((done) => {- const child = spawn(cmd, args, { cwd, shell: process.platform === 'win32' });- let stderr = '';- child.stderr.on('data', (d) => { stderr += String(d); });- child.on('close', (code) => done({ code: code ?? 1, stderr }));- });-}-async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult> {const platform = opts.platform ?? 'web';const title = opts.title ?? 'Game';@@ -721,23 +704,6 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>errors.push(...explainBundleErrors(proj.errors));}- // 3b. The systems the project PROMISED would compile, as wasm beside the- // bundle: no marker is not a build step, a promise the subset cannot- // keep is an error. The engine wasm stays prebuilt.- if (!nativeContent) {- const aot = await buildCompiledSystems(opts.root, {- mode: opts.aot ?? 'release',- emcc: emccPath(),- run: runEmcc,- });- errors.push(...aot.errors);- for (const note of aot.notes) warnings.push(note);- if (aot.ok && aot.wasmPath && aot.manifest) {- progress({ phase: 'Compiling promised systems' });- await cp(aot.wasmPath, path.join(payloadDir, AOT_WASM));- await writeFile(path.join(payloadDir, AOT_MANIFEST), JSON.stringify(aot.manifest));- }- }} catch (err) {const e = err as { errors?: BundleMessage[]; message?: string };errors.push(...(e.errors ? explainBundleErrors(e.errors) : [String(e.message ?? err)]));diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.tsindex aa911b38f..94607f6cb 100644--- a/pipeline/src/runtime/gameHost.ts+++ b/pipeline/src/runtime/gameHost.ts@@ -18,8 +18,7 @@ import {packagedAppOptions, packagedRuntimeInit, Transform, SceneManager, Nav, UINode,acquireWebGPUDevice,} from 'esengine';-import type { SceneData, AddressableManifest, PackagedGameConfig, RenderSurfaceSource, AotManifest } from 'esengine';-import { AOT_MANIFEST, AOT_WASM } from '../bundle/aotArtifacts';+import type { SceneData, AddressableManifest, PackagedGameConfig, RenderSurfaceSource } from 'esengine';import type { ESEngineModule } from 'esengine/wasm';async function boot(): Promise<void> {const canvas = document.getElementById('canvas') as HTMLCanvasElement;@@ -108,19 +107,6 @@ async function boot(): Promise<void> {setEditorMode(false);setPlayMode(true);- // The compiled twins, if the build made any. A project with no `@compiled`- // marker ships neither file and interprets, which the 404 below detects.- // Once the manifest IS there the wasm must be too.- const aotManifest = await fetch(new URL(`./${AOT_MANIFEST}`, import.meta.url)).catch(() => null);- if (aotManifest?.ok) {- const wasm = await fetch(new URL(`./${AOT_WASM}`, import.meta.url));- if (!wasm.ok) throw new Error(`${AOT_MANIFEST} shipped without ${AOT_WASM}`);- await app.useCompiledSystems({- host: module,- manifest: await aotManifest.json() as AotManifest,- wasm: await wasm.arrayBuffer(),- });- }if (headless) {(window as unknown as { __estellaCooked?: unknown }).__estellaCooked = {capture(): { width: number; height: number; rgba: Uint8Array } {diff --git a/pipeline/tests/export-aot.test.ts b/pipeline/tests/export-aot.test.tsindex 9e19057f5..3ccf9c8df 100644--- a/pipeline/tests/export-aot.test.ts+++ b/pipeline/tests/export-aot.test.ts@@ -1,25 +1,27 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file Whether a web package carries the systems the project promised would- * compile, and whether the host it ships with goes looking for them.+ * @file What the MANIFEST beside a package's compiled module says, and what the+ * module itself imports.*- * Two files and one name. If the export writes `systems.wasm` and the- * host fetches something else, nothing fails: the fetch 404s, no twin is- * installed, and the game runs the interpreter with nothing to say. So- * the name is asserted in the BUNDLE, not just in the source.+ * `export-compiled-systems.test.ts` holds the staging — which file lands+ * where, and that the config names it. This holds the two things that+ * would still be wrong with all of that right: a manifest that describes+ * the systems differently than the runtime reads them, and a module that+ * brought its own memory or a data section to write over the engine's.*/import { describe, it, expect } from 'vitest';-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';import { tmpdir } from 'node:os';import path from 'node:path';import { fileURLToPath } from 'node:url';import { exportGame } from '../src/export/exportGame';-import { AOT_MANIFEST, AOT_WASM } from '../src/bundle/aotArtifacts';import { emccPath } from '../../build-tools/utils/emscripten.js';const HERE = path.dirname(fileURLToPath(import.meta.url));const GAME_HOST = path.join(HERE, '..', 'src', 'runtime', 'gameHost.ts');+/** Where an export stages the module, and where the config points at it. */+const STAGED = path.join('aot', 'systems.wasm');const EMCC = emccPath();const SCN = 'ffffffff-ffff-ffff-ffff-ffffffffffff';@@ -70,11 +72,11 @@ function setup(files: Record<string, string>): { root: string; out: string } {return { root, out: path.join(root, 'dist') };}-const run = (f: { root: string; out: string }, aot?: 'dev' | 'release' | 'ship') => exportGame({+const run = (f: { root: string; out: string }) => exportGame({root: f.root, entryScene: 'scenes/main.esscene', gameHostEntry: GAME_HOST,scriptsEntry: 'src/main.ts',sdkDistDir: path.join(f.root, '_sdk'), wasmDir: path.join(f.root, '_wasm'),- outDir: f.out, ...(aot === undefined ? {} : { aot }),+ outDir: f.out,});describe('the promised systems in a web package', () => {@@ -82,60 +84,49 @@ describe('the promised systems in a web package', () => {if (!EMCC) console.warn('[export-aot] NO EMSDK — the compiling cases did NOT run.');});- it('ships neither file for a project that promised nothing', async () => {- const f = setup({ 'src/components.ts': COMPONENTS, 'src/main.ts': "export const n = 1;\n" });- const res = await run(f);- expect(res.errors).toEqual([]);- expect(existsSync(path.join(f.out, AOT_WASM))).toBe(false);- expect(existsSync(path.join(f.out, AOT_MANIFEST))).toBe(false);- });-- it.skipIf(!EMCC)('ships both, and a manifest that says how to call them', async () => {+ it.skipIf(!EMCC)('writes a manifest that says how to call them', async () => {const f = setup({ 'src/components.ts': COMPONENTS, 'src/systems.ts': PROMISED, 'src/main.ts': MAIN });const res = await run(f);expect(res.errors).toEqual([]);- expect(existsSync(path.join(f.out, AOT_WASM))).toBe(true);- const manifest = JSON.parse(readFileSync(path.join(f.out, AOT_MANIFEST), 'utf8')) as {- engineAbi: string; projectShapes: string;- systems: { name: string; symbol: string; queries: { comp: string; mut: boolean }[][]; resources: { name: string; mut: boolean }[]; readers: unknown[]; writers: unknown[] }[];+ const cfg = JSON.parse(readFileSync(path.join(f.out, 'game.config.json'), 'utf8')) as {+ aot?: {+ wasm: string;+ manifest: {+ engineAbi: string; projectShapes: string;+ systems: {+ name: string; symbol: string;+ queries: { comp: string; mut: boolean }[][];+ resources: { name: string; mut: boolean }[];+ readers: unknown[]; writers: unknown[];+ }[];+ };+ };};- expect(manifest.systems).toEqual([{+ expect(cfg.aot?.manifest.systems).toEqual([{name: 'MoveSystem',symbol: 'es_sys_MoveSystem',queries: [[{ comp: 'Transform', mut: true }, { comp: 'Mover', mut: false }]],+ // `mut` per resource, because a read-only mirror written back would+ // overwrite what the engine put there this frame.resources: [{ name: 'Time', mut: false }],// A system with no events still declares the two lists, so a runtime// never has to tell "none" from "an older manifest".readers: [],writers: [],}]);- expect(manifest.engineAbi).toMatch(/^[0-9a-f]{16}$/);-- // The shipped module is the one the runtime loads, so ask the artifact the- // two questions a fake host cannot: it imports the engine's memory, and it- // brought no data section to write over the engine's own bytes.- const bytes = readFileSync(path.join(f.out, AOT_WASM));- const mod = new WebAssembly.Module(bytes as unknown as BufferSource);- expect(WebAssembly.Module.imports(mod)).toEqual([{ module: 'env', name: 'memory', kind: 'memory' }]);- expect(WebAssembly.Module.exports(mod).map((e) => e.name)).toContain('es_sys_MoveSystem');+ expect(cfg.aot?.manifest.engineAbi).toMatch(/^[0-9a-f]{16}$/);});- it.skipIf(!EMCC)('and the host it ships with asks for those exact names', async () => {+ it.skipIf(!EMCC)('and the module it staged imports the engine\'s memory, and nothing else', async () => {const f = setup({ 'src/components.ts': COMPONENTS, 'src/systems.ts': PROMISED, 'src/main.ts': MAIN });await run(f);- // In the BUNDLE: the constant is inlined by esbuild, so this is what the- // shipped game will actually fetch — a source-level check would pass while- // the two ends disagreed.- const host = readFileSync(path.join(f.out, 'game.js'), 'utf8');- expect(host).toContain(AOT_MANIFEST);- expect(host).toContain(AOT_WASM);- });-- it('a dev export never compiles, so it needs no toolchain', async () => {- const f = setup({ 'src/components.ts': COMPONENTS, 'src/systems.ts': PROMISED, 'src/main.ts': MAIN });- const res = await run(f, 'dev');- expect(res.errors).toEqual([]);- expect(existsSync(path.join(f.out, AOT_WASM))).toBe(false);+ // Ask the ARTIFACT the two questions a fake host cannot: it imports the+ // engine's memory rather than owning one, and it brought no data section to+ // write over the engine's own bytes.+ const bytes = readFileSync(path.join(f.out, STAGED));+ const mod = new WebAssembly.Module(bytes as unknown as BufferSource);+ expect(WebAssembly.Module.imports(mod)).toEqual([{ module: 'env', name: 'memory', kind: 'memory' }]);+ expect(WebAssembly.Module.exports(mod).map((e) => e.name)).toContain('es_sys_MoveSystem');});});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 5257ce257..a9f259621 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,6 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 64 beta · 1514 experimental · 3 deprecatedSymbols: 113 public · 65 beta · 1515 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental@@ -511,6 +510,11 @@ to: stringComponentDef<any> | BuiltinComponentDef<any>```+## AotHost — type @experimental+```+WasmHeap & { readonly memory: WebAssembly.Memory }+```+## AotManifest — interface @experimental```engineAbi: stringdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex e918c50b1..f6a03e480 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,6 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 69 beta · 1533 experimental · 3 deprecatedSymbols: 113 public · 70 beta · 1534 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental@@ -511,6 +510,11 @@ to: stringComponentDef<any> | BuiltinComponentDef<any>```+## AotHost — type @experimental+```+WasmHeap & { readonly memory: WebAssembly.Memory }+```+## AotManifest — interface @experimental```engineAbi: stringdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 463cd5ef3..edb89e614 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,6 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 66 beta · 1513 experimental · 3 deprecatedSymbols: 113 public · 67 beta · 1514 experimental · 3 deprecated## ANCHOR_AXES — const @experimental@@ -506,6 +505,11 @@ to: stringComponentDef<any> | BuiltinComponentDef<any>```+## AotHost — type @experimental+```+WasmHeap & { readonly memory: WebAssembly.Memory }+```+## AotManifest — interface @experimental```engineAbi: stringdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 3a0fd8917..791dc182e 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,6 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 64 beta · 1535 experimental · 3 deprecatedSymbols: 113 public · 65 beta · 1536 experimental · 3 deprecated## ANCHOR_AXES — const @experimental@@ -506,6 +505,11 @@ to: stringComponentDef<any> | BuiltinComponentDef<any>```+## AotHost — type @experimental+```+WasmHeap & { readonly memory: WebAssembly.Memory }+```+## AotManifest — interface @experimental```engineAbi: stringdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 78ed39ddb..6307afd1f 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,6 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 64 beta · 1525 experimental · 3 deprecatedSymbols: 113 public · 65 beta · 1526 experimental · 3 deprecated## ANCHOR_AXES — const @experimental@@ -506,6 +505,11 @@ to: stringComponentDef<any> | BuiltinComponentDef<any>```+## AotHost — type @experimental+```+WasmHeap & { readonly memory: WebAssembly.Memory }+```+## AotManifest — interface @experimental```engineAbi: stringdiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex e96b30571..7b4b039d3 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -8,7 +8,7 @@import { World } from '../ecs/world';import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, rescopeSystem, type RunCondition } from '../ecs/system';import { builtinResource, ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';-import { prepareAot, type AotHost } from '../ecs/aot/installAot';+import { installAot, prepareAot, type AotHost } from '../ecs/aot/installAot';import type { AotManifest } from '../ecs/aot/AotSystems';import type { AotRuntime } from '../ecs/aot/AotRuntime';import { EventRegistry, eventNamed, type EventDef } from '../ecs/event';@@ -20,9 +20,6 @@ import { inputPlugin, Input } from '../input/input';import { assetPlugin } from '../asset';import { prefabsPlugin } from '../prefab/prefabServer';import { setWasmErrorHandler } from '../wasm/wasmError';-import { installAot, type AotHost } from '../ecs/aot/installAot';-import type { AotRuntime } from '../ecs/aot/AotRuntime';-import type { AotManifest } from '../ecs/aot/AotSystems';import { corePlugin, DEFAULT_UI_CAMERA_INFO } from './corePlugin';import {ancestors,@@ -626,6 +623,7 @@ export class App {readonly manifest: AotManifest;readonly wasm: BufferSource;}): Promise<void> {+ this.ensureTime_();this.aot_ = await prepareAot({world: this.world_,host: opts.host,@@ -663,9 +661,6 @@ export class App {this.runner_?.useAot(this.aot_);}- /** Held until there is a runner to give them to: one is made on the first frame. */- private aot_: AotRuntime | null = null;-/*** Which systems this App is running compiled, and how many twin calls have* happened. `installed` without `calls` rising means the module loaded and@@ -940,6 +935,7 @@ export class App {_free: (ptr: number) => module._free(ptr),get HEAPU8(): Uint8Array { return module.HEAPU8; },};+ this.ensureTime_();this.aot_ = await installAot({world: this.world_,runner: this.ensureRunner_(),@@ -1108,15 +1104,23 @@ export class App {return this.runner_;}+ /**+ * The clock, before anything asks for it. Installing compiled systems is one+ * such thing and it runs BEFORE the first frame: a twin declaring `Res(Time)`+ * is refused outright if this App cannot yet say what Time's fields are.+ */+ private ensureTime_(): void {+ if (this.resources_.has(Time)) return;+ this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });+ }+/** Once per app, on the way into the first frame: the clock every system* reads, and the plugins' last chance to add one. */private boot_(): void {this.ensureRunner_();if (this.booted_) return;this.booted_ = true;- if (!this.resources_.has(Time)) {- this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });- }+ this.ensureTime_();this.finishPlugins_();}diff --git a/sdk/src/ecs/aot/AotDispatch.ts b/sdk/src/ecs/aot/AotDispatch.tsindex 1ba4fbeff..28f541b6f 100644--- a/sdk/src/ecs/aot/AotDispatch.ts+++ b/sdk/src/ecs/aot/AotDispatch.ts@@ -73,6 +73,8 @@ interface QueryPlan {interface Plan {readonly queries: QueryPlan[];+ /** Whether any slot is an event reader, so a call took payload blocks. */+ readonly reads: boolean;readonly resources: readonly { name: string; mut: boolean }[];/** Rows for every query, back to back, in query order. */scratch: Uint32Array;@@ -142,7 +144,7 @@ export class AotDispatch {}// The payload blocks are valid for exactly this call: `packRows_` takes// one per payload per frame, and nothing else hands them back.- this.runtime.addresses.releasePayloads();+ if (plan.reads) this.runtime.addresses.releasePayloads();for (const cmd of this.runtime.ctx.commands()) {// Only despawn is in the v1 record set.@@ -284,6 +286,7 @@ export class AotDispatch {});plan = {queries,+ reads: queries.some((q) => q.reader !== null),resources: twin.decl.resources,scratch: new Uint32Array(0),counts: new Uint32Array(queries.length),diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.tsindex c742f6f57..9c02faec1 100644--- a/sdk/src/ecs/aot/installAot.ts+++ b/sdk/src/ecs/aot/installAot.ts@@ -33,11 +33,11 @@ import { AotSystems, type AotManifest } from './AotSystems';import type { AotAddresses, AotRuntime } from './AotRuntime';/**- * The engine module a compiled system shares memory with. `wasmMemory` is- * emscripten's own name for the Memory object, and the engine exports it for- * exactly this — a HEAP view's buffer is an ArrayBuffer and cannot be imported.- */-export type AotHost = WasmHeap & { readonly wasmMemory: WebAssembly.Memory };+ * The engine module a compiled system shares memory with. The Memory OBJECT,+ * which the module imports as `env.memory`: a HEAP view's buffer is an+ * ArrayBuffer and cannot be imported.+ */+export type AotHost = WasmHeap & { readonly memory: WebAssembly.Memory };export interface InstallAotOptions {readonly world: World;diff --git a/sdk/tests/aot-app.test.ts b/sdk/tests/aot-app.test.tsindex 58b43d64a..cd25274d3 100644--- a/sdk/tests/aot-app.test.ts+++ b/sdk/tests/aot-app.test.ts@@ -15,7 +15,7 @@ import {buildAotModule, buildFadeModule, eventManifest, fadeManifest, fadeTaggedManifest,keyProbeC, keyProbeManifest, EVENT_C,timeScaleManifest, userResManifest, FADE_TAGGED_C, USER_RES_C,- FADE_PROBE_ALPHA, FADE_PROBE_C, TIME_SCALE_C,+ FADE_PROBE_ALPHA, FADE_PROBE_C, TIME_SCALE_C, useBytesPlatform,} from './helpers/aotFade';import { FakeEngine } from './fakeEngine';import { emccPath } from '../../build-tools/utils/emscripten.js';@@ -31,6 +31,8 @@ import type { Entity } from '../src/types';const EMCC = emccPath();const N = 8;+useBytesPlatform();+/** The same author's system either way; only whether a twin exists differs. */function fadeApp(): { app: ReturnType<typeof bootMockApp>['app']; Fade: AnyComponentDef } {const { app } = bootMockApp();diff --git a/sdk/tests/aot-context.test.ts b/sdk/tests/aot-context.test.tsindex 471dd2794..a81403db0 100644--- a/sdk/tests/aot-context.test.ts+++ b/sdk/tests/aot-context.test.ts@@ -132,7 +132,7 @@ describe('a compiled system, called by the SDK', () => {const memory = new WasmPoolMemory(engine);const instance = await WebAssembly.instantiate(new WebAssembly.Module(buildModule() as unknown as BufferSource),- { env: { memory: engine.wasmMemory } });+ { env: { memory: engine.memory } });const api = instance.exports as unknown as Record<string, unknown>;(api['_initialize'] as (() => void) | undefined)?.();const decay = api['es_sys_Decay'] as (ctx: number) => void;@@ -200,7 +200,7 @@ describe('a compiled system, called by the SDK', () => {const memory = new WasmPoolMemory(engine);const instance = await WebAssembly.instantiate(new WebAssembly.Module(buildModule() as unknown as BufferSource),- { env: { memory: engine.wasmMemory } });+ { env: { memory: engine.memory } });const api = instance.exports as unknown as Record<string, unknown>;(api['_initialize'] as (() => void) | undefined)?.();diff --git a/sdk/tests/aot-dispatch.test.ts b/sdk/tests/aot-dispatch.test.tsindex 4b814ebf6..9a3da519a 100644--- a/sdk/tests/aot-dispatch.test.ts+++ b/sdk/tests/aot-dispatch.test.ts@@ -163,7 +163,7 @@ describe('the scheduler and its compiled twin', () => {const instance = await WebAssembly.instantiate(new WebAssembly.Module(bytes as unknown as BufferSource),- { env: { memory: heap.wasmMemory } });+ { env: { memory: heap.memory } });const exports = instance.exports as unknown as Record<string, unknown>;(exports['_initialize'] as (() => void) | undefined)?.();@@ -219,7 +219,7 @@ describe('the scheduler and its compiled twin', () => {if (compiled) {const instance = await WebAssembly.instantiate(new WebAssembly.Module(bytes as unknown as BufferSource),- { env: { memory: heap.wasmMemory } });+ { env: { memory: heap.memory } });const exports = instance.exports as unknown as Record<string, unknown>;(exports['_initialize'] as (() => void) | undefined)?.();const systems = new AotSystems();diff --git a/sdk/tests/aot-install.test.ts b/sdk/tests/aot-install.test.tsindex 0d0ef20c9..3894883e4 100644--- a/sdk/tests/aot-install.test.ts+++ b/sdk/tests/aot-install.test.ts@@ -38,6 +38,7 @@ import type { AnyComponentDef } from '../src/ecs/component';import type { WasmHeap } from '../src/ecs/WasmPoolMemory';import type { Entity } from '../src/types';import { emccPath } from '../../build-tools/utils/emscripten.js';+import { WASM_LINK_FLAGS } from '../../compiler/src/codegen';import { FakeEngine } from './fakeEngine';import { buildFadeModule, FADE_FIELDS, fadeManifest } from './helpers/aotFade';diff --git a/sdk/tests/aot-perf.test.ts b/sdk/tests/aot-perf.test.tsindex b5d7cd5b0..c36697e33 100644--- a/sdk/tests/aot-perf.test.ts+++ b/sdk/tests/aot-perf.test.ts@@ -19,7 +19,7 @@*/import { describe, it, expect } from 'vitest';import { bootMockApp } from './helpers/mockApp';-import { buildFadeModule, fadeManifest } from './helpers/aotFade';+import { buildFadeModule, fadeManifest, useBytesPlatform } from './helpers/aotFade';import { FakeEngine } from './fakeEngine';import { emccPath } from '../../build-tools/utils/emscripten.js';import { defineComponent } from '../src/ecs/component';@@ -29,6 +29,8 @@ import type { AnyComponentDef } from '../src/ecs/component';import type { Entity } from '../src/types';const EMCC = emccPath();++useBytesPlatform();const N = 5000;const FRAMES = 300;const WARMUP = 60;diff --git a/sdk/tests/fakeEngine.ts b/sdk/tests/fakeEngine.tsindex 58fa2b0e2..5b15c0157 100644--- a/sdk/tests/fakeEngine.ts+++ b/sdk/tests/fakeEngine.ts@@ -27,8 +27,8 @@ const STATICS_BYTE = 0xab;export class FakeEngine implements WasmHeap {/** 256 pages because that is the minimum a built module declares it needs. */- readonly wasmMemory = new WebAssembly.Memory({ initial: 256, maximum: 32768 });- HEAPU8 = new Uint8Array(this.wasmMemory.buffer);+ readonly memory = new WebAssembly.Memory({ initial: 256, maximum: 32768 });+ HEAPU8 = new Uint8Array(this.memory.buffer);private next = STATICS_AT + STATICS_LEN;constructor() { this.statics().fill(STATICS_BYTE); }@@ -37,8 +37,8 @@ export class FakeEngine implements WasmHeap {const at = this.next;this.next += (size + 15) & ~15;while (this.next > this.HEAPU8.byteLength) {- this.wasmMemory.grow(1);- this.HEAPU8 = new Uint8Array(this.wasmMemory.buffer);+ this.memory.grow(1);+ this.HEAPU8 = new Uint8Array(this.memory.buffer);}return at;}@@ -47,7 +47,7 @@ export class FakeEngine implements WasmHeap {/** The bytes the engine owns. Read after loading and after running. */statics(): Uint8Array {- return new Uint8Array(this.wasmMemory.buffer, STATICS_AT, STATICS_LEN);+ return new Uint8Array(this.memory.buffer, STATICS_AT, STATICS_LEN);}/** Whether anything wrote where the engine keeps its own data. */diff --git a/sdk/tests/helpers/aotFade.ts b/sdk/tests/helpers/aotFade.tsindex 86ea2a80e..d6e420c8d 100644--- a/sdk/tests/helpers/aotFade.ts+++ b/sdk/tests/helpers/aotFade.ts@@ -17,6 +17,8 @@ import { WASM_LINK_FLAGS } from '../../../compiler/src/codegen';import { engineAbiDigest, projectShapeDigest } from '../../src/ecs/aot/abiDigest';import { resourceMethodBit } from '../../src/ecs/resourceShapes';import type { AotManifest } from '../../src/ecs/aot/AotSystems';+import { setPlatform } from '../../src/platform/base';+import type { PlatformAdapter, WasmInstantiateResult } from '../../src/platform/types';/** `Fade`: alpha -= step, addressed the way the ABI lays a call out. */export const FADE_C = `#include <stdint.h>@@ -275,3 +277,18 @@ export function fadeManifest(}],};}++/**+ * A platform that instantiates from BYTES, which every install goes through now.+ * A test building its own module has no package to name, so the path form these+ * helpers cannot produce is the one WeChat takes — `aot-install.test.ts` is where+ * both shapes are held to their refusals.+ */+export function useBytesPlatform(): void {+ setPlatform({+ instantiateWasm: (src: string | ArrayBuffer, imports: WebAssembly.Imports) => {+ if (typeof src === 'string') throw new Error('these helpers hand over bytes');+ return WebAssembly.instantiate(src, imports) as Promise<WasmInstantiateResult>;+ },+ } as unknown as PlatformAdapter);+}