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
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.mjsindex 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.mdxnew file mode 100644index 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.mdxindex 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. WheUse **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 ConfigurationEach 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 SettingsBuild 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.mdxindex 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 SupportIf 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 OptimizationPlayable 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.mdxnew file mode 100644index 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.mdxindex 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.mdxindex 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)。以下是减小输出体积的建议: