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): one answer to "does this project promise compilation"
yhh498f26147627
diff --git a/desktop b/desktopindex d3ab86a91..bf445b821 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit d3ab86a91ea5c2e34b25d22ddd033a5866bee346+Subproject commit bf445b821bfebd1fec857b25b2646b23ccdd833ddiff --git a/pipeline/src/bundle/buildCompiledSystems.ts b/pipeline/src/bundle/buildCompiledSystems.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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');+ });+});