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.

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.yml
index 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 that
diff --git a/desktop/electron/buildPlayRealm.ts b/desktop/electron/buildPlayRealm.ts
index 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<voi
export 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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',