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): unify esengine resolution → fixes playable bundle, completes wechat subpaths

esengine819c6baacc7b
diff --git a/desktop/electron/esengineResolve.ts b/desktop/electron/esengineResolve.ts
new file mode 100644
index 000000000..67537cefd
--- /dev/null
+++ b/desktop/electron/esengineResolve.ts
@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file One source of truth for resolving the `esengine` SDK across every export
+ * pipeline. There are two strategies, and they must agree on the same set
+ * of subpath exports (mirrors sdk/package.json "exports"):
+ *
+ * EXTERNAL (web / desktop) — esengine stays external, resolved at runtime
+ * by the page import map. The runtime side of this map lives in
+ * buildPlayRealm.IMPORT_MAP; keep the subpath set there in sync.
+ * ALIASED + INLINED (wechat / playable) — no import map, so the bundle
+ * inlines the SDK; esbuild `alias` points esengine (+ subpaths) at dist.
+ */
+import path from 'node:path';
+
+/** esengine left external (web / desktop import-map builds). */
+export const ESENGINE_EXTERNAL = ['esengine', 'esengine/*'];
+
+/**
+ * esbuild `alias` resolving `esengine` and its subpath exports to files under
+ * `sdkDir`, for INLINED builds (the project root has no esengine to resolve from).
+ * `mainEntry` picks the SDK build: 'index.js' (web SDK — web/playable) or
+ * 'index.wechat.js' (the WeChat SDK).
+ */
+export function esengineAlias(sdkDir: string, mainEntry = 'index.js'): Record<string, string> {
+ return {
+ esengine: path.join(sdkDir, mainEntry),
+ 'esengine/spine': path.join(sdkDir, 'spine', 'index.js'),
+ 'esengine/physics': path.join(sdkDir, 'physics', 'index.js'),
+ 'esengine/wasm': path.join(sdkDir, 'wasm.js'),
+ 'esengine/factory': path.join(sdkDir, 'webAppFactory.js'),
+ };
+}
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index faf1f377d..ce7f011ca 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -28,6 +28,7 @@ import { IMPORT_MAP_JSON, IMPORT_MAP_CSP_HASH } from './buildPlayRealm';
import { exportWeChat } from './exportWeChat';
import { exportPlayable } from './exportPlayable';
import type { OnExportProgress } from './exportProgress';
+import { ESENGINE_EXTERNAL } from './esengineResolve';
export type ExportPlatform = 'web' | 'desktop' | 'wechat' | 'playable';
@@ -205,8 +206,6 @@ export async function exportGame(opts: {
outDir: string;
title?: string;
platform?: ExportPlatform;
- /** Built wechat SDK (dist/index.wechat.js) the WeChat bundle aliases `esengine` to. */
- wechatSdkEntry?: string;
/** Playable host source (src/playableHost.ts). */
playableHostEntry?: string;
/** SINGLE_FILE engine glue (esengine.single.js from `-t playable`) for playable ads. */
@@ -234,7 +233,7 @@ export async function exportGame(opts: {
root: opts.root,
entryScene: opts.entryScene,
scriptsEntry: opts.scriptsEntry,
- wechatSdkEntry: opts.wechatSdkEntry ?? path.join(opts.sdkDistDir, 'index.wechat.js'),
+ sdkDir: opts.sdkDistDir,
wasmDir: opts.wasmDir,
outDir: opts.outDir,
title,
@@ -252,6 +251,7 @@ export async function exportGame(opts: {
entryScene: opts.entryScene,
scriptsEntry: opts.scriptsEntry,
playableHostEntry: opts.playableHostEntry ?? path.join(path.dirname(opts.gameHostEntry), 'playableHost.ts'),
+ sdkDir: opts.sdkDistDir,
glueFile: opts.glueFile ?? path.join(opts.wasmDir, 'esengine.single.js'),
outDir: opts.outDir,
title,
@@ -271,7 +271,7 @@ export async function exportGame(opts: {
format: 'esm',
platform: 'browser',
target: 'es2020',
- external: ['esengine', 'esengine/*'],
+ external: ESENGINE_EXTERNAL,
minify: opts.minify ?? false,
sourcemap: opts.sourcemap ?? false,
write: true,
diff --git a/desktop/electron/exportPlayable.ts b/desktop/electron/exportPlayable.ts
index 06a30eb6c..b8b2ae11c 100644
--- a/desktop/electron/exportPlayable.ts
+++ b/desktop/electron/exportPlayable.ts
@@ -20,6 +20,7 @@ import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets } from './cookAssets';
import type { OnExportProgress } from './exportProgress';
+import { esengineAlias } from './esengineResolve';
export interface ExportPlayableResult {
ok: boolean;
@@ -80,6 +81,9 @@ export async function exportPlayable(opts: {
entryScene: string;
scriptsEntry?: string;
playableHostEntry: string;
+ /** Web SDK dist dir — `esengine` is INLINED for playable (no import map), so the
+ * bundle aliases it here (the project root has no esengine to resolve). */
+ sdkDir: string;
glueFile: string;
outDir: string;
title?: string;
@@ -136,6 +140,9 @@ export async function exportPlayable(opts: {
format: 'iife',
platform: 'browser',
target: 'es2020',
+ // esengine is INLINED (single-file, no import map) → resolve it from the SDK
+ // dist; the project root has no esengine installed.
+ alias: esengineAlias(opts.sdkDir),
minify: opts.minify ?? false,
write: false,
outfile: 'game-bundle.js',
diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.ts
index f09d4540b..39c1879ac 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -27,6 +27,7 @@ import { existsSync } from 'node:fs';
import path from 'node:path';
import { cookAssets } from './cookAssets';
import type { OnExportProgress } from './exportProgress';
+import { esengineAlias } from './esengineResolve';
export interface ExportWeChatResult {
ok: boolean;
@@ -103,15 +104,15 @@ async function buildAddressableManifest(absOut: string): Promise<string> {
}
/**
- * Export the open project as a WeChat MiniGame into `outDir`. `wechatSdkEntry` is
- * the built wechat SDK (dist/index.wechat.js) the bundle aliases `esengine` to;
+ * Export the open project as a WeChat MiniGame into `outDir`. `sdkDir` is the SDK
+ * dist dir the bundle aliases `esengine` to (the wechat build, index.wechat.js);
* `wasmDir` the -t wechat engine runtime to copy.
*/
export async function exportWeChat(opts: {
root: string;
entryScene: string;
scriptsEntry?: string;
- wechatSdkEntry: string;
+ sdkDir: string;
wasmDir: string;
outDir: string;
title?: string;
@@ -171,7 +172,7 @@ export async function exportWeChat(opts: {
format: 'cjs',
platform: 'browser',
target: 'es2020',
- alias: { esengine: opts.wechatSdkEntry },
+ alias: esengineAlias(opts.sdkDir, 'index.wechat.js'),
minify: opts.minify ?? false,
sourcemap: false,
outfile: path.join(absOut, 'game-bundle.js'),
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 24d740cea..906469164 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -303,7 +303,6 @@ ipcMain.handle(
scriptsEntry: resolveScripts(manifest).main,
sdkDistDir,
wasmDir: opts?.platform === 'wechat' ? wechatWasm : webWasm,
- wechatSdkEntry: path.join(sdkDistDir, 'index.wechat.js'),
glueFile,
outDir: opts?.outDir || 'dist-game',
title: manifest.name,
diff --git a/desktop/tests/export-playable.test.ts b/desktop/tests/export-playable.test.ts
index f583ef969..a13689a29 100644
--- a/desktop/tests/export-playable.test.ts
+++ b/desktop/tests/export-playable.test.ts
@@ -30,11 +30,14 @@ beforeAll(() => {
JSON.stringify({ version: '1.0', name: 'Main', entities: [{ id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] }] }),
);
writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
- // Stub project script + stub host that DON'T import esengine (keeps the test
- // bundle trivial; real bundling is the same esbuild path the web/wechat tests use).
+ // Host + project script BOTH import 'esengine' (aliased to the stub SDK below) —
+ // exercises the real esengine resolution, so a missing alias fails the build.
mkdirSync(path.join(root, 'src'), { recursive: true });
- writeFileSync(path.join(root, 'src', 'main.ts'), `globalThis.__PROJ__ = 'SpawnMarker';\n`);
- writeFileSync(path.join(root, '_host.ts'), `globalThis.__HOST__ = 'playable-host-boot';\n`);
+ writeFileSync(path.join(root, 'src', 'main.ts'), `import { defineComponent } from 'esengine';\ndefineComponent('SpawnMarker', {});\n`);
+ writeFileSync(path.join(root, '_host.ts'), `import { createWebApp } from 'esengine';\nvoid createWebApp;\nglobalThis.__HOST__ = 'playable-host-boot';\n`);
+ // Stub SDK dist (the bundle aliases `esengine` → <sdkDir>/index.js).
+ mkdirSync(path.join(root, '_sdk'), { recursive: true });
+ writeFileSync(path.join(root, '_sdk', 'index.js'), `export function createWebApp(){return{};}\nexport function defineComponent(){}\n`);
// Stub SINGLE_FILE glue (real one comes from `-t playable`).
writeFileSync(path.join(root, '_glue.js'), `globalThis.ESEngineModule = function(){};/*SINGLE_FILE_GLUE*/\n`);
diff --git a/desktop/tests/export-wechat.test.ts b/desktop/tests/export-wechat.test.ts
index 02292858c..aa5121643 100644
--- a/desktop/tests/export-wechat.test.ts
+++ b/desktop/tests/export-wechat.test.ts
@@ -34,8 +34,9 @@ beforeAll(() => {
writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
mkdirSync(path.join(root, 'src'), { recursive: true });
writeFileSync(path.join(root, 'src', 'main.ts'), `import { defineComponent } from 'esengine';\ndefineComponent('SpawnMarker', { rate: 1 });\n`);
- // Stub wechat SDK (the bundle aliases `esengine` to this) + stub -t wechat runtime.
- writeFileSync(path.join(root, '_wechat-sdk.js'), `export function initWeChatRuntime(){return Promise.resolve();}\nexport function defineComponent(){}\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`);
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');
@@ -53,7 +54,6 @@ describe('exportGame (wechat)', () => {
gameHostEntry: 'unused-for-wechat',
scriptsEntry: 'src/main.ts',
sdkDistDir: path.join(root, '_sdk'),
- wechatSdkEntry: path.join(root, '_wechat-sdk.js'),
wasmDir: path.join(root, '_wxwasm'),
outDir: out,
title: 'My Game',