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.

feat(render): puddles gather in the low places of the ground and thin on its rises

yhh383bc8ffaa62
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cda69c28e..102e7e834 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,7 +19,7 @@ published separately; it ships inside the editor.
- **Weather.** A Weather component puts a scene under clear, mist, overcast, rain or storm, turns between them and cycles by itself. A preset is a set of multipliers of what the scene already has — the sun at a fraction of its strength, the fog thicker, the picture greyer — plus absolute levels for rain and wetness, so one preset fits any project. The component drives the directional and ambient lights (in play mode only), the effects the scene's volumes resolve (Height Fog, Rain, Screen Space Reflections, Colour Grade, Auto Exposure), and takes `registerWeatherPreset` for weathers of a project's own. Volumes whose effects differ only in numbers now write the numbers into the passes they have instead of rebuilding them. Reflection probes follow the weather: the ambient light scales what baked probes show and how much colour they keep. The Ambient `Light` gains `reflectionScale` and `reflectionSaturation`, which the weather drives.
- **Quality levels are edited in Settings.** Settings → Project → Rendering edits each quality level, including which effects it runs. **Editing level** picks Low, Medium or High and the groups below — Rendering (render scale, minimum scale, MSAA), Shadows, Reflections and particles, Post-processing — show and change that level, so a level is read the way Unity's Quality page reads: a level, then its settings by subsystem. Post-processing lists every effect the engine has, ticked where the level runs it; an unticked one is skipped at that level wherever a camera's volume asks for it, with all of its passes. Device rules — the model, GPU, memory and core conditions Auto chooses a level by — are a table, shown when the mode is Auto, that says so on a row with no condition instead of dropping it while it is typed. Only what you change is saved to `project.esproject`, as a difference to that level, so an engine default that improves later still reaches a project that never touched it; a row's "changed" mark and reset follow the default of the level it is showing. The old per-level shadow distance rows are the Shadows group's Distance now. The effects a level leaves out had been matched by the prefix of a pass's name, which found none of Auto Exposure's passes; they are now matched by effect type. A new Quality Levels page in the performance docs describes it.
- **A G-buffer, and reflections that read it.** Reflections now know how rough and how metal each surface is, from a G-buffer the frame draws on request. A post-process shader that says `#pragma gbuffer` makes the scene target carry a second RGBA8 colour attachment, written in the same pass by the scene's own shaders — octahedral normal in `r`/`g`, roughness in `b`, metalness in `a` (0 where nothing wrote) — and finds it at `u_gbuffer`. A frame whose chain has no such effect makes none and compiles no variant. The render device grew multiple colour attachments for it on both backends: WebGL2 attaches and resolves a second target and sets the draw buffers per pipeline, and WebGPU declares the second target on every pipeline of the pass (written by the ones that write it, an empty write mask for the rest), clears it to zero and resolves it with the colour. Pipelines say whether they write it (`PipelineDesc::gbuffer`), a blended draw never does, and the second output is its own shader variant (`ES_GBUFFER`), so no pass pays for what it did not ask for. The built-in Model shader — what an imported glTF material becomes — writes it from the material's roughness, metalness and normal map. `ssr` reads it: it takes the surface's own normal (normal-map detail that depth cannot see), weighs and blurs the reflection by roughness, reflects a metal at nearly full strength where a dielectric reflects 4%, skips a surface rougher than `maxRoughness` before marching the ray, and takes the Rain effect's `wetness` as a film that smooths the ground. Where nothing wrote a record, it falls back to depth and the dielectric it has always assumed. Verified in the editor on both backends: of two floors that differ only in their material's roughness, the glossy one changes ten times the pixels the rough one does. Quality levels can also leave out expensive effects now: quality levels can now skip expensive post-process effects by name. A level's `skipEffects` lists the effects it leaves out, each named by its effect type (`ssr`, `taa`, `depthOfField`, `lightShafts`, `autoExposure`, …), and an effect leaves with all of its passes however they are named; a project's own list in its quality profile replaces the level's. By default low leaves out reflections, temporal anti-aliasing, depth of field and light shafts, and medium leaves out reflections and depth of field; high leaves out nothing. These defaults come from the work each effect does per pixel, not from a weak device: the editor's new `fx-cost` check measured every effect on Bistro at 2560×1600 on a fast desktop GPU, and none added more than about 6 ms (reflections ~5, bloom ~4, the example's whole eight-effect chain ~11, the rest within the ±3 ms the run drifts by), so the levels have not been checked against the hardware they are for. Screen-space reflections leave a surface that recorded nothing alone, plain meshes now record a rough dielectric, and a puddle reflects the sky and what lies off screen.
-- **Rain, wet ground and puddles.** A Rain post-process effect adds falling rain, wet ground, puddles and ripples. `rain` draws three layers of slanted streaks, each at its own distance so a nearer surface hides them and the sky does not; darkens the ground that faces up by `wetness`; lays ripples and splashes where drops land on a grid in the world, so they stay on the ground as the camera moves (ripples need `intensity` above 0: wet ground under no rain is still); and, by `puddles` and `puddleScale`, covers part of the flat ground with standing water that is darker and takes denser, clearer ripples. `ssr` takes the same two numbers and treats those pools as mirrors — flat, far more reflective than dry ground, and sharp — so the pools the rain darkens are the pools that reflect. The clock is `u_time * timeScale + phase`, so a capture can pin it. The rain is a screen-space layer, not particles that collide with the world, and a puddle is flat ground whatever it lies on. Verified in the editor on both backends: streaks light a dark sky and move between two moments, wet ground reads darker, standing water darker still, and puddles change the reflection.
+- **Rain, wet ground and puddles.** A Rain post-process effect adds falling rain, wet ground, puddles and ripples. `rain` draws three layers of slanted streaks, each at its own distance so a nearer surface hides them and the sky does not; darkens the ground that faces up by `wetness`; lays ripples and splashes where drops land on a grid in the world, so they stay on the ground as the camera moves (ripples need `intensity` above 0: wet ground under no rain is still); and, by `puddles` and `puddleScale`, covers part of the flat ground with standing water that is darker and takes denser, clearer ripples. `ssr` takes the same two numbers and treats those pools as mirrors — flat, far more reflective than dry ground, and sharp — so the pools the rain darkens are the pools that reflect. The clock is `u_time * timeScale + phase`, so a capture can pin it. The rain is a screen-space layer, not particles that collide with the world, and a puddle is flat ground whatever it lies on. Verified in the editor on both backends: streaks light a dark sky and move between two moments, wet ground reads darker, standing water darker still, and puddles change the reflection. Puddles gather in the low places of the ground and thin on its rises, read from the depth buffer. Three rings of depth taps measure the ground around a pixel, so pools gather against a kerb, in a dip and at the foot of a slope instead of lying on the world-space noise alone.
- **Auto Exposure and Depth of Field.** Auto Exposure and Depth of Field post-process effects are available. `autoExposure` measures the average log luminance of the picture (leaving out pixels darker than 2^-8, so a black backdrop does not open the exposure to its limit), turns it into the exposure that puts it at middle grey, and moves toward that over time from where the last frame left it — brighter faster than darker, per second, within `minEV` and `maxEV`, with a `bias` in stops. To keep the settled value between frames a post-process shader can now declare a `u_feedback` texture: the engine keeps that pass's last output, at the pass's own size, and binds it there, without shifting the picture the way `u_history` does. `depthOfField` blurs by distance from `focusDistance`, with a sharp slab of `focusRange`, a blur radius that grows with how far a surface is from focus up to `maxBlur`, and a gather that counts a neighbour only where its own blur reaches back, so a sharp object does not bleed into a blurred background. Verified in the editor on both backends: a dim scene brightens (mean 6.9 to 16.5) and a bright one darkens (30.7 to 20.4), a drop in light is first dark and then recovered over real time (5.2 then 15.8), and focusing close takes the squared edge energy down to 21% of the sharp frame.
- **Height Fog and Light Shafts.** Height Fog and Light Shafts post-process effects add atmosphere. `heightFog` is exponential height fog with a closed-form integral — no marching — so a valley fills and a hilltop clears, the horizon turns hazy while the zenith stays clear, and looking toward the sun the haze takes the sun's colour; sky pixels run through the same formula with a very long ray, and `skyFog` sets how much haze the sky keeps. `lightShafts` marches each pixel toward the sun's place on screen and counts how much of the way is open sky, leaving rays through whatever stands in front of the sun. The sun's direction is set on the effects (azimuth and elevation), not read from a light. Neither is a shadowed volume: fog is lit evenly. Both run on WebGL2 and WebGPU; with an output transform of None, a floor fully taken by the fog reads exactly the authored colour on both. Height Fog and Light Shafts follow the scene's own sun, and Height Fog can carry the sun's shadows as volumetric light. `followSun` (on by default) takes the sun from the first directional light that shines; `volumetric` walks the air in 24 steps against the sun's shadow map, so shadows are dark fog and gaps between them beams. A post-process shader can ask for the light block and shadow atlas with `#pragma lights`.
- **Screen Space Reflections.** A Screen Space Reflections post-process effect mirrors props in floors. Add `ssr` to a `PostProcessVolume`: with no G-buffer, the surface normal is rebuilt from the depth buffer, the reflected ray is marched through the world and projected back to the screen at every step, and a step landing just behind the visible surface is a hit, refined by bisection. The reflection is blended over the pixel by a Schlick Fresnel term — faint face-on, strong at a grazing angle — and blurred by how far the ray travelled, which stands in for roughness. `intensity`, `maxDistance`, `thickness` and `floorBias` are the settings; `floorBias` at 1 lets only up-facing surfaces reflect, since the chain does not know a material's roughness. What is off screen or in the sky is not reflected; the pixel is left as it was. It reads the same depth buffer as ambient occlusion, runs on WebGL2 and WebGPU alike, and its per-pixel start offset is meant to be averaged away by `taa`. Verified in the editor on a lit scene with both backends: the props appear in the floor they stand on and nothing else on screen changes.
diff --git a/desktop b/desktop
index 35230d91b..3dca8913c 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 35230d91bddb41467079e22a12375c982dd72778
+Subproject commit 3dca8913ca033b3a5153319df7fa615ce5a385c9
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index 11179eb34..4274a81ca 100644
--- a/docs/astro/src/content/docs/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx
@@ -56,15 +56,18 @@ stay on the ground when the camera moves. Ripples need drops: with `intensity` a
**Puddles** are standing water: `puddles` is how much of the flat ground is under it and `puddleScale` how big the
pools are, a world length. A pool is darker still, takes denser and clearer ripples, and no splashes. Where a puddle
-lies is a function of the world position alone, so it does not move with the camera. A puddle is also a *mirror*, and
+lies is a function of the world position and of the ground around it: the noise places the pools, and the depth buffer
+says which places are low — a point lower than the ground within a pool's reach holds more water, one on a rise holds
+less, and flat ground keeps the coverage it was given. Pools therefore gather against a kerb, in a dip and at the foot
+of a slope, and they do not move with the camera. A puddle is also a *mirror*, and
that is the reflections effect's part: give `ssr` the same `puddles` and `puddleScale` and the pools the rain
darkens are the pools that reflect — flat, whatever the ground under them, and far more reflective than a dry surface,
with a sharp reflection where a dry one is blurred. Wet ground in general is shinier than dry: raise `ssr`'s `intensity`
when it rains.
The clock is the game's. A capture that has to be the same on every run sets `timeScale` to 0 and `phase` to the time it
-wants. What this is not: it does not know a material's roughness or the real shape of the ground, so a puddle is
-a patch of flat ground whatever it lies on, and the rain is a screen-space layer, not particles that collide with the world.
+wants. What this is not: the ground's shape is read from what the camera sees (a hollow behind a wall is not known),
+and the rain is a screen-space layer, not particles that collide with the world.
### Auto exposure
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
index a682acb2b..b891aac17 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
@@ -49,12 +49,12 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
小而快的冠状溅起),它们排布在世界里的网格上,所以相机移动时仍留在地面上。涟漪需要雨滴:`intensity` 为 0 时地面潮湿但静止。
**水坑**是积水:`puddles` 是多少平地被水覆盖,`puddleScale` 是水坑多大(世界长度)。水坑更暗,涟漪更密更清晰,没有水花。
-水坑在哪里只取决于世界位置,所以不会随相机移动。水坑同时是一面**镜子**,这是反射效果的部分:给 `ssr` 同样的 `puddles` 与
+水坑在哪里取决于世界位置和周围的地面:噪声决定水坑的位置,深度缓冲说明哪些地方低——比一个水坑范围内的周围地面更低的点积水更多,在隆起上的点积水更少,平地保持给定的覆盖率。所以水坑会聚在路缘旁、凹处和坡脚,而且不会随相机移动。水坑同时是一面**镜子**,这是反射效果的部分:给 `ssr` 同样的 `puddles` 与
`puddleScale`,雨压暗的水坑就是会反射的水坑——不管下面是什么地面都是平的,反射比干燥表面强得多,且清晰,而干燥表面的反射是模糊的。
潮湿的地面整体比干燥的更亮泽:下雨时提高 `ssr` 的 `intensity`。
-时钟是游戏的。要在每次运行都相同的截图,把 `timeScale` 设为 0,`phase` 设为想要的时间。它不是什么:它不知道材质的粗糙度或地面真实的形状,
-所以水坑是一片平地,不管它落在什么上;雨是屏幕空间的一层,不是会与世界碰撞的粒子。
+时钟是游戏的。要在每次运行都相同的截图,把 `timeScale` 设为 0,`phase` 设为想要的时间。它不是什么:地面的形状是从相机看到的东西里读出来的(墙后面的凹处它不知道),
+雨是屏幕空间的一层,不是会与世界碰撞的粒子。
### 自动曝光
diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.ts
index 315da7aad..399e5af96 100644
--- a/sdk/src/postprocess/postProcessEffects.ts
+++ b/sdk/src/postprocess/postProcessEffects.ts
@@ -111,6 +111,60 @@ fn puddleMask(xz : vec2f, coverage : f32, scale : f32) -> f32 {
return smoothstep(t - 0.03, t + 0.03, n);
}`;
+/**
+ * Where water gathers. Standing water collects in the low places of a surface and is gone from its crowns, so the
+ * coverage the author asked for is not the same everywhere: it is measured against the ground around, three rings of eight
+ * depth taps whose reach is the size of a pool. A point lower than what surrounds it (by up to a rim's height) holds
+ * more of the water, one that stands above it holds less, and flat ground keeps the coverage it was given — where the
+ * noise alone decides which patch becomes a pool. Needs the depth helpers above it.
+ */
+const BASIN_GLSL = `
+float basinCoverage(ivec2 c, ivec2 size, vec3 P, float coverage, float scale) {
+ if (coverage <= 0.0) return 0.0;
+ // How big a pixel is in the world here, which says how many of them a pool's reach is.
+ float pixel = length(worldAt(c + ivec2(1, 0), size) - P);
+ float reach = scale * 1.2;
+ float r = clamp(reach / max(pixel, 1e-3), 3.0, 80.0);
+ // A rise this high is a rim: more than that is a wall or a prop, which is not what water gathers against.
+ float rim = reach * 0.12;
+ float sum = 0.0;
+ // Three rings, so a rise of any width between here and the edge of the reach has taps on it.
+ for (int k = 1; k <= 3; ++k) {
+ float rk = r * float(k) / 3.0;
+ for (int i = 0; i < 8; ++i) {
+ float a = (float(i) + 0.5 * float(k)) * 0.7853982;
+ ivec2 t = c + ivec2(floor(vec2(cos(a), sin(a)) * rk + 0.5));
+ if (depthAt(t, size) >= 1.0) continue;
+ float rise = worldAt(t, size).y - P.y;
+ sum += clamp(rise, -rim, rim) * step(abs(rise), reach);
+ }
+ }
+ float basin = clamp(sum / (24.0 * rim) * 3.0, -1.0, 1.0);
+ return clamp(coverage * (1.0 + 2.2 * basin), 0.0, 1.0);
+}`;
+
+const BASIN_WGSL = `
+fn basinCoverage(c : vec2i, size : vec2i, P : vec3f, coverage : f32, scale : f32) -> f32 {
+ if (coverage <= 0.0) { return 0.0; }
+ let pixel = length(worldAt(c + vec2i(1, 0), size) - P);
+ let reach = scale * 1.2;
+ let r = clamp(reach / max(pixel, 1e-3), 3.0, 80.0);
+ let rim = reach * 0.12;
+ var sum = 0.0;
+ for (var k : i32 = 1; k <= 3; k = k + 1) {
+ let rk = r * f32(k) / 3.0;
+ for (var i : i32 = 0; i < 8; i = i + 1) {
+ let a = (f32(i) + 0.5 * f32(k)) * 0.7853982;
+ let t = c + vec2i(floor(vec2f(cos(a), sin(a)) * rk + 0.5));
+ if (depthAt(t, size) >= 1.0) { continue; }
+ let rise = worldAt(t, size).y - P.y;
+ sum = sum + clamp(rise, -rim, rim) * select(0.0, 1.0, abs(rise) <= reach);
+ }
+ }
+ let basin = clamp(sum / (24.0 * rim) * 3.0, -1.0, 1.0);
+ return clamp(coverage * (1.0 + 2.2 * basin), 0.0, 1.0);
+}`;
+
/**
* Reading the scene's surface record, in both languages: what each pixel IS, as the scene's own shaders
* wrote it beside the colour — octahedral normal in rg, roughness in b, metalness in a (a is 0 where nothing
@@ -535,6 +589,7 @@ out vec4 fragColor;
${SSAO_GLSL}
${PUDDLE_GLSL}
+${BASIN_GLSL}
${GBUFFER_GLSL}
${ENV_GLSL}
${GLSL}
@@ -578,7 +633,7 @@ void main() {
float flatUp = smoothstep(0.86, 0.95, N.y);
float puddle = 0.0;
if (u_puddles > 0.0) {
- puddle = puddleMask(P.xz, u_puddles, u_puddleScale) * flatUp;
+ puddle = puddleMask(P.xz, basinCoverage(c, size, P, u_puddles, u_puddleScale), u_puddleScale) * flatUp;
N = normalize(mix(N, vec3(0.0, 1.0, 0.0), puddle));
}
// Wet ground is smoother than dry: a film of water fills the pores a rough surface scatters from.
@@ -669,6 +724,7 @@ void main() {
#pragma fragment wgsl
${SSAO_WGSL}
${PUDDLE_WGSL}
+${BASIN_WGSL}
${GBUFFER_WGSL}
${ENV_WGSL}
${WGSL}
@@ -705,7 +761,7 @@ ${WGSL}
let flatUp = smoothstep(0.86, 0.95, N.y);
var puddle = 0.0;
if (mc.u_puddles > 0.0) {
- puddle = puddleMask(P.xz, mc.u_puddles, mc.u_puddleScale) * flatUp;
+ puddle = puddleMask(P.xz, basinCoverage(c, size, P, mc.u_puddles, mc.u_puddleScale), mc.u_puddleScale) * flatUp;
N = normalize(mix(N, vec3f(0.0, 1.0, 0.0), puddle));
}
rough = mix(rough, rough * 0.35, mc.u_wetness * flatUp);
@@ -2163,6 +2219,7 @@ out vec4 fragColor;
${SSAO_GLSL}
${PUDDLE_GLSL}
+${BASIN_GLSL}
${GLSL}
void main() {
@@ -2198,7 +2255,7 @@ void main() {
float up = smoothstep(0.86, 0.95, N.y);
// A wet surface is darker, because water in the pores takes the light a dry one scatters;
// standing water is darker still.
- float puddle = puddleMask(P.xz, u_puddles, u_puddleScale) * up * u_wetness;
+ float puddle = puddleMask(P.xz, basinCoverage(c, size, P, u_puddles, u_puddleScale), u_puddleScale) * up * u_wetness;
col *= 1.0 - 0.32 * u_wetness * up;
col *= 1.0 - 0.35 * puddle;
// Drops landing need drops falling: wet ground under no rain is still.
@@ -2238,6 +2295,7 @@ void main() {
#pragma fragment wgsl
${SSAO_WGSL}
${PUDDLE_WGSL}
+${BASIN_WGSL}
${WGSL}
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
@@ -2271,7 +2329,7 @@ ${WGSL}
var N = normalize(cross(ax, ay));
if (dot(N, viewDirection(P)) < 0.0) { N = -N; }
let up = smoothstep(0.86, 0.95, N.y);
- let puddle = puddleMask(P.xz, mc.u_puddles, mc.u_puddleScale) * up * mc.u_wetness;
+ let puddle = puddleMask(P.xz, basinCoverage(c, size, P, mc.u_puddles, mc.u_puddleScale), mc.u_puddleScale) * up * mc.u_wetness;
col = col * (1.0 - 0.32 * mc.u_wetness * up);
col = col * (1.0 - 0.35 * puddle);
let falling = clamp(mc.u_intensity, 0.0, 1.0);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 17223e38b..3b283aea7 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2497,6 +2497,8 @@ export const NOTED = {
{"note":"A Weather component puts a scene under clear, mist, overcast, rain or storm, turns between them and cycles by itself."},
"feat(render): baked reflection probes follow the weather through the ambient light's reflection scale and saturation":
{"note":"Reflection probes follow the weather: the ambient light scales what baked probes show and how much colour they keep."},
+ "feat(render): puddles gather in the low places of the ground and thin on its rises":
+ {"note":"Puddles gather in the low places of the ground and thin on its rises, read from the depth buffer."},
"feat(render): reflections no longer guess a surface, plain meshes record themselves, and what the ray never finds is the sky":
{"note":"Screen-space reflections leave a surface that recorded nothing alone, plain meshes now record a rough dielectric, and a puddle reflects the sky and what lies off screen."},
};