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(cli): a project platform exports headless, and an unknown id is refused

esengine744465dc4e93
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ea0dfd5b..8d2f3e822 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,9 @@ published separately; it ships inside the editor.
### Fixed
+- A mini-game on any host but WeChat no longer throws at boot. The lifecycle plugin knew one vendor by name and sent every other one down the web path, where the `document` stub every mini-game carries has no `addEventListener`; foreground/background now come from the host's own `onShow`/`onHide` for the whole family, as they already did for the native shell.
+- A mini-game that fails to start says why. The generated entry now catches a boot that rejects — a host without `onUnhandledRejection` dropped it silently, leaving the loading screen up and nothing in the log — and a failed engine instantiation names the error instead of printing `[object Object]`.
+- `estella export --platform <id>` packages a platform the project defines in `.esengine/platforms/`, as the build dialog does, and an id that is neither built in nor defined is refused instead of silently packaged as a web game.
- A mini-game host that offers only WebGL1 is told the game cannot start there, instead of booting to shader failures and a black screen — the engine renders on WebGL2.
- **Sharing, in-game purchase, the friends leaderboard and the recorder can be used at all.** They live in `estella-plugin-minigame-services`, which every doc page said to `npm install` — and it is on no registry, so the command failed and a project that imported it failed to build, in play and in every export. The editor already carried the package; now every bundle of a project's scripts resolves `estella-plugin-*` to that copy (play, web, desktop, native, WeChat, Douyin, playable, the open data context and component extraction), and the editor's script checking and the built-in agent see its types. A copy the project installs into its own `node_modules` still takes precedence, and an unknown `estella-plugin-*` names the ones that do ship.
- The agent drawer's History button shows it is open with a grey press again, not the accent colour 0.71 gave it.
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index ad7d3421c..0338f6e0e 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -18,7 +18,8 @@ const USAGE = `usage: node pipeline/bin/estella.mjs export <projectDir> [options
node pipeline/bin/estella.mjs import-hdr <file.hdr> [outDir] [--face-size <n>]
node pipeline/bin/estella.mjs bake-scene <scene.esscene> [--check]
- --platform <id> web | desktop | wechat | playable | android | ios (default web)
+ --platform <id> a built-in (web, desktop, wechat, douyin, kuaishou, bilibili, playable, android, ios)
+ or a platform the project defines in .esengine/platforms/ (default web)
--out <dir> output dir (default <projectDir>/dist-<platform>)
--wasm <dir> engine runtime to ship (default: the build tree, else the editor's copy)
--scene <path> entry scene, project-relative (default: the project's own)
@@ -780,6 +781,25 @@ const sizeBudgetBytes = manifest.packaging?.sizeBudget?.[platform];
const { mod: exporter, cleanup: cleanupExport } = await loadPipeline(
path.join(PIPELINE, 'src', 'export', 'exportGame.ts'), 'exportGame.mjs');
+// A platform the project defines in .esengine/platforms/, loaded the way the
+// build dialog loads it, so a headless package is the one the dialog makes.
+let projectPlatform = null;
+if (!fmt.BUILTIN_PLATFORMS.includes(platform)) {
+ const { mod: catalog, cleanup: cleanupCatalog } = await loadPipeline(
+ path.join(PIPELINE, 'src', 'export', 'platformCatalog.ts'), 'platformCatalog.mjs');
+ try {
+ projectPlatform = await catalog.loadProjectPlatform(opts.projectDir, platform,
+ { web: engineRuntimeDir('web'), minigame: engineRuntimeDir('wechat') });
+ } finally {
+ cleanupCatalog();
+ }
+ if (!projectPlatform) {
+ console.error(`Unknown platform "${platform}": not a built-in (${fmt.BUILTIN_PLATFORMS.join(', ')}),`
+ + ` and ${opts.projectDir} defines none by that id in .esengine/platforms/.`);
+ process.exit(2);
+ }
+}
+
let code = 1;
try {
const result = await exporter.exportGame({
@@ -789,7 +809,8 @@ try {
hostsDir: path.join(PIPELINE, 'src', 'runtime'),
packagesDir: path.join(REPO, 'plugins'),
sdkDistDir: path.join(REPO, 'sdk', 'dist'),
- wasmDir: opts.wasm ? path.resolve(opts.wasm) : engineRuntimeDir(platform),
+ wasmDir: opts.wasm ? path.resolve(opts.wasm) : projectPlatform?.wasmDir ?? engineRuntimeDir(platform),
+ miniGameProfile: projectPlatform?.profile,
outDir,
platform,
title: opts.title ?? project.name ?? path.basename(opts.projectDir),
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 08597c272..8ef9cd01a 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -65,7 +65,7 @@ import { assembleAab, aabFileName } from '../../../build-tools/utils/aab.js';
import { assembleDesktopApp } from '../../../build-tools/utils/desktopApp.js';
import { emitSteamBuild, defaultDepotId } from '../../../build-tools/utils/steamChannel.js';
import { debugSigningKey, type SigningKey } from '../../../build-tools/utils/androidKeystore.js';
-import { compileTargetFor, isNativePlatform, desktopTemplateFor, type DesktopOs, type ExportPlatform } from '../project/platforms';
+import { BUILTIN_PLATFORMS, compileTargetFor, isNativePlatform, desktopTemplateFor, type DesktopOs, type ExportPlatform } from '../project/platforms';
import type { DesktopPackaging, ProjectFeatures, ProjectPackaging, SteamPackaging } from '../project/format';
import type { SizeBudget } from '../project/sizeBudget';
import { measureBuild, type BuildSizeReport } from './sizeReport';
@@ -756,6 +756,16 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
});
}
+ // Everything past here is the web / desktop / native pipeline. An id that is
+ // none of those and brought no profile is a typo or an unloaded project
+ // platform, and packaging it as a web game would hand back the wrong package.
+ if (!(BUILTIN_PLATFORMS as readonly string[]).includes(platform)) {
+ throw new Error(
+ `"${platform}" is not a platform this export knows: the built-ins are ${BUILTIN_PLATFORMS.join(', ')},`
+ + ' and a project platform arrives with its profile (loadProjectPlatform).',
+ );
+ }
+
// path.resolve, not isAbsolute-or-join: on Windows `/Users/me/out` IS absolute
// and yet names no DRIVE, so it survived that branch unchanged — and then each
// consumer anchored it somewhere else. Node's fs took the current drive's root;
diff --git a/pipeline/tests/export-project-platform.test.ts b/pipeline/tests/export-project-platform.test.ts
index 2a4db0954..8e04b90bd 100644
--- a/pipeline/tests/export-project-platform.test.ts
+++ b/pipeline/tests/export-project-platform.test.ts
@@ -155,4 +155,13 @@ describe('exportGame — a platform the project defines', () => {
expect(bundle).not.toContain('installMiniGamePlatform');
expect(bundle).toContain('initMiniGameRuntime');
}, 60_000);
+
+ it('refuses an id that is neither built in nor handed a profile, rather than packaging it as web', async () => {
+ await expect(exportGame({
+ root, entryScene: 'scenes/main.esscene',
+ hostsDir: path.resolve(__dirname, '../src/runtime'), packagesDir: OFFICIAL_PACKAGES,
+ sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
+ outDir: path.join(root, 'dist-typo'), platform: 'acme-plya',
+ })).rejects.toThrow('"acme-plya" is not a platform this export knows');
+ });
});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b0e2ef6bd..69400ef31 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -990,6 +990,12 @@ export const NOTED = {
{ note: 'A project can be packaged for Bilibili (B 站).' },
'feat(runtime): a mini-game host that asks to hear the first frame is told':
{ note: 'A mini-game host that asks to hear when the first screen has rendered is told' },
+ 'fix(runtime): a mini-game host other than WeChat keeps its lifecycle':
+ { note: 'A mini-game on any host but WeChat no longer throws at boot.' },
+ 'fix(export): a mini-game that fails to start says why':
+ { note: 'A mini-game that fails to start says why.' },
+ 'fix(cli): a project platform exports headless, and an unknown id is refused':
+ { note: '`estella export --platform <id>` packages a platform the project defines' },
'fix(agent): the history toggle presses grey again, not the accent':
{ note: "The agent drawer's History button shows it is open with a grey press again, not the accent colour 0.71 gave it." },
};