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(wechat): the package installs its platform by calling for it
esengined0db1d2781ee
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3e65e6341..6f53787ed 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -23,6 +23,12 @@ published separately; it ships inside the editor.### Fixed+- **A WeChat mini-game boots again.** Its package had no platform in it: the SDK entry+ installed one as a module side effect, and the lean entry added for smaller packages is+ pure re-exports — so the install sat in a shared chunk the bundler was free to drop, and+ every WeChat package threw `[ESEngine] Platform not initialized` on the first frame. The+ generated entry now calls for the platform the way the Douyin one already did.+- **A mini-game export no longer fails on a project whose sprites are atlased.** Names thata vendor's packer will not upload are shipped with a `.bin` suffix, and the rename walkedthe manifest one asset at a time — so the seven sprites packed into one atlas page tried todiff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.tsindex 6480c5f6b..59c1231c0 100644--- a/pipeline/src/export/exportMiniGame.ts+++ b/pipeline/src/export/exportMiniGame.ts@@ -475,10 +475,11 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {const entrySrc =installs.map((m) => `import ${JSON.stringify(m)};\n`).join('') +- `import { ${profile.runtimeInit}${installsPlatform ? ', installMiniGamePlatform' : ''}${themeColors ? ', parseThemeOverrides' : ''} } from 'esengine';\n` ++ `import { ${profile.runtimeInit}${profile.platformInit ? `, ${profile.platformInit}` : ''}${installsPlatform ? ', installMiniGamePlatform' : ''}${themeColors ? ', parseThemeOverrides' : ''} } from 'esengine';\n` +(installsPlatform ? `import __platformProfile from ${JSON.stringify(platformProfileModule)};\n` : '') +(scriptsAbs && existsSync(scriptsAbs) ? `import ${JSON.stringify(scriptsAbs)};\n` : '') +`export function boot(engineFactory, sideModuleFactories) {\n` ++ (profile.platformInit ? ` ${profile.platformInit}();\n` : '') +(installsPlatform ? ` installMiniGamePlatform(__platformProfile);\n` : '') +` return ${profile.runtimeInit}({ engineFactory, engineWasmPath: ${JSON.stringify(engineWasmPath)}, sideModuleFactories, sceneNames: ${JSON.stringify(scenes.map((s) => s.name))}, firstScene: ${JSON.stringify(sceneName)}${runtimeArgs}${projectDeclarations.length > 0 ? `, sideModules: ${JSON.stringify(projectDeclarations)}` : ''}${aotArg} });\n` +`}\n`;diff --git a/pipeline/src/export/miniGameExportProfile.ts b/pipeline/src/export/miniGameExportProfile.tsindex eaa06c88a..19da4b730 100644--- a/pipeline/src/export/miniGameExportProfile.ts+++ b/pipeline/src/export/miniGameExportProfile.ts@@ -125,6 +125,13 @@ export interface MiniGameExportProfile {readonly sdkLeanEntryFile?: string;/** Runtime bootstrap fn imported from 'esengine' in the generated boot. */readonly runtimeInit: string;+ /**+ * An SDK export the generated entry CALLS before `runtimeInit` to install+ * the platform. A vendor whose SDK entry installs it as a module side+ * effect has no answer here that survives a bundler: the WeChat package+ * booted to "Platform not initialized" for exactly that reason.+ */+ readonly platformInit?: string;/** Engine glue filenames to look for in wasmDir, in preference order. */readonly engineGlueCandidates: readonly string[];/** esbuild target for the game bundle + glue down-level (real-device syntax floor). */@@ -224,6 +231,7 @@ export const wechatExportProfile: MiniGameExportProfile = {sdkEntryFile: 'index.wechat.js',sdkLeanEntryFile: 'index.wechat.lean.js',runtimeInit: 'initWeChatRuntime',+ platformInit: 'initWeChatPlatform',// Require by the ACTUAL name in the wasm dir: the -t wechat build emits// esengine.wxgame.js; a web-aligned build, esengine.js.engineGlueCandidates: ['esengine.wxgame.js', 'esengine.js'],diff --git a/pipeline/tests/export-compiled-systems.test.ts b/pipeline/tests/export-compiled-systems.test.tsindex 2d320967d..edf0156f2 100644--- a/pipeline/tests/export-compiled-systems.test.ts+++ b/pipeline/tests/export-compiled-systems.test.ts@@ -21,6 +21,8 @@ import type { PackagedGameConfig } from 'esengine';import { exportGame } from '../src/export/exportGame';import { resolveEmcc } from '../src/bundle/emccPath';import { writeFakeSdkDist } from './fixtures/fakeSdkDist';+import { miniGameSdkStub } from './fixtures/miniGameSdkStub';+import { wechatExportProfile } from '../src/export/miniGameExportProfile';const HERE = path.dirname(fileURLToPath(import.meta.url));const HOSTS = path.join(HERE, '..', 'src', 'runtime');@@ -57,7 +59,7 @@ function miniGameStubs(root: string): void {// The names the fixture project imports: a stub entry missing one fails the// bundle, and the bundle is what carries the boot call under test.writeFileSync(path.join(root, '_sdk', 'index.wechat.js'),- 'export function initWeChatRuntime(){return Promise.resolve();}\n'+ miniGameSdkStub(wechatExportProfile)+ 'export const defineComponent = () => {};\nexport const defineSystem = () => {};\n'+ 'export const Query = () => {};\nexport const Mut = () => {};\n');writeFileSync(path.join(root, '_wasm', 'esengine.wxgame.js'), 'module.exports = () => Promise.resolve({});');diff --git a/pipeline/tests/export-wechat-audio-src.test.ts b/pipeline/tests/export-wechat-audio-src.test.tsindex dfd7d1713..a13d28bf9 100644--- a/pipeline/tests/export-wechat-audio-src.test.ts+++ b/pipeline/tests/export-wechat-audio-src.test.ts@@ -16,6 +16,8 @@ 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';+import { miniGameSdkStub } from './fixtures/miniGameSdkStub';+import { wechatExportProfile } from '../src/export/miniGameExportProfile';let root: string;let out: string;@@ -57,7 +59,7 @@ beforeAll(() => {);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');+ writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile));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');diff --git a/pipeline/tests/export-wechat-read-paths.test.ts b/pipeline/tests/export-wechat-read-paths.test.tsindex 08ac448f8..dcf2ce0bc 100644--- a/pipeline/tests/export-wechat-read-paths.test.ts+++ b/pipeline/tests/export-wechat-read-paths.test.ts@@ -24,6 +24,8 @@ import { tmpdir } from 'node:os';import path from 'node:path';import { exportGame } from '../src/export/exportGame';import { ManifestModel, type AddressableManifest } from '../../sdk/src/asset/AddressableManifest';+import { miniGameSdkStub } from './fixtures/miniGameSdkStub';+import { wechatExportProfile } from '../src/export/miniGameExportProfile';const TEX = 'dddddddd-dddd-dddd-dddd-dddddddddddd';const MAT = 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee';@@ -72,7 +74,7 @@ function scaffold(): { root: string; out: string } {mkdirSync(path.join(root, 'src'), { recursive: true });writeFileSync(path.join(root, 'src', 'main.ts'), "import { defineComponent } from 'esengine';\ndefineComponent('Marker', { n: 1 });\n");mkdirSync(path.join(root, '_sdk'), { recursive: true });- writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), 'export function initWeChatRuntime(){return Promise.resolve();}\nexport function defineComponent(){}\n');+ writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile, ['defineComponent']));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');diff --git a/pipeline/tests/export-wechat-subpackage.test.ts b/pipeline/tests/export-wechat-subpackage.test.tsindex a2c50d0e4..f03a7ff97 100644--- a/pipeline/tests/export-wechat-subpackage.test.ts+++ b/pipeline/tests/export-wechat-subpackage.test.ts@@ -15,6 +15,8 @@ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSyncimport { tmpdir } from 'node:os';import path from 'node:path';import { exportGame } from '../src/export/exportGame';+import { miniGameSdkStub } from './fixtures/miniGameSdkStub';+import { wechatExportProfile } from '../src/export/miniGameExportProfile';let root: string;let out: string;@@ -46,7 +48,7 @@ beforeAll(() => {mkdirSync(path.join(root, 'src'), { recursive: true });writeFileSync(path.join(root, 'src', 'main.ts'), `import { defineComponent } from 'esengine';\ndefineComponent('SpawnMarker', { rate: 1 });\n`);mkdirSync(path.join(root, '_sdk'), { recursive: true });- writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), `export function initWeChatRuntime(){return Promise.resolve();}\nexport function defineComponent(){}\n`);+ writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile, ['defineComponent']));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');@@ -113,7 +115,7 @@ describe('WeChat 分包 declared through asset-groups.json', () => {);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');+ writeFileSync(path.join(root2, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile));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');@@ -169,7 +171,7 @@ describe('WeChat 分包 declared through asset-groups.json', () => {}),);mkdirSync(path.join(root2, '_sdk'), { recursive: true });- writeFileSync(path.join(root2, '_sdk', 'index.wechat.js'), 'export function initWeChatRuntime(){return Promise.resolve();}\n');+ writeFileSync(path.join(root2, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile));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');diff --git a/pipeline/tests/export-wechat.test.ts b/pipeline/tests/export-wechat.test.tsindex 5e03b79a1..de18c4eac 100644--- a/pipeline/tests/export-wechat.test.ts+++ b/pipeline/tests/export-wechat.test.ts@@ -15,6 +15,8 @@ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSyncimport { tmpdir } from 'node:os';import path from 'node:path';import { exportGame } from '../src/export/exportGame';+import { miniGameSdkStub } from './fixtures/miniGameSdkStub';+import { wechatExportProfile } from '../src/export/miniGameExportProfile';let root: string;let out: string;@@ -50,7 +52,7 @@ beforeAll(() => {writeFileSync(path.join(root, 'src', 'main.ts'), `import { defineComponent } from 'esengine';\ndefineComponent('SpawnMarker', { rate: 1 });\n`);// Stub SDK dist (the bundle aliases `esengine` → <sdkDir>/index.wechat.js) + stub -t wechat runtime.mkdirSync(path.join(root, '_sdk'), { recursive: true });- writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), `export function initWeChatRuntime(){return Promise.resolve();}\nexport function defineComponent(){}\n`);+ writeFileSync(path.join(root, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile, ['defineComponent']));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');@@ -706,7 +708,7 @@ describe('exportGame (wechat) — open data context', () => {);writeFileSync(path.join(dir, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));mkdirSync(path.join(dir, '_sdk'), { recursive: true });- writeFileSync(path.join(dir, '_sdk', 'index.wechat.js'), 'export function initWeChatRuntime(){return Promise.resolve();}\n');+ writeFileSync(path.join(dir, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile));mkdirSync(path.join(dir, '_wxwasm'), { recursive: true });writeFileSync(path.join(dir, '_wxwasm', 'esengine.js'), 'module.exports = () => Promise.resolve({});');writeFileSync(path.join(dir, '_wxwasm', 'esengine.wasm'), 'wasmbytes');@@ -815,7 +817,7 @@ describe('two assets, one staged file', () => {}));writeFileSync(path.join(dir, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));mkdirSync(path.join(dir, '_sdk'), { recursive: true });- writeFileSync(path.join(dir, '_sdk', 'index.wechat.js'), 'export function initWeChatRuntime(){return Promise.resolve();}\n');+ writeFileSync(path.join(dir, '_sdk', 'index.wechat.js'), miniGameSdkStub(wechatExportProfile));mkdirSync(path.join(dir, '_wxwasm'), { recursive: true });writeFileSync(path.join(dir, '_wxwasm', 'esengine.js'), 'module.exports = () => Promise.resolve({});');writeFileSync(path.join(dir, '_wxwasm', 'esengine.wasm'), 'wasmbytes');diff --git a/pipeline/tests/fixtures/miniGameSdkStub.ts b/pipeline/tests/fixtures/miniGameSdkStub.tsnew file mode 100644index 000000000..8720c840f--- /dev/null+++ b/pipeline/tests/fixtures/miniGameSdkStub.ts@@ -0,0 +1,20 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A stub SDK exporting what a generated mini-game entry imports.+ *+ * The entry's import list comes from the vendor profile, so this derives from+ * the same profile: eight tests had each written the stub by hand, and adding+ * `platformInit` to the profile broke every one of them at once — which is the+ * fixture telling the truth, but eight times.+ */+import type { MiniGameExportProfile } from '../../src/export/miniGameExportProfile';++/**+ * Source for `<sdkDir>/<entry>.js`. `extra` names anything a particular test's+ * project imports beyond the entry's own list (`defineComponent`, say).+ */+export function miniGameSdkStub(profile: MiniGameExportProfile, extra: readonly string[] = []): string {+ const named = [profile.runtimeInit, profile.platformInit, ...extra].filter((n): n is string => !!n);+ return `${named.map((n) => `export function ${n}(){return Promise.resolve();}`).join('\n')}\n`;+}diff --git a/sdk/src/index.wechat.base.ts b/sdk/src/index.wechat.base.tsindex d7138688f..74fb16470 100644--- a/sdk/src/index.wechat.base.ts+++ b/sdk/src/index.wechat.base.ts@@ -41,3 +41,8 @@ export {// The host as data: spread it to keep everything but the one thing you replace.export { wechatProfile } from './platform/wechat';++// A package installs the platform by CALLING this: the call above is a module+// side effect, and a bundler dropped it — a lean-entry WeChat package booted to+// "Platform not initialized". Idempotent.+export { initWeChatPlatform } from './platform/wechat';diff --git a/tools/check-minigame-platform-install.mjs b/tools/check-minigame-platform-install.mjsnew file mode 100644index 000000000..887d76755--- /dev/null+++ b/tools/check-minigame-platform-install.mjs@@ -0,0 +1,54 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A mini-game profile says how its platform gets installed.+ *+ * The generated entry is the only thing that runs before the game does, so the+ * platform has to be installed from there: `platformInit` names a function it+ * calls, or `runtimeProfileHost`/`runtimeProfileModule` names a profile it+ * hands to `installMiniGamePlatform`.+ *+ * WeChat named neither, and relied on `index.wechat.base` doing it as a module+ * side effect. Then the lean entry arrived — pure re-exports, with the call now+ * in a shared chunk that `sideEffects` does not list — and every WeChat package+ * booted to "[ESEngine] Platform not initialized". It built clean, it passed+ * every test, and only a device said so.+ *+ * node tools/check-minigame-platform-install.mjs+ */+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const FILE = 'pipeline/src/export/miniGameExportProfile.ts';++const src = readFileSync(path.join(ROOT, FILE), 'utf8');+const profiles = [...src.matchAll(/export const (\w+)ExportProfile: MiniGameExportProfile = \{([\s\S]*?)\n\};/g)];++if (profiles.length === 0) {+ console.error(`check-minigame-platform-install: no profiles in ${FILE} — they moved.`);+ process.exit(1);+}++/** Any one of these makes the install explicit; none of them leaves it to chance. */+const DOORS = ['platformInit', 'runtimeProfileHost', 'runtimeProfileModule'];++const problems = [];+const answered = [];+for (const [, vendor, body] of profiles) {+ const named = DOORS.filter((d) => new RegExp(`^\\s{4}${d}:`, 'm').test(body));+ if (named.length === 0) {+ problems.push(`${vendor} names none of ${DOORS.join(' / ')} — its package would rely on an SDK `+ + 'entry installing the platform as a module side effect, which a bundler may drop');+ } else answered.push(`${vendor}: ${named.join(' + ')}`);+}++if (problems.length > 0) {+ for (const p of problems) console.error(` ${FILE}: ${p}`);+ console.error(`check-minigame-platform-install: ${problems.length} profile(s) leave the platform to a side effect.`);+ process.exit(1);+}++console.log(`check-minigame-platform-install: ${profiles.length} profile(s) — ${answered.join(', ')}.`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex b79497108..bea1d4ce3 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -265,6 +265,10 @@ export const GATES = [// A packaging setting the manifest parser does not read is a setting that// does nothing, in the editor and on a build server alike.{ id: 'packaging-settings', run: 'node tools/check-packaging-settings.mjs' },+ // The generated entry is the only code that runs before the game, so the+ // platform has to be installed there — not by a module side effect a bundler+ // is free to drop, which is how every WeChat package stopped booting.+ { id: 'minigame-platform-install', run: 'node tools/check-minigame-platform-install.mjs' },// A vendor claim that is wrong fails at upload or on a device, never at// build: so each one cites the vendor or says what it is assumed from.{ id: 'minigame-profile-claims', run: 'node tools/check-minigame-profile-claims.mjs' },diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex f312d79e3..197ce3cb9 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -682,4 +682,6 @@ export const NOTED = {{ internal: 'a verifier\'s reading of a boot it already watched finish' },'fix(wechat): an atlas page is one file however many sprites name it':{ note: 'A mini-game export no longer fails on a project whose sprites are atlased.' },+ 'fix(wechat): the package installs its platform by calling for it':+ { note: 'A WeChat mini-game boots again — its packages had been shipping without a platform.' },};