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): the package installs its platform by calling for it

esengined0db1d2781ee
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 that
a vendor's packer will not upload are shipped with a `.bin` suffix, and the rename walked
the manifest one asset at a time — so the seven sprites packed into one atlas page tried to
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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, rmSync
import { 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.ts
index 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, rmSync
import { 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.ts
new file mode 100644
index 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.ts
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.' },
};