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: rewrite the Post-processing guide to the complete-reference template
yhhecdf5f31bd39
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/guides/postprocess.mdxindex 1cb8292bb..641c4ea05 100644--- a/docs/astro/src/content/docs/guides/postprocess.mdx+++ b/docs/astro/src/content/docs/guides/postprocess.mdx@@ -1,42 +1,53 @@---title: Post-processing-description: Full-screen effects via the PostProcessVolume component.+description: The complete guide to full-screen effects — the PostProcessVolume component, the built-in effect library, and the programmatic PostProcess API.---import { Aside } from '@astrojs/starlight/components';Estella runs full-screen post-processing through ping-pong framebuffers. Add a-`PostProcessVolume` component — usually in the editor — enable the effects you-want, and tune their parameters in the inspector.+`PostProcessVolume` component, enable the effects you want, and tune their+parameters — in the editor or in code. Effects share the ping-pong buffers, so+several can stack in one frame at no extra target cost beyond the passes.## Built-in effects-| Effect | What it does |-|--------|--------------|-| `bloom` | Glow on bright areas (threshold + intensity) |-| `tonemap` | ACES tonemapping |-| `colorGrade` | Color grading |-| `vignette` | Darkened screen edges |-| `chromaticAberration` | RGB fringing |-| `blur` | Gaussian blur |-| `fxaa` | Fast anti-aliasing |-| `lensDistortion` | Barrel / pincushion distortion |-| `pixelate` | Pixelation |-| `grayscale` | Desaturate |+| Effect | What it does | Key uniforms |+|---|---|---|+| `bloom` | Glow on bright areas | `threshold`, `intensity` |+| `tonemap` | ACES filmic tonemapping | `exposure` |+| `colorGrade` | Exposure / contrast / saturation / white balance | `exposure`, `contrast`, `saturation`, `temperature`, `tint` |+| `vignette` | Darkened screen edges | `intensity`, `radius` |+| `chromaticAberration` | RGB fringing | `intensity` |+| `blur` | Gaussian blur | `radius` |+| `fxaa` | Fast anti-aliasing | `intensity` |+| `lensDistortion` | Barrel / pincushion warp | `strength`, `zoom` |+| `pixelate` | Block quantization | `pixelSize` |+| `grayscale` | Desaturate | — |-Each effect exposes tunable uniforms (for example bloom's `threshold` and-`intensity`) in the inspector.+Every effect is a no-op at its default values, so adding one to a stack doesn't+change the image until you dial it in.-## Using a volume+## Using a `PostProcessVolume`-Add a `PostProcessVolume`, enable the effects, and set their parameters. Volumes-**blend where they overlap**, so you can drive effects by area or fade them in-over a transition.+Add a `PostProcessVolume`, enable effects, and set their parameters. Volumes+**blend where they overlap**, so you can drive effects by area (a "underwater"+volume) or fade them in over a transition.++| Property | Type | Default | Description |+|---|---|---|---|+| `effects` | list | `[]` | `{ type, enabled, uniforms }` per effect. |+| `isGlobal` | boolean | `true` | Apply everywhere vs. only inside the volume shape. |+| `shape` | `'box' \| 'sphere'` | `'box'` | Bounds shape for a local volume. |+| `size` | Vec2 | `{5, 5}` | Volume extents (local volumes). |+| `priority` | number | `0` | Higher-priority volumes win where they overlap. |+| `weight` | number | `1` | Blend weight, 0..1 (fade the whole volume). |+| `blendDistance` | number | `0` | Falloff distance at the volume edge. |## Programmatic control-For a custom pipeline, read the `PostProcess` resource — create a stack and bind-it to a camera:+For a custom pipeline, read the `PostProcess` resource — create a stack, tune it,+and bind it to a camera:```typescriptimport { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';@@ -44,13 +55,37 @@ import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {for (const [camera] of q) {const stack = pp.createStack();+ stack.setEnabled('bloom', true)+ .setUniform('bloom', 'intensity', 1.2)+ .setUniform('bloom', 'threshold', 0.8);pp.bind(camera, stack); // pp.unbind(camera) to remove}});```+| Method | Description |+|---|---|+| `PostProcess.createStack()` | Create an effect stack. |+| `PostProcess.bind(camera, stack)` | Attach a stack to a camera. |+| `PostProcess.unbind(camera)` | Remove the camera's stack. |+| `stack.setEnabled(name, on)` | Enable/disable an effect (chainable). |+| `stack.setUniform(pass, uniform, value)` | Set an effect parameter (chainable). |++## Best practices++- **Order matters** — effects run in registration order and share the buffers, so+ a sensible chain is bloom → tonemap → color grade → vignette.+- **Use volumes for locality** (an area's mood) and the `PostProcess` API for a+ fixed camera pipeline.+- **Fade with `weight`** on a volume for smooth transitions instead of toggling.+- **Keep the stack short** on low-end/mobile — each pass is a full-screen draw.+<Aside type="note">- Effects run in registration order and share the ping-pong buffers, so several- can stack in one frame (e.g. bloom → tonemap → vignette) at no extra target- cost beyond the passes themselves.+ Effects are pure-GLSL and data-driven from a registry, so the editor and runtime+ share one list — there's no hard-coded effect set to drift.</Aside>++## See also++- [Materials & Shaders](/docs/guides/material/) — per-object shaders (a separate path).+- [Camera](/docs/guides/camera/) — bind a stack per camera.diff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdxindex 174cb60a8..efd4cb840 100644--- a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx@@ -1,38 +1,49 @@---title: 后处理-description: 通过 PostProcessVolume 组件实现全屏效果。+description: 全屏效果的完整指南——PostProcessVolume 组件、内置效果库,以及程序化的 PostProcess API。---import { Aside } from '@astrojs/starlight/components';-Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcessVolume` 组件——通常-在编辑器里——启用你想要的效果,并在检视面板里调参数。+Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcessVolume` 组件,启用你要的+效果,并调节它们的参数——在编辑器里或用代码。效果共享 ping-pong 缓冲,所以多个可以在一帧里+叠加,除各遍(pass)本身外没有额外的目标开销。## 内置效果-| 效果 | 作用 |-|------|------|-| `bloom` | 高亮区域泛光(阈值 + 强度)|-| `tonemap` | ACES 色调映射 |-| `colorGrade` | 调色 |-| `vignette` | 屏幕边缘压暗 |-| `chromaticAberration` | RGB 色散 |-| `blur` | 高斯模糊 |-| `fxaa` | 快速抗锯齿 |-| `lensDistortion` | 桶形 / 枕形畸变 |-| `pixelate` | 像素化 |-| `grayscale` | 去色 |+| 效果 | 作用 | 关键 uniform |+|---|---|---|+| `bloom` | 亮部辉光 | `threshold`、`intensity` |+| `tonemap` | ACES filmic 色调映射 | `exposure` |+| `colorGrade` | 曝光 / 对比度 / 饱和度 / 白平衡 | `exposure`、`contrast`、`saturation`、`temperature`、`tint` |+| `vignette` | 屏幕边缘变暗 | `intensity`、`radius` |+| `chromaticAberration` | RGB 色散 | `intensity` |+| `blur` | 高斯模糊 | `radius` |+| `fxaa` | 快速抗锯齿 | `intensity` |+| `lensDistortion` | 桶形 / 枕形畸变 | `strength`、`zoom` |+| `pixelate` | 块状量化 | `pixelSize` |+| `grayscale` | 去色 | — |-每个效果都在检视面板里暴露可调 uniform(例如 bloom 的 `threshold` 与 `intensity`)。+每个效果在默认值下都是恒等(no-op),所以把它加进栈里、在你调参之前不会改变画面。-## 使用体积(Volume)+## 使用 `PostProcessVolume`-加一个 `PostProcessVolume`,启用效果并设定参数。多个体积**重叠时会混合**,因此你可以-按区域驱动效果,或在过渡中淡入。+加一个 `PostProcessVolume`,启用效果,设置参数。体积**在重叠处混合**,所以你可以按区域驱动+效果(比如一个"水下"体积),或在过渡中淡入。-## 代码控制+| 属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `effects` | list | `[]` | 每个效果的 `{ type, enabled, uniforms }`。 |+| `isGlobal` | boolean | `true` | 全局应用 vs 仅在体积形状内。 |+| `shape` | `'box' \| 'sphere'` | `'box'` | 局部体积的边界形状。 |+| `size` | Vec2 | `{5, 5}` | 体积范围(局部体积)。 |+| `priority` | number | `0` | 重叠处优先级高者胜。 |+| `weight` | number | `1` | 混合权重,0..1(淡化整个体积)。 |+| `blendDistance` | number | `0` | 体积边缘的衰减距离。 |-要自定义管线,读取 `PostProcess` 资源——创建一个 stack 并绑定到相机:+## 程序化控制++自定义管线时,读 `PostProcess` 资源——创建一个栈、调参,并绑定到相机:```typescriptimport { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';@@ -40,12 +51,34 @@ import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {for (const [camera] of q) {const stack = pp.createStack();- pp.bind(camera, stack); // pp.unbind(camera) 可移除+ stack.setEnabled('bloom', true)+ .setUniform('bloom', 'intensity', 1.2)+ .setUniform('bloom', 'threshold', 0.8);+ pp.bind(camera, stack); // pp.unbind(camera) to remove}});```+| 方法 | 说明 |+|---|---|+| `PostProcess.createStack()` | 创建一个效果栈。 |+| `PostProcess.bind(camera, stack)` | 把栈附加到相机。 |+| `PostProcess.unbind(camera)` | 移除相机的栈。 |+| `stack.setEnabled(name, on)` | 启用/禁用一个效果(可链式)。 |+| `stack.setUniform(pass, uniform, value)` | 设置一个效果参数(可链式)。 |++## 最佳实践++- **顺序有讲究**——效果按注册顺序运行并共享缓冲,合理的链是 bloom → tonemap → 调色 → vignette。+- **用体积做局部**(某区域的氛围),用 `PostProcess` API 做固定的相机管线。+- 过渡时**用 `weight` 淡化**体积,而不是硬开关。+- 低端/移动端**让栈保持简短**——每一遍都是一次全屏绘制。+<Aside type="note">- 效果按注册顺序运行并共享 ping-pong 缓冲,所以多个效果可以在一帧里叠加(例如- bloom → tonemap → vignette),除了各自的 pass 之外不产生额外的渲染目标开销。+ 效果是纯 GLSL、由注册表数据驱动的,所以编辑器和运行时共用一份列表——没有会漂移的硬编码效果集。</Aside>++## 参见++- [材质与着色器](/docs/zh-cn/guides/material/) —— 逐物体着色器(独立的路径)。+- [相机](/docs/zh-cn/guides/camera/) —— 为每个相机绑定一个栈。