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): the sky's clouds cast shadows on the scene

yhh5673181faa3d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 889ae341e..9f3c137b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ published separately; it ships inside the editor.
### Added
- **Contact shadows and screen-space bounce light.** Contact Shadows and Screen Space GI effects add small sharp shadows at contacts and one bounce of colour between surfaces, and the weather softens the sun's shadows. `contactShadows` marches a short ray toward the scene's sun in the depth buffer; `ssgi` gathers eight rays a pixel over the G-buffer's normals at half size into a float target and averages the neighbours on the same surface before laying the light, times the receiver's colour, over the picture. The Weather component raises the sun's `sourceAngle` and lowers its `shadowStrength` as the sky clouds over.
+- **Cloud shadows.** The Sky Atmosphere's clouds can now cast shadows on the scene. **Cloud Shadows** marches the sun's ray up through the same cloud slab the sky draws, so the ground is darker and patchier under cloud; it also pins the clouds to the world instead of the camera, and **World Units per km** says how large a kilometre of sky is in the scene. The default is 0, which leaves every existing scene as it was. Ambient light is not shadowed, and the clouds are still only drawn where there is sky.
- **Voxel GI on WebGL2.** Voxel GI now runs on WebGL2: the world-space bounce light is built with fragment passes where there is no compute stage. The result matches the WebGPU one in the editor check; the gather is fixed at half size, grazing surfaces are thinner in the cache, a 32 MB half-float atlas is used, and the `low` quality tier leaves the effect out. Its cost on real GPUs has not been measured.
- **Cyber Rooftop example.** Cyber Rooftop adds a rooftop survival-base example with a 2D HUD and a first-person build tool. The world is editable 3D models (a rooftop shelter, planters, containers, pipework, a water plant, city buildings, a train) with rain, steam and puddle reflections; the HUD is built from Canvas, UINode, UIVisual and Text. It is a runnable reconstruction of a reference image, not a pixel match, and its survival systems (inventory, saving) are not implemented.
- **Thin lines against the sky.** A wire or railing thinner than a pixel stays one line against the sky instead of breaking into dashes. The Sky Atmosphere effect paints every pixel whose depth is the far plane, and depth is resolved from a single sample of a multisampled target, so a wire covered at some samples and not at that one was painted over wherever the sample missed. With the sky in the chain the scene is now cleared to nothing, its alpha is how much of each pixel geometry covers, and the sky is laid under it by that coverage: on a half-pixel wire across the sky the columns that show it went from 49% to 100%, on WebGL2 and WebGPU. An effect asks for this by declaring `u_sceneCoverage`; with Keep Background above zero the scene is cleared to the camera's colour as before.
diff --git a/desktop b/desktop
index 8b7706862..27ae222d1 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 8b77068628a8bfa58a5fbb60f96016a73cbb4ff4
+Subproject commit 27ae222d1ce6877b0f992fdde8749da15be547e0
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index 1f87497ec..35c13f26b 100644
--- a/docs/astro/src/content/docs/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx
@@ -74,6 +74,15 @@ scene is cleared to nothing while the effect is in the chain and its alpha says
sky is laid under an edge by that share instead of replacing the pixel. Nothing downstream sees it: the effect hands back alpha 1.
Turn **Keep Background** up and the scene is cleared to the camera's colour again, which is what keeping the background means.
+### Cloud shadows
+
+Turn **Cloud Shadows** above 0 and the sun's ray from each surface is marched up through the cloud layer the sky draws, against the
+same density, so the ground is darker and patchier under a cloud and lit where the sky is open. The sun's own light is what is
+kept off; ambient light is not shadowed. Casting shadows also pins the clouds to the world instead of carrying them along with the
+camera, so walking under a cloud and out of it works. The sky is in kilometres and the scene in its own units: **World Units per km**
+says how many of the scene's units make one. At 0 (the default) the effect is exactly as it was. The shadow falls on surfaces only; the
+clouds are still drawn where there is sky.
+
### Rain, wet ground and puddles
`rain` is a storm in two parts. **Falling rain** is three layers of thin slanted streaks scrolling down the
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 8da2c09f9..e850edf5b 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
@@ -62,6 +62,10 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
`skyAtmosphere` 在场景之后、在场景下面绘制天空。为了让比一个像素还细的电线或栏杆保持完整,只要这个效果在链里,场景就被清为全透明,它的 alpha 表示几何体覆盖了每个像素的多少,于是天空按这个比例垫在边缘下面,而不是整个替换这个像素。下游看不到这一点:效果交回的 alpha 是 1。把**保留背景**调高,场景就恢复成清为相机颜色,这正是保留背景的含义。
+### 云影
+
+把**云影**调到 0 以上,从每个表面朝太阳发出的光线会穿过天空绘制的云层逐步前进,用的是同一份密度,所以云下的地面更暗、更斑驳,天空开阔处则被照亮。被挡掉的是太阳直射光;环境光不受影响。开启云影也会把云固定在世界里而不是跟着相机走,所以人可以走进云影再走出来。天空以千米为单位,场景用自己的单位:**每千米世界单位**说明场景里多少个单位是一千米。为 0(默认值)时效果与之前完全一样。阴影只落在表面上;云仍然只画在有天空的地方。
+
### 雨、潮湿的地面与水坑
`rain` 是由两部分组成的暴雨。**落下的雨**是三层在屏幕上向下滚动的细斜线,每层站在自己的距离上:比该层更近的表面会挡住
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index 55cd4d98b..54681c341 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -302,6 +302,10 @@ registerEffect({
{ name: 'u_followSun', label: 'Follow Scene Sun', min: 0, max: 1, step: 1, defaultValue: 1, neutralValue: 1 },
{ name: 'u_sunAzimuth', label: 'Sun Azimuth', min: 0, max: 360, step: 1, defaultValue: 40 },
{ name: 'u_sunElevation', label: 'Sun Elevation', min: -90, max: 90, step: 1, defaultValue: 35 },
+ // How much of the sun the clouds keep off the scene's surfaces. Above 0 the clouds are fixed to the world, not carried along with the camera.
+ { name: 'u_cloudShadow', label: 'Cloud Shadows', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 0 },
+ // How many world units are a kilometre: the sky is in kilometres, the scene in its own units.
+ { name: 'u_unitsPerKm', label: 'World Units per km', min: 1, max: 100000, step: 1, defaultValue: 1000 },
],
});
diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.ts
index 40361d221..8e6cddcce 100644
--- a/sdk/src/postprocess/postProcessEffects.ts
+++ b/sdk/src/postprocess/postProcessEffects.ts
@@ -1548,6 +1548,8 @@ fn depthAt(texel : vec2i, size : vec2i) -> f32 {
#pragma param u_followSun float default(1) range(0,1)
#pragma param u_sunAzimuth float default(40) range(0,360)
#pragma param u_sunElevation float default(35) range(-90,90)
+#pragma param u_cloudShadow float default(0) range(0,1)
+#pragma param u_unitsPerKm float default(1000) range(1,100000)
#pragma lights
#pragma fragment
@@ -1655,6 +1657,29 @@ float cloudDensity(vec3 p, float coverage, float base, float thick, int octaves)
return smoothstep(1.0 - coverage, 1.0 - coverage + 0.22, n) * shape;
}
+/// How much of the sun reaches a surface at @p world through the cloud layer: 1 is all of it. The sun's ray is marched up through
+/// the slab against the same density the sky draws, so a shadow falls where the cloud above it is. Ambient light is not shadowed.
+float cloudShadowAt(vec3 world, vec3 cam, vec3 sun, float coverage, float overcast, vec3 drift) {
+ float strength = u_cloudShadow * smoothstep(0.02, 0.14, sun.y);
+ if (strength <= 0.001 || coverage <= 0.01) return 1.0;
+ float k = 1.0 / max(u_unitsPerKm, 1e-3);
+ float h = u_altitude + (world.y - cam.y) * k;
+ float tt = (u_cloudBase + u_cloudThickness - h) / sun.y;
+ if (tt <= 0.0) return 1.0;
+ float tb = max(u_cloudBase - h, 0.0) / sun.y;
+ const int N = 6;
+ float ds = (tt - tb) / float(N);
+ float sigma = 1.3 * (1.0 + overcast * 1.5);
+ float tau = 0.0;
+ float jitter = ign(gl_FragCoord.xy);
+ for (int i = 0; i < N; ++i) {
+ float t = tb + (float(i) + jitter) * ds;
+ vec3 p = vec3(world.x * k + sun.x * t, h + sun.y * t, world.z * k + sun.z * t) + drift;
+ tau += cloudDensity(p, coverage, u_cloudBase, u_cloudThickness, 2) * sigma * ds;
+ }
+ return 1.0 - strength * 0.8 * (1.0 - exp(-tau));
+}
+
void main() {
vec4 src = texture(u_texture, v_texCoord);
ivec2 size = textureSize(u_sceneDepth, 0);
@@ -1662,7 +1687,8 @@ void main() {
// The scene was cleared to nothing when the background is not kept (the engine's rule, same threshold): what is left of a pixel's
// alpha is how much the sky shows through it, and that includes a pixel whose depth says surface because one sample of it is.
bool covered = u_panorama <= 0.001;
- if (covered ? (depth < 1.0 && src.a > 0.999) : depth < 1.0) { fragColor = src; return; }
+ bool geometry = covered ? (depth < 1.0 && src.a > 0.999) : depth < 1.0;
+ if (geometry && u_cloudShadow <= 0.001) { fragColor = src; return; }
vec3 entry = worldFromDepth(v_texCoord, 0.0);
vec3 dir = normalize(worldFromDepth(v_texCoord, 1.0) - entry);
@@ -1679,6 +1705,17 @@ void main() {
float overcast = clamp(u_overcast, 0.0, 1.0);
float haze = u_haze * (1.0 + overcast * 2.0);
+ // Clouds that cast shadows are in the world, not on the camera: the pattern is anchored to where the camera stands.
+ bool shadowed = u_cloudShadow > 0.001;
+ vec3 anchor = shadowed ? vec3(entry.x, 0.0, entry.z) / max(u_unitsPerKm, 1e-3) : vec3(0.0);
+ float windAngle = radians(u_windDirection);
+ vec3 windDrift = vec3(sin(windAngle), 0.0, cos(windAngle)) * (u_windSpeed * u_time.x) + anchor;
+ if (geometry) {
+ float lit = cloudShadowAt(worldFromDepth(v_texCoord, depth), entry, sun, max(u_clouds, overcast * 0.95), overcast, windDrift);
+ fragColor = vec4(src.rgb * lit, src.a);
+ return;
+ }
+
// The dome. Below the horizon there is no sky: the ray is flattened onto it so a camera that looks down sees the haze there.
vec3 sdir = normalize(vec3(dir.x, max(dir.y, 0.015), dir.z));
vec3 sunTrans;
@@ -1736,8 +1773,7 @@ void main() {
float ds = (tt - tb) / float(STEPS);
float jitter = ign(gl_FragCoord.xy);
float sigma = 1.3 * (1.0 + overcast * 1.5);
- float wind = radians(u_windDirection);
- vec3 drift = vec3(sin(wind), 0.0, cos(wind)) * (u_windSpeed * u_time.x);
+ vec3 drift = windDrift;
float cosS = dot(dir, sun);
float phase = mix(0.35 + 0.65 * pow(max(cosS, 0.0), 6.0), 0.5, 0.4);
vec3 ambient = dome * 0.7 + lin(vec3(0.55, 0.65, 0.9)) * 0.015 * night;
@@ -1879,12 +1915,34 @@ fn cloudDensity(p : vec3f, coverage : f32, base : f32, thick : f32, octaves : i3
return smoothstep(1.0 - coverage, 1.0 - coverage + 0.22, n) * shape;
}
+fn cloudShadowAt(world : vec3f, cam : vec3f, sun : vec3f, coverage : f32, overcast : f32, drift : vec3f, px : vec2f) -> f32 {
+ let strength = mc.u_cloudShadow * smoothstep(0.02, 0.14, sun.y);
+ if (strength <= 0.001 || coverage <= 0.01) { return 1.0; }
+ let k = 1.0 / max(mc.u_unitsPerKm, 1e-3);
+ let h = mc.u_altitude + (world.y - cam.y) * k;
+ let tt = (mc.u_cloudBase + mc.u_cloudThickness - h) / sun.y;
+ if (tt <= 0.0) { return 1.0; }
+ let tb = max(mc.u_cloudBase - h, 0.0) / sun.y;
+ let N = 6;
+ let ds = (tt - tb) / f32(N);
+ let sigma = 1.3 * (1.0 + overcast * 1.5);
+ var tau = 0.0;
+ let jitter = ign(px);
+ for (var i : i32 = 0; i < N; i = i + 1) {
+ let t = tb + (f32(i) + jitter) * ds;
+ let p = vec3f(world.x * k + sun.x * t, h + sun.y * t, world.z * k + sun.z * t) + drift;
+ tau = tau + cloudDensity(p, coverage, mc.u_cloudBase, mc.u_cloudThickness, 2) * sigma * ds;
+ }
+ return 1.0 - strength * 0.8 * (1.0 - exp(-tau));
+}
+
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
let src = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
let size = vec2i(textureDimensions(t7, 0));
let depth = textureLoad(t7, clamp(vec2i(v.v_texCoord * vec2f(size)), vec2i(0), size - vec2i(1)), 0);
let covered = mc.u_panorama <= 0.001;
- if ((covered && depth < 1.0 && src.a > 0.999) || (!covered && depth < 1.0)) { return src; }
+ let geometry = (covered && depth < 1.0 && src.a > 0.999) || (!covered && depth < 1.0);
+ if (geometry && mc.u_cloudShadow <= 0.001) { return src; }
let entry = worldFromDepth(v.v_texCoord, 0.0);
let dir = normalize(worldFromDepth(v.v_texCoord, 1.0) - entry);
@@ -1900,6 +1958,15 @@ fn cloudDensity(p : vec3f, coverage : f32, base : f32, thick : f32, octaves : i3
let overcast = clamp(mc.u_overcast, 0.0, 1.0);
let haze = mc.u_haze * (1.0 + overcast * 2.0);
+ var anchor = vec3f(0.0);
+ if (mc.u_cloudShadow > 0.001) { anchor = vec3f(entry.x, 0.0, entry.z) / max(mc.u_unitsPerKm, 1e-3); }
+ let windAngle = radians(mc.u_windDirection);
+ let windDrift = vec3f(sin(windAngle), 0.0, cos(windAngle)) * (mc.u_windSpeed * tc.u_time.x) + anchor;
+ if (geometry) {
+ let lit = cloudShadowAt(worldFromDepth(v.v_texCoord, depth), entry, sun, max(mc.u_clouds, overcast * 0.95), overcast, windDrift, v.pos.xy);
+ return vec4f(src.rgb * lit, src.a);
+ }
+
let sdir = normalize(vec3f(dir.x, max(dir.y, 0.015), dir.z));
let sc = scatter(sdir, sun, mc.u_altitude, haze);
let sunTrans = sc.sunTrans;
@@ -1952,8 +2019,7 @@ fn cloudDensity(p : vec3f, coverage : f32, base : f32, thick : f32, octaves : i3
let ds = (tt - tb) / f32(STEPS);
let jitter = ign(v.pos.xy);
let sigma = 1.3 * (1.0 + overcast * 1.5);
- let wind = radians(mc.u_windDirection);
- let drift = vec3f(sin(wind), 0.0, cos(wind)) * (mc.u_windSpeed * tc.u_time.x);
+ let drift = windDrift;
let cosS = dot(dir, sun);
let phase = mix(0.35 + 0.65 * pow(max(cosS, 0.0), 6.0), 0.5, 0.4);
let ambient = dome * 0.7 + lin(vec3f(0.55, 0.65, 0.9)) * 0.015 * night;
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index a0d4743f9..57f368252 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2501,6 +2501,10 @@ export const NOTED = {
{"note":"Voxel GI now runs on WebGL2: the world-space bounce light is built with fragment passes where there is no compute stage."},
"chore(editor-checks): Voxel GI is checked on WebGL2 as well":
{"internal":"the editor check for the WebGL2 Voxel GI entry above"},
+ "feat(render): the sky's clouds cast shadows on the scene":
+ {"note":"The Sky Atmosphere's clouds can now cast shadows on the scene."},
+ "chore(editor-checks): a cloud-shadow check":
+ {"internal":"the editor check for the cloud shadows entry above"},
"fix(render): a wire narrower than a pixel is no longer painted over by the sky in dashes":
{"note":"A wire or railing thinner than a pixel stays one line against the sky instead of breaking into dashes."},
"fix(render): contact shadows no longer speckle a surface the sun does not reach, and a temporal pass placed before a noisy effect is flagged":