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(wechat): exporter emits packOptions.include for staged custom extensions

yhhc419ede00c33
diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.ts
index b0a6fcada..099c311cd 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -93,13 +93,32 @@ function subPackagesOf(entries: CookManifest['entries']): Array<{ name: string;
return [...names].map((name) => ({ name, root: `subpackages/${name}` }));
}
-function projectConfigJson(title: string, appid: string): string {
+// Extensions WeChat's packer/fs handles without a packOptions.include entry:
+// script + config it compiles itself. Every OTHER staged extension gets an
+// include rule — WeChat denies fs reads of unlisted custom types (the .skel/
+// .atlas/.ktx2 family), and a redundant rule for a native type is harmless.
+const WECHAT_NATIVE_SUFFIXES = new Set(['.js', '.json']);
+
+/** packOptions.include suffix rules for every custom extension the cook staged. */
+function packIncludeSuffixes(entries: CookManifest['entries']): string[] {
+ const suffixes = new Set<string>();
+ for (const e of entries) {
+ const ext = path.extname(e.path).toLowerCase();
+ if (ext && !WECHAT_NATIVE_SUFFIXES.has(ext)) suffixes.add(ext);
+ }
+ return [...suffixes].sort();
+}
+
+function projectConfigJson(title: string, appid: string, includeSuffixes: string[]): string {
return JSON.stringify({
miniprogramRoot: './',
projectname: title,
appid, // set in Project Settings → Packaging → WeChat (else fill in devtools)
setting: { es6: false, minified: false },
compileType: 'game',
+ ...(includeSuffixes.length > 0
+ ? { packOptions: { include: includeSuffixes.map((value) => ({ type: 'suffix', value })) } }
+ : {}),
}, null, 2) + '\n';
}
@@ -339,7 +358,7 @@ export async function exportWeChat(opts: {
// 5. Entry + config.
await writeFile(path.join(absOut, 'game.js'), gameEntryJs(sideModules, engineGlueFile));
await writeFile(path.join(absOut, 'game.json'), gameJson(opts.orientation ?? 'portrait', subPackagesOf(cookEntries)));
- await writeFile(path.join(absOut, 'project.config.json'), projectConfigJson(title, opts.appid ?? ''));
+ await writeFile(path.join(absOut, 'project.config.json'), projectConfigJson(title, opts.appid ?? '', packIncludeSuffixes(cookEntries)));
// 6. The engine runtime + exactly the side modules the scene needs. WeChat's
// main package has a 4MB budget — unneeded side modules must not ride along.
diff --git a/desktop/tests/export-wechat.test.ts b/desktop/tests/export-wechat.test.ts
index c42bf2ba5..47eda3547 100644
--- a/desktop/tests/export-wechat.test.ts
+++ b/desktop/tests/export-wechat.test.ts
@@ -189,6 +189,10 @@ describe('exportGame (wechat)', () => {
const entry = readFileSync(path.join(outSpine, 'game.js'), 'utf8');
expect(entry).toContain("\"spine:4.2\": asFactory(require('./wasm/spine42.js'))");
expect(existsSync(path.join(outSpine, 'wasm', 'spine42.wasm'))).toBe(true);
+ const spcfg = JSON.parse(readFileSync(path.join(outSpine, 'project.config.json'), 'utf8'));
+ expect(spcfg.packOptions.include).toContainEqual({ type: 'suffix', value: '.esscene' });
+ // Native types stay out of the include list — it exists for the custom ones.
+ expect(spcfg.packOptions.include).not.toContainEqual({ type: 'suffix', value: '.json' });
// The manifest keeps the real addressable type, not a 'binary' downgrade.
const manifest = JSON.parse(readFileSync(path.join(outSpine, 'asset-manifest.json'), 'utf8'));
expect(manifest.groups.main.assets[SPINE].type).toBe('spine');
@@ -241,6 +245,10 @@ describe('exportGame (wechat)', () => {
expect(res.ok).toBe(true);
expect(readFileSync(path.join(outKtx, 'game.js'), 'utf8')).toContain("\"basis\": asFactory(require('./wasm/basis.js'))");
expect(existsSync(path.join(outKtx, 'wasm', 'basis.wasm'))).toBe(true);
+ // WeChat denies fs reads of unlisted custom extensions — the staged .ktx2
+ // must ride into packOptions.include.
+ const pcfg = JSON.parse(readFileSync(path.join(outKtx, 'project.config.json'), 'utf8'));
+ expect(pcfg.packOptions.include).toContainEqual({ type: 'suffix', value: '.ktx2' });
}, 60_000);
it('a .ktx2 texture without a wechat basis build fails the export', async () => {
diff --git a/sdk/src/assetTypes.ts b/sdk/src/assetTypes.ts
index 431a8596b..5e5e6a34f 100644
--- a/sdk/src/assetTypes.ts
+++ b/sdk/src/assetTypes.ts
@@ -29,7 +29,9 @@ const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [
// GPU-compressed texture container (Basis/KTX2). Decoded straight to a
// compressed GPU format at runtime; large, so it stays out of the WeChat
// main package (remote CDN, content-addressed).
- { extensions: ['ktx2'], contentType: 'binary', editorType: 'texture', addressableType: 'texture', wechatPackInclude: false, hasTransitiveDeps: false },
+ // wechatPackInclude: WeChat's fs denies package reads of unlisted custom
+ // extensions — KTX2 textures are fs-read (transcoded), not image-decoded.
+ { extensions: ['ktx2'], contentType: 'binary', editorType: 'texture', addressableType: 'texture', wechatPackInclude: true, hasTransitiveDeps: false },
{ extensions: ['mp3', 'wav', 'ogg', 'aac', 'flac', 'webm'], contentType: 'audio', editorType: 'audio', addressableType: 'audio', wechatPackInclude: false, hasTransitiveDeps: false },
{ extensions: ['esmaterial'], contentType: 'json', editorType: 'material', addressableType: 'material', wechatPackInclude: true, hasTransitiveDeps: true },
{ extensions: ['esshader'], contentType: 'text', editorType: 'shader', addressableType: null, wechatPackInclude: false, hasTransitiveDeps: false },
diff --git a/sdk/src/platform/wechat/fs.ts b/sdk/src/platform/wechat/fs.ts
index 224b59d79..8bf940634 100644
--- a/sdk/src/platform/wechat/fs.ts
+++ b/sdk/src/platform/wechat/fs.ts
@@ -51,12 +51,20 @@ function formatReadError(path: string, errMsg: string): string {
export function wxReadFileSync(path: string): ArrayBuffer {
const fs = getFileSystemManager();
- return fs.readFileSync(path) as ArrayBuffer;
+ try {
+ return fs.readFileSync(path) as ArrayBuffer;
+ } catch (e) {
+ throw new Error(formatReadError(path, e instanceof Error ? e.message : String(e)));
+ }
}
export function wxReadTextFileSync(path: string, encoding: 'utf8' | 'utf-8' = 'utf-8'): string {
const fs = getFileSystemManager();
- return fs.readFileSync(path, encoding) as string;
+ try {
+ return fs.readFileSync(path, encoding) as string;
+ } catch (e) {
+ throw new Error(formatReadError(path, e instanceof Error ? e.message : String(e)));
+ }
}
export function wxReadFile(path: string): Promise<ArrayBuffer> {
diff --git a/sdk/tests/asset-types-ktx2.test.ts b/sdk/tests/asset-types-ktx2.test.ts
index e2b7350ff..1025511b5 100644
--- a/sdk/tests/asset-types-ktx2.test.ts
+++ b/sdk/tests/asset-types-ktx2.test.ts
@@ -10,8 +10,9 @@ describe('.ktx2 asset type registration', () => {
expect(entry?.contentType).toBe('binary');
expect(entry?.editorType).toBe('texture');
expect(entry?.addressableType).toBe('texture');
- // large compressed textures stay out of the WeChat main package
- expect(entry?.wechatPackInclude).toBe(false);
+ // fs-read on WeChat (basis transcode), so the packer must include the
+ // extension — an unlisted custom type is denied at readFileSync.
+ expect(entry?.wechatPackInclude).toBe(true);
});
it('resolves texture types and the KTX2 mime', () => {
diff --git a/sdk/tests/assetTypes.test.ts b/sdk/tests/assetTypes.test.ts
index 07749278e..786c96f6d 100644
--- a/sdk/tests/assetTypes.test.ts
+++ b/sdk/tests/assetTypes.test.ts
@@ -147,6 +147,7 @@ describe('getCustomExtensions', () => {
expect(exts).toContain('.esmaterial');
expect(exts).toContain('.esprefab');
expect(exts).toContain('.esanim');
+ expect(exts).toContain('.ktx2'); // fs-read on WeChat (basis transcode), not image-decoded
});
it('should not include non-packable extensions', () => {