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.

docs: add toolchain setup and engine modules section to building guide

esengined851c0cd3413
diff --git a/docs/astro/src/content/docs/guides/building.mdx b/docs/astro/src/content/docs/guides/building.mdx
index 6138a67cf..acfd904e5 100644
--- a/docs/astro/src/content/docs/guides/building.mdx
+++ b/docs/astro/src/content/docs/guides/building.mdx
@@ -14,6 +14,43 @@ ESEngine projects can be built for two target platforms from the editor: **Playa
| Playable Ads | Single `.html` file | All assets, WASM, and scripts inlined into one file. Designed for ad networks that require a single-file deliverable. |
| WeChat MiniGame | Directory | Contains `game.js`, `game.json`, `project.config.json`, scene files, and assets. Ready to open in WeChat DevTools. |
+## Toolchain Setup
+
+Before your first build, the editor needs a C++ toolchain to compile the engine WASM binary. Open **Build Settings** and expand the **Toolchain (emsdk)** section. The status badge shows whether the toolchain is ready:
+
+| Status | Meaning |
+|--------|---------|
+| **Ready** (green) | Emscripten, CMake, and Python are all detected and meet minimum versions |
+| **Not ready** (red) | One or more tools are missing or outdated |
+
+### Auto Install
+
+Click **Auto Install** to download a pre-packaged toolchain (~550–700 MB depending on platform). This includes Emscripten 5.0.0, CMake, and Python — no external dependencies required. Download progress is shown in a toast notification.
+
+### Manual Setup
+
+If you already have emsdk installed, click **Select emsdk** and point to your emsdk root directory. The editor validates the path and detects versions automatically.
+
+<Aside type="note">
+The toolchain is installed once and shared across all projects. It is stored in the editor's app data directory and persists across updates.
+</Aside>
+
+### Engine Modules
+
+Each build configuration can toggle which engine modules to include in the WASM binary:
+
+| Module | Description |
+|--------|-------------|
+| **Tilemap** | 2D tilemap renderer |
+| **Particles** | Particle system |
+| **Timeline** | Timeline animation system |
+| **PostProcess** | Post-processing effects |
+| **Bitmap Text** | Bitmap font rendering |
+| **Spine** | Spine skeletal animation (select runtime versions: 3.8, 4.1, 4.2) |
+| **Physics** | Box2D physics (compiled as a separate WASM module) |
+
+Disabling unused modules reduces the output WASM size. The engine is recompiled only when the module configuration changes; subsequent builds with the same configuration use a cached result.
+
## Using the Build Panel
Open the **Build** panel from the editor toolbar. The panel has a three-column layout:
diff --git a/docs/astro/src/content/docs/zh/guides/building.mdx b/docs/astro/src/content/docs/zh/guides/building.mdx
index 27150e0e1..a29828269 100644
--- a/docs/astro/src/content/docs/zh/guides/building.mdx
+++ b/docs/astro/src/content/docs/zh/guides/building.mdx
@@ -14,6 +14,43 @@ ESEngine 项目可以从编辑器构建到两个目标平台:**可玩广告**
| 可玩广告 | 单个 `.html` 文件 | 所有资源、WASM 和脚本内联到一个文件中。适用于要求单文件交付的广告平台。 |
| 微信小游戏 | 目录 | 包含 `game.js`、`game.json`、`project.config.json`、场景文件和资源。可直接在微信开发者工具中打开。 |
+## 工具链配置
+
+首次构建前,编辑器需要 C++ 工具链来编译引擎 WASM 二进制。打开**构建设置**,展开 **Toolchain (emsdk)** 部分。状态徽章显示工具链是否就绪:
+
+| 状态 | 含义 |
+|------|------|
+| **Ready**(绿色) | Emscripten、CMake 和 Python 均已检测到且满足最低版本要求 |
+| **Not ready**(红色) | 一个或多个工具缺失或版本过低 |
+
+### 自动安装
+
+点击 **Auto Install** 下载预打包的工具链(约 550–700 MB,取决于平台)。包含 Emscripten 5.0.0、CMake 和 Python,无需任何外部依赖。下载进度会在 Toast 通知中实时显示。
+
+### 手动配置
+
+如果你已经安装了 emsdk,点击 **Select emsdk** 并指向 emsdk 根目录。编辑器会自动校验路径并检测版本。
+
+<Aside type="note">
+工具链只需安装一次,所有项目共享使用。它存储在编辑器的应用数据目录中,跨版本更新保留。
+</Aside>
+
+### 引擎模块
+
+每个构建配置可以选择在 WASM 二进制中包含哪些引擎模块:
+
+| 模块 | 说明 |
+|------|------|
+| **Tilemap** | 2D 瓦片地图渲染器 |
+| **Particles** | 粒子系统 |
+| **Timeline** | 时间轴动画系统 |
+| **PostProcess** | 后处理效果 |
+| **Bitmap Text** | 位图字体渲染 |
+| **Spine** | Spine 骨骼动画(可选运行时版本:3.8、4.1、4.2) |
+| **Physics** | Box2D 物理(编译为独立 WASM 模块) |
+
+关闭不使用的模块可以减小输出 WASM 体积。引擎仅在模块配置变化时重新编译;相同配置的后续构建使用缓存结果。
+
## 使用构建面板
从编辑器工具栏打开**构建**面板。面板采用三栏布局: