Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(aot): a packaged desktop game runs its systems as machine code

yhh7cdc20d05455
diff --git a/native/host/Host.hpp b/native/host/Host.hpp
index 86927a0d1..26294d2dd 100644
--- a/native/host/Host.hpp
+++ b/native/host/Host.hpp
@@ -104,6 +104,14 @@ struct Platform {
* app bundle on iOS. Empty when missing. Backs NativeBridge.readFile. */
virtual std::vector<esengine::u8> readAsset(const char* path) = 0;
+ /**
+ * The same file as a filesystem PATH, or empty where the assets are not
+ * files (an APK's are not). For the one thing bytes cannot serve: a library
+ * the OS loader opens by name, which is how a desktop build reaches its
+ * compiled systems.
+ */
+ virtual std::string assetPath(const char*) { return {}; }
+
/**
* Writable private directory for things the host can REGENERATE — the SDK
* bytecode cache, downloaded hot-update content. Empty disables it.
diff --git a/native/host/bindings/AotBindings.cpp b/native/host/bindings/AotBindings.cpp
index b53c67189..7498ac4a0 100644
--- a/native/host/bindings/AotBindings.cpp
+++ b/native/host/bindings/AotBindings.cpp
@@ -102,9 +102,15 @@ JSValue js_install(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
const char* path = JS_ToCString(ctx, argv[0]);
if (path == nullptr) return JS_NewInt32(ctx, -1);
+ // A content-relative name, resolved the way every other packaged file is:
+ // the OS loader searches its own path for a bare name and would find
+ // anything but this one.
+ const std::string resolved = host().platform ? host().platform->assetPath(path) : std::string{};
+ const char* open = resolved.empty() ? path : resolved.c_str();
+
AotState& s = state();
std::string why;
- const bool ok = s.dispatcher.install(path, aot::abiHash(ES_ENGINE_ABI_DIGEST),
+ const bool ok = s.dispatcher.install(open, aot::abiHash(ES_ENGINE_ABI_DIGEST),
componentAt, resourceAt, &why);
if (!ok) ESHOST_LOGE("[aot] %s: %s", path, why.c_str());
JS_FreeCString(ctx, path);
@@ -188,11 +194,13 @@ JSValue js_run(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {
std::uint32_t i = 0;
JS_ToUint32(ctx, &i, argv[0]);
AotState& s = state();
- if (!s.installed || !s.dispatcher.boundAt(i)) return JS_NewInt32(ctx, -1);
+ if (!s.installed) return JS_NewInt32(ctx, -1);
s.candidates.clear();
host().registry->forEachEntity([&s](esengine::Entity e) { s.candidates.push_back(e.id()); });
const auto cmds = s.dispatcher.run(i, s.candidates, resourceAt);
+ // Asked AFTER the run, because that is where a late binding is settled.
+ if (!s.dispatcher.boundAt(i)) return JS_NewInt32(ctx, -1);
// After the call, never during it: a despawn invalidates the rows it read.
return JS_NewInt32(ctx, static_cast<int>(aot::applyCommands(*host().registry, cmds)));
}
diff --git a/native/host/platform/desktop.cpp b/native/host/platform/desktop.cpp
index e3d25abe2..98a64f99f 100644
--- a/native/host/platform/desktop.cpp
+++ b/native/host/platform/desktop.cpp
@@ -123,6 +123,12 @@ struct DesktopPlatform final : eshost::Platform {
return readFileBytes(contentRoot + path);
}
+ /** Loose files, so a content path IS a filesystem path. */
+ std::string assetPath(const char* path) override {
+ if (contentRoot.empty() || !path) return {};
+ return contentRoot + path;
+ }
+
/** Regenerable state, under the same per-user root as the saves — a store
* syncs that root, and a cache that syncs is merely slow where a save that
* does not is a lost game. */
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index ad0f8637b..d17a4c6d5 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -41,6 +41,7 @@ import type { OnExportProgress } from './exportProgress';
import { ESENGINE_EXTERNAL } from '../bundle/esengineResolve';
import { buildCompiledSystems, type BuildMode } from '../bundle/buildCompiledSystems';
import { resolveEmcc, runEmcc } from '../bundle/emccPath';
+import { findHostCC } from '../../../compiler/src/hostCC';
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';
@@ -51,7 +52,7 @@ import { assembleAab, aabFileName } from '../../../build-tools/utils/aab.js';
import { assembleDesktopApp } from '../../../build-tools/utils/desktopApp.js';
import { emitSteamBuild, defaultDepotId } from '../../../build-tools/utils/steamChannel.js';
import { debugSigningKey, type SigningKey } from '../../../build-tools/utils/androidKeystore.js';
-import { compilesSystems, isNativePlatform, desktopTemplateFor, type DesktopOs, type ExportPlatform } from '../project/platforms';
+import { compileTargetFor, isNativePlatform, desktopTemplateFor, type DesktopOs, type ExportPlatform } from '../project/platforms';
import type { DesktopPackaging, SteamPackaging } from '../project/format';
import type { SizeBudget } from '../project/sizeBudget';
import { measureBuild, type BuildSizeReport } from './sizeReport';
@@ -710,16 +711,35 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
return { ok: false, platform, outDir: absOut, included: cook.included.length, warnings, errors };
}
- // 3b. Compiled systems (docs/REARCH_AOT.md), for the page host. Which targets
- // get one is `compilesSystems`, because the build dialog has to answer the
- // same question before an export starts.
+ /** The desktop apps this export will assemble that this machine cannot make a
+ * compiled module for. Empty means every one of them is this machine. */
+ function foreignDesktopOses(templates: { os: DesktopOs }[] | undefined): DesktopOs[] {
+ const here = desktopTemplateFor(process.platform);
+ return (templates ?? []).map((t) => t.os).filter((os) => os !== here);
+ }
+
+ // 3b. Compiled systems. Which machine they are built for is `compileTargetFor`,
+ // because the build dialog looks for the same compiler this does, before
+ // an export starts.
let aot: PackagedGameConfig['aot'];
- if (compilesSystems(platform)) {
+ const aotTarget = compileTargetFor(platform);
+ const foreignOs = aotTarget === 'native' ? foreignDesktopOses(opts.desktopTemplates) : [];
+ if (aotTarget !== null && foreignOs.length > 0) {
+ // A compiled system is machine code for ONE machine, and this assembles an
+ // app per installed template. Half a package with AOT is worse than a
+ // uniform one, so nothing is compiled and the build says why.
+ warnings.push('Compiled systems were left out: this build also assembles '
+ + `${foreignOs.join(' and ')}, and a compiled system is machine code for one machine. `
+ + `Export on the machine you are targeting, or install only its runtime template.`);
+ } else if (aotTarget !== null) {
// An export is not the editor's preview: here a `@compiled` marker is a
// promise someone is collecting on, so a promise the subset cannot keep
// fails the build rather than quietly falling back to the interpreter.
const built = await buildCompiledSystems(opts.root, {
- mode: opts.aotMode ?? 'release', cc: resolveEmcc(opts.emcc), run: runEmcc,
+ mode: opts.aotMode ?? 'release',
+ target: aotTarget,
+ cc: aotTarget === 'native' ? findHostCC() : resolveEmcc(opts.emcc),
+ run: runEmcc,
});
if (!built.ok) {
errors.push(...built.errors);
@@ -727,9 +747,10 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
}
if (built.modulePath && built.manifest) {
progress({ phase: 'Compiling systems', detail: `${built.manifest.systems.length} system(s)` });
+ const name = path.basename(built.modulePath);
await mkdir(path.join(payloadDir, 'aot'), { recursive: true });
- await cp(built.modulePath, path.join(payloadDir, 'aot', 'systems.wasm'));
- aot = { module: `aot/${path.basename(built.modulePath)}`, manifest: built.manifest };
+ await cp(built.modulePath, path.join(payloadDir, 'aot', name));
+ aot = { module: `aot/${name}`, manifest: built.manifest };
}
}
diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.ts
index aaa8f9521..49cf1cb1f 100644
--- a/pipeline/src/export/platformCatalog.ts
+++ b/pipeline/src/export/platformCatalog.ts
@@ -30,7 +30,7 @@ import {
BUILTIN_PLAYABLE_PROFILES, builtinPlayableProfile, genericPlayableProfile,
type PlayableAdProfile,
} from './playableAdProfile';
-import { BUILTIN_PLATFORMS, DESKTOP_OSES, compilesSystems, desktopTemplateFor, type PlatformPrereq } from '../project/platforms';
+import { BUILTIN_PLATFORMS, DESKTOP_OSES, compileTargetFor, desktopTemplateFor, type PlatformPrereq } from '../project/platforms';
import { promisesCompilation } from '../bundle/buildCompiledSystems';
import { resolveNativeTemplate } from './nativeTemplates';
import { templateId } from '../../../build-tools/utils/nativeTemplate.js';
@@ -613,10 +613,11 @@ export async function loadPlayableProfile(root: string | null, id: string | unde
*/
export async function listPlatforms(
root: string | null, dirs: PlatformRuntimeDirs, engineVersion: string,
- /** Where this machine's emcc is, or null. Required rather than probed here so
- * the caller passes the SAME answer to the export — a readiness the dialog
- * computed one way and the export another is worse than none. */
- emcc: string | null,
+ /** The compilers this machine has, one per target a package can be built
+ * for. Required rather than probed here so the caller passes the SAME
+ * answers to the export — a readiness the dialog computed one way and the
+ * export another is worse than none. */
+ toolchains: AotToolchains,
): Promise<PlatformStatus[]> {
const out: PlatformStatus[] = BUILTIN_PLATFORMS.map((id) => ({
id,
@@ -686,7 +687,15 @@ export async function listPlatforms(
});
}
- return withAotPrereq(out, root, emcc);
+ return withAotPrereq(out, root, toolchains);
+}
+
+/** What a machine has for each road a compiled module can be built along. */
+export interface AotToolchains {
+ /** emcc, for a module that shares the engine's memory. */
+ emcc: string | null;
+ /** The host's own C compiler, for a library a native host loads. */
+ cc: string | null;
}
/**
@@ -697,13 +706,19 @@ export async function listPlatforms(
* missing engine runtime keeps that harder answer.
*/
function withAotPrereq(
- rows: PlatformStatus[], root: string, emcc: string | null,
+ rows: PlatformStatus[], root: string, toolchains: AotToolchains,
): PlatformStatus[] {
- if (emcc || !promisesCompilation(root)) return rows;
+ if (!promisesCompilation(root)) return rows;
for (const row of rows) {
- if (!row.ready || !compilesSystems(row.id)) continue;
+ if (!row.ready) continue;
+ const target = compileTargetFor(row.id);
+ if (target === null) continue;
+ // One probe per road: a machine with emcc and no cc packages for the web
+ // and not for the desktop, and being sent to install the other toolchain
+ // is worse than being told nothing.
+ if (target === 'wasm' ? toolchains.emcc : toolchains.cc) continue;
row.ready = false;
- row.prereq = { kind: 'toolchain-missing', tool: 'emsdk' };
+ row.prereq = { kind: 'toolchain-missing', tool: target === 'wasm' ? 'emsdk' : 'hostcc' };
}
return rows;
}
diff --git a/pipeline/src/project/platforms.ts b/pipeline/src/project/platforms.ts
index 1427e080f..1ed152567 100644
--- a/pipeline/src/project/platforms.ts
+++ b/pipeline/src/project/platforms.ts
@@ -150,18 +150,22 @@ export type PlatformPrereq =
* target missing them still exports its content. `emsdk` gates the export
* itself, because the compiled module ships inside the package.
*/
-export type ToolchainPiece = 'xcode' | 'macos' | 'emsdk';
+export type ToolchainPiece = 'xcode' | 'macos' | 'emsdk' | 'hostcc';
/**
- * Whether this target's export compiles the project's `@compiled` systems.
+ * WHICH machine this target's compiled systems are built for, or null where it
+ * runs no such step.
*
- * A page host and a mini-game host can load a module; a playable inlines
- * everything, and a native app runs its scripts on QuickJS. Two surfaces read
- * this — the export that runs the step, and the catalog that says a machine cannot.
+ * Not a boolean: the two answers want different compilers — emcc for a module
+ * sharing the engine's memory, the host's own cc for a library it loads — and a
+ * surface asking only "does it compile" would guess which to look for. A
+ * playable has nowhere to put a module; iOS and Android need a cross-compiler.
*/
-export function compilesSystems(platform: ExportPlatform): boolean {
- if (platform === 'web' || platform === 'wechat') return true;
+export function compileTargetFor(platform: ExportPlatform): 'wasm' | 'native' | null {
+ if (platform === 'web' || platform === 'wechat') return 'wasm';
+ if (platform === 'desktop') return 'native';
+ if (platform === 'playable' || platform === 'android' || platform === 'ios') return null;
// A project platform is a mini-game platform: the playable ones are chosen
// inside the built-in target, not offered as a row of their own.
- return !(BUILTIN_PLATFORMS as readonly string[]).includes(platform);
+ return 'wasm';
}
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index b9574a1e9..77345c225 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -229,7 +229,6 @@ async function boot(): Promise<void> {
// The compiled twins this build produced, if any. The path, not the bytes:
// reading it is the platform seam's job, and on a mini-game only the seam
// knows how (docs/REARCH_AOT.md §9).
- ...(cfg.aot ? { aot: cfg.aot } : {}),
manifest: index.manifest,
catalog: index.catalog,
remoteRoot: cfg.hotUpdate?.remoteRoot,
diff --git a/pipeline/tests/native-template.test.ts b/pipeline/tests/native-template.test.ts
index 1c548db22..439bfa629 100644
--- a/pipeline/tests/native-template.test.ts
+++ b/pipeline/tests/native-template.test.ts
@@ -30,7 +30,7 @@ import { makeZip } from '../../build-tools/utils/zip.js';
const VERSION = '9.9.9';
/** No project root here, so nothing can have promised compilation. */
-const EMCC = null;
+const NO_TOOLCHAINS = { emcc: null, cc: null };
let store: string;
let scratch: string;
@@ -289,7 +289,7 @@ describe('downloading a template from a release', () => {
describe('the iOS row reports what is missing', () => {
const dirs = () => ({ web: path.join(scratch, 'web'), wechat: path.join(scratch, 'wx') });
- const iosRow = async () => (await listPlatforms(null, dirs(), VERSION, EMCC)).find((r) => r.id === 'ios')!;
+ const iosRow = async () => (await listPlatforms(null, dirs(), VERSION, NO_TOOLCHAINS)).find((r) => r.id === 'ios')!;
it('asks for the runtime template before anything about Xcode', async () => {
const row = await iosRow();
diff --git a/pipeline/tests/platform-catalog.test.ts b/pipeline/tests/platform-catalog.test.ts
index 9c19b11a3..b37adb167 100644
--- a/pipeline/tests/platform-catalog.test.ts
+++ b/pipeline/tests/platform-catalog.test.ts
@@ -17,7 +17,7 @@ import {
listPlatforms, loadProjectPlatform, createProjectPlatform, PROJECT_PLATFORM_DIR,
listPlayableNetworks, loadPlayableProfile,
} from '../src/export/platformCatalog';
-import { BUILTIN_PLATFORMS } from '../src/project/platforms';
+import { BUILTIN_PLATFORMS, compileTargetFor } from '../src/project/platforms';
let root: string;
let webDir: string;
@@ -29,10 +29,12 @@ const VERSION = '9.9.9';
const dirs = () => ({ web: webDir, wechat: wxDir });
-/** The catalog with the machine facts this file owns. `null` emcc is deliberate:
- * a project that marks nothing `@compiled` must be told it needs no toolchain,
- * which is the half of that rule a passing machine cannot check. */
-const platforms = (r: string | null) => listPlatforms(r, dirs(), VERSION, null);
+/** The catalog with the machine facts this file owns. A machine with NEITHER
+ * compiler is deliberate: a project that marks nothing `@compiled` must be
+ * told it needs no toolchain, which is the half of that rule a machine that
+ * happens to have one cannot check. */
+const NONE = { emcc: null, cc: null };
+const platforms = (r: string | null) => listPlatforms(r, dirs(), VERSION, NONE);
function writePlatform(name: string, source: string): void {
const dir = path.join(root, PROJECT_PLATFORM_DIR);
@@ -429,13 +431,14 @@ describe('listPlatforms — the AOT toolchain, only where it is owed', () => {
writeFileSync(path.join(webDir, 'esengine.js'), '//');
writeFileSync(path.join(wxDir, 'esengine.wxgame.js'), '//');
};
- const rows = (emcc: string | null) => listPlatforms(root, dirs(), VERSION, emcc);
+ const rows = (t: { emcc: string | null; cc: string | null }) =>
+ listPlatforms(root, dirs(), VERSION, t);
it('says nothing to a project that promised nothing, on a machine with no emcc', async () => {
mkdirSync(path.join(root, 'src'), { recursive: true });
writeFileSync(path.join(root, 'src', 'move.ts'), 'export const x = 1;');
writeFileSync(path.join(webDir, 'esengine.js'), '//');
- const byId = Object.fromEntries((await rows(null)).map((r) => [r.id, r]));
+ const byId = Object.fromEntries((await rows(NONE)).map((r) => [r.id, r]));
expect(byId.web.ready).toBe(true);
expect(byId.web.prereq).toBeUndefined();
@@ -443,7 +446,7 @@ describe('listPlatforms — the AOT toolchain, only where it is owed', () => {
it('blocks the targets that would compile, and names emsdk', async () => {
promising();
- const byId = Object.fromEntries((await rows(null)).map((r) => [r.id, r]));
+ const byId = Object.fromEntries((await rows(NONE)).map((r) => [r.id, r]));
expect(byId.web.ready).toBe(false);
expect(byId.web.prereq).toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
@@ -453,14 +456,33 @@ describe('listPlatforms — the AOT toolchain, only where it is owed', () => {
it('leaves alone the targets whose export never compiles', async () => {
promising();
- const byId = Object.fromEntries((await rows(null)).map((r) => [r.id, r]));
+ const byId = Object.fromEntries((await rows(NONE)).map((r) => [r.id, r]));
- // A playable inlines everything and has nowhere to put a module; a native
- // app runs its scripts on QuickJS. Neither runs the step, so neither is
+ // A playable inlines everything and has nowhere to put a module; iOS and
+ // Android would need a cross-compiler. None runs the step, so none is
// blocked by a toolchain it will not spawn.
expect(byId.playable.ready).toBe(true);
expect(byId.playable.prereq).toBeUndefined();
- expect(byId.desktop.prereq).not.toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
+ });
+
+ it('asks each road for its OWN compiler', async () => {
+ promising();
+ const webRow = async (t: { emcc: string | null; cc: string | null }) =>
+ (await rows(t)).find((r) => r.id === 'web')!;
+
+ // Web is the row that reaches the AOT question here rather than a harder
+ // blocker. Pinned: the question is emcc's, and the OTHER compiler does not
+ // answer it — a machine with only a host cc cannot package for the web.
+ expect((await webRow(NONE)).prereq).toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
+ expect((await webRow({ emcc: null, cc: 'cc' })).prereq)
+ .toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
+ expect((await webRow({ emcc: '/emcc', cc: null })).prereq).toBeUndefined();
+
+ // And the desktop asks the other one. Its row is blocked by a missing runtime
+ // template here, which is the harder answer and the one it must keep.
+ expect(compileTargetFor('desktop')).toBe('native');
+ expect(compileTargetFor('web')).toBe('wasm');
+ expect(compileTargetFor('playable')).toBeNull();
});
it('a project platform rides the same rule — it packages through the mini-game path', async () => {
@@ -468,7 +490,7 @@ describe('listPlatforms — the AOT toolchain, only where it is owed', () => {
writePlatform('acme.mjs', `export default {
id: 'acme', label: 'ACME', emitConfigFiles: () => [],
};`);
- const acme = (await rows(null)).find((r) => r.id === 'acme');
+ const acme = (await rows(NONE)).find((r) => r.id === 'acme');
expect(acme!.ready).toBe(false);
expect(acme!.prereq).toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
@@ -476,7 +498,7 @@ describe('listPlatforms — the AOT toolchain, only where it is owed', () => {
it('clears once the machine has one', async () => {
promising();
- const byId = Object.fromEntries((await rows('/opt/emsdk/emcc')).map((r) => [r.id, r]));
+ const byId = Object.fromEntries((await rows({ emcc: '/opt/emsdk/emcc', cc: 'cc' })).map((r) => [r.id, r]));
expect(byId.web.ready).toBe(true);
expect(byId.wechat.ready).toBe(true);
@@ -485,7 +507,7 @@ describe('listPlatforms — the AOT toolchain, only where it is owed', () => {
it('does not speak over a harder blocker — no runtime means no package at all', async () => {
mkdirSync(path.join(root, 'src'), { recursive: true });
writeFileSync(path.join(root, 'src', 'move.ts'), '/** @compiled */ export const x = 1;');
- const web = (await rows(null)).find((r) => r.id === 'web');
+ const web = (await rows(NONE)).find((r) => r.id === 'web');
expect(web!.ready).toBe(false);
expect(web!.prereq?.kind).toBe('runtime-missing');
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index ec555b54d..0a256a343 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -11205,7 +11205,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; }
```
## paramDefaultValue — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 4a128c1aa..d42437037 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -11448,7 +11448,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; }
```
## paramDefaultValue — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a14f35372..cf5231c34 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -11210,7 +11210,7 @@ NodePlatformAdapter
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; }
```
## paramDefaultValue — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 5e221dec3..9b6c8b511 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -11467,7 +11467,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; }
```
## paramDefaultValue — function @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index db5c67304..ccb239b59 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -11233,7 +11233,7 @@ NavPlugin
## packagedRuntimeInit — function @experimental
```
-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit" | "aot">): { physicsEnabled?: boolean; physicsConfig?: Physics2DPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; aot?: PackagedGameConfig["aot"]; }
```
## paramDefaultValue — function @experimental
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 4f624d1e1..4257e8a5e 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -974,6 +974,8 @@ export class App {
manifest,
heap,
bindings,
+ resources: (name: string) => this.getResourceByName(name) as
+ Readonly<Record<string, unknown>> | undefined,
});
return this.aot_?.systems.size ?? 0;
}
diff --git a/sdk/src/ecs/aot/AotDispatch.ts b/sdk/src/ecs/aot/AotDispatch.ts
index 28f541b6f..310c83721 100644
--- a/sdk/src/ecs/aot/AotDispatch.ts
+++ b/sdk/src/ecs/aot/AotDispatch.ts
@@ -118,7 +118,7 @@ export class AotDispatch {
constructor(private readonly world: World, private readonly runtime: AotRuntime) {}
- run(twin: AotTwin): void {
+ run(twin: AotTwin): boolean {
const plan = this.planFor_(twin);
this.packRows_(plan, this.world.layoutEpoch());
@@ -151,6 +151,9 @@ export class AotDispatch {
if (cmd.kind === CMD_DESPAWN) this.world.despawn(cmd.a as unknown as Entity);
}
this.markChanged_(plan);
+ // Always: this module shares the engine's memory, so whatever it names
+ // is reachable the moment it is installed.
+ return true;
}
/** Drop the plans; the next call rebuilds them. */
diff --git a/sdk/src/ecs/aot/AotResources.ts b/sdk/src/ecs/aot/AotResources.ts
index e0682df45..75b4b381d 100644
--- a/sdk/src/ecs/aot/AotResources.ts
+++ b/sdk/src/ecs/aot/AotResources.ts
@@ -58,7 +58,8 @@ export class AotResources {
}
/** Bytes `name`'s block needs, by whichever layout answers for it. */
- private bytesOf(name: string): number {
+ /** How many bytes `name`'s mirror is, for a host that must be given a range. */
+ bytesOf(name: string): number {
const declared = this.declared.get(name);
return declared ? declared.length * POOL_SLOT_BYTES : resourceBlockBytes(name);
}
diff --git a/sdk/src/ecs/aot/AotRuntime.ts b/sdk/src/ecs/aot/AotRuntime.ts
index 5d720059e..ed7511abd 100644
--- a/sdk/src/ecs/aot/AotRuntime.ts
+++ b/sdk/src/ecs/aot/AotRuntime.ts
@@ -51,7 +51,12 @@ export interface AotAddresses {
* hold, so it packs them itself and takes only which system to run.
*/
export interface AotDispatcher {
- run(twin: AotTwin): void;
+ /**
+ * True when the twin RAN. False is the no-cliff rule arriving where it can
+ * still be honoured: a host that cannot yet name every component of a system
+ * has not failed, it has not taken this one, and the interpreter keeps it.
+ */
+ run(twin: AotTwin): boolean;
}
/**
diff --git a/sdk/src/ecs/aot/installNativeAot.ts b/sdk/src/ecs/aot/installNativeAot.ts
index bf0b17383..13f2d2e7b 100644
--- a/sdk/src/ecs/aot/installNativeAot.ts
+++ b/sdk/src/ecs/aot/installNativeAot.ts
@@ -19,11 +19,13 @@
*/
import { getComponent, type AnyComponentDef } from '../component';
+import { log } from '../../util/logger';
import type { World } from '../world';
import type { SystemRunner } from '../system';
import type { Entity } from '../../types';
import { WasmPoolMemory, type WasmHeap } from '../WasmPoolMemory';
import { AotSystems, type AotManifest, type AotTwin } from './AotSystems';
+import { AotResources, type ResourceReader } from './AotResources';
import type { AotDispatcher, AotRuntime } from './AotRuntime';
/** `sizeof(es_addr_t)` where a loaded library runs. */
@@ -51,10 +53,22 @@ export interface InstallNativeAotOptions {
/** The host's linear heap: what a pool allocates from, so an offset means
* the same thing on both sides of the boundary. */
readonly heap: WasmHeap;
+ /** This world's resource values, for the mirror a call reads them from. */
+ readonly resources?: ResourceReader;
/** The host calls, for a test to stand in for. Absent ⇒ read off globalThis. */
readonly bindings?: NativeAotBindings;
}
+/** A project resource's field order, as the build compiled it. The engine's own
+ * come from `resourceShapes`; a project's cannot, and only the build knows. */
+function declaredResourceLayouts(manifest: AotManifest): Map<string, readonly string[]> {
+ const out = new Map<string, readonly string[]>();
+ for (const decl of manifest.systems) {
+ for (const res of decl.resources) if (res.fields) out.set(res.name, res.fields);
+ }
+ return out;
+}
+
/** The entity index mask a sparse table is addressed by, from the engine's own. */
const ENTITY_INDEX_MASK = 0xfffff;
@@ -92,20 +106,20 @@ export function installNativeAot(opts: InstallNativeAotOptions): AotRuntime | nu
// Before the first pooled component exists: a pool cannot move to other
// memory once it has rows, and the host addresses only this heap.
- opts.world.useScriptPoolMemory(new WasmPoolMemory(opts.heap));
+ const memory = new WasmPoolMemory(opts.heap);
+ opts.world.useScriptPoolMemory(memory);
const count = bindings.install(opts.modulePath);
if (count < 0) return null;
- // Only the ones the host BOUND become twins: the runner calls a twin
- // wherever it finds one, so a twin that dispatches to nothing is a system
- // that never runs at all.
- const byTwin = new Map<string, number>();
+ // The index the scheduler keeps. Whether the host can BIND one is settled at
+ // the first run instead: a script pool does not exist until an entity has
+ // that component, and until then the interpreter keeps the system.
+ const byName = new Map<string, number>();
for (const decl of opts.manifest.systems) {
const at = bindings.index(decl.name);
- if (at >= 0 && bindings.bound(at)) byTwin.set(decl.name, at);
+ if (at >= 0) byName.set(decl.name, at);
}
- const running = opts.manifest.systems.filter((decl) => byTwin.has(decl.name));
// The handshake at the loading width, over the WHOLE manifest — that is
// what the module is. The exports throw because the host holds the function
@@ -118,14 +132,19 @@ export function installNativeAot(opts: InstallNativeAotOptions): AotRuntime | nu
};
}
systems.install(opts.manifest, exports, (name) => getComponent(name),
- () => [], NATIVE_ADDRESS_BYTES, (name) => byTwin.has(name));
+ () => [], NATIVE_ADDRESS_BYTES, (name) => byName.has(name));
- // Every script component any running twin names, so one epoch change
- // re-reports all of them rather than whichever twin happened to run first.
+ // Every script component any twin names, so one epoch change re-reports all
+ // of them rather than whichever twin happened to run first.
const pooled = new Set<string>();
- for (const decl of running) {
+ for (const decl of opts.manifest.systems) {
for (const query of decl.queries) for (const arg of query) pooled.add(arg.comp);
}
+ // The resources, mirrored into the same heap the pools use. A resource has no
+ // address of its own until something writes one down, and doing that per call
+ // is what the contract promises — the address is good for one call.
+ const resources = new AotResources(memory, opts.resources ?? (() => undefined),
+ declaredResourceLayouts(opts.manifest));
const runtime: AotRuntime = {
systems,
@@ -136,7 +155,8 @@ export function installNativeAot(opts: InstallNativeAotOptions): AotRuntime | nu
resourceAt: () => undefined,
} as unknown as AotRuntime['addresses'],
ctx: null as unknown as AotRuntime['ctx'],
- dispatcherFor: (world) => new NativeAotDispatch(world, bindings, byTwin, pooled),
+ dispatcherFor: (world) =>
+ new NativeAotDispatch(world, bindings, byName, pooled, resources),
};
opts.runner.useAot(runtime);
return runtime;
@@ -152,20 +172,52 @@ export function installNativeAot(opts: InstallNativeAotOptions): AotRuntime | nu
class NativeAotDispatch implements AotDispatcher {
/** The epoch the pools were last reported at. Null means never. */
private reportedAt_: number | null | undefined = undefined;
+ /** Systems the host has taken at least once, so it is said once. */
+ private readonly running_ = new Set<string>();
constructor(
private readonly world: World,
private readonly bindings: NativeAotBindings,
private readonly indexByName: ReadonlyMap<string, number>,
private readonly pooled: ReadonlySet<string>,
+ private readonly resources: AotResources,
) {}
- run(twin: AotTwin): void {
- // Every twin that exists is one the host bound; install made sure of it.
- const at = this.indexByName.get(twin.decl.name)!;
+ run(twin: AotTwin): boolean {
+ const at = this.indexByName.get(twin.decl.name);
+ if (at === undefined) return false;
this.reportPools_();
- this.bindings.run(at);
+ this.reportResources_(twin);
+ // Negative means the host still cannot name everything this system
+ // reads — a pool with no rows yet, a resource nothing has written.
+ // The interpreter keeps it this frame and it is asked again next.
+ if (this.bindings.run(at) < 0) return false;
+ // Once, the first time the host takes it. "Installed" says a module
+ // loaded; this says a system is actually running as machine code, and
+ // the two are different frames when a pool has to exist first.
+ if (!this.running_.has(twin.decl.name)) {
+ this.running_.add(twin.decl.name);
+ log.info('runtime', `AOT: ${twin.decl.name} is running compiled`);
+ }
+ this.writeBackResources_(twin);
this.markChanged_(twin);
+ return true;
+ }
+
+ /** Mirror each declared resource into the heap and say where it landed. */
+ private reportResources_(twin: AotTwin): void {
+ for (const res of twin.decl.resources) {
+ const at = this.resources.addressOf(res.name);
+ if (at === undefined) continue;
+ this.bindings.resource(res.name, at, this.resources.bytesOf(res.name));
+ }
+ }
+
+ /** A `ResMut` the compiled code wrote is in the mirror, not in the world. */
+ private writeBackResources_(twin: AotTwin): void {
+ for (const res of twin.decl.resources) {
+ if (res.mut) this.resources.writeBack(res.name);
+ }
}
/**
diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.ts
index a04fe7caa..002d1ea81 100644
--- a/sdk/src/ecs/system.ts
+++ b/sdk/src/ecs/system.ts
@@ -475,10 +475,9 @@ export class SystemRunner {
run(system: SystemDef): void | Promise<void> {
const twin = this.aot_?.systems.get(system._name);
- if (twin) {
- this.runCompiled_(system, twin);
- return;
- }
+ // Falls through when the dispatcher could not take it, which is the
+ // interpreter keeping the system rather than the system not running.
+ if (twin && this.runCompiled_(system, twin)) return;
let args = this.argsCache_.get(system._id);
if (!args) {
args = new Array(system._params.length);
@@ -567,14 +566,18 @@ export class SystemRunner {
* A compiled system's frame: the dispatcher does the contract, this keeps the
* scheduler's own books — what it cost, and when it last ran.
*/
- private runCompiled_(system: SystemDef, twin: AotTwin): void {
+ private runCompiled_(system: SystemDef, twin: AotTwin): boolean {
const t0 = this.timings_ ? performance.now() : 0;
- this.aotDispatch_!.run(twin);
+ // A dispatcher that could not take this one has not failed: the system
+ // is interpreted this frame, which is the fallback the whole design
+ // rests on, arriving at the only layer that still has the closure.
+ if (!this.aotDispatch_!.run(twin)) return false;
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());
+ return true;
}
private flushSystem_(system: SystemDef, args: unknown[], t0: number): void {
diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.ts
index ffc381352..00cbca68b 100644
--- a/sdk/src/runtime/packagedRuntime.ts
+++ b/sdk/src/runtime/packagedRuntime.ts
@@ -179,7 +179,7 @@ export function packagedAppOptions(
export function packagedRuntimeInit(
config: Pick<PackagedGameConfig,
'physicsEnabled' | 'physicsConfig' | 'audioConfig' | 'uiTheme' | 'uiThemeColors'
- | 'achievements' | 'steamAppId' | 'screenFit'>,
+ | 'achievements' | 'steamAppId' | 'screenFit' | 'aot'>,
): {
physicsEnabled?: boolean;
physicsConfig?: Physics2DPluginConfig;
@@ -189,6 +189,7 @@ export function packagedRuntimeInit(
achievements?: string[];
steamAppId?: number;
screenFit?: PackagedGameConfig['screenFit'];
+ aot?: PackagedGameConfig['aot'];
} {
return {
physicsEnabled: config.physicsEnabled,
@@ -201,6 +202,10 @@ export function packagedRuntimeInit(
// Also here, not only in packagedAppOptions: the camera fit is baked into
// the app's construction, but the WINDOW is sized on a live one.
screenFit: config.screenFit,
+ // Here rather than per host: a host that names the fields it knows about
+ // is a host the next one never reaches, and this one reached none of the
+ // native road until it was asked for by hand.
+ aot: config.aot,
};
}
diff --git a/sdk/tests/aot-dispatcher-seam.test.ts b/sdk/tests/aot-dispatcher-seam.test.ts
index c4246f817..8fa1e0357 100644
--- a/sdk/tests/aot-dispatcher-seam.test.ts
+++ b/sdk/tests/aot-dispatcher-seam.test.ts
@@ -49,11 +49,12 @@ const MANIFEST: AotManifest = {
class HostPackedDispatcher {
readonly ran: string[] = [];
constructor(private readonly world: World) {}
- run(twin: AotTwin): void {
+ run(twin: AotTwin): boolean {
this.ran.push(twin.decl.name);
for (const e of this.world.queryEntities([Drift])) {
this.world.set(e, Drift, { x: this.world.get(e, Drift).x + 1 });
}
+ return true;
}
}
diff --git a/sdk/tests/aot-native-install.test.ts b/sdk/tests/aot-native-install.test.ts
index 1b9c44194..f1ae70836 100644
--- a/sdk/tests/aot-native-install.test.ts
+++ b/sdk/tests/aot-native-install.test.ts
@@ -49,21 +49,27 @@ const MANIFEST: AotManifest = {
],
};
-/** A host that bound only the systems it was told to. */
-function fakeHost(boundNames: readonly string[]) {
+/** A host that can run only the systems it was told it could name. */
+function fakeHost(runnable: readonly string[]) {
const order = MANIFEST.systems.map((s) => s.name);
const calls: number[] = [];
const reported: { name: string; rows: number; sparseCount: number }[] = [];
const bindings: NativeAotBindings = {
install: () => order.length,
index: (name) => order.indexOf(name),
- bound: (i) => boundNames.includes(order[i] ?? ''),
+ bound: (i) => runnable.includes(order[i] ?? ''),
scriptRows: (name, _sparse, sparseCount, rows) => {
reported.push({ name, rows, sparseCount });
return true;
},
resource: () => true,
- run: (i) => { calls.push(i); return 0; },
+ // Negative is "I still cannot name everything this reads" — the answer
+ // that sends the system back to the interpreter for this frame.
+ run: (i) => {
+ if (!runnable.includes(order[i] ?? '')) return -1;
+ calls.push(i);
+ return 0;
+ },
reset: () => {},
};
return { bindings, calls, reported };
@@ -82,18 +88,19 @@ function fixture(boundNames: readonly string[]) {
}
describe('installing compiled systems on a host that loads a library', () => {
- it('makes a twin only of what the host bound, so the rest still interpret', () => {
+ it('a system the host cannot run is interpreted that frame, not skipped', () => {
const f = fixture(['DriftSystem']);
const Drift = f.Drift;
expect(f.runtime).not.toBeNull();
- expect(f.runtime!.systems.size).toBe(1);
- expect(f.runtime!.systems.get('DriftSystem')).toBeDefined();
- expect(f.runtime!.systems.get('OtherSystem')).toBeUndefined();
+ // Every declared system has a twin: whether the host can run one is a
+ // fact about the frame — a pool has no rows until an entity has that
+ // component — so it is settled at the call and asked again next time.
+ expect(f.runtime!.systems.size).toBe(2);
let interpreted = 0;
const other = defineSystem([Query(Mut(Drift))], () => { interpreted++; }, { name: 'OtherSystem' });
const compiled = defineSystem([Query(Mut(Drift))], () => {
- throw new Error('the closure must not run when the host bound this one');
+ throw new Error('the closure must not run when the host took this one');
}, { name: 'DriftSystem' });
const entity = f.world.spawn();
@@ -105,17 +112,18 @@ describe('installing compiled systems on a host that loads a library', () => {
expect(interpreted).toBe(1);
});
- it('says nothing at all where the host bound nothing', () => {
+ it('every system interprets where the host can run none of them', () => {
const f = fixture([]);
const Drift = f.Drift;
- expect(f.runtime!.systems.size).toBe(0);
let interpreted = 0;
const system = defineSystem([Query(Mut(Drift))], () => { interpreted++; }, { name: 'DriftSystem' });
f.runner.run(system);
+ f.runner.run(system);
expect(f.calls).toEqual([]);
- expect(interpreted).toBe(1);
+ // Twice, because a refusal is per frame: the host may be able to next one.
+ expect(interpreted).toBe(2);
});
it('tells the host where the rows are, once per move rather than per frame', () => {
diff --git a/src/esengine/aot/AotDispatcher.hpp b/src/esengine/aot/AotDispatcher.hpp
index 4345d1630..7f847c445 100644
--- a/src/esengine/aot/AotDispatcher.hpp
+++ b/src/esengine/aot/AotDispatcher.hpp
@@ -47,9 +47,11 @@ public:
std::string* why = nullptr) {
reset();
if (!module_.open(path, expected, why)) return false;
+ components_ = components;
+ resources_ = resources;
for (const EsSystemDecl& decl : module_.systems()) {
names_.push_back(decl.name != nullptr ? decl.name : "");
- bound_.push_back(bind(decl, components, resources));
+ bound_.push_back(::esengine::aot::bind(decl, components, resources));
}
return true;
}
@@ -81,6 +83,14 @@ public:
std::span<const EsCmd> run(std::size_t i, std::span<const std::uint32_t> candidates,
const ResourceLookup& resources) {
if (i >= bound_.size()) return {};
+ // Asked again where install could not name everything: a pool the
+ // scripting language owns does not exist until an entity has that
+ // component, so the answer is about the frame, not the module.
+ if (bound_[i].fn == nullptr) {
+ // Qualified: `std::bind` is visible through <functional> and takes anything.
+ bound_[i] = ::esengine::aot::bind(module_.systems()[i], components_, resources_);
+ }
+ if (bound_[i].fn == nullptr) return {};
return runBound(bound_[i], candidates, resources, arena_);
}
@@ -88,6 +98,8 @@ public:
void reset() {
bound_.clear();
names_.clear();
+ components_ = {};
+ resources_ = {};
module_.close();
}
@@ -97,6 +109,10 @@ private:
Module module_;
std::vector<const char*> names_;
std::vector<BoundSystem> bound_;
+ /** Kept so a system that could not be named at install can be asked
+ * again — the answer changes as the world comes up. */
+ ComponentLookup components_;
+ ResourceLookup resources_;
CallArena arena_;
};
diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjs
index cc19db8f8..1b5dd6db6 100644
--- a/tools/releaseGate.mjs
+++ b/tools/releaseGate.mjs
@@ -89,6 +89,19 @@ export const CRITERIA = [
'pipeline/tests/hotupdate-verify-fixture.test.ts',
],
},
+ {
+ id: 'a-desktop-app-runs-its-systems-as-machine-code',
+ says: 'a packaged desktop game loads its compiled systems and dispatches to them',
+ // Installed is not enough. A module can load and never be reached: on this
+ // road binding is settled at the first call, because a script pool does not
+ // exist until an entity has that component.
+ answeredBy: 'node tools/verify-aot-native.mjs',
+ needs: [
+ 'tools/verify-aot-native.mjs',
+ 'native/host/bindings/AotBindings.cpp',
+ 'sdk/src/ecs/aot/installNativeAot.ts',
+ ],
+ },
{
id: 'compiled-systems-compute-what-the-interpreter-computes',
says: 'a packaged compiled system moves the world exactly as the interpreted one does',
diff --git a/tools/verify-aot-native.mjs b/tools/verify-aot-native.mjs
new file mode 100644
index 000000000..772f9dfd2
--- /dev/null
+++ b/tools/verify-aot-native.mjs
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file verify-aot-native.mjs — a packaged desktop game runs its systems as machine code.
+ *
+ * The wasm road is gated end to end and the pieces of this one are gated apart:
+ * the module builds, the loader opens it, the dispatcher binds it, the SDK
+ * installs it. None of that says a shipped app on this machine actually reaches
+ * a compiled system, and the ways it can fail to are quiet — a module staged
+ * where the loader does not look, a config field no host projects, a pool that
+ * does not exist yet at install.
+ *
+ * So: export the example that marks a system `@compiled`, run the app it
+ * assembles, and require the runtime to say both things. Installed is not
+ * enough: a module can load and never be dispatched to, and on this road the
+ * two are different frames.
+ *
+ * node tools/verify-aot-native.mjs
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installedTemplateDir } from '../build-tools/utils/nativeTemplate.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** The example whose system carries the marker. */
+const PROJECT = path.join(ROOT, 'examples', 'ecs-basics');
+/** Frames to let run before the shot: enough for a pool to exist and be bound. */
+const SHOT_FRAME = '90';
+
+const version = JSON.parse(
+ spawnSync(process.execPath, ['-p', 'JSON.stringify(require("./package.json"))'],
+ { cwd: ROOT, encoding: 'utf8' }).stdout || '{}',
+).version;
+
+// The template vocabulary, which is the OS a desktop app is BUILT as. Spelled
+// here because pipeline's own answer is TypeScript and this file is not.
+const os = process.platform === 'darwin' ? 'macos'
+ : process.platform === 'win32' ? 'windows' : 'linux';
+const template = installedTemplateDir(version, os);
+if (!template || !existsSync(template)) {
+ // Loud, not silent: a gate that skipped without saying so is a gate that
+ // always passes on the machines that never had the thing it checks.
+ console.log(`aot native: no ${os} runtime template for v${version} — did NOT run.`);
+ console.log(' build one with: node build-tools/cli.js native --target ' + os);
+ process.exit(0);
+}
+
+const out = mkdtempSync(path.join(tmpdir(), 'estella-aot-native-'));
+try {
+ const exported = spawnSync(process.execPath, [
+ path.join(ROOT, 'pipeline', 'bin', 'estella.mjs'), 'export', PROJECT,
+ '--platform', 'desktop', '--out', out, '--template', template,
+ ], { encoding: 'utf8', cwd: ROOT });
+ if (exported.status !== 0) {
+ console.error('✗ the export failed');
+ console.error((exported.stderr || exported.stdout || '').trim().slice(-600));
+ process.exit(1);
+ }
+
+ const exe = findExecutable(out);
+ if (exe === null) {
+ console.error(`✗ the export assembled no app under ${out}`);
+ process.exit(1);
+ }
+
+ const run = spawnSync(exe, [], {
+ encoding: 'utf8',
+ cwd: path.dirname(exe),
+ env: {
+ ...process.env,
+ ESTELLA_SHOT: path.join(out, 'frame.raw'),
+ ESTELLA_SHOT_FRAME: SHOT_FRAME,
+ ESTELLA_SHOT_QUIT: '1',
+ },
+ });
+ const log = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+
+ const installed = /AOT: (\d+) compiled system\(s\) installed/.exec(log);
+ const running = /AOT: (\w+) is running compiled/.exec(log);
+ const drew = /"rendered":true/.test(log);
+
+ const problems = [];
+ if (installed === null || Number(installed[1]) < 1) problems.push('no module was installed');
+ // The claim this file exists for. A module that loads and is never dispatched
+ // to leaves the line above intact and the game entirely interpreted.
+ if (running === null) problems.push('no system was ever dispatched to as compiled');
+ if (!drew) problems.push('the app never drew a frame');
+
+ if (problems.length > 0) {
+ console.error('✗ aot native: ' + problems.join('; '));
+ for (const line of log.split('\n').filter((l) => /aot|AOT|error|ERROR/.test(l)).slice(0, 10)) {
+ console.error(` ${line.trim()}`);
+ }
+ process.exit(1);
+ }
+ console.log(`✓ aot native: ${installed[1]} installed, ${running[1]} running compiled, and it drew`);
+} finally {
+ rmSync(out, { recursive: true, force: true });
+}
+
+/** The assembled app's executable, wherever the assembler put it. */
+function findExecutable(dir) {
+ const stack = [dir];
+ while (stack.length > 0) {
+ const at = stack.pop();
+ for (const entry of readdirSync(at, { withFileTypes: true })) {
+ const full = path.join(at, entry.name);
+ if (entry.isDirectory()) { stack.push(full); continue; }
+ if (process.platform === 'win32' ? entry.name.endsWith('.exe') : !path.extname(entry.name)) {
+ // The content dir holds no executable, so anything found is the app's.
+ if (!full.includes(`${path.sep}Content${path.sep}`)) return full;
+ }
+ }
+ }
+ return null;
+}