A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(aot): a packaged desktop game runs its systems as machine code
yhh7cdc20d05455
diff --git a/native/host/Host.hpp b/native/host/Host.hppindex 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.cppindex 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.cppindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 @experimentaldiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 | nuresourceAt: () => 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 | nuclass 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.hppindex 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.mjsindex 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.mjsnew file mode 100644index 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;+}