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
fix(export): a build comparison blames the setting that moved, not the content
esenginee87722f73057
diff --git a/desktop b/desktopindex c122dcab4..84b2458da 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit c122dcab4ee5ec6b477a2a1eca524691250683c0+Subproject commit 84b2458dac6ab2e2a70720deced6fbf73ad62828diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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.mjsindex 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')) {