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.1 changelog and update post-processing guide

esengine9a548b7ddacd
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 5a86d20b8..858038194 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -138,6 +138,7 @@ export default defineConfig({
label: 'Changelog',
translations: { 'zh-CN': '更新日志' },
items: [
+ { label: 'v0.8.1', slug: 'changelog-v081' },
{ label: 'v0.8.0', slug: 'changelog-v080' },
{ label: 'v0.7.0', slug: 'changelog-v070' },
{ label: 'v0.6.2', slug: 'changelog-v062' },
diff --git a/docs/astro/src/content/docs/changelog-v081.mdx b/docs/astro/src/content/docs/changelog-v081.mdx
new file mode 100644
index 000000000..083d06381
--- /dev/null
+++ b/docs/astro/src/content/docs/changelog-v081.mdx
@@ -0,0 +1,100 @@
+---
+title: v0.8.1
+description: ESEngine v0.8.1 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.1 adds a volume-based post-processing system with spatial blending, screen-level effects, a Tiled map loader, and physics debug drawing.
+</Aside>
+
+## Volume-Based Post-Processing
+
+The post-processing pipeline is now three-layered: **Screen → Camera → Volume**, matching industry-standard workflows (similar to Unity/Unreal Post Process Volumes).
+
+### PostProcessVolume Component
+
+The `PostProcessVolume` component now supports spatial fields beyond just the effects list:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `isGlobal` | boolean | `true` | When true, the volume applies everywhere regardless of shape |
+| `shape` | `'box' \| 'sphere'` | `'box'` | Trigger region shape (only used when `isGlobal` is false) |
+| `size` | `{ x, y }` | `{ x: 5, y: 5 }` | Half-extents for box / radius for sphere |
+| `priority` | number | `0` | Higher priority volumes override lower ones |
+| `weight` | number | `1` | Blend weight (0–1) |
+| `blendDistance` | number | `0` | Edge fade distance in world units |
+
+### Volume Blending System
+
+When multiple volumes overlap, they are blended by priority. The system evaluates each volume's spatial influence using SDF (Signed Distance Field) distance functions:
+
+- **Box volumes** — axis-aligned box SDF with configurable half-extents
+- **Sphere volumes** — radial distance with configurable radius
+- **Blend distance** — smooth fade-in at volume edges based on distance
+
+### Screen Post-Processing
+
+A new screen-level post-processing layer applies effects after all cameras have rendered:
+
+```typescript
+import { PostProcess } from 'esengine';
+
+const screenFx = PostProcess.createStack();
+screenFx.addPass('vignette', PostProcess.createVignette());
+screenFx.setUniform('vignette', 'u_intensity', 0.8);
+
+PostProcess.setScreenStack(screenFx); // applies to final composited image
+```
+
+| Method | Description |
+|--------|-------------|
+| `PostProcess.setScreenStack(stack)` | Set the screen-level effect stack (pass `null` to clear) |
+| `PostProcess.screenStack` | Get the current screen stack |
+
+### PostProcessPlugin
+
+Post-processing is now a standard plugin, automatically included in `createWebApp()`. It registers the volume blending system and handles cleanup:
+
+```typescript
+import { postProcessPlugin } from 'esengine';
+// Already included in createWebApp() — no manual setup needed
+```
+
+### Editor Support
+
+The PostProcessVolume inspector now exposes all volume fields:
+
+- **Is Global** checkbox — toggle between global and spatial mode
+- **Priority** — integer input for volume ordering
+- **Weight** — float slider (0–1)
+- **Shape** dropdown — Box or Sphere (visible when not global)
+- **Size** — Vec2 editor for spatial extent (visible when not global)
+- **Blend Distance** — fade distance at volume edges (visible when not global)
+
+## Tilemap System
+
+New Tiled map loader and tilemap rendering pipeline with full editor integration.
+
+- **Tiled JSON loader** — load `.tmj` / `.json` Tiled maps with automatic tileset texture resolution
+- **Tilemap components** — `Tilemap` and `TilemapLayer` components for ECS integration
+- **Collision merge** — automatic rectangular collision region merging for physics optimization
+- **Editor support** — Tilemap component inspector with asset picker
+
+## Physics Debug Draw
+
+- **`PhysicsDebugDraw`** — visual overlay for physics colliders, joints, and contacts in the editor and at runtime
+- Renders wireframe outlines for box, circle, and capsule colliders
+
+## Bug Fixes
+
+- Fix CSP blocking `blob:` URL fetch for esbuild WASM initialization — add `connect-src 'self' blob:` to Tauri security policy
+- Fix tilemap texture handle resolution and Y-axis rendering
+- Fix tilemap and audio asset prefetch in preview runtime loader
+- Fix particle guide code examples to match SDK API
+
+## Testing
+
+- Add volume blending unit tests (SDF distance, factor computation, priority-based blending)
+- Add PostProcessPlugin lifecycle tests
diff --git a/docs/astro/src/content/docs/guides/post-processing.mdx b/docs/astro/src/content/docs/guides/post-processing.mdx
index d518706c0..7e92c1aef 100644
--- a/docs/astro/src/content/docs/guides/post-processing.mdx
+++ b/docs/astro/src/content/docs/guides/post-processing.mdx
@@ -149,14 +149,74 @@ fx.setUniform('chromatic', 'u_intensity', 2.0);
PostProcess.bind(cameraEntity, fx);
```
+## Screen Post-Processing
+
+Screen-level effects apply after all cameras have rendered, affecting the final composited image. This is useful for global effects like fade-to-black, full-screen vignette, or cinematic letterboxing.
+
+```typescript
+import { PostProcess } from 'esengine';
+
+const screenFx = PostProcess.createStack();
+screenFx.addPass('vignette', PostProcess.createVignette());
+screenFx.setUniform('vignette', 'u_intensity', 0.8);
+
+// Apply to the final composited image (after all cameras)
+PostProcess.setScreenStack(screenFx);
+
+// Remove screen effects
+PostProcess.setScreenStack(null);
+```
+
+<Aside type="note">
+ Screen effects run after all camera effects. The processing order is: Camera PostProcess → Screen PostProcess.
+</Aside>
+
+## Post-Process Volumes
+
+Volumes allow spatial post-processing — effects that activate when the camera enters a region. Multiple volumes blend by priority, similar to Unity's Post Process Volumes.
+
+### Volume Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `isGlobal` | boolean | `true` | Applies everywhere regardless of shape |
+| `shape` | `'box' \| 'sphere'` | `'box'` | Trigger region shape |
+| `size` | `{ x, y }` | `{ x: 5, y: 5 }` | Half-extents (box) or radius (sphere) |
+| `priority` | number | `0` | Higher priority overrides lower |
+| `weight` | number | `1` | Blend weight (0–1) |
+| `blendDistance` | number | `0` | Smooth fade distance at edges (world units) |
+
+### Volume Blending
+
+When multiple volumes overlap, the system evaluates each volume's influence using SDF distance functions and blends their effects by priority:
+
+```typescript
+// Global volume — always active, low priority (base layer)
+// Entity A: PostProcessVolume with isGlobal=true, priority=0
+// effects: [{ type: 'vignette', enabled: true, uniforms: { u_intensity: 0.3 } }]
+
+// Local volume — activates when camera enters the region
+// Entity B: PostProcessVolume with isGlobal=false, shape='sphere', size={x:10,y:10}
+// priority=1, blendDistance=3
+// effects: [{ type: 'blur', enabled: true, uniforms: { u_intensity: 5.0 } }]
+```
+
+<Aside type="tip">
+ Use `blendDistance` to create smooth transitions. A value of 0 means instant on/off; higher values create a gradual fade as the camera approaches the volume boundary.
+</Aside>
+
## Editor Workflow
Add a **PostProcessVolume** component to a Camera entity in the editor to configure effects visually:
1. Select the Camera entity in the Hierarchy
2. **Add Component** → **PostProcessVolume**
-3. Click **Add Effect** and choose from the built-in effects
-4. Adjust parameters with the sliders
+3. Configure volume properties:
+ - **Is Global** — check for scene-wide effects, uncheck for spatial volumes
+ - **Priority** / **Weight** — control blending order and strength
+ - **Shape** / **Size** / **Blend Distance** — define the spatial trigger region (when not global)
+4. Click **Add Effect** and choose from the built-in effects
+5. Adjust parameters with the sliders
Effects are visible in both the Scene View and the Game View. The component data is saved with the scene file.
@@ -245,6 +305,8 @@ PostProcess.bind(minimapCamera, minimapFx);
| `PostProcess.bind(camera, stack)` | Bind a stack to a camera |
| `PostProcess.unbind(camera)` | Unbind the stack from a camera |
| `PostProcess.getStack(camera)` | Get the bound stack (or null) |
+| `PostProcess.setScreenStack(stack)` | Set the screen-level effect stack (pass `null` to clear) |
+| `PostProcess.screenStack` | Get the current screen stack |
| `PostProcess.init(width, height)` | Initialize the pipeline (called automatically) |
| `PostProcess.shutdown()` | Shut down the pipeline |
| `PostProcess.resize(width, height)` | Update framebuffer size (called automatically) |
diff --git a/docs/astro/src/content/docs/zh/changelog-v081.mdx b/docs/astro/src/content/docs/zh/changelog-v081.mdx
new file mode 100644
index 000000000..5267849d5
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/changelog-v081.mdx
@@ -0,0 +1,100 @@
+---
+title: v0.8.1
+description: ESEngine v0.8.1 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.1 新增基于 Volume 的后处理系统(空间混合)、屏幕级后处理、Tiled 地图加载器和物理调试绘制。
+</Aside>
+
+## Volume 后处理系统
+
+后处理管线升级为三层架构:**Screen → Camera → Volume**,对齐业界标准工作流(类似 Unity/Unreal 的 Post Process Volume)。
+
+### PostProcessVolume 组件扩展
+
+`PostProcessVolume` 组件新增空间属性:
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `isGlobal` | boolean | `true` | 为 true 时忽略形状,全局生效 |
+| `shape` | `'box' \| 'sphere'` | `'box'` | 触发区域形状(仅 `isGlobal` 为 false 时有效) |
+| `size` | `{ x, y }` | `{ x: 5, y: 5 }` | Box 半尺寸 / Sphere 半径 |
+| `priority` | number | `0` | 高优先级覆盖低优先级 |
+| `weight` | number | `1` | 混合权重(0–1) |
+| `blendDistance` | number | `0` | 边缘渐入距离(世界单位) |
+
+### Volume 混合系统
+
+多个 Volume 重叠时按优先级混合。系统使用 SDF(符号距离场)函数评估每个 Volume 的空间影响:
+
+- **Box Volume** — 轴对齐盒体 SDF,可配置半尺寸
+- **Sphere Volume** — 径向距离,可配置半径
+- **渐入距离** — 基于距离的边缘平滑过渡
+
+### 屏幕级后处理
+
+新增屏幕级后处理层,在所有相机渲染完成后对合成结果应用效果:
+
+```typescript
+import { PostProcess } from 'esengine';
+
+const screenFx = PostProcess.createStack();
+screenFx.addPass('vignette', PostProcess.createVignette());
+screenFx.setUniform('vignette', 'u_intensity', 0.8);
+
+PostProcess.setScreenStack(screenFx); // 对最终合成画面生效
+```
+
+| 方法 | 说明 |
+|------|------|
+| `PostProcess.setScreenStack(stack)` | 设置屏幕级效果栈(传 `null` 清除) |
+| `PostProcess.screenStack` | 获取当前屏幕级效果栈 |
+
+### PostProcessPlugin
+
+后处理系统封装为标准 Plugin,自动包含在 `createWebApp()` 中,注册 Volume 混合系统并处理清理:
+
+```typescript
+import { postProcessPlugin } from 'esengine';
+// 已自动包含在 createWebApp() 中,无需手动设置
+```
+
+### 编辑器支持
+
+PostProcessVolume 检查器新增所有 Volume 属性编辑:
+
+- **Is Global** 复选框 — 切换全局/空间模式
+- **Priority** — 整数输入,用于 Volume 排序
+- **Weight** — 浮点滑块(0–1)
+- **Shape** 下拉框 — Box 或 Sphere(非全局时显示)
+- **Size** — Vec2 编辑器,空间范围(非全局时显示)
+- **Blend Distance** — 边缘渐入距离(非全局时显示)
+
+## Tilemap 系统
+
+新增 Tiled 地图加载器和瓦片地图渲染管线,完整编辑器集成。
+
+- **Tiled JSON 加载器** — 加载 `.tmj` / `.json` 格式的 Tiled 地图,自动解析 tileset 纹理
+- **Tilemap 组件** — `Tilemap` 和 `TilemapLayer` 组件用于 ECS 集成
+- **碰撞合并** — 自动矩形碰撞区域合并,优化物理性能
+- **编辑器支持** — Tilemap 组件检查器,带资源选择器
+
+## 物理调试绘制
+
+- **`PhysicsDebugDraw`** — 物理碰撞体、关节和接触点的可视化叠加层,编辑器和运行时均可使用
+- 渲染 Box、Circle 和 Capsule 碰撞体的线框轮廓
+
+## Bug 修复
+
+- 修复 CSP 阻止 `blob:` URL 请求导致 esbuild WASM 初始化失败 — 在 Tauri 安全策略中添加 `connect-src 'self' blob:`
+- 修复 Tilemap 纹理句柄解析和 Y 轴渲染
+- 修复预览运行时加载器中 Tilemap 和音频资源的预加载
+- 修复粒子系统指南代码示例与 SDK API 不匹配
+
+## 测试
+
+- 新增 Volume 混合单元测试(SDF 距离、因子计算、优先级混合)
+- 新增 PostProcessPlugin 生命周期测试
diff --git a/docs/astro/src/content/docs/zh/guides/post-processing.mdx b/docs/astro/src/content/docs/zh/guides/post-processing.mdx
index 76a2b5d3f..5adf70c42 100644
--- a/docs/astro/src/content/docs/zh/guides/post-processing.mdx
+++ b/docs/astro/src/content/docs/zh/guides/post-processing.mdx
@@ -149,14 +149,74 @@ fx.setUniform('chromatic', 'u_intensity', 2.0);
PostProcess.bind(cameraEntity, fx);
```
+## 屏幕级后处理
+
+屏幕级效果在所有相机渲染完成后应用于最终合成画面,适用于全局渐变、全屏暗角、电影黑边等效果。
+
+```typescript
+import { PostProcess } from 'esengine';
+
+const screenFx = PostProcess.createStack();
+screenFx.addPass('vignette', PostProcess.createVignette());
+screenFx.setUniform('vignette', 'u_intensity', 0.8);
+
+// 对最终合成画面应用效果(在所有相机之后)
+PostProcess.setScreenStack(screenFx);
+
+// 移除屏幕效果
+PostProcess.setScreenStack(null);
+```
+
+<Aside type="note">
+ 屏幕效果在所有相机效果之后执行。处理顺序:Camera PostProcess → Screen PostProcess。
+</Aside>
+
+## 后处理 Volume
+
+Volume 允许空间后处理 — 当相机进入指定区域时激活效果。多个 Volume 按优先级混合,类似 Unity 的 Post Process Volume。
+
+### Volume 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `isGlobal` | boolean | `true` | 为 true 时忽略形状,全局生效 |
+| `shape` | `'box' \| 'sphere'` | `'box'` | 触发区域形状 |
+| `size` | `{ x, y }` | `{ x: 5, y: 5 }` | Box 半尺寸 / Sphere 半径 |
+| `priority` | number | `0` | 高优先级覆盖低优先级 |
+| `weight` | number | `1` | 混合权重(0–1) |
+| `blendDistance` | number | `0` | 边缘渐入距离(世界单位) |
+
+### Volume 混合
+
+当多个 Volume 重叠时,系统使用 SDF 距离函数评估每个 Volume 的影响范围,按优先级混合效果参数:
+
+```typescript
+// 全局 Volume — 始终生效,低优先级(基础层)
+// 实体 A: PostProcessVolume,isGlobal=true,priority=0
+// effects: [{ type: 'vignette', enabled: true, uniforms: { u_intensity: 0.3 } }]
+
+// 局部 Volume — 相机进入区域时激活
+// 实体 B: PostProcessVolume,isGlobal=false,shape='sphere',size={x:10,y:10}
+// priority=1,blendDistance=3
+// effects: [{ type: 'blur', enabled: true, uniforms: { u_intensity: 5.0 } }]
+```
+
+<Aside type="tip">
+ 使用 `blendDistance` 创建平滑过渡。值为 0 表示立即开关;值越大,相机接近 Volume 边界时过渡越平滑。
+</Aside>
+
## 编辑器工作流
在编辑器中为 Camera 实体添加 **PostProcessVolume** 组件即可可视化配置效果:
1. 在 Hierarchy 中选中 Camera 实体
2. **添加组件** → **PostProcessVolume**
-3. 点击 **添加效果** 并从内置效果列表中选择
-4. 使用滑块调整参数
+3. 配置 Volume 属性:
+ - **Is Global** — 勾选为全局效果,取消勾选为空间触发
+ - **Priority** / **Weight** — 控制混合顺序和强度
+ - **Shape** / **Size** / **Blend Distance** — 定义空间触发区域(非全局时可见)
+4. 点击 **添加效果** 并从内置效果列表中选择
+5. 使用滑块调整参数
效果在场景视图和游戏视图中都可见。组件数据随场景文件保存。
@@ -245,6 +305,8 @@ PostProcess.bind(minimapCamera, minimapFx);
| `PostProcess.bind(camera, stack)` | 将 Stack 绑定到相机 |
| `PostProcess.unbind(camera)` | 解绑相机的 Stack |
| `PostProcess.getStack(camera)` | 获取已绑定的 Stack(无则返回 null) |
+| `PostProcess.setScreenStack(stack)` | 设置屏幕级效果栈(传 `null` 清除) |
+| `PostProcess.screenStack` | 获取当前屏幕级效果栈 |
| `PostProcess.init(width, height)` | 初始化管线(自动调用) |
| `PostProcess.shutdown()` | 关闭管线 |
| `PostProcess.resize(width, height)` | 更新帧缓冲尺寸(自动调用) |