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(project): seven packaging settings a project could declare did nothing
esengineceb136f8f155
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c73f1a986..4b3a12442 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -23,6 +23,13 @@ published separately; it ships inside the editor.### Fixed+- **A WeChat package can put its engine binary in a compressed subpackage.** The settings for both — `compressWasm` and `engineSubpackage` — existed, had a+ row in Project Settings and were honoured by the exporter, and the manifest parser read+ neither, so turning them on did nothing anywhere. Five other packaging settings were dropped+ the same way, `assetCompression` among them. On hello-world the engine goes from 1.83MB+ uncompressed in the main package to 363KB in a subpackage, and the main package from 80% of+ WeChat's 4MB cap to 37%.+- **A game that fails to start says what its frame actually did.** A realm that never reports in left the editor with one sentence andno cause — the case CI hits about every third build. The failure now carries the frame's ownnavigation, the HTTP status it was served, any load error and its console, with timings: adiff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex a9cd951c1..05311d46f 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -743,7 +743,7 @@ const desktopTemplates = platform !== 'desktop' ? [] : (opts.templateconst { mod: fmt, cleanup: cleanupFmt } = await loadPipeline(path.join(PIPELINE, 'src', 'project', 'index.ts'), 'projectFormat.mjs');-const { resolveOrientation, parseManifest, runtimeConfigOf, cookOptionsOf } = fmt;+const { resolveOrientation, parseManifest, runtimeConfigOf, cookOptionsOf, packagingOptionsOf } = fmt;// PARSED, not read by hand: the parser normalizes legacy platform ids and drops// values that could not be judged against. A setting read straight off the JSON// here is a second answer to what a project means.@@ -771,6 +771,7 @@ try {// claiming to be the package the dialog makes.runtime: runtimeConfigOf(manifest),...cookOptionsOf(manifest),+ ...packagingOptionsOf(manifest),androidTemplate: platform === 'android' ? templateDir : null,desktopTemplates,desktopChannel: opts['steam-appid'] ? 'steam' : undefined,diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex f3d8e4642..d25c175c4 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -666,6 +666,16 @@ export function parseManifest(raw: unknown): ProjectManifest {if (typeof p.appId === 'string' && p.appId !== '') pkg.appId = p.appId;if (typeof p.sourceMaps === 'boolean') pkg.sourceMaps = p.sourceMaps;if (typeof p.openFolder === 'boolean') pkg.openFolder = p.openFolder;+ if (typeof p.compressWasm === 'boolean') pkg.compressWasm = p.compressWasm;+ if (typeof p.engineSubpackage === 'boolean') pkg.engineSubpackage = p.engineSubpackage;+ if (p.assetCompression === 'auto' || p.assetCompression === 'skip') pkg.assetCompression = p.assetCompression;+ // The deprecated trio the `assetCompression` switch replaced. Still read:+ // a project written before it exists on disk, and dropping them here would+ // silently turn its choice back on.+ if (typeof p.compressTextures === 'boolean') pkg.compressTextures = p.compressTextures;+ if (typeof p.compressAudio === 'boolean') pkg.compressAudio = p.compressAudio;+ if (typeof p.atlasTextures === 'boolean') pkg.atlasTextures = p.atlasTextures;+ if (typeof p.icon === 'string' && p.icon !== '') pkg.icon = p.icon;// Project-wide orientation. `orientation` is authoritative; a project written by// an older editor carried it per-platform (packaging.platforms.{wechat|playable}// .orientation) — hoist the first legacy value found (below) as a migration, thendiff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.tsindex 4859b9773..4d7612aeb 100644--- a/pipeline/src/project/runtimeConfig.ts+++ b/pipeline/src/project/runtimeConfig.ts@@ -229,6 +229,34 @@ export function cookOptionsOf(manifest: Pick<ProjectManifest, 'packaging'>): Cooreturn { compressTextures: on, compressAudio: on, atlasTextures: on };}+/**+ * The packaging POLICY a headless export must carry, beyond the cook's.+ *+ * Third derivation of this shape and the third time for one reason: the Build+ * dialog reads these settings and the command line did not, so an automated+ * package silently differed from the one a person makes.+ */+export interface PackagingOptions {+ compressWasm: boolean;+ engineSubpackage: boolean;+ excludeScenes: string[];+ sourcemap: boolean;+ appIcon: string | undefined;+}++export function packagingOptionsOf(manifest: Pick<ProjectManifest, 'packaging'>): PackagingOptions {+ const p = manifest.packaging;+ return {+ compressWasm: p?.compressWasm ?? false,+ engineSubpackage: p?.engineSubpackage ?? false,+ excludeScenes: p?.excludeScenes ?? [],+ // A shipping build carries no maps unless the project asked; `config` is the+ // word the dialog uses for the same choice.+ sourcemap: p?.sourceMaps ?? (p?.config === 'development'),+ appIcon: p?.icon,+ };+}+/** The effective settings of a project with nothing declared — every default. */export const DEFAULT_RUNTIME_CONFIG: RuntimeProjectConfig = runtimeConfigOf({});diff --git a/pipeline/tests/packaging-settings-reach.test.ts b/pipeline/tests/packaging-settings-reach.test.tsnew file mode 100644index 000000000..bc9a16823--- /dev/null+++ b/pipeline/tests/packaging-settings-reach.test.ts@@ -0,0 +1,42 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A packaging setting a project declares reaches the thing it controls.+ *+ * The gate next door proves the parser reads every field. This proves the two+ * that decide a mini-game's main-package size are still connected all the way+ * through the derivation the headless export spreads — the step that was missing+ * when `compressWasm` was honoured by the Build dialog and by nothing else.+ */+import { describe, it, expect } from 'vitest';+import { parseManifest } from '../src/project/format';+import { packagingOptionsOf, cookOptionsOf } from '../src/project/runtimeConfig';++const project = (packaging: Record<string, unknown>) =>+ parseManifest({ formatVersion: '1', name: 'p', packaging });++describe('a packaging setting a project declares', () => {+ it('survives the parser and reaches the export options', () => {+ const m = project({ compressWasm: true, engineSubpackage: true });+ expect(m.packaging?.compressWasm).toBe(true);+ expect(packagingOptionsOf(m)).toMatchObject({ compressWasm: true, engineSubpackage: true });+ });++ it('defaults to off rather than to undefined, so a host cannot read it as "unset"', () => {+ expect(packagingOptionsOf(project({}))).toMatchObject({+ compressWasm: false, engineSubpackage: false, excludeScenes: [],+ });+ });++ it('carries the asset-compression choice the cook reads', () => {+ expect(cookOptionsOf(project({ assetCompression: 'skip' })).compressTextures).toBe(false);+ expect(cookOptionsOf(project({ assetCompression: 'auto' })).compressTextures).toBe(true);+ // Absent is the default, and the default is on.+ expect(cookOptionsOf(project({})).compressTextures).toBe(true);+ });++ it('keeps the scenes a project asked not to ship out of the options', () => {+ const m = project({ excludeScenes: ['assets/scenes/dev.esscene'] });+ expect(packagingOptionsOf(m).excludeScenes).toEqual(['assets/scenes/dev.esscene']);+ });+});diff --git a/tools/check-packaging-settings.mjs b/tools/check-packaging-settings.mjsnew file mode 100644index 000000000..ebfbf38ce--- /dev/null+++ b/tools/check-packaging-settings.mjs@@ -0,0 +1,62 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Every packaging setting a project can declare survives being read.+ *+ * `parseManifest` is the one authority on what a project means — the CLI's own+ * comment says a setting read straight off the JSON would be a second answer.+ * It reads the block field by field, and seven of the eighteen `ProjectPackaging`+ * declares were never in that list: `compressWasm` and `engineSubpackage` among+ * them, so the settings that move the engine binary off a mini-game's 4MB main+ * package had no effect anywhere, in the editor or on a build server.+ *+ * `assetCompression` was one of them too, which is the reason this is a gate and+ * not a fix: the previous round of this same bug was closed by deriving cook+ * options from that field, and the field the derivation reads was never+ * populated. A hand-written reader needs something that counts its fields.+ *+ * node tools/check-packaging-settings.mjs+ */+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const FORMAT = 'pipeline/src/project/format.ts';++const src = readFileSync(path.join(ROOT, FORMAT), 'utf8');++const shape = /interface ProjectPackaging\s*\{([\s\S]*?)\n\}/.exec(src);+if (!shape) {+ console.error(`check-packaging-settings: no ProjectPackaging in ${FORMAT} — the shape moved.`);+ process.exit(1);+}+const declared = [...shape[1].matchAll(/^\s{2}([a-zA-Z][A-Za-z0-9]*)\??[:?]/gm)].map(([, f]) => f);++const reader = /if \(o\.packaging && typeof o\.packaging === 'object'\) \{([\s\S]*?)\n {2}\}/.exec(src);+if (!reader) {+ console.error(`check-packaging-settings: no packaging block in parseManifest — the reader moved.`);+ process.exit(1);+}++/** Read as `p.<field>`, or assigned as `pkg.<field>` by a migration. */+const reads = (field) =>+ new RegExp(`\\bp\\.${field}\\b`).test(reader[1]) || new RegExp(`\\bpkg\\.${field}\\b`).test(reader[1]);++const dropped = declared.filter((f) => !reads(f));+if (declared.length === 0) {+ console.error('check-packaging-settings: ProjectPackaging declares nothing — the shape cannot be read.');+ process.exit(1);+}++if (dropped.length > 0) {+ for (const f of dropped) {+ console.error(` ${FORMAT}: packaging.${f} is declared and parseManifest never reads it — `+ + 'a project setting it gets the default everywhere, silently');+ }+ console.error(`check-packaging-settings: ${dropped.length} setting(s) declared but dropped on load.`);+ process.exit(1);+}++console.log(`check-packaging-settings: ${declared.length} packaging setting(s), each one read back.`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex f5d6e01d7..ad8b46736 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -259,6 +259,9 @@ export const GATES = [// The specifiers a game writes against the SDK, held to what the package// publishes: a map entry that resolves to nothing fails at load, not at build.{ id: 'import-map', run: 'node tools/check-import-map.mjs' },+ // A packaging setting the manifest parser does not read is a setting that+ // does nothing, in the editor and on a build server alike.+ { id: 'packaging-settings', run: 'node tools/check-packaging-settings.mjs' },{ id: 'comment-style', run: 'node tools/check-comment-style.mjs' },{ id: 'silent-writes', run: 'node tools/mutation-census.mjs --gate' },{diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 143514c7f..66c0e0766 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 = {+ 'fix(project): seven packaging settings a project could declare did nothing':+ { note: "A WeChat package can put its engine binary in a compressed subpackage." },+'feat(play): a cold start that never says hello now says what its frame did':{ note: 'A game that fails to start says what its frame actually did.' },