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.1 changelog and update post-processing guide
esengine9a548b7ddacd
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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 testsdiff --git a/docs/astro/src/content/docs/guides/post-processing.mdx b/docs/astro/src/content/docs/guides/post-processing.mdxindex 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 WorkflowAdd a **PostProcessVolume** component to a Camera entity in the editor to configure effects visually:1. Select the Camera entity in the Hierarchy2. **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 slidersEffects 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.mdxnew file mode 100644index 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.mdxindex 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)` | 更新帧缓冲尺寸(自动调用) |