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
fix(render): Voxel GI brings a bounce at full strength however far the ray went, and weighs each voxel by how much of it a surface covers, so a fine grid is no longer dim and a coarse one no longer brighter
yhh258116eda8a4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bd22c56bb..834e18aa8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,7 +16,7 @@ published separately; it ships inside the editor.### Added-- **Voxel GI lights what the camera does not see, and bounces light more than once (WebGPU).** The cache now reads the sun's shadow map back into the world, so a surface the sun lights behind or beside the camera still sends light into the view. Each surface also gives off again the bounce light it received, so a corner or a floor in shade gets light that took two or more bounces to reach it. In a sunlit room whose lit patch is behind the camera, the walls went from no bounce light to 10–30% of a path tracer's. With 12 cm voxels, the room with the patch in view went from 2–57% to 43–62%. Two inspector controls tune it: **Off-screen Sun Albedo** (the colour the shadow map cannot give, assumed) and **Multi-bounce**. A fine grid (voxels a sample a frame lands in) no longer drops every voxel: a count truncated by the cache's ageing had kept them below the two samples a ray asks for. The WebGL2 fallback still sees only the picture.+- **Voxel GI lights what the camera does not see, and bounces light more than once (WebGPU).** The cache now reads the sun's shadow map back into the world, so a surface the sun lights behind or beside the camera still sends light into the view. Each surface also gives off again the bounce light it received, so a corner or a floor in shade gets light that took two or more bounces to reach it. A ray now brings what it meets at full strength however far it went (it used to fade with distance, 40% at 4 m with 12 cm voxels). Each voxel is weighed by how much of it a surface covers, so a bright patch no longer lights like the whole voxel around it. Together these keep the result close to a path tracer's whatever the voxel size. In a sunlit test room the whole frame carries 0.95 of Cycles' light at the default size and 0.74 at 12 cm voxels; before, it was 0.54 at the default and darker the finer the grid. With the lit patch behind the camera, the walls went from no bounce light to 25–57%. A closed room the sun only lights from outside stays dark. Two inspector controls tune it: **Off-screen Sun Albedo** (the colour the shadow map cannot give, assumed) and **Multi-bounce**. A fine grid no longer drops every voxel: a count truncated by the cache's ageing had kept them below the two samples a ray asks for. The WebGL2 fallback still sees only the picture.- **A model of many parts that moves: `CompositeBatch`.** Put it on the root of a ship, a vehicle or a moving platform assembled from many meshes, and while the game runs its parts are drawn in a few draws parented to the root: a mesh repeated four times or more (a deck plank, a rail post) as one instanced set that copies no vertices, every other part merged by draw state into chunks of the root's own space. Moving, turning or scaling the root moves the whole model and merges nothing again. Adding, removing, re-meshing or re-placing a part re-merges only its chunk within half a second (`CompositeBatchingRes.refresh(root)` looks at once), and a part that keeps moving inside the model is let go to draw itself. The root reports what it drew, and so does `get_stats`. On a model of 2,004 parts, the meshes handed to the renderer went from 2,003 to 5 and the CPU frame from 3.3 ms to 1.2–1.4 ms; a model of about a hundred parts costs the same either way. A part under a composite is never also statically batched.diff --git a/src/esengine/renderer/frame/VoxelGI.cpp b/src/esengine/renderer/frame/VoxelGI.cppindex 71c2a269d..2e8e37038 100644--- a/src/esengine/renderer/frame/VoxelGI.cpp+++ b/src/esengine/renderer/frame/VoxelGI.cpp@@ -16,7 +16,8 @@ namespace esengine {namespace {-/// Eight u32 per voxel: radiance r, g, b (fixed point), a sample count, the facing x, y, z (fixed point), a spare.+/// Eight u32 per voxel: radiance r, g, b (fixed point), a sample count, the facing x, y, z (fixed point), and how much of the+/// voxel the surfaces in it cover (the area they put in it, over a face of the voxel, fixed point).constexpr u32 kVoxelWords = 8;#ifdef ES_ENABLE_WEBGPU@@ -43,12 +44,23 @@ const FACING : f32 = 256.0;// to 0 — a voxel that one sample a frame lands in (a small voxel, or one far away) then never reached the 2 a ray asks for, and a// fine grid drew no bounce at all.const COUNT : u32 = 16u;+// The covered area, in AREA parts of one voxel face. A ray that meets a voxel takes its light in proportion to how much of the voxel+// a surface fills: averaged over a whole voxel, a bright patch that fills a corner of one would otherwise light like the whole voxel,+// which spreads every light by up to a voxel and makes a coarse grid brighter than a fine one.+const AREA : f32 = 4096.0;+fn addArea(base : u32, area : f32) {+ let vs = gi.a.x;+ atomicAdd(&grid[base + 7u], u32(clamp(area / (vs * vs), 0.0, 1.0) * AREA));+}+// Set on a slot's tag by the inject when the picture showed its cell this frame, and cleared by the maintain each frame.+const SEEN : u32 = 2u;fn hash3(c : vec3i) -> u32 {var h = (u32(c.x) * 73856093u) ^ (u32(c.y) * 19349663u) ^ (u32(c.z) * 83492791u);h = (h ^ (h >> 16u)) * 0x45d9f3bu;h = h ^ (h >> 16u);- return h | 1u;+ // Bit 0 always set (no live cell hashes to 0, which an empty slot holds); bit 1 is not part of the hash, but the mark SEEN.+ return (h | 1u) & ~SEEN;}fn wrapIndex(cell : vec3i) -> u32 {let d = vec3i(gi.dims.xyz);@@ -96,11 +108,12 @@ fn main(@builtin(global_invocation_id) id : vec3u) {let cell = gi.origin.xyz + rel;let tag = hash3(cell);let base = i * WORDS;- if (tags[i] != tag) {+ if ((tags[i] & ~SEEN) != tag) {tags[i] = tag;for (var k = 0u; k < WORDS; k = k + 1u) { atomicStore(&grid[base + k], 0u); }} else {- for (var k = 0u; k < 7u; k = k + 1u) {+ tags[i] = tag;+ for (var k = 0u; k < WORDS; k = k + 1u) {atomicStore(&grid[base + k], u32(f32(atomicLoad(&grid[base + k])) * gi.a.y));}}@@ -132,6 +145,21 @@ fn main(@builtin(global_invocation_id) id : vec3u) {let cell = vec3i(floor(p / gi.a.x));if (!inWindow(cell)) { return; }let base = wrapIndex(cell) * WORDS;+ // The surface this sample stands for: the two-by-two pixels around it, measured on the surface from the neighbours' depth+ // (which carries the slant). A neighbour off the surface (an edge) leaves the footprint the pixel's own square seen face on.+ let tx = select(t + vec2i(2, 0), t - vec2i(2, 0), t.x + 2 >= size.x);+ let ty = select(t + vec2i(0, 2), t - vec2i(0, 2), t.y + 2 >= size.y);+ let px = worldFromDepth((vec2f(tx) + 0.5) / vec2f(size), textureLoad(depthTex, tx, 0));+ let py = worldFromDepth((vec2f(ty) + 0.5) / vec2f(size), textureLoad(depthTex, ty, 0));+ var footprint = length(cross(px - p, py - p));+ let side = max(length(px - p), length(py - p));+ if (side > gi.a.x) {+ footprint = min(length(px - p), length(py - p));+ footprint = footprint * footprint;+ }+ addArea(base, footprint);+ // Every writer writes the same value, so the race is harmless.+ tags[wrapIndex(cell)] = hash3(cell) | SEEN;var lit = textureLoad(scene, t, 0).rgb;let albedo = textureLoad(albedoTex, t, 0);if (gi.view.y > 0.5 && albedo.a > 0.5) {@@ -206,6 +234,10 @@ fn main(@builtin(global_invocation_id) id : vec3u) {let cell = vec3i(floor((p.xyz + nrm * (vs * 0.25)) / vs));if (!inWindow(cell)) { return; }let base = wrapIndex(cell) * WORDS;+ // Where the picture has shown this voxel (the inject ran first this frame), its own colour is the better answer than an assumed+ // albedo: the sun's estimate is what stands in only where the camera has not looked.+ if ((tags[wrapIndex(cell)] & SEEN) != 0u) { return; }+ addArea(base, sqrt(area));let c = clamp(sun.light.rgb * (sun.light.w * max(dot(nrm, L), 0.0)), vec3f(0.0), vec3f(gi.a.z));atomicAdd(&grid[base], u32(c.r * FIXED));atomicAdd(&grid[base + 1u], u32(c.g * FIXED));@@ -250,6 +282,8 @@ fn trace(origin : vec3f, dir : vec3f) -> vec3f {var tMax = (next - pos) / safe;let range = gi.b.x;var t = 0.0;+ var acc = vec3f(0.0);+ var trans = 1.0;for (var i = 0; i < 96; i = i + 1) {if (t > range) { break; }// Step into the neighbouring cell along the axis whose boundary comes first.@@ -262,7 +296,7 @@ fn trace(origin : vec3f, dir : vec3f) -> vec3f {}if (!inWindow(cell)) { break; }let idx = wrapIndex(cell);- if (tags[idx] != hash3(cell)) { continue; }+ if ((tags[idx] & ~SEEN) != hash3(cell)) { continue; }let base = idx * WORDS;let count = atomicLoad(&grid[base + 3u]);if (count < 2u * COUNT) { continue; }@@ -271,9 +305,18 @@ fn trace(origin : vec3f, dir : vec3f) -> vec3f {// A surface is met from the side it faces. One facing away is behind the ray, or the ray skims along it.if (dot(normalize(facing), dir) > -0.15) { continue; }let radiance = vec3f(f32(atomicLoad(&grid[base])), f32(atomicLoad(&grid[base + 1u])), f32(atomicLoad(&grid[base + 2u]))) * inv / FIXED;- return radiance * clamp(1.0 - t / range, 0.0, 1.0);+ // The area aged the way every word is (a frame adds `a`, the sum settles at a / (1 - keep)), so one frame's worth of it is the+ // sum times (1 - keep). Two surfaces in one voxel (a corner) add past one face, which is a voxel fully covered.+ let covered = min(f32(atomicLoad(&grid[base + 7u])) / AREA * (1.0 - gi.a.y), 1.0);+ // What a ray meets is what it brings, however far it went: distance is already in how few rays reach a far surface. A fade over+ // the last stretch of the range only, so the edge of what a ray can see does not draw a line. (A falloff over the whole range had+ // darkened every bounce by its distance: 40% at 4 m with 12 cm voxels.)+ // A voxel a surface only partly fills lets the rest of the ray through to what stands behind it.+ acc = acc + trans * covered * radiance * clamp((range - t) / (range * 0.15), 0.0, 1.0);+ trans = trans * (1.0 - covered);+ if (trans < 0.05) { return acc; }}- return vec3f(0.0);+ return acc;}@compute @workgroup_size(8, 8)diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 6ae377751..287200d98 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3822,4 +3822,6 @@ export const NOTED = {{"note":"Bounce light takes the colour of what it lands on."},"feat(render): Voxel GI on WebGPU reads the sun's shadow map back into its cache and feeds each bounce back, so light the camera does not see and light past the first bounce reach the picture":{"note":"Voxel GI lights what the camera does not see, and bounces light more than once (WebGPU)."},+ "fix(render): Voxel GI brings a bounce at full strength however far the ray went, and weighs each voxel by how much of it a surface covers, so a fine grid is no longer dim and a coarse one no longer brighter":+ {"note":"Voxel GI lights what the camera does not see, and bounces light more than once (WebGPU)."},};diff --git a/tools/render-lab/README.md b/tools/render-lab/README.mdindex 65a73703f..2e573e738 100644--- a/tools/render-lab/README.md+++ b/tools/render-lab/README.md@@ -76,3 +76,24 @@ Each figure is a region's linear value in the engine as a share of Cycles' valueGPU cost at 1280×720, WebGL2, on this desktop:- SSGI: gather 0.8–0.9 ms + apply 0.4 ms. Frame 1.25 → 2.8 ms.- Voxel GI: voxels 0.6 ms + gather 1.9 ms + apply 0.1 ms. Frame → 4.3 ms.++### Calibration (2026-11-05, WebGPU)++| Run | Frame light share | Regions |+| --- | --- | --- |+| `gi_room` at 40 cm, before | 1.09 | 0.98–1.61 |+| `gi_room` at 40 cm, after | 0.95 (mean \|d\| 0.0093) | 0.71–1.51 |+| `gi_room` at 12 cm, before | 0.65 | 0.43–0.62 |+| `gi_room` at 12 cm, after | 0.74 | 0.54–0.84 |+| `gi_away` with cascades, before | 0.23 | — |+| `gi_away` with cascades, after | 0.35 | 0.24–0.57 |++`gi_leak` stays black. The block face that only the unlit, off-screen front wall sees stays at about 0. What changed:++1. **No distance falloff.** A hit used to be scaled by 1 − t/range. Now only the last 15% of the range fades out.+2. **Coverage.** Each voxel accumulates the surface area put into it, in word 7. For a screen sample that is its 2×2-pixel footprint measured on the surface; for a sun sample it is its texel on the surface. A ray takes covered × radiance and goes on through the rest of the voxel. A bright patch filling a corner of a coarse voxel had lit like the whole voxel, which was the coarse-grid overshoot.+3. **A seen mark (tag bit 1).** Voxels the picture showed this frame keep their own colour rather than the sun's assumed albedo. This measured no different here, but it is the right priority.++The remaining under-shoot at 12 cm (about 25%) has no single cause found. Rays still escape through partly covered voxels and past the facing test.++Trap: the first frame captured right after the hidden editor restarts can be a stale one (no GI). Step and capture again before you read anything.diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 3b07100ac..5a6ee5cfa 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -167,7 +167,7 @@ export const SCENES = [// The same room unbaked, lit by Voxel GI: the bounce light on the red wall is red, because it is reflected by the albedo the wall wrote beside its// normal. Before the albedo attachment it was guessed from the lit picture, and a wall the sun does not reach came out grey. WebGPU has its own// numbers: its cache also takes the sun's shadow map and feeds each bounce back (several bounces), which the WebGL2 fallback does not.- { id: "gi-room-voxel", tier: "pr", webgpu: { "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[85,81,80],\"tol\":18},{\"x\":0.239,\"y\":0.508,\"rgb\":[85,42,37],\"tol\":18},{\"x\":0.761,\"y\":0.508,\"rgb\":[21,40,18],\"tol\":18}]" }, env: { "ESTELLA_VERIFY_PLAY": "1", "ESTELLA_VERIFY_COLORSPACE": "linear", "ESTELLA_VERIFY_SCENE": "/scenes/gi-room-voxel.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/gi-room-voxel.textures.json", "ESTELLA_VERIFY_W": "320", "ESTELLA_VERIFY_H": "180", "ESTELLA_VERIFY_STEPS": "120", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[58,58,58],\"tol\":16},{\"x\":0.239,\"y\":0.508,\"rgb\":[64,28,25],\"tol\":16},{\"x\":0.761,\"y\":0.508,\"rgb\":[18,41,20],\"tol\":16}]" } },+ { id: "gi-room-voxel", tier: "pr", webgpu: { "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[78,74,73],\"tol\":18},{\"x\":0.239,\"y\":0.508,\"rgb\":[74,36,31],\"tol\":18},{\"x\":0.761,\"y\":0.508,\"rgb\":[31,56,30],\"tol\":18}]" }, env: { "ESTELLA_VERIFY_PLAY": "1", "ESTELLA_VERIFY_COLORSPACE": "linear", "ESTELLA_VERIFY_SCENE": "/scenes/gi-room-voxel.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/gi-room-voxel.textures.json", "ESTELLA_VERIFY_W": "320", "ESTELLA_VERIFY_H": "180", "ESTELLA_VERIFY_STEPS": "120", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.5,\"y\":0.099,\"rgb\":[58,58,58],\"tol\":16},{\"x\":0.239,\"y\":0.508,\"rgb\":[64,28,25],\"tol\":16},{\"x\":0.761,\"y\":0.508,\"rgb\":[18,41,20],\"tol\":16}]" } },{ id: "lightmap-model", tier: "pr", webgpu: true, env: { "ESTELLA_VERIFY_MESH_MATERIAL": "/scenes/lightmap-model/rough.esmaterial", "ESTELLA_VERIFY_SCENE": "/scenes/lightmap-model.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/lightmap-model.textures.json", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "2", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.25,\"y\":0.4,\"rgb\":[0,255,255],\"tol\":20},{\"x\":0.25,\"y\":0.6,\"rgb\":[128,255,0],\"tol\":20},{\"x\":0.75,\"y\":0.4,\"rgb\":[29,255,61],\"tol\":20},{\"x\":0.75,\"y\":0.6,\"rgb\":[29,255,61],\"tol\":20}]" } },// Why the rectangle rides the per-object record: ONE mesh and ONE atlas, and// the two objects drawn from them read different halves of it. A rectangle