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): only lazy delivery is a WeChat 分包

esengine1f901d6620c2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8e830f4d3..ee8fc6e16 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,13 @@ published separately; it ships inside the editor.
### Fixed
+- **A folder that is no longer a 分包 stops being declared as one.** A group is a
+ name plus a delivery, and the name outlives the delivery: a folder marked
+ *always include* keeps its group after its mode goes back to local. The WeChat
+ export read the name and declared `subpackages/<name>` for it, so a project with
+ no subpackages at all could still fail to open with `["subPackages"][0]["root"]
+ 不存在`. Only lazy delivery is a 分包 now.
+
- **Play always reaches a stage you can read.** Pressing 运行 could sit at "启动中"
with no error, no game, and nothing to do but restart the editor (#57). Three
independent causes, each enough on its own: two of the boot's three legs had no
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index e83f68c3c..aeec486ab 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -82,9 +82,9 @@ function stripUuidRefs(v: unknown): unknown {
/**
* The vendor subPackage roots this package actually carries, read off the STAGED
- * paths: a root the package lacks fails the whole game at load ("root 不存在"),
- * so the declaration comes from the files rather than from the group names beside
- * them. Remote (CDN / hot-update) groups are not 分包 and are skipped.
+ * paths: a root the package lacks fails the whole game at load ("root 不存在").
+ * Only LAZY delivery is a 分包 — a group's name outlives its delivery, so a
+ * project that once had one still carries the name of one.
*/
function subPackagesOf(
entries: CookManifest['entries'],
@@ -93,7 +93,7 @@ function subPackagesOf(
const carried = new Set<string>();
const strays: string[] = [];
for (const e of entries) {
- if (!e.group || e.group === 'main' || e.groupMode === 'remote') continue;
+ if (!e.group || e.group === 'main' || e.groupMode !== 'lazy') continue;
const root = `${subpackageDir}/${e.group}`;
if (e.path === root || e.path.startsWith(`${root}/`)) carried.add(e.group);
else strays.push(`${e.sourcePath} is in 分包 '${e.group}' but ships at ${e.path}, outside ${root}/`);
diff --git a/pipeline/tests/export-wechat-audio-src.test.ts b/pipeline/tests/export-wechat-audio-src.test.ts
new file mode 100644
index 000000000..9cb564a64
--- /dev/null
+++ b/pipeline/tests/export-wechat-audio-src.test.ts
@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A mini-game player is handed a SOURCE, not a cache key, and the cook
+ * renamed the file: `tap.wav` ships as an MP3. The asset loader now asks
+ * the ref resolver for that name instead of fetching bytes it cannot use,
+ * so this holds the join — a real cook, the manifest the export writes,
+ * and the runtime's own resolver — rather than a stub on either side.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { exportGame } from '../src/export/exportGame';
+import { runtimeConfigOf } from '../src/project/runtimeConfig';
+import { ManifestModel } from '../../sdk/src/asset/AddressableManifest';
+import { extractUuid } from '../../sdk/src/asset/AssetRegistry';
+import type { AddressableManifest } from '../../sdk/src/asset/AddressableManifest';
+
+let root: string;
+let out: string;
+const CLIP = 'dddddddd-dddd-dddd-dddd-dddddddddddd';
+const SCN = 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee';
+const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
+
+/** A real RIFF/WAVE the LAME encoder will actually take: 16-bit mono, long
+ * enough that the MP3 comes out smaller (the cook keeps the smaller file). */
+function wav(frames = 44100): Uint8Array {
+ const bytes = frames * 2;
+ const buf = new ArrayBuffer(44 + bytes);
+ const v = new DataView(buf);
+ const tag = (o: number, s: string) => { for (let i = 0; i < 4; i++) v.setUint8(o + i, s.charCodeAt(i)); };
+ tag(0, 'RIFF'); v.setUint32(4, 36 + bytes, true); tag(8, 'WAVE');
+ tag(12, 'fmt '); v.setUint32(16, 16, true);
+ v.setUint16(20, 1, true); v.setUint16(22, 1, true);
+ v.setUint32(24, 44100, true); v.setUint32(28, 88200, true);
+ v.setUint16(32, 2, true); v.setUint16(34, 16, true);
+ tag(36, 'data'); v.setUint32(40, bytes, true);
+ for (let f = 0; f < frames; f++) v.setInt16(44 + f * 2, Math.round(Math.sin(f / 20) * 12000), true);
+ return new Uint8Array(buf);
+}
+
+beforeAll(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-wechat-audio-'));
+ mkdirSync(path.join(root, 'assets', 'audio'), { recursive: true });
+ writeFileSync(path.join(root, 'assets', 'audio', 'tap.wav'), wav());
+ writeFileSync(path.join(root, 'assets', 'audio', 'tap.wav.meta'), meta(CLIP, 'audio'));
+ mkdirSync(path.join(root, 'scenes'), { recursive: true });
+ // An AudioSource's `clip` is an asset field, so the scene REACHES the clip and
+ // the asset system is what loads it — the door the reported silence came in by.
+ writeFileSync(
+ path.join(root, 'scenes', 'main.esscene'),
+ JSON.stringify({
+ version: '1.0', name: 'Main',
+ entities: [{ id: 0, components: [{ type: 'AudioSource', data: { clip: `@uuid:${CLIP}`, playOnAwake: true } }] }],
+ }),
+ );
+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
+ mkdirSync(path.join(root, '_sdk'), { recursive: true });
+ writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), 'export function initWeChatRuntime(){return Promise.resolve();}\n');
+ mkdirSync(path.join(root, '_wxwasm'), { recursive: true });
+ writeFileSync(path.join(root, '_wxwasm', 'esengine.js'), 'module.exports = () => Promise.resolve({});');
+ writeFileSync(path.join(root, '_wxwasm', 'esengine.wasm'), 'wasmbytes');
+ out = path.join(root, 'dist-wechat');
+}, 60_000);
+
+afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));
+
+describe('the source a cooked mini-game hands its audio player', () => {
+ it('is the file the package carries, resolved from the authored path', async () => {
+ const res = await exportGame({
+ root,
+ entryScene: 'scenes/main.esscene',
+ gameHostEntry: 'unused-for-wechat',
+ sdkDistDir: path.join(root, '_sdk'),
+ wasmDir: path.join(root, '_wxwasm'),
+ outDir: out,
+ title: 'Audio',
+ platform: 'wechat',
+ wechatAppid: 'wxTEST0123456789',
+ orientation: 'landscape',
+ compressAudio: true,
+ runtime: runtimeConfigOf({ designResolution: { width: 1280, height: 720 } }),
+ });
+ expect(res.ok).toBe(true);
+
+ // The cook renamed it, so the authored name is not what ships.
+ const staged = readdirSync(path.join(out, 'assets', 'audio'));
+ expect(staged).toContain('tap.mp3');
+ expect(staged).not.toContain('tap.wav');
+
+ // The runtime's OWN resolver, over the manifest the export wrote: this is
+ // the channel `Audio.preload` asks, and a miss here is silence on device.
+ // Spelled exactly as packagedRuntime spells it, so the two cannot disagree.
+ const manifest = ManifestModel.fromJson(
+ JSON.parse(readFileSync(path.join(out, 'asset-manifest.json'), 'utf8')) as AddressableManifest,
+ );
+ const resolve = (ref: string): string => manifest.resolvePath(extractUuid(ref) ?? ref);
+ const src = resolve('assets/audio/tap.wav');
+ expect(src).toBe('assets/audio/tap.mp3');
+ expect(existsSync(path.join(out, src))).toBe(true);
+
+ // And by uuid, which is how the scene names it.
+ expect(resolve(`@uuid:${CLIP}`)).toBe('assets/audio/tap.mp3');
+ }, 120_000);
+});
diff --git a/pipeline/tests/export-wechat-subpackage.test.ts b/pipeline/tests/export-wechat-subpackage.test.ts
index 8c6febfd7..f7fe5f8db 100644
--- a/pipeline/tests/export-wechat-subpackage.test.ts
+++ b/pipeline/tests/export-wechat-subpackage.test.ts
@@ -85,6 +85,61 @@ describe('WeChat 分包 declared through asset-groups.json', () => {
}
}, 120_000);
+ it('is not fooled by a named group that ships in the main package', async () => {
+ // `alwaysInclude` keeps a folder's group alive after its delivery goes back
+ // to local, so a project that ONCE had a 分包 still carries the name. Only
+ // lazy delivery is a 分包; a local group is main-package content with a label.
+ const root2 = mkdtempSync(path.join(tmpdir(), 'estella-wechat-localgroup-'));
+ try {
+ mkdirSync(path.join(root2, 'assets', 'level2'), { recursive: true });
+ writeFileSync(path.join(root2, 'assets', 'level2', 'extra.png'), 'PNG2DATA');
+ writeFileSync(path.join(root2, 'assets', 'level2', 'extra.png.meta'), meta(LAZY, 'texture'));
+ mkdirSync(path.join(root2, '.esengine'), { recursive: true });
+ writeFileSync(
+ path.join(root2, '.esengine', 'asset-groups.json'),
+ JSON.stringify({
+ version: '1.0',
+ groups: { level2: { folder: 'assets/level2', mode: 'local', alwaysInclude: true } },
+ }),
+ );
+ mkdirSync(path.join(root2, 'scenes'), { recursive: true });
+ writeFileSync(
+ path.join(root2, 'scenes', 'main.esscene'),
+ JSON.stringify({ version: '1.0', name: 'Main', entities: [] }),
+ );
+ writeFileSync(path.join(root2, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
+ mkdirSync(path.join(root2, '_sdk'), { recursive: true });
+ writeFileSync(path.join(root2, '_sdk', 'index.wechat.js'), 'export function initWeChatRuntime(){return Promise.resolve();}\n');
+ mkdirSync(path.join(root2, '_wxwasm'), { recursive: true });
+ writeFileSync(path.join(root2, '_wxwasm', 'esengine.js'), 'module.exports = () => Promise.resolve({});');
+ writeFileSync(path.join(root2, '_wxwasm', 'esengine.wasm'), 'wasmbytes');
+ const out2 = path.join(root2, 'dist-wechat');
+
+ const res = await exportGame({
+ root: root2,
+ entryScene: 'scenes/main.esscene',
+ gameHostEntry: 'unused-for-wechat',
+ sdkDistDir: path.join(root2, '_sdk'),
+ wasmDir: path.join(root2, '_wxwasm'),
+ outDir: out2,
+ title: 'Local Group',
+ platform: 'wechat',
+ wechatAppid: 'wxTEST0123456789',
+ orientation: 'landscape',
+ runtime: runtimeConfigOf({ designResolution: { width: 1280, height: 720 } }),
+ });
+ expect(res.ok).toBe(true);
+
+ const gjson = JSON.parse(readFileSync(path.join(out2, 'game.json'), 'utf8'));
+ expect(gjson.subPackages).toBeUndefined();
+ // Nor a warning: nothing about this project is a 分包 that went wrong.
+ expect(res.warnings.filter((w) => w.includes('分包'))).toEqual([]);
+ expect(existsSync(path.join(out2, 'assets', 'level2', 'extra.png'))).toBe(true);
+ } finally {
+ rmSync(root2, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ }
+ }, 120_000);
+
it('never declares a root nothing was staged under', async () => {
// A scene keeps its logical path in every layout, so a group made of one
// cannot be delivered — the declaration must follow the files, not the group.