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(export): a progress notice is never what takes a mini-game boot down

esenginee03fb9311af9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.ts
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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':