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(export): the engine binary can ship in a 分包 the host loads at startup
esengine733a2c684da7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 mainpackage.** The engine binary is the largest single file such a package carries — 1.74MBagainst WeChat's 4MB main-package limit, 43.6% of it spent before any of your content.diff --git a/desktop b/desktopindex 4342add95..424f29110 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 4342add952fd8f971be7c54c0620c7a5417f5156+Subproject commit 424f29110ed77ed9fdf72a4b73521f1e64d4b837diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.' },