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 mini-game package carries only what its packer will upload

esengine7c02e7de8cd1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bdd8928a5..7ce1f99e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,15 @@ published separately; it ships inside the editor.
### Fixed
+- **A WeChat package no longer carries files the upload would refuse.** WeChat publishes
+ the file types its packer accepts, and an authored format outside that list — a behaviour
+ tree, a locale table, a tileset, a prefab — was staged under its own suffix. Such a
+ package builds clean and runs in devtools, and is rejected at the moment it is uploaded,
+ which is the one step nobody automates. The flagship shipped six such files. They now
+ travel under a name the packer takes, with their real suffix kept in it, and which
+ suffixes those are is derived from the published list rather than from the two that
+ happened to be known.
+
- **An asset that fails to load says so.** A reference pointing at nothing already warned,
but an asset whose load actually threw was recorded silently: the scene opened with no
texture, no environment and no complaint anywhere, which looks exactly like a scene that
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index e6e748f79..5878a2b37 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -300,29 +300,30 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo: true, platform: profile.id });
warnings.push(...cook.warnings);
- // 1a. Restage for the vendor's code-package suffix whitelist (WeChat has no
- // `ktx2`, `esv` or `esscene`; the packer drops such files and fs reads are
- // denied regardless of packOptions):
- // *.ktx2 → *.ktx2.bin (whitelisted; isKtx2Path accepts both)
- // *.esv → *.esv.bin (the wasm video backend strips the
- // .bin when deriving the .m4a audio sibling)
- // assets/…/<x>.esscene → scenes/<name>.json, @uuid: refs stripped to the
- // bare uuids the resolver keys by; the manifest
- // entry follows, so scene refs resolve to the file.
+ // 1a. Anything the packer will not upload ships as `<name>.<ext>.bin`. Scenes
+ // have their own transform below (`<x>.esscene` → `scenes/<name>.json`,
+ // @uuid: refs stripped to the bare uuids the resolver keys by).
progress({ phase: 'Transforming scenes' });
- const binRestageRe = new RegExp(`\\.(${profile.binRestageExts.join('|')})$`);
+ const needsRestage = (p: string): boolean => {
+ if (!profile.packerSuffixes) return false;
+ const ext = path.extname(p).slice(1).toLowerCase();
+ return ext !== '' && !profile.packerSuffixes.has(ext);
+ };
const flatManifestPath = path.join(absOut, 'assets.manifest.json');
let cookEntries: CookManifest['entries'] = [];
const sceneRawByName = new Map<string, unknown>();
try {
const flat = JSON.parse(await readFile(flatManifestPath, 'utf8')) as CookManifest;
for (const e of flat.entries) {
- if (binRestageRe.test(e.path.toLowerCase())) {
+ // Scenes FIRST: they have a transform of their own below, which leaves a
+ // `.json` the packer takes. Restaging one would ship the authored file
+ // beside the transformed one, under a name nothing reads.
+ const scene = scenes.find((s) => s.path === e.path);
+ if (!scene && needsRestage(e.path)) {
await rename(path.join(absOut, e.path), path.join(absOut, `${e.path}.bin`));
e.path = `${e.path}.bin`;
continue;
}
- const scene = scenes.find((s) => s.path === e.path);
if (scene) {
const staged = path.join(absOut, e.path);
const raw = JSON.parse(await readFile(staged, 'utf8'));
@@ -377,7 +378,8 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
const brotli = profile.wasmBrotli && (opts.compressWasm ?? false);
const runtimeLayout = planRuntimeLayout(engineGlueFile, engineSideModules, {
brotli,
- subpackage: profile.subpackageDir !== '' && (opts.engineSubpackage ?? false),
+ // No API global ⇒ nothing to ask for the 分包 with, so it stays in the main package.
+ subpackage: profile.hostGlobal !== null && profile.subpackageDir !== '' && (opts.engineSubpackage ?? false),
subpackageDir: profile.subpackageDir,
});
const engineWasmPath = runtimeLayout.enginePath;
diff --git a/pipeline/src/export/miniGameExportProfile.ts b/pipeline/src/export/miniGameExportProfile.ts
index b91b9ebfd..2edee0bc3 100644
--- a/pipeline/src/export/miniGameExportProfile.ts
+++ b/pipeline/src/export/miniGameExportProfile.ts
@@ -61,8 +61,9 @@ export interface MiniGameEntryContext {
/** Package-relative directory those artifacts landed in, decided by the
* export's runtime layout. The entry asks for them WHERE THEY ARE. */
runtimeDir: string;
- /** The host's API global (`wx` / `tt`), from the profile. */
- hostGlobal: string;
+ /** The host's API global (`wx` / `tt`), from the profile; null when the
+ * vendor did not say, in which case nothing is subpackaged. */
+ hostGlobal: string | null;
/** The 分包 holding the engine binary, when it is in one: the entry has to
* ask the host for it before booting, since the file is not in the package
* until then. Null when the binary ships in the main package. */
@@ -128,14 +129,19 @@ export interface MiniGameExportProfile {
readonly sideModuleBuildTargets: Readonly<Record<string, string>>;
/** Extensions the packer handles natively (no packOptions.include needed). */
readonly nativeSuffixes: ReadonlySet<string>;
- /** Custom extensions the packer denies unless restaged to `<ext>.bin`. */
- readonly binRestageExts: readonly string[];
+ /**
+ * Every extension this host's packer will UPLOAD; anything staged outside it
+ * ships as `<name>.<ext>.bin` (`unwrapRestagedPath` reads through that).
+ * Null ⇒ no published list, so the package is staged exactly as cooked.
+ * A list, not the known failures: an upload rule refuses where nobody looks.
+ */
+ readonly packerSuffixes: ReadonlySet<string> | null;
/**
* The global this host exposes its API on: `wx` for WeChat, `tt` for Douyin.
- * The shared entry needs it to ask for a 分包, and taking it from the profile
- * is what keeps that entry free of any one vendor's name.
+ * Taking it from the profile keeps the shared entry free of any vendor's
+ * name; null means nothing can be subpackaged, there being nothing to ask.
*/
- readonly hostGlobal: string;
+ readonly hostGlobal: string | null;
/**
* Whether this vendor's loader takes a `.wasm.br` path — a CAPABILITY;
* spending the build time is `packaging.compressWasm`. WeChat's
@@ -190,6 +196,12 @@ export interface MiniGameExportProfile {
// WeChat profile
// =============================================================================
+/** WeChat's published code-package suffix whitelist (the "文件类型" table). */
+const WECHAT_PACKER_SUFFIXES: ReadonlySet<string> = new Set(`png jpg jpeg gif svg js json cer obj dae fbx mtl stl 3ds mp3 pvr wav plist ttf fnt gz ccz m4a
+ mp4 bmp atlas swf ani part proto bin sk mipmaps txt zip tt map ogg silk dbbin dbmv etc lmat lm
+ ls lh lani lav lsani ltc aac astc br csv cur dat dds glb gltf ico ktx lmani lml pkm prefab
+ scene wasm xml`.split(/\s+/).filter(Boolean));
+
export const wechatExportProfile: MiniGameExportProfile = {
id: 'wechat',
// The bundle aliases `esengine` → <sdkDir>/index.wechat.js (the wechat SDK build).
@@ -207,8 +219,9 @@ export const wechatExportProfile: MiniGameExportProfile = {
// Script + config WeChat's packer compiles itself; every OTHER staged custom
// extension needs a packOptions.include rule (fs reads are otherwise denied).
nativeSuffixes: new Set(['.js', '.json']),
- // WeChat's code-package suffix whitelist has no ktx2/esv; restage to *.bin.
- binRestageExts: ['ktx2', 'esv'],
+ // developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html,
+ // "文件类型": only these may be uploaded.
+ packerSuffixes: WECHAT_PACKER_SUFFIXES,
wasmBrotli: true,
subpackageDir: 'subpackages',
subpackageEntry: 'game.js',
diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.ts
index 2d535571c..8e9d6393b 100644
--- a/pipeline/src/export/platformCatalog.ts
+++ b/pipeline/src/export/platformCatalog.ts
@@ -160,7 +160,11 @@ export const MINIGAME_PROFILE_DEFAULTS = {
wasmBuildHint: 'web',
sideModuleBuildTargets: {} as Readonly<Record<string, string>>,
nativeSuffixes: new Set(['.js', '.json']) as ReadonlySet<string>,
- binRestageExts: [] as readonly string[],
+ // A project's own vendor publishes neither a whitelist nor an API global, so
+ // its package is staged as cooked and its engine stays in the main package.
+ packerSuffixes: null as ReadonlySet<string> | null,
+ hostGlobal: null as string | null,
+ wasmBrotli: false,
subpackageDir: 'subpackages',
// Most vendors take a root of assets as a subpackage; the ones that want an
// entry script in it say so (WeChat: game.js).
diff --git a/pipeline/tests/export-wechat-read-paths.test.ts b/pipeline/tests/export-wechat-read-paths.test.ts
index de5a6a167..08ac448f8 100644
--- a/pipeline/tests/export-wechat-read-paths.test.ts
+++ b/pipeline/tests/export-wechat-read-paths.test.ts
@@ -103,8 +103,17 @@ describe('exportGame (wechat) — every asset resolves to a file the package car
expect(keys).toContain(MAT);
expect(keys).toContain(PREFAB);
const pcfg = JSON.parse(readFileSync(path.join(out, 'project.config.json'), 'utf8'));
- expect(pcfg.packOptions.include).toContainEqual({ type: 'suffix', value: '.esprefab' });
- expect(pcfg.packOptions.include).toContainEqual({ type: 'suffix', value: '.esmaterial' });
+ // Every suffix the package actually holds is declared, whatever it turned out
+ // to be: an asset whose own suffix the packer refuses ships restaged as
+ // `.bin`, and THAT is what has to be carried.
+ const held = new Set(Object.values(manifest.groups.main.assets)
+ .map((a) => path.extname(a.path).toLowerCase())
+ .filter((e) => e !== '' && e !== '.js' && e !== '.json'));
+ expect(held.size).toBeGreaterThan(0);
+ for (const ext of held) {
+ expect(pcfg.packOptions.include, `the packer is not told to carry ${ext}`)
+ .toContainEqual({ type: 'suffix', value: ext });
+ }
// Every spelling the game can hold: the uuid a scene carries (the runtime
// strips the `@uuid:` before the lookup) and the project-relative path code
diff --git a/pipeline/tests/export-wechat.test.ts b/pipeline/tests/export-wechat.test.ts
index eabdd0e29..dd997e0d5 100644
--- a/pipeline/tests/export-wechat.test.ts
+++ b/pipeline/tests/export-wechat.test.ts
@@ -11,7 +11,7 @@
*/
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { runtimeConfigOf } from '../src/project/runtimeConfig';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, readdirSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { exportGame } from '../src/export/exportGame';
@@ -21,6 +21,7 @@ let out: string;
const TEX = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
const SCN = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
const SUBTEX = 'cccccccc-cccc-cccc-cccc-cccccccccccc';
+const LOC = 'dddddddd-dddd-dddd-dddd-dddddddddddd';
const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
beforeAll(() => {
@@ -34,6 +35,12 @@ beforeAll(() => {
JSON.stringify({ version: '1.0', name: 'Main', entities: [{ id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] }] }),
);
writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
+ // An authored format whose suffix is NOT on WeChat's upload whitelist. Without
+ // one here, a gate about that whitelist has nothing to be wrong about — which
+ // is how a package full of them built clean for as long as it did.
+ mkdirSync(path.join(root, 'assets', 'i18n'), { recursive: true });
+ writeFileSync(path.join(root, 'assets', 'i18n', 'en.eslocale'), JSON.stringify({ hello: 'hi' }));
+ writeFileSync(path.join(root, 'assets', 'i18n', 'en.eslocale.meta'), meta(LOC, 'locale'));
// A lazy-subpackage asset (folder convention): NOT referenced by the entry
// scene, so it exercises force-include + grouping.
mkdirSync(path.join(root, 'subpackages', 'level2'), { recursive: true });
@@ -633,6 +640,47 @@ describe('exportGame (wechat)', () => {
expect(existsSync(path.join(o, 'subpackages', 'engine'))).toBe(false);
expect(readFileSync(path.join(o, 'game.js'), 'utf8')).not.toContain('loadSubpackage');
}, 60_000);
+ // WeChat publishes the suffixes its packer will UPLOAD. A file outside that
+ // list is readable in devtools and refused at upload — so a package can build
+ // clean, run in the simulator and fail at the one step nobody automates.
+ it('stages nothing the packer would refuse to upload', async () => {
+ const o = path.join(root, 'dist-wx-suffixes');
+ const res = await exportGame({
+ root,
+ entryScene: 'scenes/main.esscene',
+ hostsDir: 'unused-for-wechat',
+ scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(root, '_sdk'),
+ wasmDir: path.join(root, '_wxwasm'),
+ outDir: o,
+ platform: 'wechat',
+ wechatAppid: 'wxTEST0123456789',
+ runtime: runtimeConfigOf({ designResolution: { width: 1280, height: 720 } }),
+ });
+ expect(res.ok).toBe(true);
+
+ // developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html
+ const whitelist = new Set(`png jpg jpeg gif svg js json cer obj dae fbx mtl stl 3ds mp3 pvr
+ wav plist ttf fnt gz ccz m4a mp4 bmp atlas swf ani part proto bin sk mipmaps txt zip tt map
+ ogg silk dbbin dbmv etc lmat lm ls lh lani lav lsani ltc aac astc br csv cur dat dds glb
+ gltf ico ktx lmani lml pkm prefab scene wasm xml`.split(/\s+/).filter(Boolean));
+
+ const walk = (dir: string, out: string[] = []): string[] => {
+ for (const e of readdirSync(dir)) {
+ const p = path.join(dir, e);
+ if (statSync(p).isDirectory()) walk(p, out);
+ else out.push(p);
+ }
+ return out;
+ };
+ const refused = walk(o)
+ .map((f) => path.relative(o, f))
+ .filter((f) => {
+ const ext = path.extname(f).slice(1).toLowerCase();
+ return ext !== '' && !whitelist.has(ext);
+ });
+ expect(refused, `these would be refused at upload: ${refused.join(', ')}`).toEqual([]);
+ }, 60_000);
});
/**
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 8c8e0cecd..5c6f4ae16 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(export): a mini-game package carries only what its packer will upload':
+ { note: 'A WeChat package no longer carries files the upload would refuse.' },
+
'refactor(assets): what a restaged .bin really is, answered in one place':
{ internal: 'One reader for a packaging spelling; what resolves is unchanged.' },