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 mini-game package carries only what its packer will upload
esengine7c02e7de8cd1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 notexture, no environment and no complaint anywhere, which looks exactly like a scene thatdiff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.tsindex 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.tsindex 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.tsindex 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.tsindex 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 carexpect(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 codediff --git a/pipeline/tests/export-wechat.test.ts b/pipeline/tests/export-wechat.test.tsindex 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.mjsindex 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.' },