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(editor): streamed build log (per-phase export progress)

esenginedb316e48c9bb
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index 9c7d01b9e..f9d1ee506 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -27,6 +27,7 @@ import { cookAssets } from './cookAssets';
import { IMPORT_MAP_JSON, IMPORT_MAP_CSP_HASH } from './buildPlayRealm';
import { exportWeChat } from './exportWeChat';
import { exportPlayable } from './exportPlayable';
+import type { OnExportProgress } from './exportProgress';
export type ExportPlatform = 'web' | 'desktop' | 'wechat' | 'playable';
@@ -209,12 +210,15 @@ export async function exportGame(opts: {
playableHostEntry?: string;
/** SINGLE_FILE engine glue (esengine.single.js from `-t playable`) for playable ads. */
glueFile?: string;
+ /** Per-phase progress (build log). */
+ onProgress?: OnExportProgress;
/** Shipping config: minify the bundles, no sourcemap. Default off (dev). */
minify?: boolean;
sourcemap?: boolean;
}): Promise<ExportGameResult> {
const platform = opts.platform ?? 'web';
const title = opts.title ?? 'Game';
+ const progress = opts.onProgress ?? (() => {});
// WeChat has no import maps + a different module/asset model → its own pipeline.
if (platform === 'wechat') {
@@ -227,6 +231,7 @@ export async function exportGame(opts: {
outDir: opts.outDir,
title,
minify: opts.minify,
+ onProgress: opts.onProgress,
});
}
@@ -241,6 +246,7 @@ export async function exportGame(opts: {
outDir: opts.outDir,
title,
minify: opts.minify,
+ onProgress: opts.onProgress,
});
}
@@ -263,18 +269,22 @@ export async function exportGame(opts: {
};
// 1. Cook reachable assets + manifest (the entry scene file is staged too).
+ progress({ phase: 'Cooking assets' });
const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: payloadDir });
warnings.push(...cook.warnings);
+ progress({ phase: 'Cooking assets', detail: `${cook.included.length} reachable` });
try {
// 2. Game host — esengine EXTERNAL (resolved by the index.html import map),
// 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 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.
const scriptsAbs = opts.scriptsEntry ? path.join(opts.root, opts.scriptsEntry) : null;
if (scriptsAbs && existsSync(scriptsAbs)) {
+ progress({ phase: 'Bundling project scripts' });
const proj = await build({ ...common, entryPoints: [scriptsAbs], outfile: path.join(payloadDir, 'scripts.mjs') });
errors.push(...proj.errors.map((e) => e.text));
}
@@ -285,12 +295,14 @@ export async function exportGame(opts: {
}
// 4. SDK (import-map target) + wasm runtime.
+ progress({ phase: 'Copying SDK + runtime' });
if (existsSync(opts.sdkDistDir)) await cp(opts.sdkDistDir, path.join(payloadDir, 'sdk'), { recursive: true });
else warnings.push(`sdk dist not found: ${opts.sdkDistDir}`);
if (existsSync(opts.wasmDir)) await cp(opts.wasmDir, path.join(payloadDir, 'wasm'), { recursive: true });
else warnings.push(`wasm runtime dir not found: ${opts.wasmDir}`);
// 5. Host page + entry-scene config.
+ progress({ phase: 'Writing host page' });
await writeFile(path.join(payloadDir, 'index.html'), indexHtml(title));
await writeFile(
path.join(payloadDir, 'game.config.json'),
@@ -298,7 +310,7 @@ export async function exportGame(opts: {
);
// 6. Desktop: wrap the payload in a runnable Electron app.
- if (platform === 'desktop') await stageDesktopApp(absOut, title);
+ if (platform === 'desktop') { progress({ phase: 'Staging Electron app' }); await stageDesktopApp(absOut, title); }
return { ok: errors.length === 0, platform, outDir: absOut, included: cook.included.length, warnings, errors };
}
diff --git a/desktop/electron/exportPlayable.ts b/desktop/electron/exportPlayable.ts
index 75fd551f1..06a30eb6c 100644
--- a/desktop/electron/exportPlayable.ts
+++ b/desktop/electron/exportPlayable.ts
@@ -19,6 +19,7 @@ import { writeFile, mkdir, readFile, stat, rm } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets } from './cookAssets';
+import type { OnExportProgress } from './exportProgress';
export interface ExportPlayableResult {
ok: boolean;
@@ -83,19 +84,23 @@ export async function exportPlayable(opts: {
outDir: string;
title?: string;
minify?: boolean;
+ onProgress?: OnExportProgress;
}): Promise<ExportPlayableResult> {
const title = opts.title ?? 'Game';
const absOut = path.isAbsolute(opts.outDir) ? opts.outDir : path.join(opts.root, opts.outDir);
+ const progress = opts.onProgress ?? (() => {});
const warnings: string[] = [];
const errors: string[] = [];
await mkdir(absOut, { recursive: true });
const cookDir = path.join(absOut, '.playable-cook');
// 1. Cook reachable assets to a temp dir (everything ends up inlined → removed after).
+ progress({ phase: 'Cooking assets' });
const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: cookDir });
warnings.push(...cook.warnings);
// 2. Assets → base64 data URLs, keyed by the scene's @uuid: refs.
+ progress({ phase: 'Encoding assets' });
const assets: Record<string, string> = {};
try {
const manifest = JSON.parse(await readFile(path.join(cookDir, 'assets.manifest.json'), 'utf8')) as CookManifest;
@@ -118,6 +123,7 @@ export async function exportPlayable(opts: {
}
// 4. Host + esengine + project scripts → ONE IIFE (esengine INLINED; no import map).
+ progress({ phase: 'Bundling game' });
const scriptsAbs = opts.scriptsEntry ? path.join(opts.root, opts.scriptsEntry) : null;
const entrySrc =
(scriptsAbs && existsSync(scriptsAbs) ? `import ${JSON.stringify(scriptsAbs)};\n` : '') +
@@ -148,6 +154,7 @@ export async function exportPlayable(opts: {
else warnings.push(`single-file engine glue not found: ${opts.glueFile} — run \`node build-tools/cli.js build -t playable\``);
// 6. Assemble the single HTML, then drop the temp cook dir.
+ progress({ phase: 'Assembling HTML' });
const globals =
`window.__GAME_ASSETS__=${JSON.stringify(assets)};` +
`window.__GAME_SCENES__=${JSON.stringify(scenes)};` +
diff --git a/desktop/electron/exportProgress.ts b/desktop/electron/exportProgress.ts
new file mode 100644
index 000000000..dc30e7dfb
--- /dev/null
+++ b/desktop/electron/exportProgress.ts
@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Export progress events. The export pipelines emit a `phase` per major
+ * step so the Package Project dialog can show a live build log (UE-style)
+ * instead of a single spinner line. The IPC handler forwards these to the
+ * renderer over `project:exportProgress`.
+ */
+export interface ExportProgress {
+ /** Human label of the current step (shown in the build log). */
+ phase: string;
+ /** Optional detail — a count, a path, a size. */
+ detail?: string;
+}
+
+export type OnExportProgress = (p: ExportProgress) => void;
diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.ts
index 2b230fc3c..afc02310e 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -26,6 +26,7 @@ import { writeFile, mkdir, cp, readFile, stat, rm } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets } from './cookAssets';
+import type { OnExportProgress } from './exportProgress';
export interface ExportWeChatResult {
ok: boolean;
@@ -115,18 +116,22 @@ export async function exportWeChat(opts: {
outDir: string;
title?: string;
minify?: boolean;
+ onProgress?: OnExportProgress;
}): Promise<ExportWeChatResult> {
const title = opts.title ?? 'Game';
const absOut = path.isAbsolute(opts.outDir) ? opts.outDir : path.join(opts.root, opts.outDir);
+ const progress = opts.onProgress ?? (() => {});
const warnings: string[] = [];
const errors: string[] = [];
await mkdir(absOut, { recursive: true });
// 1. Cook reachable assets (paths preserved) + the flat manifest.
+ progress({ phase: 'Cooking assets' });
const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: absOut });
warnings.push(...cook.warnings);
// 2. Flat manifest → AddressableManifest (asset-manifest.json); drop the web one.
+ progress({ phase: 'Building manifest' });
try {
await writeFile(path.join(absOut, 'asset-manifest.json'), await buildAddressableManifest(absOut));
await rm(path.join(absOut, 'assets.manifest.json'), { force: true });
@@ -135,6 +140,7 @@ export async function exportWeChat(opts: {
}
// 3. Entry scene → scenes/<name>.json with @uuid: refs stripped to bare uuids.
+ progress({ phase: 'Transforming scene' });
const sceneName = path.basename(opts.entryScene).replace(/\.[^.]+$/, '');
try {
const raw = JSON.parse(await readFile(path.join(absOut, opts.entryScene), 'utf8'));
@@ -153,6 +159,7 @@ export async function exportWeChat(opts: {
`export function boot(engineFactory) {\n` +
` return initWeChatRuntime({ engineFactory, sceneNames: ${JSON.stringify([sceneName])}, firstScene: ${JSON.stringify(sceneName)} });\n` +
`}\n`;
+ progress({ phase: 'Bundling game' });
try {
const res = await build({
stdin: { contents: entrySrc, resolveDir: opts.root, loader: 'js', sourcefile: 'wechat-entry.js' },
@@ -179,6 +186,7 @@ export async function exportWeChat(opts: {
await writeFile(path.join(absOut, 'project.config.json'), projectConfigJson(title));
// 6. The -t wechat engine runtime (WXWebAssembly glue + binary + side modules).
+ progress({ phase: 'Copying runtime' });
if (existsSync(opts.wasmDir)) await cp(opts.wasmDir, path.join(absOut, 'wasm'), { recursive: true });
else warnings.push(`wechat wasm runtime dir not found: ${opts.wasmDir}`);
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index ac9eea20f..e178ef32c 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -275,7 +275,7 @@ ipcMain.handle('project:cookAssets', async (_e, outDir?: string) => {
// Export a runnable web build (play == ship): cook + game host + wasm + index.html.
ipcMain.handle(
'project:exportGame',
- async (_e, opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' }) => {
+ async (e, opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable' }) => {
const root = requireRoot();
const manifest = await readManifest(root);
const entryScene = manifest.defaultScene;
@@ -309,6 +309,7 @@ ipcMain.handle(
platform: opts?.platform,
minify: opts?.minify,
sourcemap: opts?.sourcemap,
+ onProgress: (p) => e.sender.send('project:exportProgress', p),
});
},
);
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 79fa26fdc..71a44c41f 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -43,6 +43,12 @@ const api = {
/** Export a runnable web build (play==ship) → self-contained `outDir` (default dist-game/). */
exportGame: (opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable' }): Promise<ExportGameResult> =>
ipcRenderer.invoke('project:exportGame', opts),
+ /** Subscribe to export build-log phases while a package runs. Returns unsubscribe. */
+ onExportProgress: (cb: (p: { phase: string; detail?: string }) => void): (() => void) => {
+ const listener = (_e: unknown, p: { phase: string; detail?: string }) => cb(p);
+ ipcRenderer.on('project:exportProgress', listener);
+ return () => ipcRenderer.removeListener('project:exportProgress', listener);
+ },
/** Stage the isolated play realm (host + SDK + wasm + project bundle) under
* `.esengine/play/`; returns the project-relative host page path. */
preparePlayRealm: (): Promise<PlayRealmResult> => ipcRenderer.invoke('project:preparePlayRealm'),
diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsx
index 295e83239..ac7098a52 100644
--- a/desktop/src/components/BuildDialog.tsx
+++ b/desktop/src/components/BuildDialog.tsx
@@ -93,6 +93,7 @@ export function BuildDialog() {
const [sourceMaps, setSourceMaps] = useState(saved.sourceMaps ?? false);
const [phase, setPhase] = useState<Phase>('idle');
const [result, setResult] = useState<Result | null>(null);
+ const [log, setLog] = useState<string[]>([]);
const def = PLATFORMS.find((p) => p.id === platform)!;
const running = phase === 'running';
@@ -114,8 +115,13 @@ export function BuildDialog() {
const build = async () => {
setPhase('running');
setResult(null);
+ setLog([]);
// Persist the chosen settings to project.esproject (restored next time).
void ProjectStore.setPackaging({ platform, config, sourceMaps, openFolder, outDir: { [platform]: outDir } });
+ // Live build log (UE-style): each export phase streams over IPC.
+ const unsub = window.estella.project?.onExportProgress?.((p) =>
+ setLog((l) => [...l, p.detail ? `${p.phase} — ${p.detail}` : p.phase]),
+ );
try {
const res = (await ProjectStore.exportGame({
platform,
@@ -134,6 +140,8 @@ export function BuildDialog() {
} catch (err) {
setResult({ ok: false, outDir, included: 0, warnings: [], errors: [err instanceof Error ? err.message : String(err)] });
setPhase('error');
+ } finally {
+ unsub?.();
}
};
@@ -229,9 +237,14 @@ export function BuildDialog() {
<div className={`build__status ${phase}`}>
{phase === 'running' && (
<span className="build__status-line">
- <Loader2 size={14} className="spin" /> Cooking assets, bundling the {def.label} build…
+ <Loader2 size={14} className="spin" /> Packaging the {def.label} build…
</span>
)}
+ {log.length > 0 && (
+ <ol className="build__log">
+ {log.map((line, i) => <li key={i}>{line}</li>)}
+ </ol>
+ )}
{phase === 'done' && result && (
<>
<span className="build__status-line">
diff --git a/desktop/src/theme/menus.css b/desktop/src/theme/menus.css
index 7224356e4..3d40aa487 100644
--- a/desktop/src/theme/menus.css
+++ b/desktop/src/theme/menus.css
@@ -141,3 +141,6 @@
.build__prereq { display: flex; align-items: flex-start; gap: 7px; padding: 8px 10px; border-radius: var(--r-sm); font-size: var(--fs-xs); color: var(--text-dim); background: var(--srf-3); border: 1px solid var(--border-line); }
.build__prereq svg { flex-shrink: 0; margin-top: 1px; color: var(--text-mute); }
.build__next { font-size: var(--fs-xs); color: var(--text-mute); font-family: var(--mono); }
+.build__log { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; max-height: 116px; overflow-y: auto; font-family: var(--mono); font-size: var(--fs-2xs); color: var(--text-mute); }
+.build__log li::before { content: '\203A '; color: var(--text-dim); }
+.build__log li:last-child { color: var(--text-dim); }
diff --git a/desktop/tests/export-progress.test.ts b/desktop/tests/export-progress.test.ts
new file mode 100644
index 000000000..74f3a1b16
--- /dev/null
+++ b/desktop/tests/export-progress.test.ts
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Export progress events — the pipeline emits a phase per major step so the
+ * Package Project dialog can show a live build log.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exportGame } from '../electron/exportGame';
+import type { ExportProgress } from '../electron/exportProgress';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const GAME_HOST = path.join(HERE, '..', 'src', 'gameHost.ts');
+
+let root: string;
+const TEX = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+const SCN = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
+
+beforeAll(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-export-progress-'));
+ mkdirSync(path.join(root, 'assets'), { recursive: true });
+ writeFileSync(path.join(root, 'assets', 'hero.png'), 'PNGDATA');
+ writeFileSync(path.join(root, 'assets', 'hero.png.meta'), meta(TEX, 'texture'));
+ mkdirSync(path.join(root, 'scenes'), { recursive: true });
+ writeFileSync(path.join(root, 'scenes', 'main.esscene'),
+ JSON.stringify({ version: '1.0', name: 'Main', entities: [{ id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] }] }));
+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
+ mkdirSync(path.join(root, 'src'), { recursive: true });
+ writeFileSync(path.join(root, 'src', 'main.ts'), `import { defineComponent } from 'esengine';\ndefineComponent('M', { n: 1 });\n`);
+ mkdirSync(path.join(root, '_sdk'), { recursive: true });
+ writeFileSync(path.join(root, '_sdk', 'index.js'), 'export const x = 1;');
+ mkdirSync(path.join(root, '_wasm'), { recursive: true });
+ writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'export default () => {};');
+ writeFileSync(path.join(root, '_wasm', 'esengine.wasm'), 'wasmbytes');
+}, 60_000);
+
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+describe('export progress', () => {
+ it('emits a phase per major step (web)', async () => {
+ const phases: string[] = [];
+ const res = await exportGame({
+ root,
+ entryScene: 'scenes/main.esscene',
+ gameHostEntry: GAME_HOST,
+ scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(root, '_sdk'),
+ wasmDir: path.join(root, '_wasm'),
+ outDir: path.join(root, 'out'),
+ platform: 'web',
+ onProgress: (p: ExportProgress) => phases.push(p.phase),
+ });
+
+ expect(res.ok).toBe(true);
+ for (const expected of ['Cooking assets', 'Bundling game host', 'Bundling project scripts', 'Copying SDK + runtime', 'Writing host page']) {
+ expect(phases).toContain(expected);
+ }
+ // Cooking is first; writing the host page is among the last.
+ expect(phases.indexOf('Cooking assets')).toBeLessThan(phases.indexOf('Writing host page'));
+ }, 60_000);
+});