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.

fix(postprocess): voxelGI and ssgi take voxel sizes, radii and thicknesses down to a centimetre

yhh90b9435ed30d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 97d4086bd..941db058d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -50,6 +50,7 @@ published separately; it ships inside the editor.
### Fixed
+- **Global illumination at metre scale.** The global-illumination effects accept lengths down to a centimetre: the voxel size of voxelGI, and the radius and thickness of ssgi, used to stop at four, ten and one world units, so a 3D scene measured in metres could not set them small enough to do anything. Against Blender's render of the same frame, a character lit by one sun gets its soft bounce light in the shadows once they are set to metre-scale values.
- **Lite engine builds compile.** The lite WeChat and mini-game engine builds compile again: the pass that puts the opaque scene back after water and glass named the post-process pipeline outside the guard that leaves it out of those builds, so every package without post-processing failed to build.
- **Shadow cascades fit the scene.** A directional light's shadow cascades are now spread over the geometry that is in the scene instead of over the whole view. A close shot of a character in a view that reaches fifty metres used to spend its first cascade on three metres and drew blocky, misplaced shadow edges; the cascades now end where the scene's geometry ends (rounded in quarter octaves, so the split does not swim as the camera moves), and the shadow lands where it should.
- **Colour fringes on skin shadows.** An imported skin no longer blurs its diffuse light separately per colour channel, which put a red and cyan fringe along the edge of every shadow on it; like the rest of the scattering, it is written as off unless the source says otherwise.
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index 4304e7790..e021f073d 100644
--- a/docs/astro/src/content/docs/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx
@@ -220,6 +220,10 @@ where one meets a voxel that faces it, that voxel's radiance is the light it bri
Because the cache is the world's and not the screen's, a bright wall that has left the picture still tints the floor beside it, a surface lit
only by another is lit, and a moving light lights its surroundings — the three things the screen-space bounce (`ssgi`) cannot do.
+The defaults are tuned for a world measured in pixels. In a 3D scene where a world unit is a metre, scale the lengths to match: for a character
+shot a `voxelSize` of 0.03 (a cache about four metres across) with a `range` of 48 voxels, and for `ssgi` a `radius` of 0.4 and a `thickness` of
+0.15. Both accept values down to a centimetre.
+
It is **not a trace of the scene's geometry**, and it says so:
- the cache holds the surfaces the camera has *seen*, at the voxel's size — a surface it has not seen yet sends no light, and a thin one is as thick as a cell;
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 f9197c64c..fe1256e28 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
@@ -156,6 +156,8 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
因为缓存属于世界而不是屏幕,一面已经离开画面的亮墙仍会给旁边的地面染色,只被另一个表面照亮的表面也能被照亮,移动的光会照亮周围——这三件事屏幕空间的弹射(`ssgi`)都做不到。
+默认值是按以像素为单位的世界调的。在一个世界单位等于一米的 3D 场景里,请把这些长度按比例改小:拍一个角色时,`voxelGI` 的 `voxelSize` 取 0.03(缓存约四米见方)、`range` 取 48 格;`ssgi` 的 `radius` 取 0.4、`thickness` 取 0.15。两者都接受小到一厘米的值。
+
它**不是对场景几何体的追踪**,并且如实说明:
- 缓存里只有相机*见过*的表面,精度是体素大小——没见过的表面不发光,薄的东西和一格一样厚;
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index 2006a52b7..1eb63df5d 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -344,7 +344,7 @@ registerEffect({
// Rays per surface point: more is smoother and costs in proportion.
{ name: 'u_rays', label: 'Rays', min: 1, max: 32, step: 1, defaultValue: 8 },
// The world size of a voxel: the cache is 128 x 64 x 128 of them around the camera, so this sets how far it reaches and how finely.
- { name: 'u_voxelSize', label: 'Voxel Size', min: 4, max: 400, step: 1, defaultValue: 40 },
+ { name: 'u_voxelSize', label: 'Voxel Size', min: 0.01, max: 400, step: 0.01, defaultValue: 40 },
// How far a ray looks, in voxels.
{ name: 'u_range', label: 'Range', min: 4, max: 90, step: 1, defaultValue: 48 },
// Brighter than this a surface does not give out, so one lamp does not light the street from a single pixel.
@@ -418,9 +418,9 @@ registerEffect({
// How much of the bounced light is added: 1 is what the surfaces gave out, scaled by the receiver's colour.
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 4, step: 0.01, defaultValue: 1, neutralValue: 0 },
// A WORLD length: how far from a surface the rays look for something to bounce light from.
- { name: 'u_radius', label: 'Radius', min: 10, max: 1500, step: 5, defaultValue: 150 },
+ { name: 'u_radius', label: 'Radius', min: 0.05, max: 1500, step: 0.05, defaultValue: 150 },
// A WORLD length: how thick a thing the rays can land on, so a far wall is not taken for the one beside it.
- { name: 'u_thickness', label: 'Thickness', min: 1, max: 300, step: 1, defaultValue: 30 },
+ { name: 'u_thickness', label: 'Thickness', min: 0.01, max: 300, step: 0.01, defaultValue: 30 },
// Brighter than this a surface does not bounce, so one lamp does not light the street from a single pixel.
{ name: 'u_maxBounce', label: 'Max Bounce', min: 0.5, max: 16, step: 0.5, defaultValue: 3 },
],
diff --git a/sdk/src/postprocess/sources/lighting.ts b/sdk/src/postprocess/sources/lighting.ts
index bab05130d..c01151fbf 100644
--- a/sdk/src/postprocess/sources/lighting.ts
+++ b/sdk/src/postprocess/sources/lighting.ts
@@ -526,8 +526,8 @@ fn cosineDirection(N : vec3f, u : f32, v : f32) -> vec3f {
const source = `#pragma shader "PP SSGI Gather"
#pragma version 300 es
#pragma domain PostProcess
-#pragma param u_radius float default(150) range(10,1500)
-#pragma param u_thickness float default(30) range(1,300)
+#pragma param u_radius float default(150) range(0.05,1500)
+#pragma param u_thickness float default(30) range(0.01,300)
#pragma param u_maxBounce float default(3) range(0.5,16)
#pragma gbuffer
#pragma highprecision
diff --git a/sdk/src/postprocess/voxelGIFallback.ts b/sdk/src/postprocess/voxelGIFallback.ts
index 66dd4871e..351c85dd8 100644
--- a/sdk/src/postprocess/voxelGIFallback.ts
+++ b/sdk/src/postprocess/voxelGIFallback.ts
@@ -50,7 +50,7 @@ export const voxelGIFallback = {
#pragma domain PostProcess
#pragma highprecision
#pragma gbuffer
-#pragma param u_voxelSize float default(40) range(4,400)
+#pragma param u_voxelSize float default(40) range(0.01,400)
#pragma param u_decay float default(0.93) range(0,0.99)
#pragma param u_maxBounce float default(3) range(0.5,16)
#pragma param u_feedback texture default(black)
@@ -152,7 +152,7 @@ void main() {
#pragma domain PostProcess
#pragma highprecision
#pragma gbuffer
-#pragma param u_voxelSize float default(40) range(4,400)
+#pragma param u_voxelSize float default(40) range(0.01,400)
#pragma param u_rays float default(8) range(1,32)
#pragma param u_range float default(48) range(4,90)
#pragma param u_bias float default(1.2) range(0,4)
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 3f87239f3..91df03d38 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -54,6 +54,8 @@ export const NOTED = {
{"note":"An imported skin no longer blurs its diffuse light separately per colour channel, which put a red and cyan fringe along the edge of every shadow on it; like the rest of the scattering, it is written as off unless the source says otherwise."},
'fix(render): the lite engine builds compile again, with the layered water pass behind the post-process guard':
{"note":"The lite WeChat and mini-game engine builds compile again: the pass that puts the opaque scene back after water and glass named the post-process pipeline outside the guard that leaves it out of those builds, so every package without post-processing failed to build."},
+ 'fix(postprocess): voxelGI and ssgi take voxel sizes, radii and thicknesses down to a centimetre':
+ {"note":"The global-illumination effects accept lengths down to a centimetre: the voxel size of voxelGI, and the radius and thickness of ssgi, used to stop at four, ten and one world units, so a 3D scene measured in metres could not set them small enough to do anything. Against Blender's render of the same frame, a character lit by one sun gets its soft bounce light in the shadows once they are set to metre-scale values."},
'fix: serialize binaryen optimization on windows': { internal: 'Uses one optimizer worker after wider builds reproduced heap corruption with four; release optimization flags stay unchanged.' },
'feat: add budgeted 2d and 3d particle scene collisions': { note: 'Budgeted particle scene collisions.' },
'feat(editor): add particle collision authoring and diagnostics': { note: 'Budgeted particle scene collisions.' },