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.

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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.json
index 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.ts
index 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 './playableAdProf
import 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.ts
index 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.ts
index 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.md
index 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 deprecated
Symbols: 113 public · 65 beta · 1515 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
@@ -511,6 +510,11 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotHost — type @experimental
+```
+WasmHeap & { readonly memory: WebAssembly.Memory }
+```
+
## AotManifest — interface @experimental
```
engineAbi: string
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 deprecated
Symbols: 113 public · 70 beta · 1534 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
@@ -511,6 +510,11 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotHost — type @experimental
+```
+WasmHeap & { readonly memory: WebAssembly.Memory }
+```
+
## AotManifest — interface @experimental
```
engineAbi: string
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 deprecated
Symbols: 113 public · 67 beta · 1514 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
@@ -506,6 +505,11 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotHost — type @experimental
+```
+WasmHeap & { readonly memory: WebAssembly.Memory }
+```
+
## AotManifest — interface @experimental
```
engineAbi: string
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 deprecated
Symbols: 113 public · 65 beta · 1536 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
@@ -506,6 +505,11 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotHost — type @experimental
+```
+WasmHeap & { readonly memory: WebAssembly.Memory }
+```
+
## AotManifest — interface @experimental
```
engineAbi: string
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 deprecated
Symbols: 113 public · 65 beta · 1526 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
@@ -506,6 +505,11 @@ to: string
ComponentDef<any> | BuiltinComponentDef<any>
```
+## AotHost — type @experimental
+```
+WasmHeap & { readonly memory: WebAssembly.Memory }
+```
+
## AotManifest — interface @experimental
```
engineAbi: string
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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);
+}