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.

build: bundle emsdk as submodule with auto-discovery; pin Windows dev host

yhha786ba397cae
diff --git a/.gitignore b/.gitignore
index 4fe0d37a2..cc0a0a024 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,6 +57,9 @@ compile_commands.json
*.js.mem
*.data
+# emsdk discovery cache (per-machine path written by build-tools auto-discovery)
+.emsdk-path
+
# Astro
.astro/
diff --git a/.gitmodules b/.gitmodules
index 6b023d399..316fada86 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -34,3 +34,6 @@
[submodule "third_party/basis_universal"]
path = third_party/basis_universal
url = https://github.com/BinomialLLC/basis_universal.git
+[submodule "tools/emsdk"]
+ path = tools/emsdk
+ url = https://github.com/emscripten-core/emsdk.git
diff --git a/build-tools/toolchain/setup-emsdk.js b/build-tools/toolchain/setup-emsdk.js
new file mode 100644
index 000000000..38639f4f9
--- /dev/null
+++ b/build-tools/toolchain/setup-emsdk.js
@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+
+/**
+ * One-time setup for the bundled emsdk submodule (tools/emsdk): install and
+ * activate the pinned Emscripten version so the build's auto-discovery can use
+ * it. Run after `git submodule update --init tools/emsdk` on a fresh checkout.
+ *
+ * pnpm emsdk:setup
+ *
+ * This downloads the emscripten toolchain (~GB) into tools/emsdk. If you already
+ * have an emsdk elsewhere, you don't need this — set EMSDK=/path/to/emsdk (or
+ * drop it at ~/emsdk) and the build will discover it.
+ */
+
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+
+const EMSCRIPTEN_VERSION = '5.0.0';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const EMSDK_DIR = path.join(REPO_ROOT, 'tools', 'emsdk');
+
+function log(msg) {
+ console.log(`[emsdk:setup] ${msg}`);
+}
+
+function run(emsdkCmd, args) {
+ log(`emsdk ${args.join(' ')}`);
+ const result = spawnSync(emsdkCmd, args, {
+ cwd: EMSDK_DIR,
+ stdio: 'inherit',
+ // emsdk on Windows is a .bat/.ps1; let the shell resolve it.
+ shell: process.platform === 'win32',
+ });
+ if (result.status !== 0) {
+ log(`Command failed (exit ${result.status ?? 'signal'}).`);
+ process.exit(result.status || 1);
+ }
+}
+
+function main() {
+ if (!existsSync(EMSDK_DIR)) {
+ log(`Submodule not found at ${EMSDK_DIR}`);
+ log('Run: git submodule update --init tools/emsdk');
+ process.exit(1);
+ }
+
+ // tools/emsdk/emsdk (POSIX) or tools/emsdk/emsdk.bat (Windows). With shell:true
+ // on Windows, the bare name resolves to emsdk.bat from EMSDK_DIR.
+ const emsdkCmd = process.platform === 'win32'
+ ? 'emsdk.bat'
+ : path.join(EMSDK_DIR, 'emsdk');
+
+ run(emsdkCmd, ['install', EMSCRIPTEN_VERSION]);
+ run(emsdkCmd, ['activate', EMSCRIPTEN_VERSION]);
+
+ log(`Done. emsdk ${EMSCRIPTEN_VERSION} is activated at tools/emsdk.`);
+ log('The build will auto-discover it (no need to source emsdk_env).');
+}
+
+main();
diff --git a/build-tools/utils/emscripten.js b/build-tools/utils/emscripten.js
index 92f68ad7e..7247ad2ef 100644
--- a/build-tools/utils/emscripten.js
+++ b/build-tools/utils/emscripten.js
@@ -1,11 +1,112 @@
// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { spawn } from 'child_process';
+import fs, { existsSync } from 'fs';
import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
import * as logger from './logger.js';
const MIN_EMSCRIPTEN_VERSION = '5.0.0';
+// Repo root, derived from this file's location (build-tools/utils/emscripten.js).
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+// Per-machine cache of the resolved emsdk path (gitignored). Lets the next build
+// skip the directory scan and pins the choice once discovered.
+const EMSDK_CACHE_FILE = path.join(REPO_ROOT, '.emsdk-path');
+
+// An emsdk root is usable if it has an activated emscripten install: the
+// `upstream/emscripten` tree (emcc/em++/emcmake) plus the generated `.emscripten`
+// config that emcc reads via EM_CONFIG.
+function isActivatedEmsdk(root) {
+ return !!root
+ && existsSync(path.join(root, 'upstream', 'emscripten'))
+ && existsSync(path.join(root, '.emscripten'));
+}
+
+// emsdk ships its own Node under node/<version>/bin — return the first one.
+function firstEmsdkNodeBin(root) {
+ const nodeDir = path.join(root, 'node');
+ if (!existsSync(nodeDir)) return null;
+ for (const ver of fs.readdirSync(nodeDir)) {
+ const bin = path.join(nodeDir, ver, 'bin');
+ if (existsSync(bin)) return bin;
+ }
+ return null;
+}
+
+// Candidate emsdk roots, highest priority first:
+// 1. EMSDK env var (explicit, e.g. a sourced emsdk_env)
+// 2. .emsdk-path cache written by a previous discovery
+// 3. the tools/emsdk submodule (set up via `pnpm emsdk:setup`)
+// 4. common install locations (~/emsdk, drive roots on Windows, /opt on *nix)
+function candidateEmsdkRoots() {
+ const candidates = [];
+ if (process.env.EMSDK) candidates.push(process.env.EMSDK);
+ try {
+ if (existsSync(EMSDK_CACHE_FILE)) {
+ const cached = fs.readFileSync(EMSDK_CACHE_FILE, 'utf8').trim();
+ if (cached) candidates.push(cached);
+ }
+ } catch {
+ // unreadable cache is non-fatal — fall through to scanning
+ }
+ candidates.push(path.join(REPO_ROOT, 'tools', 'emsdk'));
+ candidates.push(path.join(os.homedir(), 'emsdk'));
+ if (process.platform === 'win32') {
+ for (const drive of ['C', 'D', 'E', 'F', 'G', 'H']) {
+ candidates.push(`${drive}:\\emsdk`);
+ }
+ } else {
+ candidates.push('/opt/emsdk', '/usr/local/emsdk');
+ }
+ return candidates;
+}
+
+let emsdkActivated = false;
+
+/**
+ * Locate an activated emsdk and inject it into this process's environment so
+ * `emcc`/`em++`/`emcmake`/`wasm-opt` resolve without the caller having to source
+ * `emsdk_env`. Mutates process.env (PATH, EM_CONFIG, EMSDK), which every child
+ * spawned via runCommand inherits. Idempotent; returns true once an emsdk is
+ * active (either pre-existing on PATH or freshly discovered).
+ */
+export function ensureEmscriptenEnv() {
+ if (emsdkActivated) return true;
+
+ let root = null;
+ for (const candidate of candidateEmsdkRoots()) {
+ if (isActivatedEmsdk(candidate)) {
+ root = path.resolve(candidate);
+ break;
+ }
+ }
+ if (!root) return false;
+
+ const emscriptenDir = path.join(root, 'upstream', 'emscripten');
+ const binDir = path.join(root, 'upstream', 'bin');
+ const nodeBin = firstEmsdkNodeBin(root);
+ const additions = [root, emscriptenDir, binDir, nodeBin].filter(existsSync);
+
+ process.env.EMSDK = root;
+ process.env.EM_CONFIG = path.join(root, '.emscripten');
+ if (nodeBin) {
+ process.env.EMSDK_NODE = path.join(nodeBin, process.platform === 'win32' ? 'node.exe' : 'node');
+ }
+ process.env.PATH = additions.join(path.delimiter) + path.delimiter + (process.env.PATH || '');
+
+ try {
+ fs.writeFileSync(EMSDK_CACHE_FILE, `${root}\n`);
+ } catch {
+ // cache is an optimization — a read-only tree is fine
+ }
+
+ emsdkActivated = true;
+ logger.debug(`Activated emsdk at ${root}`);
+ return true;
+}
+
function compareVersions(a, b) {
const pa = a.split('.').map(Number);
const pb = b.split('.').map(Number);
@@ -17,6 +118,10 @@ function compareVersions(a, b) {
}
export async function checkEmscripten() {
+ // Auto-discover + activate a local emsdk (EMSDK env → .emsdk-path cache →
+ // tools/emsdk submodule → common locations) so `emcc` resolves even when the
+ // caller never sourced emsdk_env. No-op if emsdk is already on PATH.
+ ensureEmscriptenEnv();
try {
const result = await runCommand('emcc', ['--version'], { silent: true });
const versionMatch = result.stdout.match(/(\d+\.\d+\.\d+)/);
@@ -76,10 +181,11 @@ export async function checkEnvironment() {
};
if (!checks.emscripten) {
- logger.error('Emscripten not found. Please install and activate emsdk:');
+ logger.error('Emscripten not found. No activated emsdk was discovered.');
logger.info(` Required version: ${MIN_EMSCRIPTEN_VERSION}`);
- logger.info(` Install: emsdk install ${MIN_EMSCRIPTEN_VERSION} && emsdk activate ${MIN_EMSCRIPTEN_VERSION}`);
- logger.info(' Activate: source /path/to/emsdk/emsdk_env.sh');
+ logger.info(' Set up the bundled submodule: pnpm emsdk:setup');
+ logger.info(' Or point at an existing install: set EMSDK=/path/to/emsdk');
+ logger.info(' (auto-discovery checks: $EMSDK → .emsdk-path → tools/emsdk → ~/emsdk)');
return false;
}
diff --git a/desktop/vite.config.ts b/desktop/vite.config.ts
index 5f0051bbc..b6f55755b 100644
--- a/desktop/vite.config.ts
+++ b/desktop/vite.config.ts
@@ -14,6 +14,13 @@ export default defineConfig({
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
+ server: {
+ // Bind IPv4 loopback explicitly. On Windows `localhost` resolves to ::1 first,
+ // so a default bind leaves Vite on [::1] only — but Electron's loadURL hits
+ // 127.0.0.1 and gets ERR_CONNECTION_REFUSED. Pinning 127.0.0.1 keeps the dev
+ // renderer origin reachable from the Electron window.
+ host: '127.0.0.1',
+ },
build: {
rollupOptions: {
// Renderer entries: the editor shell (index) + the headless render host
diff --git a/package.json b/package.json
index ab865588a..b6b72e9e1 100644
--- a/package.json
+++ b/package.json
@@ -16,6 +16,7 @@
"clean": "node build-tools/cli.js clean -a",
"eht": "node build-tools/cli.js eht",
"sync": "node build-tools/cli.js sync",
+ "emsdk:setup": "node build-tools/toolchain/setup-emsdk.js",
"asset-meta": "node tools/asset-meta.js",
"migrate-asset-refs": "node tools/migrate-asset-refs.js"
},
diff --git a/tools/emsdk b/tools/emsdk
new file mode 160000
index 000000000..7555392bc
--- /dev/null
+++ b/tools/emsdk
@@ -0,0 +1 @@
+Subproject commit 7555392bc137ea2172b3f815a0bd256bc403d9a2