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): only lazy delivery is a WeChat 分包
esengine1f901d6620c2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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). Threeindependent causes, each enough on its own: two of the boot's three legs had nodiff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.tsindex 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.tsnew file mode 100644index 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.tsindex 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.