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): a mini-game package says which subsystem each byte came from
esengineefd523ea9db3
diff --git a/pipeline/src/export/bundleBreakdown.ts b/pipeline/src/export/bundleBreakdown.tsnew file mode 100644index 000000000..8123d7ab8--- /dev/null+++ b/pipeline/src/export/bundleBreakdown.ts@@ -0,0 +1,74 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file bundleBreakdown.ts — which subsystem each byte of a JS bundle came from.+ *+ * A mini-game inlines the SDK, so once the engine binary moves out of the main+ * package the bundle is the largest file left — and `.js` is the one thing a+ * vendor's brotli path does not take. "The scripts are 1.4MB" is not something+ * anyone can act on; "spine is 180KB of it, in a project with no spine" is.+ *+ * esbuild already knows this: a metafile says how many bytes of each INPUT+ * survived into an output, tree-shaking included. This only groups them, and the+ * grouping is the SDK's own directory layout rather than a list kept here.+ */++/** Bytes of one output that came from one module. */+export interface ModuleBytes {+ /** An SDK subsystem (`spine`, `tilemap`…), `dep:<pkg>`, `core`, or `project`. */+ readonly module: string;+ readonly bytes: number;+ /** How many input files contributed — a module that is one file and a module+ * that is forty read very differently when deciding what to make optional. */+ readonly files: number;+}++/** The shape this reads out of esbuild's metafile — its own type is not imported+ * so a caller can pass a parsed metafile from anywhere. */+export interface BundleMetafile {+ outputs: Record<string, { inputs?: Record<string, { bytesInOutput?: number }> }>;+}++/**+ * Which module an input path belongs to.+ *+ * A mini-game bundles the SDK's BUILT chunks, and a chunk is also the unit a+ * bundler can act on: it can drop one nothing reaches, and cannot drop half of+ * one. So the SDK's own split is the grouping, not a list kept here.+ */+export function moduleOfInput(input: string): string {+ const chunk = /(?:^|\/)sdk\/dist\/(?:shared\/)?([^/]+)\.[cm]?js$/.exec(input);+ if (chunk) return chunk[1];+ const src = /(?:^|\/)sdk\/src\/([^/]+)\/.+$/.exec(input);+ if (src) return src[1];+ if (/(?:^|\/)sdk\/src\/[^/]+$/.test(input)) return 'core';+ const dep = /(?:^|\/)node_modules\/((?:@[^/]+\/)?[^/]+)\//.exec(input);+ if (dep) return `dep:${dep[1]}`;+ return 'project';+}++/**+ * Group one output's inputs by module, largest first.+ *+ * `output` is the key as the metafile spells it; a caller that cannot predict+ * esbuild's path spelling can pass a suffix and the single match is used.+ */+export function breakdownOf(meta: BundleMetafile, output: string): ModuleBytes[] {+ const key = meta.outputs[output] ? output+ : Object.keys(meta.outputs).find((k) => k.endsWith(output));+ const inputs = key ? meta.outputs[key]?.inputs ?? {} : {};+ const by = new Map<string, { bytes: number; files: number }>();+ for (const [input, info] of Object.entries(inputs)) {+ const bytes = info.bytesInOutput ?? 0;+ // A file tree-shaken down to nothing is not a module this package carries,+ // and listing it as 0 bytes reads as one that is merely small.+ if (bytes <= 0) continue;+ const at = by.get(moduleOfInput(input)) ?? { bytes: 0, files: 0 };+ at.bytes += bytes;+ at.files += 1;+ by.set(moduleOfInput(input), at);+ }+ return [...by.entries()]+ .map(([module, v]) => ({ module, bytes: v.bytes, files: v.files }))+ .sort((a, b) => b.bytes - a.bytes);+}diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.tsindex 5878a2b37..bd84ba4d5 100644--- a/pipeline/src/export/exportMiniGame.ts+++ b/pipeline/src/export/exportMiniGame.ts@@ -41,6 +41,7 @@ import { cookAssets, type Inclusion } from '../assets/cookAssets';import { buildAddressableManifest } from '../assets/addressableManifest';import type { ExportScene } from './exportGame';import type { OnExportProgress } from './exportProgress';+import { breakdownOf, type ModuleBytes } from './bundleBreakdown';import { esengineAlias } from '../bundle/esengineResolve';import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';@@ -59,6 +60,11 @@ export interface ExportMiniGameResult {errors: string[];/** @internal Why each asset is in the build; the size report consumes and drops it. */inclusion?: Record<string, Inclusion>;+ /** What each subsystem costs inside `game-bundle.js`, largest first. The bundle+ * is the main package's biggest file once the engine binary can move out, and+ * a vendor's brotli path does not take `.js`, so this is where the remaining+ * room is. */+ bundleModules?: ModuleBytes[];}interface CookManifest {@@ -437,6 +443,8 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {` return ${profile.runtimeInit}({ engineFactory, engineWasmPath: ${JSON.stringify(engineWasmPath)}, sideModuleFactories, sceneNames: ${JSON.stringify(scenes.map((s) => s.name))}, firstScene: ${JSON.stringify(sceneName)}${runtimeArgs}${projectDeclarations.length > 0 ? `, sideModules: ${JSON.stringify(projectDeclarations)}` : ''}${aotArg} });\n` +`}\n`;progress({ phase: 'Bundling game' });+ /** What each subsystem costs in the bundle — empty if esbuild wrote no metafile. */+ let bundleModules: ModuleBytes[] = [];try {const { build } = await loadEsbuild();const res = await build({@@ -453,8 +461,13 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {outfile: path.join(absOut, 'game-bundle.js'),logLevel: 'silent',write: true,+ // Once the engine binary can leave the main package, this bundle is the+ // largest file in it — and the vendor's brotli path does not take `.js`.+ // esbuild already knows which subsystem each surviving byte came from.+ metafile: true,});errors.push(...explainBundleErrors(res.errors));+ if (res.metafile) bundleModules = breakdownOf(res.metafile, 'game-bundle.js');} catch (err) {const e = err as { errors?: BundleMessage[]; message?: string };errors.push(...(e.errors ? explainBundleErrors(e.errors) : [String(e.message ?? err)]));@@ -603,5 +616,6 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {return {ok: errors.length === 0, platform: profile.id, outDir: absOut,included: cook.included.length, warnings, errors, inclusion: cook.inclusion,+ bundleModules,};}diff --git a/pipeline/tests/bundle-breakdown.test.ts b/pipeline/tests/bundle-breakdown.test.tsnew file mode 100644index 000000000..f5f8ad499--- /dev/null+++ b/pipeline/tests/bundle-breakdown.test.ts@@ -0,0 +1,74 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { breakdownOf, moduleOfInput } from '../src/export/bundleBreakdown';++/**+ * Paths exactly as esbuild spelled them for a real WeChat export. The first rule+ * read `sdk/src/` while a mini-game bundles `sdk/dist/`, so every byte landed+ * under `project` — and a one-row breakdown still looks like a breakdown, which+ * is why the shapes are pinned rather than described.+ */+const REAL_INPUTS = {+ 'sdk/dist/shared/webAppFactory.js': 870_617,+ 'sdk/dist/shared/system.js': 225_253,+ 'sdk/dist/shared/spine.js': 95_156,+ 'sdk/dist/shared/physics.js': 60_629,+ 'sdk/dist/shared/dragonbones.js': 15_338,+ 'sdk/dist/index.wechat.js': 2_049,+};++const metaWith = (inputs: Record<string, number>) => ({+ outputs: {+ 'out/game-bundle.js': {+ inputs: Object.fromEntries(+ Object.entries(inputs).map(([k, v]) => [k, { bytesInOutput: v }]),+ ),+ },+ },+});++describe('moduleOfInput', () => {+ it('names an SDK chunk by the chunk, which is the unit a bundler can drop', () => {+ expect(moduleOfInput('sdk/dist/shared/spine.js')).toBe('spine');+ expect(moduleOfInput('sdk/dist/index.wechat.js')).toBe('index.wechat');+ });++ it('still reads a source tree, for a bundle built from one', () => {+ expect(moduleOfInput('sdk/src/tilemap/tilemapPlugin.ts')).toBe('tilemap');+ expect(moduleOfInput('sdk/src/index.ts')).toBe('core');+ });++ it('separates a dependency from the project', () => {+ expect(moduleOfInput('node_modules/@foo/bar/dist/x.js')).toBe('dep:@foo/bar');+ expect(moduleOfInput('src/game/player.ts')).toBe('project');+ });+});++describe('breakdownOf', () => {+ it('splits a real mini-game bundle into the chunks it is made of', () => {+ const rows = breakdownOf(metaWith(REAL_INPUTS), 'game-bundle.js');+ // The regression this pins: a rule that matches nothing yields one `project`+ // row holding every byte, which reads as a successful measurement.+ expect(rows.length).toBeGreaterThan(1);+ expect(rows.every((r) => r.module === 'project')).toBe(false);+ expect(rows[0].module).toBe('webAppFactory');+ expect(rows.find((r) => r.module === 'spine')?.bytes).toBe(95_156);+ });++ it('accounts for every byte it was given', () => {+ const rows = breakdownOf(metaWith(REAL_INPUTS), 'game-bundle.js');+ const total = Object.values(REAL_INPUTS).reduce((a, b) => a + b, 0);+ expect(rows.reduce((n, r) => n + r.bytes, 0)).toBe(total);+ });++ it('leaves out an input tree-shaken to nothing, rather than calling it small', () => {+ const rows = breakdownOf(metaWith({ ...REAL_INPUTS, 'sdk/dist/shared/unused.js': 0 }), 'game-bundle.js');+ expect(rows.some((r) => r.module === 'unused')).toBe(false);+ });++ it('finds the output by suffix, since the caller cannot predict esbuild spelling', () => {+ expect(breakdownOf(metaWith(REAL_INPUTS), 'game-bundle.js')).not.toHaveLength(0);+ expect(breakdownOf(metaWith(REAL_INPUTS), 'nothing.js')).toHaveLength(0);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex d61de086a..bee7e7ad0 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(export): a mini-game package says which subsystem each byte came from':+ { internal: 'A field on the export result; no panel shows it yet, so nothing a creator sees.' },+'feat(export): a packaged game says it is loading':{ note: 'A packaged game now says it is loading.' },