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
feat(web): the JavaScript engine is opt-in — Project Settings → Web → Run without WebAssembly
yhh66324a7d7e63
diff --git a/desktop b/desktopindex 3f27ade5f..7a1b5caa4 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 3f27ade5fb58425140886aca2c06b8c5abffe7c8+Subproject commit 7a1b5caa45617b90132eb1cc0a5e4b4d87a86c31diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdxindex 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 enginecompiled 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 isnever downloaded. Where it does not exist (some locked-down WebViews andembedded 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 stayinterpreted, 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 debuggablediff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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();+ });+});