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(editor): streamed build log (per-phase export progress)
esenginedb316e48c9bb
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.cssindex 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.tsnew file mode 100644index 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);+});