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.

feat(web): the JavaScript engine is opt-in — Project Settings → Web → Run without WebAssembly

yhh66324a7d7e63
diff --git a/desktop b/desktop
index 3f27ade5f..7a1b5caa4 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 3f27ade5fb58425140886aca2c06b8c5abffe7c8
+Subproject commit 7a1b5caa45617b90132eb1cc0a5e4b4d87a86c31
diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdx
index 26e44949a..5e56677ea 100644
--- a/docs/astro/src/content/docs/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/publishing/overview.mdx
@@ -278,15 +278,26 @@ runtime API.
## Browsers without WebAssembly
-A Web export carries the engine twice: `wasm/esengine.wasm`, and the same engine
+Turn on **Project Settings → Packaging → Web → Run without WebAssembly** and a
+Web export carries the engine twice: `wasm/esengine.wasm`, and the same engine
compiled to plain JavaScript as `wasm/esengine.asm.js`. The page picks at boot.
Where `WebAssembly` exists it loads the wasm engine, and the JavaScript one is
never downloaded. Where it does not exist (some locked-down WebViews and
embedded browsers), the page loads `esengine.asm.js`, and the game runs the same
-scenes and scripts.
+scenes and scripts. In the manifest the setting is:
-To try the JavaScript engine in an ordinary browser, add `?engine=js` to the
-page URL.
+```json
+"packaging": { "platforms": { "web": { "engineJs": true } } }
+```
+
+It is off by default. Nobody with WebAssembly downloads the file, but it adds
+about 4 MB to every package, which counts against a host's upload limit. With
+it off, a browser with no WebAssembly shows an error that names the setting.
+Mini-game targets never carry it: every one they support runs WebAssembly, and
+the file alone is larger than WeChat's 4 MB main package.
+
+To try the JavaScript engine in an ordinary browser, export with the setting on
+and add `?engine=js` to the page URL.
What it costs, measured on `hello-world` in headless Chromium:
@@ -304,15 +315,6 @@ What it does not have:
- **Compiled (`@compiled`) systems.** These are wasm modules too. They stay
interpreted, which is the same result as an export without AOT.
-To leave the file out (it is about 4 MB on the server, though nobody with
-WebAssembly downloads it), set `engineJs` to `false`:
-
-```json
-"packaging": { "platforms": { "web": { "engineJs": false } } }
-```
-
-A browser with no WebAssembly then gets a clear error instead of a game.
-
## Build config & source maps
- **Development** — an unminified build; pair it with source maps for debuggable
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
index 190da85a0..99aeb7e1e 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
@@ -235,12 +235,21 @@ node build-tools/cli.js build -t wechat
## 不支持 WebAssembly 的浏览器
-Web 导出会带两份引擎:`wasm/esengine.wasm`,以及同一引擎编译成纯 JavaScript 的
-`wasm/esengine.asm.js`。页面启动时二选一。有 `WebAssembly` 的环境加载 wasm 引擎,
-JavaScript 版本不会被下载。没有 `WebAssembly` 的环境(一些锁死的 WebView、
-嵌入式浏览器)加载 `esengine.asm.js`,游戏照常运行同样的场景和脚本。
+打开 **项目设置 → 打包 → Web → 无 WebAssembly 时运行** 后,Web 导出会带两份引擎:
+`wasm/esengine.wasm`,以及同一引擎编译成纯 JavaScript 的 `wasm/esengine.asm.js`。
+页面启动时二选一。有 `WebAssembly` 的环境加载 wasm 引擎,JavaScript 版本不会被下载。
+没有 `WebAssembly` 的环境(一些锁死的 WebView、嵌入式浏览器)加载 `esengine.asm.js`,
+游戏照常运行同样的场景和脚本。清单里对应的写法:
-要在普通浏览器里试 JavaScript 引擎,在页面地址后加 `?engine=js`。
+```json
+"packaging": { "platforms": { "web": { "engineJs": true } } }
+```
+
+默认关闭。有 WebAssembly 的用户不会下载这个文件,但每个包都会多出约 4 MB,
+会计入托管平台的上传限制。关闭时,没有 WebAssembly 的浏览器会显示一条写明这个设置的报错。
+小游戏目标从不带它:它们支持的平台都能跑 WebAssembly,而且单这一个文件就超过微信 4 MB 的主包。
+
+要在普通浏览器里试 JavaScript 引擎,打开这个设置导出,再在页面地址后加 `?engine=js`。
代价(`hello-world`,headless Chromium 实测):
@@ -258,15 +267,6 @@ JavaScript 版本不会被下载。没有 `WebAssembly` 的环境(一些锁死
- **编译(`@compiled`)系统**:它们也是 wasm 模块,这里保持解释执行,
结果和不开 AOT 的导出一样。
-不想带这个文件(服务器上约 4 MB,有 WebAssembly 的用户不会下载它),
-把 `engineJs` 设为 `false`:
-
-```json
-"packaging": { "platforms": { "web": { "engineJs": false } } }
-```
-
-这样一来,没有 WebAssembly 的浏览器会看到一条明确的报错,而不是游戏。
-
## 构建配置与 source map
- **Development** —— 不压缩的构建;配上 source map 得到可调试的输出。
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 88461e1fb..7375e8077 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -499,7 +499,7 @@ export interface ExportGameOptions {
webChannel?: 'poki' | 'crazygames' | 'youtube';
/** Origins the web page's policy lets the game connect to (project: packaging.platforms.web.connect). */
webConnect?: string[];
- /** Web: carry the plain-JavaScript engine for browsers without WebAssembly. Absent ⇒ true. */
+ /** Web: carry the plain-JavaScript engine for browsers without WebAssembly. Absent ⇒ false. */
webEngineJs?: boolean;
leaderboardEncryptionKey?: string;
sdkDistDir: string;
@@ -1215,7 +1215,7 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
});
// The plain-JavaScript engine is the web page's answer to a browser with no
// WebAssembly; any other package has an engine of its own kind, or none.
- if (platform !== 'web' || opts.webEngineJs === false) {
+ if (platform !== 'web' || opts.webEngineJs !== true) {
await rm(path.join(wasmOut, ENGINE_JS_FILE), { force: true });
}
} else errors.push(`wasm runtime dir not found: ${opts.wasmDir}`);
diff --git a/pipeline/src/export/projectExportOptions.ts b/pipeline/src/export/projectExportOptions.ts
index 7f2173224..95fe3a9e6 100644
--- a/pipeline/src/export/projectExportOptions.ts
+++ b/pipeline/src/export/projectExportOptions.ts
@@ -110,7 +110,7 @@ export async function projectExportOptions(
: {}),
...(platform === 'web' && (plat?.web?.channel === 'poki' || plat?.web?.channel === 'crazygames' || plat?.web?.channel === 'youtube') ? { webChannel: plat.web.channel } : {}),
...(platform === 'web' && plat?.web?.connect?.length ? { webConnect: plat.web.connect } : {}),
- ...(platform === 'web' && plat?.web?.engineJs === false ? { webEngineJs: false } : {}),
+ ...(platform === 'web' && plat?.web?.engineJs === true ? { webEngineJs: true } : {}),
...(platform === 'web' && plat?.web?.channel === 'crazygames' && plat.web.leaderboardEncryptionKey
? { leaderboardEncryptionKey: plat.web.leaderboardEncryptionKey } : {}),
desktopProductName: plat?.desktop?.productName,
diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.ts
index 1ec0ea315..ca691cd9b 100644
--- a/pipeline/src/project/format.ts
+++ b/pipeline/src/project/format.ts
@@ -454,9 +454,9 @@ export interface ProjectPackaging {
* The page's Content-Security-Policy allows only its own origin otherwise. */
connect?: string[];
/**
- * Carry the engine built as plain JavaScript beside the wasm one (default true),
- * for a browser with no WebAssembly. It is fetched only there; elsewhere it is
- * ~4 MB the server holds and nobody downloads.
+ * Carry the engine built as plain JavaScript beside the wasm one (default false),
+ * for a browser with no WebAssembly. It is fetched only there, but it is ~4 MB
+ * in every package, so a project that needs it turns it on.
*/
engineJs?: boolean;
};
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index a372460c0..d143408f5 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -202,7 +202,7 @@ async function boot(): Promise<void> {
|| new URLSearchParams(location.search).get('engine') === 'js') && cfg.engineJs === true;
if (typeof WebAssembly === 'undefined' && !engineAsJs) {
throw new Error('This browser has no WebAssembly, and this build carries no JavaScript engine '
- + '(packaging.platforms.web.engineJs is off).');
+ + '(Project Settings → Web → "Run without WebAssembly", packaging.platforms.web.engineJs).');
}
const { default: createModule } = (await import(
/* @vite-ignore */ `${wasmBase}${engineAsJs ? 'esengine.asm.js' : 'esengine.js'}`)) as {
diff --git a/pipeline/tests/web-engine-js.test.ts b/pipeline/tests/web-engine-js.test.ts
new file mode 100644
index 000000000..3ea76c12a
--- /dev/null
+++ b/pipeline/tests/web-engine-js.test.ts
@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The plain-JavaScript engine is opt-in: about 4 MB in every package for
+ * the few browsers with no WebAssembly, so only a project that asks for it
+ * carries it, and only to the web.
+ */
+import { describe, it, expect } from 'vitest';
+
+describe('web engineJs in a project', () => {
+ const manifest = (web: Record<string, unknown> | undefined) =>
+ ({ formatVersion: '1', name: 'g', ...(web ? { packaging: { platforms: { web } } } : {}) });
+
+ it('is off unless the project turns it on, and reaches only the web export', async () => {
+ const { parseManifest } = await import('../src/project/format');
+ const { projectExportOptions } = await import('../src/export/projectExportOptions');
+ expect((await projectExportOptions('/tmp/game', parseManifest(manifest(undefined)), 'web')).webEngineJs).toBeUndefined();
+ expect((await projectExportOptions('/tmp/game', parseManifest(manifest({ engineJs: false })), 'web')).webEngineJs).toBeUndefined();
+ const on = parseManifest(manifest({ engineJs: true }));
+ expect(on.packaging?.platforms?.web?.engineJs).toBe(true);
+ expect((await projectExportOptions('/tmp/game', on, 'web')).webEngineJs).toBe(true);
+ expect((await projectExportOptions('/tmp/game', on, 'wechat')).webEngineJs).toBeUndefined();
+ });
+});