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(export): a build comparison blames the setting that moved, not the content

esenginee87722f73057
diff --git a/desktop b/desktop
index c122dcab4..84b2458da 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit c122dcab4ee5ec6b477a2a1eca524691250683c0
+Subproject commit 84b2458dac6ab2e2a70720deced6fbf73ad62828
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index cb8ff3165..653332236 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -66,6 +66,7 @@ import { compileTargetFor, isNativePlatform, desktopTemplateFor, type DesktopOs,
import type { DesktopPackaging, SteamPackaging } from '../project/format';
import type { SizeBudget } from '../project/sizeBudget';
import { measureBuild, type BuildSizeReport } from './sizeReport';
+import { sizeSettingsOf } from './sizeHistory';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
import { subsystemGapWarnings, targetGaps } from '../project/targetSupport';
import { contentSubsystems } from './contentSubsystems';
@@ -564,13 +565,7 @@ async function attachSizeReport(result: ExportGameResult, opts: ExportGameOption
// read as content that grew.
history: {
projectRoot: opts.root,
- settings: {
- contentAddressed: opts.contentAddressed,
- compressTextures: opts.compressTextures,
- compressAudio: opts.compressAudio,
- atlasTextures: opts.atlasTextures,
- minify: opts.minify,
- },
+ settings: sizeSettingsOf(opts),
},
});
return { ...result, size, inclusion: undefined };
diff --git a/pipeline/src/export/sizeHistory.ts b/pipeline/src/export/sizeHistory.ts
index b0df5cbf3..9fb6ad65d 100644
--- a/pipeline/src/export/sizeHistory.ts
+++ b/pipeline/src/export/sizeHistory.ts
@@ -19,13 +19,60 @@ import path from 'node:path';
import type { BuildSizeEntry, BuildSizeReport } from './sizeReport';
import type { ExportPlatform } from '../project/platforms';
-/** Build options that change what a package weighs, recorded with the measurement. */
+/**
+ * Build options that change what a package weighs WITHOUT changing what is in
+ * it. A setting that ships different content belongs in the file diff, where a
+ * developer can see which files moved; one that ships the same content packed
+ * differently belongs here, or the next build reads it as a regression.
+ */
export interface SizeSettings {
contentAddressed?: boolean;
compressTextures?: boolean;
compressAudio?: boolean;
atlasTextures?: boolean;
minify?: boolean;
+ sourcemap?: boolean;
+ compressWasm?: boolean;
+ engineSubpackage?: boolean;
+}
+
+/**
+ * What each packaging setting does to a measurement: the {@link SizeSettings}
+ * key recording it, `content` (the file diff is the honest answer), or `inert`.
+ * Exhaustive over `ProjectPackaging` — three levers were recorded nowhere, so
+ * flipping `compressWasm` moved 1.4MB and the report blamed content.
+ */
+export const PACKAGING_SIZE_ROLE: Readonly<Record<string, keyof SizeSettings | 'content' | 'inert'>> = {
+ platform: 'inert',
+ config: 'minify',
+ sourceMaps: 'sourcemap',
+ openFolder: 'inert',
+ orientation: 'inert',
+ assetCompression: 'compressTextures',
+ compressTextures: 'compressTextures',
+ compressAudio: 'compressAudio',
+ atlasTextures: 'atlasTextures',
+
+ compressWasm: 'compressWasm',
+ engineSubpackage: 'engineSubpackage',
+ excludeScenes: 'content',
+ outDir: 'inert',
+ sizeBudget: 'inert',
+ appId: 'inert',
+ icon: 'content',
+ achievements: 'inert',
+ platforms: 'content',
+};
+
+/** The settings this build ran with, out of everything the export was given. */
+export function sizeSettingsOf(opts: SizeSettings): SizeSettings {
+ const keys: (keyof SizeSettings)[] = [
+ 'contentAddressed', 'compressTextures', 'compressAudio', 'atlasTextures',
+ 'minify', 'sourcemap', 'compressWasm', 'engineSubpackage',
+ ];
+ const out: SizeSettings = {};
+ for (const k of keys) if (opts[k] !== undefined) out[k] = opts[k];
+ return out;
}
/** One build's measurement, as the history file stores it. */
diff --git a/pipeline/tests/size-settings-recorded.test.ts b/pipeline/tests/size-settings-recorded.test.ts
new file mode 100644
index 000000000..2443be213
--- /dev/null
+++ b/pipeline/tests/size-settings-recorded.test.ts
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A build compared against the last one blames the right thing.
+ *
+ * The comparison exists to separate "you shipped more" from "you packed it
+ * differently". Three settings that pack it differently — source maps, the
+ * engine's brotli, the engine 分包 — reached the export and were never written
+ * into the record, so flipping one reported 1.4MB of content nobody wrote.
+ *
+ * The gate next door proves every packaging setting has DECLARED an effect.
+ * This proves the declaration is wired: a lever named there actually lands in
+ * the record, and a build that flips it says so.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ compareSizes, sizeSettingsOf, PACKAGING_SIZE_ROLE,
+ type SizeRecord, type SizeSettings,
+} from '../src/export/sizeHistory';
+
+const record = (settings: SizeSettings, bytes: number): SizeRecord => ({
+ at: '2026-09-21T00:00:00.000Z',
+ platform: 'wechat',
+ settings,
+ initialBytes: bytes,
+ lazyBytes: 0,
+ remoteBytes: 0,
+ packageBytes: bytes,
+ totalBytes: bytes,
+ fileCount: 1,
+ files: [{ path: 'wasm/esengine.wasm', bytes, kind: 'engine', bucket: 'initial' }],
+});
+
+/** Every role that names a SizeSettings key, deduplicated. */
+const LEVERS = [...new Set(Object.values(PACKAGING_SIZE_ROLE))]
+ .filter((r): r is keyof SizeSettings => r !== 'content' && r !== 'inert');
+
+describe('the settings a measurement is recorded with', () => {
+ it('carries every lever the role table names', () => {
+ const all = Object.fromEntries(LEVERS.map((k) => [k, true])) as SizeSettings;
+ expect(Object.keys(sizeSettingsOf(all)).sort()).toEqual([...LEVERS].sort());
+ });
+
+ it('leaves out what the export was not told, so "off" and "unset" stay apart', () => {
+ expect(sizeSettingsOf({ minify: false })).toEqual({ minify: false });
+ });
+
+ // The failing shape, one lever at a time: same content, packed differently.
+ it.each(LEVERS)('names %s when a build flips it, instead of blaming content', (lever) => {
+ const before = record({ [lever]: false }, 1_800_000);
+ const after = record({ [lever]: true }, 360_000);
+ const diff = compareSizes(before, after);
+ expect(diff.settingsChanged).toContain(lever);
+ });
+
+ it('says nothing changed when the settings and the files are the same', () => {
+ const same = { compressWasm: true, minify: true };
+ const diff = compareSizes(record(same, 360_000), record(same, 360_000));
+ expect(diff.settingsChanged).toEqual([]);
+ expect(diff.changes).toEqual([]);
+ });
+});
diff --git a/tools/check-packaging-settings.mjs b/tools/check-packaging-settings.mjs
index ebfbf38ce..3db89ffab 100644
--- a/tools/check-packaging-settings.mjs
+++ b/tools/check-packaging-settings.mjs
@@ -59,4 +59,59 @@ if (dropped.length > 0) {
process.exit(1);
}
-console.log(`check-packaging-settings: ${declared.length} packaging setting(s), each one read back.`);
+// ---------------------------------------------------------------------------
+// …and the other end: a setting that survives the load can still be missing
+// from the MEASUREMENT record, where the symptom is a build-over-build
+// comparison that blames content for a packing change. Three did.
+// ---------------------------------------------------------------------------
+
+const HISTORY = 'pipeline/src/export/sizeHistory.ts';
+const history = readFileSync(path.join(ROOT, HISTORY), 'utf8');
+
+const roleBlock = /PACKAGING_SIZE_ROLE[^=]*=\s*\{([\s\S]*?)\n\};/.exec(history);
+if (!roleBlock) {
+ console.error(`check-packaging-settings: no PACKAGING_SIZE_ROLE in ${HISTORY} — the table moved.`);
+ process.exit(1);
+}
+const roles = new Map(
+ [...roleBlock[1].matchAll(/^\s{4}([a-zA-Z][A-Za-z0-9]*):\s*'([^']+)'/gm)].map(([, f, r]) => [f, r]),
+);
+
+const settingsBlock = /interface SizeSettings\s*\{([\s\S]*?)\n\}/.exec(history);
+if (!settingsBlock) {
+ console.error(`check-packaging-settings: no SizeSettings in ${HISTORY} — the record moved.`);
+ process.exit(1);
+}
+const recorded = new Set(
+ [...settingsBlock[1].matchAll(/^\s{2}([a-zA-Z][A-Za-z0-9]*)\??:/gm)].map(([, f]) => f),
+);
+
+const problems = [];
+for (const f of declared) {
+ const role = roles.get(f);
+ if (!role) {
+ problems.push(` ${HISTORY}: packaging.${f} has no role — say which SizeSettings key records it, `
+ + "or 'content' (it ships different files) or 'inert' (it cannot move a byte)");
+ continue;
+ }
+ if (role !== 'content' && role !== 'inert' && !recorded.has(role)) {
+ problems.push(` ${HISTORY}: packaging.${f} says it is recorded as "${role}", `
+ + 'which SizeSettings does not declare');
+ }
+}
+for (const f of roles.keys()) {
+ if (!declared.includes(f)) {
+ problems.push(` ${HISTORY}: PACKAGING_SIZE_ROLE names "${f}", which ProjectPackaging no longer declares`);
+ }
+}
+
+if (problems.length > 0) {
+ for (const line of problems) console.error(line);
+ console.error(`check-packaging-settings: ${problems.length} setting(s) whose effect on a measurement `
+ + 'is undeclared — a comparison against the last build would blame the wrong thing.');
+ process.exit(1);
+}
+
+const levers = [...roles.values()].filter((r) => r !== 'content' && r !== 'inert').length;
+console.log(`check-packaging-settings: ${declared.length} packaging setting(s), each one read back `
+ + `and each one's effect on a measurement declared (${levers} recorded with it).`);
diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjs
index 2eccc50a0..1d420aec7 100644
--- a/tools/check-project-settings.mjs
+++ b/tools/check-project-settings.mjs
@@ -250,6 +250,13 @@ const CONSUMPTION = {
/** …and one of them must SAY it has none. Absence of a lie is not a truth: the
* row looks like every other one, so silence still reads as "this works". */
disclaimedBy: 'set.project.spine.version.desc',
+ /**
+ * The readers that are not the settings UI. The built-in agent's tool
+ * description promised "the build bundles that runtime", which matches no
+ * BUILD_PROMISE pattern — enumerating the ways to lie does not work. So the
+ * rule is the row's: wherever it is described, it says what it does not do.
+ */
+ describedIn: ['desktop/shared/toolCatalog.mjs'],
},
};
/** An absolute promise about what a build produces. Not the word "ships": the
@@ -294,6 +301,26 @@ for (const [field, decl] of Object.entries(CONSUMPTION)) {
problems.push(`${field} is ${decl.kind} and "${dk}" never says so — a row that reads like`
+ ' every other one is read as one that takes effect like every other one.');
}
+ for (const rel of decl.describedIn ?? []) {
+ if (!existsSync(path.join(ROOT, rel))) {
+ problems.push(`${field}: ${rel} is declared to describe it and is not there`);
+ continue;
+ }
+ const text = read(rel);
+ let from = text.indexOf(field);
+ if (from < 0) {
+ problems.push(`${field}: ${rel} is declared to describe it and never names it`);
+ continue;
+ }
+ while (from >= 0) {
+ if (!DISCLAIMS.test(text.slice(from, from + 400))) {
+ const line = text.slice(0, from).split('\n').length;
+ problems.push(`${field} is ${decl.kind}, and ${rel}:${line} describes it without saying so`
+ + ' — a reader told what a setting is and not told it does nothing assumes it does something.');
+ }
+ from = text.indexOf(field, from + 1);
+ }
+ }
}
if (process.argv.includes('--list')) {