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(project): seven packaging settings a project could declare did nothing

esengineceb136f8f155
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 and
no cause — the case CI hits about every third build. The failure now carries the frame's own
navigation, the HTTP status it was served, any load error and its console, with timings: a
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index a9cd951c1..05311d46f 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -743,7 +743,7 @@ const desktopTemplates = platform !== 'desktop' ? [] : (opts.template
const { 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.ts
index 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, then
diff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.ts
index 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'>): Coo
return { 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.ts
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.' },