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
fix(desktop): packaged editor can play + export (no runtime bundling of editor sources)
yhh7e420c81785c
diff --git a/desktop/electron-builder.yml b/desktop/electron-builder.ymlindex b128ff729..81e647aa7 100644--- a/desktop/electron-builder.yml+++ b/desktop/electron-builder.yml@@ -13,8 +13,19 @@ files:- dist/**- dist-electron/**- package.json+# Trees the runtime consumes as REAL files, not through Electron's patched fs:+# - esbuild runs as a native subprocess (project scripts, exports) — its own+# binary, the prebuilt realm-host bundles it re-bundles for exports, and the+# SDK dist that inlined (playable/wechat) bundles alias `esengine` to must+# all be readable outside app.asar;+# - the engine wasm runtime is staged into play realms / exports by recursive+# directory copy, which cannot source from inside an asar.asarUnpack:- "**/node_modules/{esbuild,@esbuild}/**"+ - dist-electron/hosts/**+ - "**/node_modules/esengine/dist/**"+ - dist/wasm/**+ - dist/wasm-wechat/**# The Basis KTX2 encoder lives at the monorepo root (build-tools/basis).# cookAssets imports it via `../../build-tools/basis` relative to the bundled# main; once packaged, main sits at resources/app.asar/dist-electron/, so thatdiff --git a/desktop/electron/buildPlayRealm.ts b/desktop/electron/buildPlayRealm.tsindex a7bd8e692..d1b81b2e4 100644--- a/desktop/electron/buildPlayRealm.ts+++ b/desktop/electron/buildPlayRealm.ts@@ -5,18 +5,22 @@* self-contained realm under the project's `.esengine/play/` so the editor* can run it from `estella://project/.esengine/play/play.html` (everything* same-origin estella://):- * - host.js esbuild of src/playHost.ts, esengine EXTERNAL+ * - host.js the PREBUILT play-host bundle (esengine EXTERNAL), copied* - sdk/ a copy of the SDK dist (the import-map target)* - wasm/ a copy of the engine runtime (glue + binary + side modules)* - play.html the host page: import map (esengine → ./sdk) + host.js- * The project bundle (`.esengine/cache/scripts.mjs`, esengine external —- * built separately by buildProjectScripts) resolves esengine through the- * SAME import map, so its defineComponent/defineSystem register into the- * instance the host's createWebApp uses (custom components+systems run).+ * The host is editor code: it's bundled at editor build time (the+ * realm-hosts step in vite.config.ts) and staged here by copy — never+ * bundled at runtime, since a packaged app ships no src/ and esbuild (a+ * native subprocess) cannot read app.asar. The project bundle+ * (`.esengine/cache/scripts.mjs`, esengine external — built separately by+ * buildProjectScripts, which DOES esbuild at runtime: project sources+ * live on the real filesystem) resolves esengine through the SAME import+ * map, so its defineComponent/defineSystem register into the instance the+ * host's createWebApp uses (custom components+systems run).*- * Pure Node (esbuild + fs); IPC wiring in main.ts.+ * Pure Node (fs); IPC wiring in main.ts.*/-import { build } from 'esbuild';import { cp, mkdir, rm, writeFile, readFile, stat, readdir } from 'node:fs/promises';import { existsSync } from 'node:fs';import { createHash } from 'node:crypto';@@ -104,7 +108,8 @@ async function syncDir(src: string, dst: string, stampFile: string): Promise<voiexport async function buildPlayRealm(opts: {root: string;- playHostEntry: string;+ /** The prebuilt play-host bundle (dist-electron/hosts/playHost.js). */+ playHostArtifact: string;sdkDistDir: string;wasmDir: string;}): Promise<PlayRealmResult> {@@ -112,35 +117,25 @@ export async function buildPlayRealm(opts: {const errors: string[] = [];await mkdir(out, { recursive: true });- // 1. Host module — esengine EXTERNAL (resolved by the realm's import map).- // Stamped on the entry's stat so a repeat Play skips esbuild.+ // 1. Host module — the prebuilt bundle, staged by copy (readFile/writeFile so+ // an asar-packed artifact reads through Electron's patched fs). Stamped on+ // the artifact's stat so a repeat Play skips the copy.+ if (!existsSync(opts.playHostArtifact)) {+ return {+ ok: false,+ hostPath: '',+ errors: [`play host bundle not found: ${opts.playHostArtifact} (built by vite build — see realm-hosts in vite.config.ts)`],+ };+ }const hostStamp = path.join(out, '.host-stamp');const hostOut = path.join(out, 'host.js');- const entryStat = await stat(opts.playHostEntry);- const hostSig = `${opts.playHostEntry}:${entryStat.size}:${Math.round(entryStat.mtimeMs)}`;+ const entryStat = await stat(opts.playHostArtifact);+ const hostSig = `${opts.playHostArtifact}:${entryStat.size}:${Math.round(entryStat.mtimeMs)}`;const hostFresh =existsSync(hostOut) && existsSync(hostStamp) && (await readFile(hostStamp, 'utf8')) === hostSig;if (!hostFresh) {- try {- const res = await build({- entryPoints: [opts.playHostEntry],- bundle: true,- format: 'esm',- platform: 'browser',- target: 'es2020',- external: ['esengine', 'esengine/*'],- outfile: hostOut,- sourcemap: false,- write: true,- logLevel: 'silent',- });- errors.push(...res.errors.map((e) => e.text));- if (errors.length === 0) await writeFile(hostStamp, hostSig);- } catch (err) {- const e = err as { errors?: { text: string }[]; message?: string };- errors.push(...(e.errors?.map((x) => x.text) ?? [String(e.message ?? err)]));- return { ok: false, hostPath: '', errors };- }+ await writeFile(hostOut, await readFile(opts.playHostArtifact));+ await writeFile(hostStamp, hostSig);}// 2. SDK + wasm copies (gated on a full dir signature, so an added file re-syncs).diff --git a/desktop/electron/buildScripts.ts b/desktop/electron/buildScripts.tsindex 1e45cd543..8705c9acf 100644--- a/desktop/electron/buildScripts.ts+++ b/desktop/electron/buildScripts.ts@@ -12,9 +12,10 @@* Pure Node (esbuild + fs/path), no Electron imports, so it is unit-testable and* reusable; the IPC wiring lives in main.ts.*/-import { build, type BuildResult } from 'esbuild';+import type { BuildResult } from 'esbuild';import { existsSync } from 'node:fs';import path from 'node:path';+import { loadEsbuild } from './esbuildRuntime';/** esengine and any subpath import are left for the realm's import map to resolve. */const EXTERNAL = ['esengine', 'esengine/*'];@@ -47,6 +48,7 @@ export async function buildProjectScripts(}const outputPath = path.join(root, CACHE_DIR, OUTPUT);try {+ const { build } = await loadEsbuild();const result: BuildResult = await build({entryPoints: [entryPath],bundle: true,diff --git a/desktop/electron/esbuildRuntime.ts b/desktop/electron/esbuildRuntime.tsnew file mode 100644index 000000000..e16b1628f--- /dev/null+++ b/desktop/electron/esbuildRuntime.ts@@ -0,0 +1,43 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The single door to esbuild in the main process. esbuild's node lib+ * snapshots ESBUILD_BINARY_PATH at module load and spawns that binary+ * as a NATIVE service — child_process does not read through app.asar,+ * so a packaged app must point it at the app.asar.unpacked twin BEFORE+ * the library first evaluates. A static `import 'esbuild'` anywhere in+ * the main bundle evaluates ahead of every module body (ESM semantics),+ * too early for any env assignment — importing lazily through here+ * makes the ordering intrinsic instead of an import-order accident,+ * and keeps the tool out of editor startup.+ *+ * Pure Node (no Electron imports — the callers are unit-testable):+ * "packaged" is detected by what actually matters here, whether this+ * module runs from inside an asar archive.+ */+import path from 'node:path';+import { fileURLToPath } from 'node:url';++export type Esbuild = typeof import('esbuild');++let loaded: Promise<Esbuild> | null = null;++export function loadEsbuild(): Promise<Esbuild> {+ if (!loaded) {+ // import.meta.url, not __dirname: the main bundle is ESM (no __dirname),+ // and a typeof-guarded __dirname dodges the bundler's ESM rewrite.+ const here = path.dirname(fileURLToPath(import.meta.url));+ if (/app\.asar[\\/]/.test(here) && !process.env.ESBUILD_BINARY_PATH) {+ // Same flat layout electron-builder packs + asarUnpacks (electron-builder.yml).+ const exe =+ process.platform === 'win32'+ ? path.join('@esbuild', `win32-${process.arch}`, 'esbuild.exe')+ : path.join('@esbuild', `${process.platform}-${process.arch}`, 'bin', 'esbuild');+ process.env.ESBUILD_BINARY_PATH = path+ .join(here, '..', 'node_modules', exe)+ .replace(/app\.asar(?=[\\/])/, 'app.asar.unpacked');+ }+ loaded = import('esbuild');+ }+ return loaded;+}diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.tsindex ec2482c41..900748b4d 100644--- a/desktop/electron/exportGame.ts+++ b/desktop/electron/exportGame.ts@@ -19,7 +19,8 @@** Pure Node (esbuild + fs) — IPC wiring is in main.ts.*/-import { build, type BuildOptions } from 'esbuild';+import type { BuildOptions } from 'esbuild';+import { loadEsbuild } from './esbuildRuntime';import { writeFile, mkdir, cp } from 'node:fs/promises';import { existsSync } from 'node:fs';import path from 'node:path';@@ -192,8 +193,10 @@ async function stageDesktopApp(absOut: string, title: string, appId?: string, pr/*** Export the open project. `entryScene` is the project-relative scene to boot;- * `gameHostEntry` the gameHost.ts source; `wasmDir` the engine runtime to copy.- * `platform` selects the target (default web).+ * `gameHostEntry` the game-host esbuild entry — the prebuilt realm-host bundle+ * (dist-electron/hosts/gameHost.js; a packaged app ships no src/ and esbuild+ * cannot read app.asar) or any source esbuild can reach (tests). `wasmDir` is+ * the engine runtime to copy. `platform` selects the target (default web).*/export async function exportGame(opts: {root: string;@@ -262,7 +265,8 @@ export async function exportGame(opts: {root: opts.root,entryScene: opts.entryScene,scriptsEntry: opts.scriptsEntry,- playableHostEntry: opts.playableHostEntry ?? path.join(path.dirname(opts.gameHostEntry), 'playableHost.ts'),+ // Default beside the game host, same flavor (prebuilt .js or a source .ts).+ playableHostEntry: opts.playableHostEntry ?? path.join(path.dirname(opts.gameHostEntry), `playableHost${path.extname(opts.gameHostEntry)}`),sdkDir: opts.sdkDistDir,wasmDir: opts.wasmDir,outDir: opts.outDir,@@ -302,6 +306,7 @@ export async function exportGame(opts: {// so the shipped game shares one SDK with the project bundle and runs// custom systems (same shape as the play realm).progress({ phase: 'Bundling game host' });+ const { build } = await loadEsbuild();const host = await build({ ...common, entryPoints: [opts.gameHostEntry], outfile: path.join(payloadDir, 'game.js') });errors.push(...host.errors.map((e) => e.text));// 3. Project bundle (defineComponent/defineSystem) → scripts.mjs, esengine external.diff --git a/desktop/electron/exportPlayable.ts b/desktop/electron/exportPlayable.tsindex 1c3826b6b..d616a4a0d 100644--- a/desktop/electron/exportPlayable.ts+++ b/desktop/electron/exportPlayable.ts@@ -14,7 +14,7 @@* contract (no playable simulator here — runtime is validated by the user in* a browser / ad preview). Pure Node (esbuild + fs); IPC wiring in main.ts.*/-import { build } from 'esbuild';+import { loadEsbuild } from './esbuildRuntime';import { writeFile, mkdir, readFile, stat, rm } from 'node:fs/promises';import { existsSync } from 'node:fs';import path from 'node:path';@@ -205,6 +205,7 @@ export async function exportPlayable(opts: {`import ${JSON.stringify(opts.playableHostEntry)};\n`;let bundle = '';try {+ const { build } = await loadEsbuild();const res = await build({stdin: { contents: entrySrc, resolveDir: opts.root, loader: 'js', sourcefile: 'playable-entry.js' },bundle: true,diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.tsindex d1eb44776..f170587bd 100644--- a/desktop/electron/exportWeChat.ts+++ b/desktop/electron/exportWeChat.ts@@ -21,7 +21,7 @@* import maps and a different module/asset model, so this is its own path.* Pure Node (esbuild + fs) — IPC wiring is in main.ts.*/-import { build } from 'esbuild';+import { loadEsbuild } from './esbuildRuntime';import { writeFile, mkdir, cp, readFile, stat, rm } from 'node:fs/promises';import { existsSync } from 'node:fs';import path from 'node:path';@@ -284,6 +284,7 @@ export async function exportWeChat(opts: {`}\n`;progress({ phase: 'Bundling game' });try {+ const { build } = await loadEsbuild();const res = await build({stdin: { contents: entrySrc, resolveDir: opts.root, loader: 'js', sourcefile: 'wechat-entry.js' },bundle: true,diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.tsindex 461733136..7ac41fc65 100644--- a/desktop/electron/extractSchemas.ts+++ b/desktop/electron/extractSchemas.ts@@ -20,7 +20,8 @@* Pure Node (esbuild + fs/path/url), no Electron imports → unit-testable and* reusable; the IPC wiring lives in main.ts.*/-import { build, type Plugin } from 'esbuild';+import type { Plugin } from 'esbuild';+import { loadEsbuild } from './esbuildRuntime';import { existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';import { tmpdir } from 'node:os';import path from 'node:path';@@ -159,6 +160,7 @@ export async function extractProjectSchemas(const bundlePath = path.join(tmp, 'extract.mjs');const warnings: string[] = [];try {+ const { build } = await loadEsbuild();const result = await build({stdin: { contents: entry, resolveDir: ANCHOR_DIR, loader: 'ts', sourcefile: 'extract-entry.ts' },bundle: true,diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex c3c053cc6..fdd3c2dc4 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -96,6 +96,25 @@ const VITE_PUBLIC = VITE_DEV_SERVER_URL? path.join(process.env.APP_ROOT, 'public'): RENDERER_DIST;+// —— Realm-host bundles + SDK dist ——————————————————————————————————————————+// Both trees are read by esbuild (a NATIVE subprocess: exports re-bundle the+// prebuilt hosts with the shipping minify config, inlined bundles alias+// `esengine` at the SDK dist). Node's fs is patched to read app.asar; a child+// process is not — so once packaged, these must live on the real filesystem.+// electron-builder asarUnpack mirrors them under app.asar.unpacked; retarget.+const unpacked = (p: string): string => p.replace(/app\.asar(?=[\\/])/, 'app.asar.unpacked');+/** Prebuilt realm-host bundles (playHost/gameHost/playableHost) — built by the+ * realm-hosts step in vite.config.ts, never from src/ at runtime (a packaged+ * app ships no sources). */+const HOSTS_DIR = unpacked(path.join(__dirname, 'hosts'));+/** The esengine SDK dist: staged into realms/exports, aliased into inlined bundles. */+const SDK_DIST = unpacked(path.join(process.env.APP_ROOT, 'node_modules', 'esengine', 'dist'));+/** The web engine runtime (glue + wasm + side modules) staged into play realms and+ * exports by recursive directory copy — which cannot source from inside app.asar. */+const WEB_WASM_DIR = unpacked(+ existsSync(path.join(VITE_PUBLIC, 'wasm')) ? path.join(VITE_PUBLIC, 'wasm') : path.join(RENDERER_DIST, 'wasm'),+);+let win: BrowserWindow | null = null;/**@@ -363,7 +382,7 @@ async function adoptRoot(root: string): Promise<void> {projectRoot = root;if (win) startProjectWatch(root, win.webContents);try {- await syncSdkTypes(root, path.join(process.env.APP_ROOT!, 'node_modules', 'esengine', 'dist'));+ await syncSdkTypes(root, SDK_DIST);} catch (err) {console.warn('[sdk-types] mirror failed:', err);}@@ -501,13 +520,12 @@ ipcMain.handle(const manifest = await readManifest(root);const entryScene = manifest.defaultScene;if (!entryScene) throw new Error('project has no defaultScene to export');- const sdkDistDir = path.join(process.env.APP_ROOT!, 'node_modules', 'esengine', 'dist');- const publicWasm = path.join(VITE_PUBLIC, 'wasm');- const webWasm = existsSync(publicWasm) ? publicWasm : path.join(RENDERER_DIST, 'wasm');+ const sdkDistDir = SDK_DIST;+ const webWasm = WEB_WASM_DIR;// WeChat needs the -t wechat runtime (WXWebAssembly glue); build it with// `node build-tools/cli.js build -t wechat`. Absent → exportWeChat warns.- const wechatWasm = [path.join(VITE_PUBLIC, 'wasm-wechat'), path.join(process.env.APP_ROOT!, '..', 'build', 'wasm', 'wechat')]- .find(existsSync) ?? path.join(VITE_PUBLIC, 'wasm-wechat');+ const wechatWasm = [unpacked(path.join(VITE_PUBLIC, 'wasm-wechat')), path.join(process.env.APP_ROOT!, '..', 'build', 'wasm', 'wechat')]+ .find(existsSync) ?? unpacked(path.join(VITE_PUBLIC, 'wasm-wechat'));const plat = manifest.packaging?.platforms;const ySortLayers =(manifest.features?.rendering?.ySortLayers ?? []).reduce((m, i) => m | (1 << i), 0) >>> 0;@@ -515,8 +533,8 @@ ipcMain.handle(root,entryScene,ySortLayers,- gameHostEntry: path.join(process.env.APP_ROOT!, 'src', 'gameHost.ts'),- playableHostEntry: path.join(process.env.APP_ROOT!, 'src', 'playableHost.ts'),+ gameHostEntry: path.join(HOSTS_DIR, 'gameHost.js'),+ playableHostEntry: path.join(HOSTS_DIR, 'playableHost.js'),scriptsEntry: resolveScripts(manifest).main,sdkDistDir,wasmDir: opts?.platform === 'wechat' ? wechatWasm : webWasm,@@ -559,12 +577,11 @@ ipcMain.handle('project:preparePlayRealm', async () => {} catch {/* no bundle — builtin components/systems only */}- const publicWasm = path.join(VITE_PUBLIC, 'wasm');return buildPlayRealm({root,- playHostEntry: path.join(process.env.APP_ROOT!, 'src', 'playHost.ts'),- sdkDistDir: path.join(process.env.APP_ROOT!, 'node_modules', 'esengine', 'dist'),- wasmDir: existsSync(publicWasm) ? publicWasm : path.join(RENDERER_DIST, 'wasm'),+ playHostArtifact: path.join(HOSTS_DIR, 'playHost.js'),+ sdkDistDir: SDK_DIST,+ wasmDir: WEB_WASM_DIR,});});diff --git a/desktop/vite.config.ts b/desktop/vite.config.tsindex 12682cf67..ec3c5d8b0 100644--- a/desktop/vite.config.ts+++ b/desktop/vite.config.ts@@ -1,9 +1,52 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import { defineConfig } from 'vite';+import { defineConfig, type Plugin } from 'vite';import { fileURLToPath, URL } from 'node:url';import react from '@vitejs/plugin-react';import electron from 'vite-plugin-electron/simple';+import { context as esbuildContext, type BuildContext } from 'esbuild';+import { ESENGINE_EXTERNAL } from './electron/esengineResolve';++/**+ * Realm hosts (src/playHost.ts, src/gameHost.ts, src/playableHost.ts) are editor+ * code that runs in a browser realm outside Vite — the play iframe and exported+ * games load them over their own import maps. They're bundled HERE, at editor+ * build time, into dist-electron/hosts/; the runtime stages the artifacts by+ * copy (play realm) or re-bundles them with the per-export shipping config+ * (exports). Never bundled from src/ at runtime: a packaged app ships no+ * sources, and esbuild — a native subprocess — cannot read app.asar. Dev serve+ * keeps an esbuild watch so host edits rebuild live.+ */+function realmHosts(): Plugin {+ let ctx: BuildContext | null = null;+ const create = () =>+ esbuildContext({+ entryPoints: ['src/playHost.ts', 'src/gameHost.ts', 'src/playableHost.ts'],+ outdir: 'dist-electron/hosts',+ bundle: true,+ format: 'esm',+ platform: 'browser',+ target: 'es2020',+ external: ESENGINE_EXTERNAL,+ sourcemap: false,+ logLevel: 'warning',+ });+ return {+ name: 'realm-hosts',+ async buildStart() {+ if (ctx) return; // serve mode owns the watching context+ const once = await create();+ await once.rebuild();+ await once.dispose();+ },+ async configureServer(server) {+ ctx = await create();+ await ctx.rebuild();+ await ctx.watch();+ server.httpServer?.once('close', () => void ctx?.dispose());+ },+ };+}// Estella Editor — Electron + React + Vite.// `public/` (wasm runtime, bundled SDK, example projects) is served at the web root,@@ -35,6 +78,7 @@ export default defineConfig({},plugins: [react(),+ realmHosts(),electron({main: {entry: 'electron/main.ts',