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(export): the engine binary can ship in a 分包 the host loads at startup

esengine733a2c684da7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e993661f..71d48faf8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,14 @@ published separately; it ships inside the editor.
### Added
+- **The engine can ship outside a WeChat mini-game's main package entirely.** Compressing
+ it left 0.35MB of the 4MB limit spent before any of your content; *Engine in a subpackage*
+ moves the binary into a 分包 the host loads at startup, and the main package keeps only
+ the 162KB of glue that starts it — 4% of the limit, down from 47.5% with neither setting
+ on. The two stack: compression shrinks what the 分包 downloads. Off by default, because
+ startup then waits on that load, which is a trade worth making when the main package is
+ what you are fighting and not otherwise.
+
- **A WeChat mini-game can ship its engine compressed, freeing a third of the main
package.** The engine binary is the largest single file such a package carries — 1.74MB
against WeChat's 4MB main-package limit, 43.6% of it spent before any of your content.
diff --git a/desktop b/desktop
index 4342add95..424f29110 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 4342add952fd8f971be7c54c0620c7a5417f5156
+Subproject commit 424f29110ed77ed9fdf72a4b73521f1e64d4b837
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 7231380f5..3b330de3c 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -360,6 +360,9 @@ export interface ExportGameOptions {
/** Compress the engine binary to `.wasm.br`, where the target's loader takes
* one. Default off; ignored by targets that cannot load it. */
compressWasm?: boolean;
+ /** Move the engine binary into a 分包 the host loads at startup, off the main
+ * package's budget. Default off; ignored by targets without subpackages. */
+ engineSubpackage?: boolean;
title?: string;
platform?: ExportPlatform;
/** The ad network a playable targets (`packaging.platforms.playable.network`),
@@ -590,6 +593,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
compressAudio: opts.compressAudio,
atlasTextures: opts.atlasTextures,
compressWasm: opts.compressWasm,
+ engineSubpackage: opts.engineSubpackage,
onProgress: opts.onProgress,
});
}
@@ -617,6 +621,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
compressAudio: opts.compressAudio,
atlasTextures: opts.atlasTextures,
compressWasm: opts.compressWasm,
+ engineSubpackage: opts.engineSubpackage,
onProgress: opts.onProgress,
});
}
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index d0fd9fd4f..2d02e7e11 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -94,8 +94,12 @@ interface RuntimeLayout {
* entry requires them (`./wasm/`) — one author for where they are and where
* they are asked for. */
readonly runtimeDir: string;
- /** Engine artifacts to stage, as the name in `wasmDir` → the name in the package. */
+ /** Engine artifacts to stage: the name in `wasmDir` → the PACKAGE-RELATIVE path
+ * it lands at, so a binary that moves into a 分包 is the same list with a
+ * different path rather than a second staging rule. */
readonly files: ReadonlyArray<{ readonly src: string; readonly staged: string; readonly brotli?: true }>;
+ /** The 分包 the engine binary went into, for the host config to declare. */
+ readonly subpackage: { readonly name: string; readonly root: string } | null;
}
/**
@@ -104,24 +108,33 @@ interface RuntimeLayout {
* found at `wasm/<file>.wasm` by three hosts that spell that suffix themselves,
* so renaming one here would leave all three naming a file that is not there.
*/
+const ENGINE_SUBPACKAGE = 'engine';
+
function planRuntimeLayout(
engineGlueFile: string,
sideModules: ReadonlyArray<{ file: string }>,
- brotli: boolean,
+ opts: { brotli: boolean; subpackage: boolean; subpackageDir: string },
): RuntimeLayout {
const engineBinary = engineGlueFile.replace(/\.js$/, '.wasm');
- const engineStaged = brotli ? `${engineBinary}.br` : engineBinary;
+ const engineName = opts.brotli ? `${engineBinary}.br` : engineBinary;
+ // Only the BINARY moves. The glue is `require`d by the entry, and a 分包's files
+ // are not requirable before the host has loaded it — so it stays beside game.js,
+ // which is where every engine that ships this keeps it.
+ const root = `${opts.subpackageDir}/${ENGINE_SUBPACKAGE}`;
+ const enginePath = opts.subpackage ? `${root}/${engineName}` : `wasm/${engineName}`;
+ const binary = opts.brotli
+ ? { src: engineBinary, staged: enginePath, brotli: true as const }
+ : { src: engineBinary, staged: enginePath };
return {
- enginePath: `wasm/${engineStaged}`,
+ enginePath,
runtimeDir: 'wasm',
+ subpackage: opts.subpackage ? { name: ENGINE_SUBPACKAGE, root } : null,
files: [
- { src: engineGlueFile, staged: engineGlueFile },
- ...(brotli
- ? [{ src: engineBinary, staged: engineStaged, brotli: true as const }]
- : [{ src: engineBinary, staged: engineStaged }]),
+ { src: engineGlueFile, staged: `wasm/${engineGlueFile}` },
+ binary,
...sideModules.flatMap((m) => [
- { src: `${m.file}.js`, staged: `${m.file}.js` },
- { src: `${m.file}.wasm`, staged: `${m.file}.wasm` },
+ { src: `${m.file}.js`, staged: `wasm/${m.file}.js` },
+ { src: `${m.file}.wasm`, staged: `wasm/${m.file}.wasm` },
]),
],
};
@@ -238,6 +251,9 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
/** The project's `packaging.compressWasm`; honoured only where the vendor can
* load a `.wasm.br` (profile.wasmBrotli) — policy meeting capability. */
compressWasm?: boolean;
+ /** The project's `packaging.engineSubpackage`: move the engine binary out of
+ * the main package into a 分包 the host loads at startup. */
+ engineSubpackage?: boolean;
onProgress?: OnExportProgress;
}): Promise<ExportMiniGameResult> {
const title = opts.title ?? 'Game';
@@ -359,7 +375,11 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
// Compressing needs both halves: a vendor whose loader takes `.wasm.br`, and a
// project that asked for it. Either alone leaves the binary as built.
const brotli = profile.wasmBrotli && (opts.compressWasm ?? false);
- const runtimeLayout = planRuntimeLayout(engineGlueFile, engineSideModules, brotli);
+ const runtimeLayout = planRuntimeLayout(engineGlueFile, engineSideModules, {
+ brotli,
+ subpackage: profile.subpackageDir !== '' && (opts.engineSubpackage ?? false),
+ subpackageDir: profile.subpackageDir,
+ });
const engineWasmPath = runtimeLayout.enginePath;
// The packaged slice of the project's settings, GENERATED rather than listed:
// a setting added to packagedRuntimeFields reaches this boot without anyone
@@ -479,13 +499,24 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
}
// 5. Entry + config (vendor-specific emission).
- const subPackages = subPackagesOf(cookEntries, profile.subpackageDir);
- warnings.push(...subPackages.strays);
+ const cooked = subPackagesOf(cookEntries, profile.subpackageDir);
+ warnings.push(...cooked.strays);
+ // The engine's 分包, if the binary went into one, joins the cook's lazy groups
+ // here: the root entry each vendor demands and the host config's declaration
+ // are written once, for every subpackage, whatever put it there.
+ const subPackages = {
+ subPackages: runtimeLayout.subpackage
+ ? [...cooked.subPackages, runtimeLayout.subpackage]
+ : cooked.subPackages,
+ };
// A vendor that wants an entry in every subpackage root refuses the package
// without one, naming the missing file rather than the rule. These roots hold
// assets the runtime reads by path, so the entry has nothing to do but exist.
if (profile.subpackageEntry) {
for (const sp of subPackages.subPackages) {
+ // A cook group's root exists because its assets landed there; the engine's
+ // is made by the staging below, which has not run yet.
+ await mkdir(path.join(absOut, sp.root), { recursive: true });
await writeFile(
path.join(absOut, sp.root, profile.subpackageEntry),
`// Entry for the "${sp.name}" subpackage, which ${profile.id} requires in every\n`
@@ -495,7 +526,8 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
}
}
await writeFile(path.join(absOut, 'game.js'),
- profile.emitEntry({ sideModules, engineGlueFile, runtimeDir: runtimeLayout.runtimeDir }));
+ profile.emitEntry({ sideModules, engineGlueFile, runtimeDir: runtimeLayout.runtimeDir,
+ engineSubpackage: runtimeLayout.subpackage?.name ?? null }));
const configFiles = profile.emitConfigFiles({
title,
appid: opts.appid ?? '',
@@ -535,7 +567,8 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
errors.push(`${profile.id} runtime file missing: ${f.src} (in ${opts.wasmDir}) — rebuild with \`node build-tools/cli.js build -t ${profile.wasmBuildHint}\``);
continue;
}
- const dest = path.join(wasmOut, f.staged);
+ const dest = path.join(absOut, f.staged);
+ await mkdir(path.dirname(dest), { recursive: true });
if (f.src.endsWith('.js')) {
// Emscripten glue can carry es2020 syntax (`?.`, `??`) that real-device
// WeChat rejects — down-level it like the game bundle.
diff --git a/pipeline/src/export/miniGameExportProfile.ts b/pipeline/src/export/miniGameExportProfile.ts
index 8b05b4777..3ac9102ca 100644
--- a/pipeline/src/export/miniGameExportProfile.ts
+++ b/pipeline/src/export/miniGameExportProfile.ts
@@ -61,6 +61,10 @@ export interface MiniGameEntryContext {
/** Package-relative directory those artifacts landed in, decided by the
* export's runtime layout. The entry asks for them WHERE THEY ARE. */
runtimeDir: string;
+ /** The 分包 holding the engine binary, when it is in one: the entry has to
+ * ask the host for it before booting, since the file is not in the package
+ * until then. Null when the binary ships in the main package. */
+ engineSubpackage: string | null;
}
/**
@@ -73,15 +77,33 @@ export function defaultMiniGameEntry(ctx: MiniGameEntryContext): string {
const requires = ctx.sideModules
.map((m) => ` ${JSON.stringify(m.id)}: asFactory(require('./${ctx.runtimeDir}/${m.file}.js')),`)
.join('\n');
- return `'use strict';
-// Generated by Estella exportGame (MiniGame entry).
-const asFactory = (m) => (typeof m === 'function' ? m : (m && m.default) || m);
+ const boot = `const asFactory = (m) => (typeof m === 'function' ? m : (m && m.default) || m);
const engineFactory = asFactory(require('./${ctx.runtimeDir}/${ctx.engineGlueFile}'));
const sideModuleFactories = {
${requires}
};
const bundle = require('./game-bundle.js');
-bundle.boot(engineFactory, sideModuleFactories);
+bundle.boot(engineFactory, sideModuleFactories);`;
+ if (!ctx.engineSubpackage) {
+ return `'use strict';
+// Generated by Estella exportGame (MiniGame entry).
+${boot}
+`;
+ }
+ // The engine binary is in a 分包, so the host has to fetch it before anything
+ // instantiates the engine. Failing loudly beats a blank canvas: without the
+ // binary there is no game to start, and the reason is worth saying once.
+ return `'use strict';
+// Generated by Estella exportGame (MiniGame entry, engine in a subpackage).
+wx.loadSubpackage({
+ name: ${JSON.stringify(ctx.engineSubpackage)},
+ success() {
+${boot.split('\n').map((l) => (l ? ` ${l}` : l)).join('\n')}
+ },
+ fail(err) {
+ console.error('[estella] the engine subpackage ${ctx.engineSubpackage} did not load — the game cannot start', err);
+ },
+});
`;
}
diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.ts
index f0d2d8efc..f3d8e4642 100644
--- a/pipeline/src/project/format.ts
+++ b/pipeline/src/project/format.ts
@@ -297,6 +297,12 @@ export interface ProjectPackaging {
* default: it costs build time, and only pays where a main-package limit is.
*/
compressWasm?: boolean;
+ /**
+ * Move the engine binary into a 分包 the host loads at startup, off the main
+ * package's budget. Off by default: it buys main-package room at the cost of a
+ * startup that cannot begin until the host has fetched the 分包.
+ */
+ engineSubpackage?: boolean;
/** Project-relative scene paths NOT shipped as switchable scenes (dev/test
* scenes). Everything else under the scenes dir exports; the startup scene
* always ships regardless. */
diff --git a/pipeline/tests/export-wechat.test.ts b/pipeline/tests/export-wechat.test.ts
index 119fbb213..eabdd0e29 100644
--- a/pipeline/tests/export-wechat.test.ts
+++ b/pipeline/tests/export-wechat.test.ts
@@ -567,6 +567,72 @@ describe('exportGame (wechat)', () => {
expect(existsSync(path.join(o, 'wasm', 'esengine.wasm.br'))).toBe(false);
expect(readFileSync(path.join(o, 'game-bundle.js'), 'utf8')).toContain('wasm/esengine.wasm');
}, 60_000);
+ // Moving the binary out of the 4MB main package means four things must agree:
+ // where it lands, what the loader is told, what game.json declares, and that
+ // the entry asks the host for the 分包 before the engine is instantiated.
+ it('moves the engine binary into a 分包 the entry loads before booting', async () => {
+ const o = path.join(root, 'dist-wx-subpkg');
+ const res = await exportGame({
+ root,
+ entryScene: 'scenes/main.esscene',
+ hostsDir: 'unused-for-wechat',
+ scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(root, '_sdk'),
+ wasmDir: path.join(root, '_wxwasm'),
+ outDir: o,
+ platform: 'wechat',
+ wechatAppid: 'wxTEST0123456789',
+ engineSubpackage: true,
+ runtime: runtimeConfigOf({ designResolution: { width: 1280, height: 720 } }),
+ });
+ expect(res.ok).toBe(true);
+
+ // 1. It landed in the 分包, and NOT in the main package's wasm/.
+ expect(existsSync(path.join(o, 'subpackages', 'engine', 'esengine.wasm'))).toBe(true);
+ expect(existsSync(path.join(o, 'wasm', 'esengine.wasm'))).toBe(false);
+ // The glue stays put: the entry `require`s it, and a 分包 is not requirable
+ // until the host has loaded it.
+ expect(existsSync(path.join(o, 'wasm', 'esengine.js'))).toBe(true);
+
+ // 2. The loader is told where it actually is.
+ expect(readFileSync(path.join(o, 'game-bundle.js'), 'utf8'))
+ .toContain('subpackages/engine/esengine.wasm');
+
+ // 3. game.json declares it, or the host refuses the root at load.
+ const cfg = JSON.parse(readFileSync(path.join(o, 'game.json'), 'utf8')) as
+ { subPackages?: Array<{ name: string; root: string }> };
+ expect(cfg.subPackages ?? []).toContainEqual({ name: 'engine', root: 'subpackages/engine' });
+ // WeChat refuses a 分包 root with no game.js.
+ expect(existsSync(path.join(o, 'subpackages', 'engine', 'game.js'))).toBe(true);
+
+ // 4. The entry asks for it BEFORE it boots — the binary is not in the package
+ // until the host has loaded the 分包.
+ const entry = readFileSync(path.join(o, 'game.js'), 'utf8');
+ expect(entry).toContain('wx.loadSubpackage');
+ expect(entry.indexOf('loadSubpackage')).toBeLessThan(entry.indexOf('bundle.boot'));
+ // And a failure says so rather than leaving a blank canvas.
+ expect(entry).toContain('did not load');
+ }, 60_000);
+
+ it('leaves the engine in the main package when the project did not ask', async () => {
+ const o = path.join(root, 'dist-wx-nosubpkg');
+ const res = await exportGame({
+ root,
+ entryScene: 'scenes/main.esscene',
+ hostsDir: 'unused-for-wechat',
+ scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(root, '_sdk'),
+ wasmDir: path.join(root, '_wxwasm'),
+ outDir: o,
+ platform: 'wechat',
+ wechatAppid: 'wxTEST0123456789',
+ runtime: runtimeConfigOf({ designResolution: { width: 1280, height: 720 } }),
+ });
+ expect(res.ok).toBe(true);
+ expect(existsSync(path.join(o, 'wasm', 'esengine.wasm'))).toBe(true);
+ expect(existsSync(path.join(o, 'subpackages', 'engine'))).toBe(false);
+ expect(readFileSync(path.join(o, 'game.js'), 'utf8')).not.toContain('loadSubpackage');
+ }, 60_000);
});
/**
diff --git a/pipeline/tests/platform-catalog.test.ts b/pipeline/tests/platform-catalog.test.ts
index 1e8d88120..729f86891 100644
--- a/pipeline/tests/platform-catalog.test.ts
+++ b/pipeline/tests/platform-catalog.test.ts
@@ -240,7 +240,7 @@ describe('loadProjectPlatform — the profile handed to exportMiniGame', () => {
expect(typeof p.emitEntry).toBe('function');
// The default entry is the same CommonJS shape WeChat ships.
- const entry = p.emitEntry({ sideModules: [{ id: 'physics', file: 'physics' }], engineGlueFile: 'esengine.js', runtimeDir: 'wasm' });
+ const entry = p.emitEntry({ sideModules: [{ id: 'physics', file: 'physics' }], engineGlueFile: 'esengine.js', runtimeDir: 'wasm', engineSubpackage: null });
expect(entry).toContain("require('./wasm/esengine.js')");
expect(entry).toContain(`"physics": asFactory(require('./wasm/physics.js'))`);
expect(entry).toContain("require('./game-bundle.js')");
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 285274503..acdd9ebd7 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,12 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(export): the engine binary can ship in a 分包 the host loads at startup':
+ { note: "The engine can ship outside a WeChat mini-game's main package entirely." },
+
+ 'feat(build): the engine binary can ship in a subpackage':
+ { note: "The engine can ship outside a WeChat mini-game's main package entirely." },
+
'refactor(export): the entry asks for the runtime where the layout put it':
{ internal: 'One author for a path inside the package; what it answers is unchanged.' },