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): 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.' },