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(lightmap): a bake reflects light 8 times by default, since two left a light-walled room at half the light Cycles gives it; the render lab takes MeshRenderer.color as the linear albedo it is

yhh89bd9f11315d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2dd462b26..28d241687 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ published separately; it ships inside the editor.
### Fixed
- **Baked lighting shows on built-in meshes.** A `builtin:` cube, sphere or plane baked with `bake-scene` or the editor drew as if nothing had been baked: the bake unwrapped a lightmap UV set for its own use, but the mesh the game loaded had none, so the atlas was never read. The built-in meshes now carry that UV set, the bake lays out its charts by it, and existing bakes stay valid.
+- **Baked lighting reflects light 8 times by default, not 2.** Two bounces left a room of light walls at about half the light a path tracer gives it, and a face only bounced light reaches at a tenth. Eight is within about 10% of Cycles in a measured room and cost a 252k-lumel bake 0.7 s more. The inspector now goes to 16. A scene that states its own bounces keeps them.
## [0.98.0] - 2026-11-05
diff --git a/desktop b/desktop
index 5ca93216d..6eba138f7 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 5ca93216d4e978f6918896466c8824af0541ebc0
+Subproject commit 6eba138f7651e9302efc2f30615de88bd2df56cb
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index e4bffd746..a704d75c0 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -207,9 +207,9 @@
{
"key": "bounces",
"type": "number",
- "default": "2",
- "doc": "How many times light may reflect. 0 = direct only.",
- "range": "0–8"
+ "default": "8",
+ "doc": "How many times light may reflect. 0 = direct only. An enclosed room of light walls needs 8 or more, or it bakes too dark.",
+ "range": "0–16"
},
{
"key": "samples",
diff --git a/sdk/src/lightmap/bake.ts b/sdk/src/lightmap/bake.ts
index fbf5913cb..021f31393 100644
--- a/sdk/src/lightmap/bake.ts
+++ b/sdk/src/lightmap/bake.ts
@@ -87,7 +87,11 @@ export interface BakeResult {
export const BAKE_DEFAULTS = {
atlasSize: 1024,
texelsPerUnit: 0.25,
- bounces: 2,
+ // A room of light walls keeps most of its light after each reflection (0.85 white keeps 85%), so two bounces
+ // left a lit room at half the light a path tracer gives it and a face only bounce reaches at a tenth.
+ // Eight is within ~10% of Cycles' twelve in the render lab's room (tools/render-lab, gi_room), and each
+ // extra bounce is one more gather: 2 to 8 took a 252k-lumel bake from 1.7 s to 2.4 s.
+ bounces: 8,
samples: 64,
ambient: [0, 0, 0] as readonly [number, number, number],
dilate: 2,
diff --git a/sdk/src/lightmap/components.ts b/sdk/src/lightmap/components.ts
index 17add1237..332e0dc76 100644
--- a/sdk/src/lightmap/components.ts
+++ b/sdk/src/lightmap/components.ts
@@ -59,7 +59,7 @@ export const BakedLighting: ComponentDef<BakedLightingData> = defineComponent<Ba
atlasSize: { min: 64, step: 64, tooltip: 'Side of the square atlas, in texels.' },
texelsPerUnit: { min: 0.01, step: 0.05, unit: 'tx/wu',
tooltip: 'How finely a surface is lit. A world unit is a design pixel.' },
- bounces: { min: 0, max: 8, tooltip: 'How many times light may reflect. 0 = direct only.' },
+ bounces: { min: 0, max: 16, tooltip: 'How many times light may reflect. 0 = direct only. An enclosed room of light walls needs 8 or more, or it bakes too dark.' },
samples: { min: 1, tooltip: 'Rays each lumel gathers per bounce.' },
probeSamples: { min: 1, tooltip: 'Directions each probe gathers, over the whole sphere.' },
bakedFrom: { advanced: true, tooltip: 'Fingerprint of the inputs the last bake read.' },
diff --git a/tools/render-lab/README.md b/tools/render-lab/README.md
index b87bc514d..eb840cd33 100644
--- a/tools/render-lab/README.md
+++ b/tools/render-lab/README.md
@@ -41,25 +41,26 @@ node tools/render-lab/gi_cost.mjs $O/web_vgi
### 2026-11-05 results
-Each figure is a region's linear value in the engine as a share of Cycles' value there; 1.00 matches. WebGL2 numbers come from headless Chromium. The WebGPU column is the compute path, rendered in the MCP's hidden editor.
+Each figure is a region's linear value in the engine as a share of Cycles' value there; 1.00 matches. A `MeshRenderer.color` is linear albedo, on both sides. A first pass linearized it for Blender only, which made Cycles' walls darker than the engine's, so the direct light read 1.19 and the bake 1.6. WebGL2 numbers come from headless Chromium. The WebGPU column is the compute path, rendered in the MCP's hidden editor.
-| Region | Cycles | no GI | SSGI (radius 400) | Voxel GI default, WebGL2 | Voxel GI default, WebGPU |
-| --- | --- | --- | --- | --- | --- |
-| `gi_room` ceiling | 0.030 | 0 | 0 | 0.30 | 0.23 |
-| `gi_room` back wall | 0.021 | 0 | 0.02 | 0.17 | 0.09 |
-| `gi_room` floor in shade | 0.018 | 0 | 0 | 0.02 | 0.01 |
-| `gi_room` block, shaded face | 0.004 | 0 | 0 | 0 | 0 |
-| `gi_away`, every region | 0.010–0.014 | 0 | 0 | 0 | — |
-| `gi_emissive` ceiling | 0.16 | 0 | 0.07 | 0.12 | — |
-| `gi_emissive` floor | 0.14 | 0 | 0.04 | 0.08 | — |
+| Region | Cycles | SSGI (radius 400) | Voxel GI default, WebGL2 | Voxel GI default, WebGPU | Bake, 2 bounces | Bake, 8 bounces | Bake, 12 bounces |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `gi_room` ceiling | 0.056 | 0 | 0.15 | 0.12 | — | 0.90 | 0.93 |
+| `gi_room` back wall | 0.043 | 0.01 | 0.08 | 0.04 | 0.59 | 0.92 | 0.94 |
+| `gi_room` floor in shade | 0.042 | 0 | 0.01 | 0 | 0.59 | 0.95 | 0.96 |
+| `gi_room` block, shaded face | 0.014 | 0 | 0 | 0 | 0.10 | 0.82 | 0.93 |
+| `gi_away`, every region | 0.006–0.03 | 0 | 0 | — | | | |
+| `gi_emissive` ceiling | 0.24 | 0.04 | 0.08 | — | | | |
+| `gi_emissive` floor | 0.21 | 0.03 | 0.05 | — | | | |
-- **Too little light.** Where the engine's GI reaches at all, it gives a tenth to a third of the bounce Cycles does. Faces that only a second bounce reaches (the block's shaded side, the floor away from the patch) get nothing.
-- **Nothing off screen.** Both methods seed from the frame's own picture, so `gi_away` is black under every method. A surface cache lit independently of the view is what changes this.
-- **No colour bleed.** On the red wall the engine's red channel is 0.10–0.32 of Cycles, but green and blue are 1–5×. The bounce arrives grey, and the wall's albedo does not tint it the way Cycles does. The green wall shows the same.
-- **No leak in `gi_leak`.** That is only because the lit outside is never on screen, so there is nothing to leak.
-- **Banding.** The WebGL2 voxel fallback and SSGI both band visibly in the emissive room.
-- **The bake showed nothing on built-in meshes (fixed the same day).** A `builtin:` mesh had no `TexCoord1` at runtime, so `MESH_LIGHTMAP` never turned on. The templates now carry the bake's own unwrap. Since the fix, the baked `gi_room` is 1.5–1.8× Cycles everywhere (ceiling 1.53, back wall 1.64, floor in shade 1.9, the block's shaded face 1.6), with dark seams at chart edges. This calibration gap is still open, and it is on top of the 1.19 the direct light shows.
-- **Direct light is 19% bright.** The sun patch is 1.19 of Cycles on both backends. This is separate from GI and not explained yet.
+- **The bake is right once it bounces enough.** With 8 bounces it lands within 5–18% of Cycles, and with 12 within 4–10%. Two bounces, which was the default, left a light-walled room at about half its light. The default is 8 now, and the inspector goes to 16. More bounces cost little: a 252k-lumel bake took 1.7 s at 2 bounces and 2.4 s at 8.
+- **The real-time methods give a fraction of the bounce.** Voxel GI gives 0.04–0.15 of it, SSGI about none. Faces that only a later bounce reaches get nothing.
+- **Nothing off screen.** Both real-time methods seed from the frame's own picture, so `gi_away` is black under them. A surface cache lit independently of the view is what changes this.
+- **No colour bleed.** On the red wall the real-time red channel is 0.11–0.15 of Cycles while green and blue are 0.5–0.85: the bounce arrives grey.
+- **No leak in `gi_leak`.** That is only because the lit outside is never on screen.
+- **Banding.** The WebGL2 voxel fallback and SSGI band visibly in the emissive room.
+- **Built-in meshes did not draw their bake until d39f6842e.** They had no `TexCoord1` at runtime.
+- **Screenshots can come too early.** One `BAKE=1` shot came out with no indirect light at all; rerun, it was fine. The shot waits a fixed 12 s, and once that was not enough for the atlas to load.
GPU 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.
diff --git a/tools/render-lab/gi_project.py b/tools/render-lab/gi_project.py
index a236f35d5..aea9cebf8 100644
--- a/tools/render-lab/gi_project.py
+++ b/tools/render-lab/gi_project.py
@@ -55,7 +55,7 @@ if spec['sun']:
if os.environ.get('BAKE') == '1':
entities.append({'id': 6, 'name': 'Lighting', 'parent': None, 'children': [], 'visible': True, 'components': [
- {'type': 'BakedLighting', 'data': {'atlasSize': 1024, 'texelsPerUnit': float(os.environ.get('TPU', '0.2')), 'bounces': 4,
+ {'type': 'BakedLighting', 'data': {'atlasSize': 1024, 'texelsPerUnit': float(os.environ.get('TPU', '0.2')), 'bounces': int(os.environ.get('BOUNCES', '4')),
'samples': int(os.environ.get('BAKE_SAMPLES', '256')), 'probeSamples': 128}}]})
effects = json.loads(os.environ.get('EFFECTS', '[]'))
diff --git a/tools/render-lab/gi_ref.py b/tools/render-lab/gi_ref.py
index b0e3243f0..7cbdab346 100644
--- a/tools/render-lab/gi_ref.py
+++ b/tools/render-lab/gi_ref.py
@@ -40,7 +40,7 @@ for name, centre, size, colour in spec['boxes']:
m = bpy.data.materials.new(name)
m.use_nodes = True
bsdf = m.node_tree.nodes['Principled BSDF']
- lin = tuple(S.srgb_to_linear(c) for c in colour)
+ lin = tuple(colour) # linear, as the engine takes MeshRenderer.color
bsdf.inputs['Base Color'].default_value = (*lin, 1.0)
bsdf.inputs['Roughness'].default_value = 1.0
bsdf.inputs['Metallic'].default_value = 0.0
diff --git a/tools/render-lab/gi_specs.py b/tools/render-lab/gi_specs.py
index abb9cc3b8..dbc0f1fcb 100644
--- a/tools/render-lab/gi_specs.py
+++ b/tools/render-lab/gi_specs.py
@@ -7,7 +7,8 @@ ratio engine / Cycles over a region is that method's answer for that region.
Units: the engine's world is centimetres (the built-in cube is 100 across), Blender's is metres. Coordinates here are the engine's
(+Y up), Blender's are (x, -z, y) / 100 of them.
-Colours are written as the editor shows them (sRGB); the engine linearizes them in a linear project and Blender is handed the linear value.
+Colours are linear albedo on both sides: a MeshRenderer's `color` reaches the mesh shader and the bake as written (only light and clear
+colours are linearized in a linear project), so Blender is handed the same numbers.
"""
import math