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 v0.8.3 changelog and update building/playable-ads guides

esengine6c09ae217ed0
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index f32aff2fe..13558eb91 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -149,6 +149,7 @@ export default defineConfig({
label: 'Changelog',
translations: { 'zh-CN': '更新日志' },
items: [
+ { label: 'v0.8.3', slug: 'changelog-v083' },
{ label: 'v0.8.2', slug: 'changelog-v082' },
{ label: 'v0.8.1', slug: 'changelog-v081' },
{ label: 'v0.8.0', slug: 'changelog-v080' },
diff --git a/docs/astro/src/content/docs/changelog-v083.mdx b/docs/astro/src/content/docs/changelog-v083.mdx
new file mode 100644
index 000000000..82bfb434d
--- /dev/null
+++ b/docs/astro/src/content/docs/changelog-v083.mdx
@@ -0,0 +1,48 @@
+---
+title: v0.8.3
+description: ESEngine v0.8.3 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.3 restructures the build pipeline with templates, hooks, and config management, adds physics support for playable builds, and fixes touch input and slider behavior.
+</Aside>
+
+## Build Pipeline Overhaul
+
+The build system has been restructured with new features for automation and reuse:
+
+- **Build Templates** — 7 built-in presets (Facebook Playable, Google Playable, Playable Debug, WeChat Production, WeChat Debug, WeChat Single File, WeChat Landscape) plus the ability to save custom templates from existing configs
+- **Build Hooks** — pre-build and post-build hooks for copying files (with glob patterns) or running shell commands, enabling custom automation workflows
+- **Config Import/Export** — export build configurations as JSON for backup or team sharing, and import them on another machine
+- **Build Status Indicators** — green/red dots on each configuration showing the last build result at a glance
+- **Auto Plugin Detection** — the build now automatically detects which UI plugins your scenes need (Text, UIRect, etc.) and includes only those, reducing output size
+
+See the [Building guide](/microes/guides/building/) for details on templates and hooks.
+
+## Physics in Playable Builds
+
+Playable ad builds now fully support the Box2D physics module. When physics is enabled in project settings, the physics WASM binary is automatically embedded as base64 in the single-file HTML output. A body position synchronization bug was also fixed, ensuring physics bodies correctly track their Transform positions.
+
+## Audio in Playable Builds
+
+Audio loading in playable builds has been fixed. Audio clips referenced by `AudioSource` components are now correctly embedded and loaded at runtime. Previously, audio files could fail to load in the single-file HTML output.
+
+## Touch Input Improvements
+
+- Added `touchcancel` event handler to the web adapter, preventing stuck touch states when the browser cancels a touch (e.g., system gesture, notification overlay)
+- Touch events now call `preventDefault()` to avoid unintended browser behaviors (scroll, zoom) during gameplay
+
+## Slider Fix
+
+The slider drag system now uses `UIInteraction.pressed` state instead of internal closure state, fixing an issue where sliders could become unresponsive after rapid interactions.
+
+## Editor Fixes
+
+- Collision layer dropdown in the Inspector now refreshes immediately when layers are renamed or added in project settings
+- Audio playback in the editor preview now works correctly (CSP `media-src` policy updated)
+
+## Example Projects
+
+A new `physics-spinner` example project demonstrates physics-driven gameplay with dynamic body spawning, motor joints, and collision layers.
diff --git a/docs/astro/src/content/docs/guides/building.mdx b/docs/astro/src/content/docs/guides/building.mdx
index b44ac424a..6138a67cf 100644
--- a/docs/astro/src/content/docs/guides/building.mdx
+++ b/docs/astro/src/content/docs/guides/building.mdx
@@ -39,6 +39,22 @@ Build progress and logs are displayed in real time via a toast notification. Whe
Use **Build All** to build every configuration in sequence. This is useful for producing both development and production builds at once.
</Aside>
+## Build Templates
+
+Click **Templates** in the toolbar to create a configuration from a preset. Built-in templates:
+
+| Template | Platform | Description |
+|----------|----------|-------------|
+| Facebook Playable | Playable Ads | Optimized for Facebook's 2 MB limit with minification enabled |
+| Google Playable | Playable Ads | Optimized for Google's 5 MB limit |
+| Playable Debug | Playable Ads | Development build with `DEBUG` define |
+| WeChat Production | WeChat | Subpackage mode, portrait orientation |
+| WeChat Debug | WeChat | Single bundle with `DEBUG` define |
+| WeChat Single File | WeChat | Single file bundle for simple games |
+| WeChat Landscape | WeChat | Landscape orientation for wide-screen games |
+
+You can also save any existing configuration as a custom template via **Save as Preset** in the detail panel.
+
## Build Configuration
Each configuration contains:
@@ -211,6 +227,160 @@ Both platforms generate an `asset-manifest.json` that maps asset UUIDs to runtim
}
```
+## Build Hooks
+
+Each configuration can define **pre-build** and **post-build** hooks to automate custom steps. Add hooks in the collapsible Build Hooks section of the configuration detail panel. Each hook has a **phase** (`pre` or `post`) and a **type** (`copy-files` or `run-command`).
+
+### Copy Files
+
+Recursively copy a directory to another location. Optionally filter files by glob pattern.
+
+| Field | Description |
+|-------|-------------|
+| **from** | Source directory path |
+| **to** | Destination directory path |
+| **pattern** | Optional filename filter (e.g. `*.png`, `*.json`) — only matching files are copied |
+
+Both `from` and `to` support path variables:
+
+| Variable | Resolves To |
+|----------|-------------|
+| `${projectDir}` | Absolute path to the project root |
+| `${outputPath}` | Full path to the output file (e.g. `build/playable.html`) |
+| `${outputDir}` | Directory containing the output (e.g. `build/`) |
+
+### Run Command
+
+Execute a shell command with the **project root** as the working directory (`cwd`).
+
+| Field | Description |
+|-------|-------------|
+| **command** | The executable to run (e.g. `node`, `python3`, `bash`) |
+| **args** | Optional array of string arguments passed to the command |
+
+The command receives:
+- **Working directory** — the project root (same as the editor's project path)
+- **Arguments** — the literal strings from the `args` array (no variable substitution)
+- **Stdout/stderr** — captured and logged to the build console (stdout truncated to 200 chars)
+- **Exit code** — non-zero exits will fail the build
+
+<Aside type="note">
+Path variables (`${projectDir}`, `${outputPath}`, etc.) are **only** supported in `copy-files` hooks. For `run-command`, pass paths as literal strings in `args`, or have your script read them from a config file / environment.
+</Aside>
+
+### Hook Examples
+
+Copy extra assets into the WeChat output after building:
+
+```json
+{
+ "phase": "post",
+ "type": "copy-files",
+ "config": {
+ "from": "${projectDir}/assets/extras",
+ "to": "${outputDir}/assets/extras",
+ "pattern": "*.png"
+ }
+}
+```
+
+Run a texture compression script before building (CWD is the project root, so relative paths work):
+
+```json
+{
+ "phase": "pre",
+ "type": "run-command",
+ "config": {
+ "command": "node",
+ "args": ["scripts/compress-textures.js", "--input", "assets/textures", "--quality", "80"]
+ }
+}
+```
+
+The script receives `args` as `process.argv.slice(2)`:
+
+```javascript
+// scripts/compress-textures.js
+const args = process.argv.slice(2);
+// args = ["--input", "assets/textures", "--quality", "80"]
+// process.cwd() = project root directory
+
+const inputDir = args[args.indexOf('--input') + 1]; // "assets/textures"
+const quality = args[args.indexOf('--quality') + 1]; // "80"
+```
+
+Post-build hook to copy the output to a deploy folder:
+
+```json
+{
+ "phase": "post",
+ "type": "copy-files",
+ "config": {
+ "from": "${outputDir}",
+ "to": "${projectDir}/deploy"
+ }
+}
+```
+
+### Config JSON Format
+
+Build configurations are stored in `editor-state.json`. Each config follows this structure:
+
+```json
+{
+ "id": "playable-prod",
+ "name": "Playable - Production",
+ "platform": "playable",
+ "scenes": ["assets/scenes/main.esscene"],
+ "defines": [],
+ "hooks": [
+ {
+ "phase": "post",
+ "type": "run-command",
+ "config": { "command": "open", "args": ["${outputDir}"] }
+ }
+ ],
+ "playableSettings": {
+ "startupScene": "assets/scenes/main.esscene",
+ "isDevelopment": false,
+ "minifyCode": true,
+ "embedFonts": true,
+ "outputPath": "build/playable.html",
+ "enableBuiltinCTA": false,
+ "ctaUrl": ""
+ }
+}
+```
+
+For WeChat configurations, replace `playableSettings` with `wechatSettings`:
+
+```json
+{
+ "id": "wechat-prod",
+ "name": "WeChat - Production",
+ "platform": "wechat",
+ "scenes": ["assets/scenes/main.esscene"],
+ "defines": [],
+ "hooks": [],
+ "wechatSettings": {
+ "appId": "wx1234567890",
+ "version": "1.0.0",
+ "bundleMode": "subpackage",
+ "outputDir": "build/wechat",
+ "orientation": "portrait"
+ }
+}
+```
+
+## Config Import & Export
+
+Build configurations can be exported as JSON for backup or team sharing:
+
+- **Export** — click the Export button in the toolbar to save all configs to a `.json` file
+- **Import** — click Import to load configs from a previously exported file
+
+Custom templates saved via **Save as Preset** are stored in `.esengine/build-templates/` as JSON files. These can be committed to version control for team sharing.
+
## Project Settings
Build behavior is also influenced by project-level settings:
diff --git a/docs/astro/src/content/docs/guides/playable-ads.mdx b/docs/astro/src/content/docs/guides/playable-ads.mdx
index 970ec6ab5..b6f73705f 100644
--- a/docs/astro/src/content/docs/guides/playable-ads.mdx
+++ b/docs/astro/src/content/docs/guides/playable-ads.mdx
@@ -106,10 +106,12 @@ All assets referenced by the startup scene are automatically embedded:
Assets not referenced by the startup scene are not included. Use addressable groups with export mode "always" to force-include assets that are loaded dynamically at runtime.
</Aside>
-## Spine & Physics Support
+## Spine, Physics & Audio Support
If your project uses Spine animations or Box2D physics, the respective WASM modules are automatically embedded as base64 and instantiated at runtime. No additional configuration is needed -- the build detects whether Spine or physics is enabled in your project settings.
+Audio clips referenced by `AudioSource` components are also automatically embedded and loaded at runtime. Both inline `playSFX`/`playBGM` calls and entity-based `AudioSource` playback work in the single-file output.
+
## Size Optimization
Playable ad networks typically impose file size limits (2-5 MB). Tips for reducing output size:
diff --git a/docs/astro/src/content/docs/zh/changelog-v083.mdx b/docs/astro/src/content/docs/zh/changelog-v083.mdx
new file mode 100644
index 000000000..552c18371
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/changelog-v083.mdx
@@ -0,0 +1,48 @@
+---
+title: v0.8.3
+description: ESEngine v0.8.3 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.3 重构了构建流水线,新增模板、钩子和配置管理,为可玩广告添加物理支持,并修复了触摸输入和滑块行为。
+</Aside>
+
+## 构建流水线改版
+
+构建系统进行了重构,新增自动化和复用功能:
+
+- **构建模板** — 7 个内置预设(Facebook 可玩广告、Google 可玩广告、可玩广告调试版、微信生产版、微信调试版、微信单文件版、微信横屏版),支持将现有配置保存为自定义模板
+- **构建钩子** — 支持构建前和构建后钩子,可复制文件(支持 glob 模式)或运行 shell 命令,实现自定义自动化工作流
+- **配置导入/导出** — 将构建配置导出为 JSON 用于备份或团队共享,也可在另一台设备上导入
+- **构建状态指示器** — 每个配置上显示绿/红圆点,一目了然地展示上次构建结果
+- **自动插件检测** — 构建现在自动检测场景所需的 UI 插件(Text、UIRect 等),仅包含必要的插件以减小输出体积
+
+详见[构建指南](/microes/zh/guides/building/)了解模板和钩子的使用方法。
+
+## 可玩广告物理支持
+
+可玩广告构建现已完整支持 Box2D 物理模块。在项目设置中启用物理后,物理 WASM 二进制会自动以 base64 编码嵌入到单文件 HTML 输出中。同时修复了刚体位置同步 bug,确保物理刚体正确跟踪其 Transform 位置。
+
+## 可玩广告音频修复
+
+修复了可玩广告构建中的音频加载问题。`AudioSource` 组件引用的音频片段现在可以正确嵌入并在运行时加载。此前,音频文件可能在单文件 HTML 输出中加载失败。
+
+## 触摸输入改进
+
+- Web 适配器新增 `touchcancel` 事件处理,防止浏览器取消触摸时(如系统手势、通知弹出)出现触摸状态卡死
+- 触摸事件现在调用 `preventDefault()` 以避免游戏过程中出现浏览器默认行为(滚动、缩放)
+
+## 滑块修复
+
+滑块拖拽系统现在使用 `UIInteraction.pressed` 状态替代内部闭包状态,修复了快速交互后滑块可能无响应的问题。
+
+## 编辑器修复
+
+- Inspector 中的碰撞层下拉框现在会在项目设置中重命名或添加层后立即刷新
+- 编辑器预览中的音频播放现在可以正常工作(更新了 CSP `media-src` 策略)
+
+## 示例项目
+
+新增 `physics-spinner` 示例项目,演示基于物理的游戏玩法,包括动态刚体生成、马达关节和碰撞层。
diff --git a/docs/astro/src/content/docs/zh/guides/building.mdx b/docs/astro/src/content/docs/zh/guides/building.mdx
index 89be6942a..27150e0e1 100644
--- a/docs/astro/src/content/docs/zh/guides/building.mdx
+++ b/docs/astro/src/content/docs/zh/guides/building.mdx
@@ -39,6 +39,22 @@ ESEngine 项目可以从编辑器构建到两个目标平台:**可玩广告**
使用**全部构建**可以依次构建所有配置。这在同时需要开发版和生产版构建时很有用。
</Aside>
+## 构建模板
+
+点击工具栏中的**模板**按钮可以从预设创建配置。内置模板:
+
+| 模板 | 平台 | 说明 |
+|------|------|------|
+| Facebook Playable | 可玩广告 | 针对 Facebook 2 MB 限制优化,启用代码压缩 |
+| Google Playable | 可玩广告 | 针对 Google 5 MB 限制优化 |
+| Playable Debug | 可玩广告 | 开发构建,带 `DEBUG` 定义 |
+| WeChat Production | 微信小游戏 | 分包模式,竖屏方向 |
+| WeChat Debug | 微信小游戏 | 单包模式,带 `DEBUG` 定义 |
+| WeChat Single File | 微信小游戏 | 单文件打包,适合简单游戏 |
+| WeChat Landscape | 微信小游戏 | 横屏方向,适合宽屏游戏 |
+
+你还可以在详情面板中通过**保存为预设**将任何现有配置保存为自定义模板。
+
## 构建配置
每个配置包含:
@@ -211,6 +227,160 @@ build/wechat/
}
```
+## 构建钩子
+
+每个配置可以定义**构建前**和**构建后**钩子来自动化自定义步骤。在配置详情面板的可折叠"构建钩子"区域添加钩子。每个钩子有一个**阶段**(`pre` 或 `post`)和一个**类型**(`copy-files` 或 `run-command`)。
+
+### 复制文件
+
+递归复制目录到另一个位置,可选按 glob 模式过滤文件。
+
+| 字段 | 说明 |
+|------|------|
+| **from** | 源目录路径 |
+| **to** | 目标目录路径 |
+| **pattern** | 可选的文件名过滤(如 `*.png`、`*.json`)——仅复制匹配的文件 |
+
+`from` 和 `to` 均支持路径变量:
+
+| 变量 | 解析为 |
+|------|--------|
+| `${projectDir}` | 项目根目录的绝对路径 |
+| `${outputPath}` | 输出文件的完整路径(如 `build/playable.html`) |
+| `${outputDir}` | 输出文件所在目录(如 `build/`) |
+
+### 运行命令
+
+以**项目根目录**为工作目录(`cwd`)执行 shell 命令。
+
+| 字段 | 说明 |
+|------|------|
+| **command** | 要运行的可执行程序(如 `node`、`python3`、`bash`) |
+| **args** | 可选的字符串参数数组,原样传递给命令 |
+
+命令接收到的信息:
+- **工作目录** — 项目根目录(与编辑器的项目路径相同)
+- **参数** — `args` 数组中的字面字符串(不做变量替换)
+- **标准输出/错误** — 被捕获并记录到构建控制台(标准输出截断为 200 字符)
+- **退出码** — 非零退出码将导致构建失败
+
+<Aside type="note">
+路径变量(`${projectDir}`、`${outputPath}` 等)**仅**在 `copy-files` 钩子中支持。对于 `run-command`,请在 `args` 中传递字面路径,或让脚本从配置文件/环境变量中读取。
+</Aside>
+
+### 钩子示例
+
+构建后将额外资源复制到微信输出目录:
+
+```json
+{
+ "phase": "post",
+ "type": "copy-files",
+ "config": {
+ "from": "${projectDir}/assets/extras",
+ "to": "${outputDir}/assets/extras",
+ "pattern": "*.png"
+ }
+}
+```
+
+构建前运行纹理压缩脚本(工作目录是项目根,所以相对路径可以直接使用):
+
+```json
+{
+ "phase": "pre",
+ "type": "run-command",
+ "config": {
+ "command": "node",
+ "args": ["scripts/compress-textures.js", "--input", "assets/textures", "--quality", "80"]
+ }
+}
+```
+
+脚本通过 `process.argv.slice(2)` 获取参数:
+
+```javascript
+// scripts/compress-textures.js
+const args = process.argv.slice(2);
+// args = ["--input", "assets/textures", "--quality", "80"]
+// process.cwd() = 项目根目录
+
+const inputDir = args[args.indexOf('--input') + 1]; // "assets/textures"
+const quality = args[args.indexOf('--quality') + 1]; // "80"
+```
+
+构建后将输出复制到部署目录:
+
+```json
+{
+ "phase": "post",
+ "type": "copy-files",
+ "config": {
+ "from": "${outputDir}",
+ "to": "${projectDir}/deploy"
+ }
+}
+```
+
+### 配置 JSON 格式
+
+构建配置存储在 `editor-state.json` 中。每个配置遵循以下结构:
+
+```json
+{
+ "id": "playable-prod",
+ "name": "Playable - Production",
+ "platform": "playable",
+ "scenes": ["assets/scenes/main.esscene"],
+ "defines": [],
+ "hooks": [
+ {
+ "phase": "post",
+ "type": "run-command",
+ "config": { "command": "open", "args": ["${outputDir}"] }
+ }
+ ],
+ "playableSettings": {
+ "startupScene": "assets/scenes/main.esscene",
+ "isDevelopment": false,
+ "minifyCode": true,
+ "embedFonts": true,
+ "outputPath": "build/playable.html",
+ "enableBuiltinCTA": false,
+ "ctaUrl": ""
+ }
+}
+```
+
+微信配置将 `playableSettings` 替换为 `wechatSettings`:
+
+```json
+{
+ "id": "wechat-prod",
+ "name": "WeChat - Production",
+ "platform": "wechat",
+ "scenes": ["assets/scenes/main.esscene"],
+ "defines": [],
+ "hooks": [],
+ "wechatSettings": {
+ "appId": "wx1234567890",
+ "version": "1.0.0",
+ "bundleMode": "subpackage",
+ "outputDir": "build/wechat",
+ "orientation": "portrait"
+ }
+}
+```
+
+## 配置导入与导出
+
+构建配置可以导出为 JSON 用于备份或团队共享:
+
+- **导出** — 点击工具栏中的导出按钮,将所有配置保存为 `.json` 文件
+- **导入** — 点击导入按钮,从之前导出的文件中加载配置
+
+通过**保存为预设**创建的自定义模板存储在 `.esengine/build-templates/` 目录下的 JSON 文件中,可以提交到版本控制中供团队共享。
+
## 项目设置
构建行为还受项目级设置的影响:
diff --git a/docs/astro/src/content/docs/zh/guides/playable-ads.mdx b/docs/astro/src/content/docs/zh/guides/playable-ads.mdx
index 820af23dc..8c3c35fe6 100644
--- a/docs/astro/src/content/docs/zh/guides/playable-ads.mdx
+++ b/docs/astro/src/content/docs/zh/guides/playable-ads.mdx
@@ -106,10 +106,12 @@ addStartupSystem(defineSystem([], () => {
未被启动场景引用的资源不会被包含。使用可寻址资源组并将导出模式设为 "always" 可以强制包含运行时动态加载的资源。
</Aside>
-## Spine 与物理支持
+## Spine、物理与音频支持
如果项目使用了 Spine 动画或 Box2D 物理,对应的 WASM 模块会被自动嵌入为 base64 并在运行时实例化。无需额外配置——构建会检测项目设置中是否启用了 Spine 或物理。
+`AudioSource` 组件引用的音频片段也会被自动嵌入并在运行时加载。内联的 `playSFX`/`playBGM` 调用和基于实体的 `AudioSource` 播放在单文件输出中均可正常工作。
+
## 体积优化
可玩广告网络通常有文件大小限制(2-5 MB)。以下是减小输出体积的建议: