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(size): the bundle report names subsystems, not the chunks they landed in

esengine201b6840f383
diff --git a/pipeline/src/export/bundleBreakdown.ts b/pipeline/src/export/bundleBreakdown.ts
index 8123d7ab8..082a66cab 100644
--- a/pipeline/src/export/bundleBreakdown.ts
+++ b/pipeline/src/export/bundleBreakdown.ts
@@ -8,10 +8,14 @@
* 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.
+ * esbuild already knows how many bytes of each INPUT survived into an output,
+ * tree-shaking included — but the inputs are the SDK's BUILT chunks, and a chunk
+ * is grouped by what reaches it rather than by what it does. So each one is read
+ * back through its source map and the grouping is the SDK's directory layout,
+ * which is a list nobody has to keep.
*/
+import path from 'node:path';
+import { sourceBytesOf } from './chunkSources';
/** Bytes of one output that came from one module. */
export interface ModuleBytes {
@@ -30,11 +34,8 @@ export interface BundleMetafile {
}
/**
- * 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.
+ * Which module a path belongs to — an original source, or a built chunk when
+ * there is no map to read it through.
*/
export function moduleOfInput(input: string): string {
const chunk = /(?:^|\/)sdk\/dist\/(?:shared\/)?([^/]+)\.[cm]?js$/.exec(input);
@@ -53,22 +54,37 @@ export function moduleOfInput(input: string): string {
* `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[] {
+export function breakdownOf(meta: BundleMetafile, output: string, sdkDist?: 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 }>();
+ const add = (module: string, bytes: number, files: number): void => {
+ const at = by.get(module) ?? { bytes: 0, files: 0 };
+ at.bytes += bytes;
+ at.files += files;
+ by.set(module, at);
+ };
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);
+ const inside = sdkDist === undefined ? undefined : sourcesOfChunk(input, sdkDist);
+ if (inside === undefined) { add(moduleOfInput(input), bytes, 1); continue; }
+ // Proportional: esbuild reports what survived into the output, which is not
+ // the chunk's size on disk — the ratio is the only thing carried across.
+ const mapped = [...inside.values()].reduce((n, v) => n + v, 0);
+ for (const [source, span] of inside) add(moduleOfInput(source), (span / mapped) * bytes, 1);
}
return [...by.entries()]
- .map(([module, v]) => ({ module, bytes: v.bytes, files: v.files }))
+ .map(([module, v]) => ({ module, bytes: Math.round(v.bytes), files: v.files }))
.sort((a, b) => b.bytes - a.bytes);
}
+
+/** The sources inside an SDK chunk, or undefined when `input` is not one. */
+function sourcesOfChunk(input: string, sdkDist: string): Map<string, number> | undefined {
+ if (!/(?:^|\/)sdk\/dist\//.test(input.replace(/\\/g, '/'))) return undefined;
+ const rel = input.replace(/\\/g, '/').replace(/^.*?(?:^|\/)sdk\/dist\//, '');
+ return sourceBytesOf(path.join(sdkDist, rel));
+}
diff --git a/pipeline/src/export/chunkSources.ts b/pipeline/src/export/chunkSources.ts
new file mode 100644
index 000000000..5821dbec9
--- /dev/null
+++ b/pipeline/src/export/chunkSources.ts
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What an SDK chunk is made of, read off the source map beside it.
+ *
+ * A bundler groups modules into a chunk by what reaches them, not by what they
+ * do, so a chunk's name is one of its modules and says nothing about the other
+ * forty: `shared/physics.js` is the whole physics directory, and deleting spine
+ * once renamed a 47KB chunk without changing a byte of it. A size report built
+ * on chunk names therefore reads as an answer while being a coincidence.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+interface RawMap {
+ sources: string[];
+ mappings: string;
+}
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const DIGIT = new Map([...B64].map((c, i) => [c, i] as const));
+
+/** Generated positions and the source each came from, in emitted order. */
+function segments(mappings: string): Array<[line: number, column: number, source: number]> {
+ const out: Array<[number, number, number]> = [];
+ let source = 0;
+ const lines = mappings.split(';');
+ for (let line = 0; line < lines.length; line++) {
+ let column = 0;
+ if (lines[line] === '') continue;
+ for (const segment of lines[line].split(',')) {
+ if (segment === '') continue;
+ const fields: number[] = [];
+ let i = 0;
+ while (i < segment.length) {
+ let shift = 0;
+ let value = 0;
+ let more = 1;
+ while (more !== 0) {
+ const digit = DIGIT.get(segment[i]);
+ i += 1;
+ if (digit === undefined) return out; // Not a map we can read; keep what we have.
+ more = digit & 32;
+ value += (digit & 31) << shift;
+ shift += 5;
+ }
+ fields.push((value & 1) !== 0 ? -(value >> 1) : value >> 1);
+ }
+ column += fields[0];
+ if (fields.length >= 4) source += fields[1];
+ out.push([line, column, fields.length >= 4 ? source : -1]);
+ }
+ }
+ return out;
+}
+
+/**
+ * Bytes of `chunk` that came from each original source, keyed by the path the
+ * map names resolved against the chunk. A span runs to the next mapping on its
+ * line, which is how a minified file — one long line — divides up at all.
+ *
+ * Undefined when there is no map: a dist built without them is still a dist.
+ */
+export function sourceBytesOf(chunk: string): Map<string, number> | undefined {
+ if (!existsSync(`${chunk}.map`)) return undefined;
+ let map: RawMap;
+ try {
+ map = JSON.parse(readFileSync(`${chunk}.map`, 'utf8')) as RawMap;
+ } catch {
+ return undefined;
+ }
+ if (!Array.isArray(map.sources) || typeof map.mappings !== 'string') return undefined;
+ const lineLengths = readFileSync(chunk, 'utf8').split('\n').map((l) => l.length + 1);
+ const segs = segments(map.mappings);
+ const bytes = new Map<string, number>();
+ for (let i = 0; i < segs.length; i++) {
+ const [line, column, source] = segs[i];
+ if (source < 0) continue;
+ const next = segs[i + 1];
+ const end = next !== undefined && next[0] === line ? next[1] : lineLengths[line] ?? column;
+ const span = Math.max(0, end - column);
+ if (span === 0) continue;
+ const name = path.resolve(path.dirname(chunk), map.sources[source] ?? '');
+ bytes.set(name, (bytes.get(name) ?? 0) + span);
+ }
+ return bytes.size > 0 ? bytes : undefined;
+}
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index 09c589086..9630a6586 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -498,7 +498,7 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
metafile: true,
});
errors.push(...explainBundleErrors(res.errors));
- if (res.metafile) bundleModules = breakdownOf(res.metafile, 'game-bundle.js');
+ if (res.metafile) bundleModules = breakdownOf(res.metafile, 'game-bundle.js', opts.sdkDir);
} catch (err) {
const e = err as { errors?: BundleMessage[]; message?: string };
errors.push(...(e.errors ? explainBundleErrors(e.errors) : [String(e.message ?? err)]));
diff --git a/pipeline/tests/bundle-breakdown.test.ts b/pipeline/tests/bundle-breakdown.test.ts
index f5f8ad499..d1cd6208f 100644
--- a/pipeline/tests/bundle-breakdown.test.ts
+++ b/pipeline/tests/bundle-breakdown.test.ts
@@ -1,6 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
import { breakdownOf, moduleOfInput } from '../src/export/bundleBreakdown';
/**
@@ -72,3 +75,45 @@ describe('breakdownOf', () => {
expect(breakdownOf(metaWith(REAL_INPUTS), 'nothing.js')).toHaveLength(0);
});
});
+
+/**
+ * A chunk's name is one of its modules, so `shared/physics.js` reads as
+ * "physics" while holding the whole directory — and once held spine too, under
+ * a name that changed when spine left without a byte of it moving. The map
+ * beside it says what is really in there.
+ */
+describe('reading a chunk through its source map', () => {
+ // Laid out as the real thing, because the map's sources are relative to it:
+ // `<root>/sdk/dist/shared/..` + `../../src/ai` is where the directory names are.
+ const root = mkdtempSync(path.join(tmpdir(), 'dist-'));
+ const dist = path.join(root, 'sdk', 'dist');
+ afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));
+
+ // Two mapped spans of ten on one line: `AAAA` is (column 0, source 0), and
+ // `UCAA` steps the column by ten and the source by one. A span runs to the
+ // next mapping, and the last runs to the end of the line.
+ mkdirSync(path.join(dist, 'shared'), { recursive: true });
+ writeFileSync(path.join(dist, 'shared', 'webAppFactory.js'), 'x'.repeat(19));
+ writeFileSync(path.join(dist, 'shared', 'webAppFactory.js.map'), JSON.stringify({
+ version: 3,
+ sources: ['../../src/ai/fsm.ts', '../../src/tilemap/paint.ts'],
+ mappings: 'AAAA,UCAA',
+ }));
+
+ it('names the directories inside the chunk, not the chunk', () => {
+ const rows = breakdownOf(metaWith({ 'sdk/dist/shared/webAppFactory.js': 1000 }), 'game-bundle.js', dist);
+ expect(rows.map((r) => r.module).sort()).toEqual(['ai', 'tilemap']);
+ expect(rows.some((r) => r.module === 'webAppFactory')).toBe(false);
+ });
+
+ it('splits the bytes that survived, not the bytes on disk', () => {
+ const rows = breakdownOf(metaWith({ 'sdk/dist/shared/webAppFactory.js': 1000 }), 'game-bundle.js', dist);
+ expect(rows.reduce((n, r) => n + r.bytes, 0)).toBe(1000);
+ expect(rows.find((r) => r.module === 'ai')?.bytes).toBe(500);
+ });
+
+ it('falls back to the chunk when there is no map to read', () => {
+ const rows = breakdownOf(metaWith({ 'sdk/dist/shared/physics.js': 60 }), 'game-bundle.js', dist);
+ expect(rows[0].module).toBe('physics');
+ });
+});