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): one answer to "does this project promise compilation"

yhh498f26147627
diff --git a/desktop b/desktop
index d3ab86a91..bf445b821 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit d3ab86a91ea5c2e34b25d22ddd033a5866bee346
+Subproject commit bf445b821bfebd1fec857b25b2646b23ccdd833d
diff --git a/pipeline/src/bundle/buildCompiledSystems.ts b/pipeline/src/bundle/buildCompiledSystems.ts
index 8e3e2e247..3bc61d0e5 100644
--- a/pipeline/src/bundle/buildCompiledSystems.ts
+++ b/pipeline/src/bundle/buildCompiledSystems.ts
@@ -89,6 +89,22 @@ function sources(root: string): string[] {
return out;
}
+/** A marker anywhere in a file. Text, not a parse: this only decides whether the
+ * expensive answer is worth computing. */
+const anyPromise = (files: string[]): boolean =>
+ files.some((f) => readFileSync(f, 'utf8').includes('@compiled'));
+
+/**
+ * Whether this project promises any compilation at all.
+ *
+ * The cheap half of what {@link buildCompiledSystems} answers, exported because
+ * the editor's platform catalog must say a target needs emcc BEFORE an export
+ * spawns one. Both read this, so they cannot disagree about what was promised.
+ */
+export function promisesCompilation(root: string): boolean {
+ return anyPromise(sources(root));
+}
+
/**
* Compile the project's `@compiled` systems to `<root>/.esengine/cache/aot/`.
*
@@ -120,7 +136,7 @@ export async function buildCompiledSystems(
// A project with no `@compiled` anywhere promised nothing, so it must not pay
// for a TypeScript Program over its sources. Nothing is decided here: the parse
// below still decides, this only skips having nothing to decide.
- if (!files.some((f) => readFileSync(f, 'utf8').includes('@compiled'))) {
+ if (!anyPromise(files)) {
return { ok: true, wasmPath: null, manifest: null, errors: [], notes: [] };
}
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index d3849c82c..2cbeaa85b 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -49,7 +49,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 { isNativePlatform, desktopTemplateFor, type DesktopOs, type ExportPlatform } from '../project/platforms';
+import { compilesSystems, 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';
@@ -699,11 +699,11 @@ 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. A mini-game
- // stages its own above and takes a path; a playable inlines everything and
- // has nowhere to put a module, and QuickJS cannot instantiate one at all.
+ // 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.
let aot: PackagedGameConfig['aot'];
- if (platform === 'web') {
+ if (compilesSystems(platform)) {
// 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.
diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.ts
index 62fb7cc97..aaa8f9521 100644
--- a/pipeline/src/export/platformCatalog.ts
+++ b/pipeline/src/export/platformCatalog.ts
@@ -30,7 +30,8 @@ import {
BUILTIN_PLAYABLE_PROFILES, builtinPlayableProfile, genericPlayableProfile,
type PlayableAdProfile,
} from './playableAdProfile';
-import { BUILTIN_PLATFORMS, DESKTOP_OSES, desktopTemplateFor, type PlatformPrereq } from '../project/platforms';
+import { BUILTIN_PLATFORMS, DESKTOP_OSES, compilesSystems, desktopTemplateFor, type PlatformPrereq } from '../project/platforms';
+import { promisesCompilation } from '../bundle/buildCompiledSystems';
import { resolveNativeTemplate } from './nativeTemplates';
import { templateId } from '../../../build-tools/utils/nativeTemplate.js';
import type { MiniGameExportProfile, MiniGameConfigContext } from './miniGameExportProfile';
@@ -612,6 +613,10 @@ 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,
): Promise<PlatformStatus[]> {
const out: PlatformStatus[] = BUILTIN_PLATFORMS.map((id) => ({
id,
@@ -681,5 +686,24 @@ export async function listPlatforms(
});
}
- return out;
+ return withAotPrereq(out, root, emcc);
+}
+
+/**
+ * Mark the targets whose export would compile systems this machine cannot build.
+ *
+ * Unlike Xcode this cannot be deferred: the module ships inside the package. A
+ * project that promised nothing is told nothing, and a row already blocked by a
+ * missing engine runtime keeps that harder answer.
+ */
+function withAotPrereq(
+ rows: PlatformStatus[], root: string, emcc: string | null,
+): PlatformStatus[] {
+ if (emcc || !promisesCompilation(root)) return rows;
+ for (const row of rows) {
+ if (!row.ready || !compilesSystems(row.id)) continue;
+ row.ready = false;
+ row.prereq = { kind: 'toolchain-missing', tool: 'emsdk' };
+ }
+ return rows;
}
diff --git a/pipeline/src/project/platforms.ts b/pipeline/src/project/platforms.ts
index 1ea76fcfc..1427e080f 100644
--- a/pipeline/src/project/platforms.ts
+++ b/pipeline/src/project/platforms.ts
@@ -124,7 +124,7 @@ export type PlatformPrereq =
| {
kind: 'toolchain-missing';
/** Which piece is absent — the dialog maps it to a localized sentence. */
- tool: NativeToolchain;
+ tool: ToolchainPiece;
}
| {
/**
@@ -143,5 +143,25 @@ export type PlatformPrereq =
version: string;
};
-/** The native toolchain pieces the editor probes for. */
-export type NativeToolchain = 'xcode' | 'macos';
+/**
+ * The toolchain pieces the editor probes for.
+ *
+ * `xcode` and `macos` gate ASSEMBLY, which can happen on another machine; a
+ * 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';
+
+/**
+ * Whether this target's export compiles the project's `@compiled` systems.
+ *
+ * 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.
+ */
+export function compilesSystems(platform: ExportPlatform): boolean {
+ if (platform === 'web' || platform === 'wechat') return true;
+ // 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);
+}
diff --git a/pipeline/tests/native-template.test.ts b/pipeline/tests/native-template.test.ts
index 00db3f4e3..1c548db22 100644
--- a/pipeline/tests/native-template.test.ts
+++ b/pipeline/tests/native-template.test.ts
@@ -29,6 +29,8 @@ import { verifyTemplateZip } from '../../build-tools/tasks/verifyTemplate.js';
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;
let store: string;
let scratch: string;
@@ -287,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)).find((r) => r.id === 'ios')!;
+ const iosRow = async () => (await listPlatforms(null, dirs(), VERSION, EMCC)).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 ab495d2b7..9c19b11a3 100644
--- a/pipeline/tests/platform-catalog.test.ts
+++ b/pipeline/tests/platform-catalog.test.ts
@@ -29,6 +29,11 @@ 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);
+
function writePlatform(name: string, source: string): void {
const dir = path.join(root, PROJECT_PLATFORM_DIR);
mkdirSync(dir, { recursive: true });
@@ -53,7 +58,7 @@ afterEach(() => {
describe('listPlatforms — built-in readiness is probed', () => {
it('web/desktop/playable are not ready without the web engine glue', async () => {
- const rows = await listPlatforms(root, dirs(), VERSION);
+ const rows = await platforms(root);
const byId = Object.fromEntries(rows.map((r) => [r.id, r]));
expect(byId.web.ready).toBe(false);
@@ -64,7 +69,7 @@ describe('listPlatforms — built-in readiness is probed', () => {
it('the web glue makes playable ready too — it inlines the WEB runtime, not a -t playable one', async () => {
writeFileSync(path.join(webDir, 'esengine.js'), '//');
- const rows = await listPlatforms(root, dirs(), VERSION);
+ const rows = await platforms(root);
const byId = Object.fromEntries(rows.map((r) => [r.id, r]));
expect(byId.web.ready).toBe(true);
@@ -77,15 +82,15 @@ describe('listPlatforms — built-in readiness is probed', () => {
it('WeChat accepts either its own glue or a web-aligned one', async () => {
writeFileSync(path.join(wxDir, 'esengine.wxgame.js'), '//');
- expect((await listPlatforms(root, dirs(), VERSION)).find((r) => r.id === 'wechat')?.ready).toBe(true);
+ expect((await platforms(root)).find((r) => r.id === 'wechat')?.ready).toBe(true);
rmSync(path.join(wxDir, 'esengine.wxgame.js'));
writeFileSync(path.join(wxDir, 'esengine.js'), '//');
- expect((await listPlatforms(root, dirs(), VERSION)).find((r) => r.id === 'wechat')?.ready).toBe(true);
+ expect((await platforms(root)).find((r) => r.id === 'wechat')?.ready).toBe(true);
});
it('reports paths with forward slashes, whatever the platform separator', async () => {
- const wx = (await listPlatforms(root, dirs(), VERSION)).find((r) => r.id === 'wechat');
+ const wx = (await platforms(root)).find((r) => r.id === 'wechat');
expect((wx?.prereq as { dir?: string } | undefined)?.dir).not.toContain('\\');
});
});
@@ -98,7 +103,7 @@ describe('listPlatforms — platforms the project defines', () => {
};`);
writeFileSync(path.join(webDir, 'esengine.js'), '//');
- const rows = await listPlatforms(root, dirs(), VERSION);
+ const rows = await platforms(root);
const acme = rows.find((r) => r.id === 'acme');
expect(acme).toBeDefined();
expect(acme!.source).toBe('project');
@@ -115,7 +120,7 @@ describe('listPlatforms — platforms the project defines', () => {
};`);
writeFileSync(path.join(webDir, 'esengine.js'), '//');
- const acme = (await listPlatforms(root, dirs(), VERSION)).find((r) => r.id === 'acme');
+ const acme = (await platforms(root)).find((r) => r.id === 'acme');
expect(acme!.ready).toBe(false);
expect((acme!.prereq as { dir?: string } | undefined)?.dir).toBe('build/wasm/acme');
// The editor does not know how a project builds its own runtime, so it
@@ -125,7 +130,7 @@ describe('listPlatforms — platforms the project defines', () => {
it('a broken profile is listed with its error, not silently dropped', async () => {
writePlatform('bad.mjs', 'export default { this is not valid javascript');
- const rows = await listPlatforms(root, dirs(), VERSION);
+ const rows = await platforms(root);
const bad = rows.find((r) => r.id === 'bad');
expect(bad).toBeDefined();
expect(bad!.ready).toBe(false);
@@ -140,7 +145,7 @@ describe('listPlatforms — platforms the project defines', () => {
writePlatform('c.mjs', `export default { id: 'ok-id', emitConfigFiles: () => [] };`);
writePlatform('d.mjs', `export default { id: 'ok-id2', label: 'X' };`);
- const rows = await listPlatforms(root, dirs(), VERSION);
+ const rows = await platforms(root);
const errs = rows.filter((r) => r.source === 'project').map((r) => r.error);
expect(errs).toHaveLength(4);
expect(errs[0]).toContain('built-in');
@@ -152,7 +157,7 @@ describe('listPlatforms — platforms the project defines', () => {
});
it('lists only built-ins when no project is open', async () => {
- const rows = await listPlatforms(null, dirs(), VERSION);
+ const rows = await platforms(null);
expect(rows.every((r) => r.source === 'builtin')).toBe(true);
});
});
@@ -178,7 +183,7 @@ describe('createProjectPlatform — scaffolding', () => {
// What was scaffolded is immediately a real platform.
writeFileSync(path.join(webDir, 'esengine.js'), '//');
- const rows = await listPlatforms(root, dirs(), VERSION);
+ const rows = await platforms(root);
const acme = rows.find((r) => r.id === 'acme-play');
expect(acme?.source).toBe('project');
expect(acme?.label).toBe('ACME Play');
@@ -279,7 +284,7 @@ describe('loadProjectPlatform — the profile handed to exportMiniGame', () => {
id: 'acme', label: 'ACME Play', runtimeProfile: 'src/missing.ts',
emitConfigFiles: () => [],
};`);
- const acme = (await listPlatforms(root, dirs(), VERSION)).find((r) => r.id === 'acme');
+ const acme = (await platforms(root)).find((r) => r.id === 'acme');
expect(acme!.ready).toBe(false);
expect(acme!.error).toContain('runtimeProfile');
});
@@ -291,7 +296,7 @@ describe('loadProjectPlatform — the profile handed to exportMiniGame', () => {
id: 'acme', label: 'A', runtimeProfile: 'src/rt', emitConfigFiles: () => [],
};`);
writeFileSync(path.join(webDir, 'esengine.js'), '//');
- const acme = (await listPlatforms(root, dirs(), VERSION)).find((r) => r.id === 'acme');
+ const acme = (await platforms(root)).find((r) => r.id === 'acme');
expect(acme!.error).toBeUndefined();
expect(acme!.ready).toBe(true);
});
@@ -394,7 +399,7 @@ describe('playable ad networks', () => {
writePlatform('acme-mini.mjs', `export default {
id: 'acme-mini', label: 'Acme MiniGame', emitConfigFiles: () => [],
};`);
- expect((await listPlatforms(root, dirs(), VERSION)).map((r) => r.id)).not.toContain('acme-ads');
+ expect((await platforms(root)).map((r) => r.id)).not.toContain('acme-ads');
expect((await listPlayableNetworks(root)).map((r) => r.id)).not.toContain('acme-mini');
// And a network id must not shadow a network the editor ships.
writePlatform('meta.mjs', "export default { id: 'meta', kind: 'playable', label: 'Mine', maxBytes: 1, limitNote: 'x' };");
@@ -414,3 +419,75 @@ describe('playable ad networks', () => {
expect(row?.error).toBeUndefined();
});
});
+
+describe('listPlatforms — the AOT toolchain, only where it is owed', () => {
+ /** A project that promises compilation, and a web runtime so the row is
+ * otherwise ready. */
+ const promising = (): void => {
+ mkdirSync(path.join(root, 'src'), { recursive: true });
+ writeFileSync(path.join(root, 'src', 'move.ts'), '/** @compiled */ export const x = 1;');
+ writeFileSync(path.join(webDir, 'esengine.js'), '//');
+ writeFileSync(path.join(wxDir, 'esengine.wxgame.js'), '//');
+ };
+ const rows = (emcc: string | null) => listPlatforms(root, dirs(), VERSION, emcc);
+
+ 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]));
+
+ expect(byId.web.ready).toBe(true);
+ expect(byId.web.prereq).toBeUndefined();
+ });
+
+ it('blocks the targets that would compile, and names emsdk', async () => {
+ promising();
+ const byId = Object.fromEntries((await rows(null)).map((r) => [r.id, r]));
+
+ expect(byId.web.ready).toBe(false);
+ expect(byId.web.prereq).toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
+ expect(byId.wechat.ready).toBe(false);
+ expect(byId.wechat.prereq).toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
+ });
+
+ it('leaves alone the targets whose export never compiles', async () => {
+ promising();
+ const byId = Object.fromEntries((await rows(null)).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
+ // 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('a project platform rides the same rule — it packages through the mini-game path', async () => {
+ promising();
+ writePlatform('acme.mjs', `export default {
+ id: 'acme', label: 'ACME', emitConfigFiles: () => [],
+ };`);
+ const acme = (await rows(null)).find((r) => r.id === 'acme');
+
+ expect(acme!.ready).toBe(false);
+ expect(acme!.prereq).toEqual({ kind: 'toolchain-missing', tool: 'emsdk' });
+ });
+
+ it('clears once the machine has one', async () => {
+ promising();
+ const byId = Object.fromEntries((await rows('/opt/emsdk/emcc')).map((r) => [r.id, r]));
+
+ expect(byId.web.ready).toBe(true);
+ expect(byId.wechat.ready).toBe(true);
+ });
+
+ 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');
+
+ expect(web!.ready).toBe(false);
+ expect(web!.prereq?.kind).toBe('runtime-missing');
+ });
+});