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(export): a progress notice is never what takes a mini-game boot down
esenginee03fb9311af9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 851707d4e..601935d95 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Added+- **A package whose engine ships in a 分包 now starts.** Its generated entry called the host's loading indicator on its first line without checking the host has one — and that call is optional in the API — so on a host that does not implement it the game died before reaching `loadSubpackage`. Every indicator call in a generated entry is guarded now; a progress message must never be what takes a boot down.+- **A group that failed to load says so instead of handing back an empty bundle.** `Assets.loadGroup` settled every asset and returned whatever survived, so a subpackage that downloaded but staged nothing — or a CDN answering 404 — read exactly like a group that was always empty. It now names the assets that failed, the way a scene preload already did.- **A mini-game's side modules compress too, not just its engine.** Brotli was applied to the engine binary alone, so a package that transcodes KTX2 textures still carried Basis at its full 1.1MB — 27% of WeChat's 4MB main-package cap on its own. They compress on the same switch now, and the loader is told which suffix the build staged instead of spelling `.wasm` itself. Measured on the platformer template: its WeChat package was 108% of the cap and is now 51.5%, with the side modules accounting for 902KB of that.diff --git a/pipeline/src/export/miniGameExportProfile.ts b/pipeline/src/export/miniGameExportProfile.tsindex 3ba16841d..532997bc5 100644--- a/pipeline/src/export/miniGameExportProfile.ts+++ b/pipeline/src/export/miniGameExportProfile.ts@@ -112,27 +112,28 @@ bundle.boot(engineFactory, sideModuleFactories);`;// cover a wait that ends when the runtime arrives. Guarded, like every// other call to it — an indicator must not take a boot down.const notice = ctx.hostGlobal- ? `try { ${ctx.hostGlobal}.showLoading({ title: 'Starting 0%', mask: true }); } catch (e) {}\n`+ ? `try { ${ctx.hostGlobal}.showLoading && ${ctx.hostGlobal}.showLoading({ title: 'Starting 0%', mask: true }); } catch (e) {}\n`: '';return `'use strict';// Generated by Estella exportGame (MiniGame entry).${notice}${boot}`;}- // The host fetches the engine binary before anything can instantiate it, and- // this runs BEFORE the bundle is parsed, so the runtime's own indicator- // cannot cover the wait. Real byte progress, unlike every later stage.+ // The host fetches the engine binary before the bundle is parsed, so the+ // runtime's own indicator cannot cover this wait — and it is the one stage+ // with real byte progress. `showLoading` is OPTIONAL, hence `__say`.return `'use strict';// Generated by Estella exportGame (MiniGame entry, engine in a subpackage).var __g = ${ctx.hostGlobal};-__g.showLoading({ title: 'Fetching the engine 0%', mask: true });+var __say = function (t) { try { __g.showLoading && __g.showLoading({ title: t, mask: true }); } catch (e) {} };+__say('Fetching the engine 0%');var __task = __g.loadSubpackage({name: ${JSON.stringify(ctx.engineSubpackage)},success() {${boot.split('\n').map((l) => (l ? ` ${l}` : l)).join('\n')}},fail(err) {- __g.hideLoading();+ try { __g.hideLoading && __g.hideLoading(); } catch (e) {}console.error('[estella] the engine subpackage ${ctx.engineSubpackage} did not load — the game cannot start', err);},});@@ -140,7 +141,7 @@ ${boot.split('\n').map((l) => (l ? ` ${l}` : l)).join('\n')}// still a package that says it is doing something.if (__task && __task.onProgressUpdate) {__task.onProgressUpdate(function (p) {- __g.showLoading({ title: 'Fetching the engine ' + Math.round(p.progress || 0) + '%', mask: true });+ __say('Fetching the engine ' + Math.round(p.progress || 0) + '%');});}`;diff --git a/pipeline/tests/export-wechat.test.ts b/pipeline/tests/export-wechat.test.tsindex e8db914bf..5763bb6a4 100644--- a/pipeline/tests/export-wechat.test.ts+++ b/pipeline/tests/export-wechat.test.ts@@ -672,6 +672,17 @@ describe('exportGame (wechat)', () => {// A failed fetch takes the notice down with it, rather than leaving the// host spinning over a game that will never start.expect(entry.slice(entry.indexOf('fail('))).toContain('hideLoading');++ // 6. …and the notice is never what kills the boot. MiniGameGlobal declares+ // showLoading OPTIONAL, and this is the entry's FIRST line: an unguarded+ // call is a package that dies for the sake of a progress message.+ for (const call of ['showLoading', 'hideLoading']) {+ for (const at of [...entry.matchAll(new RegExp(`\\.${call}\\(`, 'g'))].map((m) => m.index!)) {+ const before = entry.slice(Math.max(0, at - 90), at);+ expect(before, `${call}() at ${at} is called without checking the host has it`)+ .toMatch(new RegExp(`${call}\\s*&&`));+ }+ }}, 60_000);it('leaves the engine in the main package when the project did not ask', async () => {diff --git a/tools/launchers/launch-minigame.mjs b/tools/launchers/launch-minigame.mjsindex ec04033b1..1213336c3 100644--- a/tools/launchers/launch-minigame.mjs+++ b/tools/launchers/launch-minigame.mjs@@ -166,6 +166,14 @@ async function main() {console.log(`${ok ? '✓' : '✗'} ${path.basename(DIR)} (mini-game) — painted=${painted} live=${live} errors=${errors.length}`);for (const e of errors.slice(0, 5)) console.log(` ${e}`);if (painted && !live) console.log(' one flat colour — it started and drew nothing');+ if (!ok) {+ // What the boot last announced through the host indicator. A package stuck+ // fetching its engine 分包 and one stuck on its first scene look identical+ // from outside, and only one of them sends you to the right place.+ const stage = await win.webContents.executeJavaScript('globalThis.__estellaLoading ?? null')+ .catch(() => null);+ if (stage) console.log(` the boot was still saying: ${stage}`);+ }app.exit(ok ? 0 : 1);}diff --git a/tools/launchers/minigameHost.mjs b/tools/launchers/minigameHost.mjsindex 84bd9c53f..8ed3ecf9d 100644--- a/tools/launchers/minigameHost.mjs+++ b/tools/launchers/minigameHost.mjs@@ -82,6 +82,10 @@ export const HOST_PAGE = (entry) => `<!doctype html>};const noop = () => {};+ /** What the boot last said it was doing. On the window rather than a closure+ * because the launcher reads it when a package never reaches a frame — the+ * stage it was stuck on is the whole diagnosis. */+ globalThis.__estellaLoading = null;const wx = {createCanvas: makeCanvas,createImage: () => new Image(),@@ -133,6 +137,11 @@ export const HOST_PAGE = (entry) => `<!doctype html>setStorageSync: (k, v) => localStorage.setItem(k, JSON.stringify(v)),removeStorageSync: (k) => localStorage.removeItem(k),getStorageInfoSync: () => ({ keys: Object.keys(localStorage), currentSize: 0, limitSize: 10240 }),+ // The boot's only progress surface. Stubbed rather than left absent: an+ // absent optional makes an unguarded caller look fine here and die on a+ // device, which is the direction a stand-in must never get wrong.+ showLoading: (o) => { globalThis.__estellaLoading = o && o.title; },+ hideLoading: () => { globalThis.__estellaLoading = null; },setPreferredFramesPerSecond: noop,triggerGC: noop,exitMiniProgram: noop,@@ -215,7 +224,7 @@ export const SHIM_MEMBERS = ['offTouchStart', 'offTouchMove', 'offTouchEnd','onTouchCancel', 'offTouchCancel','onKeyDown', 'onKeyUp', 'offKeyDown', 'offKeyUp',- 'loadSubpackage', 'onMemoryWarning', 'offMemoryWarning',+ 'loadSubpackage', 'showLoading', 'hideLoading', 'onMemoryWarning', 'offMemoryWarning','onError', 'offError', 'onUnhandledRejection', 'offUnhandledRejection','onShow', 'onHide','getStorageSync', 'setStorageSync', 'removeStorageSync', 'getStorageInfoSync',diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 3dde13911..826afc398 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -700,6 +700,8 @@ export const NOTED = {{ internal: "the editor's preview page names the same subpaths it always did" },'fix(settings): the module page reads the same asset table the build installs from':{ note: 'The Engine Modules page no longer calls a module unused that the build then carries.' },+ 'fix(export): a progress notice is never what takes a mini-game boot down':+ { note: 'A package whose engine ships in a 分包 now starts.' },'fix(assets): a group load names what failed instead of returning an empty bundle':{ note: 'A group that failed to load says so instead of handing back an empty bundle.' },'docs(settings): the wasm compression switch names what it now compresses':