3D engine that AI agents drive
Add a ground bounce term for environment maps (closes #244)
Nguyen Xuan And9ef7dd6e0f6
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex 6a187a73..833ba5c2 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -20,8 +20,8 @@ All of them are against the Blender 5.2.2 renders taken on 2026-11-03 with the s| Scene | 67js against Cycles | EEVEE against Cycles | 67js against EEVEE | Baked 67js against Cycles | Path tracer against Cycles || --- | --- | --- | --- | --- | --- |-| `brick-flat` | 0.1272 | 0.1098 | 0.0462 | | 0.1152 |-| `brick-graph` | 0.1602 | 0.1221 | 0.0896 | | 0.1476 |+| `brick-flat` | 0.0636 | 0.1098 | 0.1117 | | 0.1152 |+| `brick-graph` | 0.1109 | 0.1221 | 0.1162 | | 0.1476 || `brick-room` | 0.5102 | 0.5020 | 0.0710 | 0.1423 | 0.2727 || `brushed-film` | 0.1029 | 0.0984 | 0.0855 | | 0.1524 || `car-paint` | 0.1038 | 0.0844 | 0.0650 | | 0.1343 |@@ -1055,4 +1055,27 @@ Main reproduced `baseline.json` first on the stored arrays (`brick-flat` 0.1264,- Across a joint's right edge Cycles stays dark over the whole 6 pixel transition (0.25 to 0.36) and 67js is dark over 2 or 3 pixels (0.33 to 0.47). Cycles discards light that arrives from below the geometric surface, and a bumped normal tilted 60 to 70 degrees has a third of its lobe there. 67js lit the full lobe.- Change: for a mapped normal the ambient and reflected sky term is scaled by `0.5 + 0.5 * dot(mapped, geometric)`, the share of an even sky lobe that stays above the surface. `brick-graph` 0.1584 to 0.1518 (EEVEE 0.0875 to 0.0844, CPU the same); all 22 other scenes reproduce their rows to 4 digits (none uses a normal map). Excess over its flat wall: 67js 0.0320 to 0.0254, EEVEE 0.0122.- Still open: the sun is not clipped against the surface plane (the wall faces the sun, so it changes nothing here), the colour gap on the brick faces (Cycles 0.524, EEVEE 0.476, 67js 0.466 in luminance), and a bump scale per world unit instead of per UV unit (Blender's Distance 0.15 is 0.025 per UV unit across and 0.0375 up on this 6 by 4 wall, the bake gives 0.031 both ways). Whether the condition of #50 can be met is still An's decision.-Bundle size: the two shader lines add 9 to 18 bytes gzip to eight bundles that carry the main fragment shader (ntry:core, ntry:agent-scene, ntry:agent-asset, ntry:cascaded-shadows, scene:lit-box, scene:gltf-box, scene:gltf-box+lazy, scene:agent-scene); their budgets rose by 20 to 30 bytes.\ No newline at end of file+Bundle size: the two shader lines add 9 to 18 bytes gzip to eight bundles that carry the main fragment shader (ntry:core, ntry:agent-scene, ntry:agent-asset, ntry:cascaded-shadows, scene:lit-box, scene:gltf-box, scene:gltf-box+lazy, scene:agent-scene); their budgets rose by 20 to 30 bytes.+## Ground bounce (2026-11-03, issue #244)++Cause of the 10.7 percent gap on `brick-flat`, measured: light the ground bounces onto the wall. Main reproduced `baseline.json` first (GPU columns to 4 digits after a fresh render of every scene; `brick-flat` 0.1264, `brick-graph` 0.1518). Cycles of `brick-flat`, 256 samples, RTX 3060, mean display luminance over the wall (rows 110 to 430, columns 230 to 730; same tone map as 67js):++| Cycles setting | wall luminance | linear |+| --- | --- | --- |+| normal (stored) | 0.6150 | 0.2389 |+| floor painted black (`--floor-color 0`) | 0.5466 | 0.1854 |+| light bounces limited to 0 (`--max-bounces 0`, sun and sky only) | 0.5370 | 0.1791 |+| 67js before | 0.5558 | |++The ground adds 0.0535 linear (22 percent of the wall's light) in Cycles. With bounces off, Cycles is 0.019 below 67js (display), so the sun units and colour, the sky irradiance on a vertical wall, Lambert against Principled diffuse and the tone map are not the cause: they leave 67js slightly bright, not dark. 67js showed the lower half of the sky HDRI to the wall, where Cycles has the floor.++Fix: `withGroundBounce(map, { albedo, keyColor, lightDirection })` (`src/ground-bounce.js`, `67js/addons/ground-bounce`) replaces the lower half of the environment map with `albedo * (sun * max(l.y, 0) / pi + sky irradiance on a level surface)` once, when the scene is built. Nothing in the renderer or a shader changes, and a frame costs the same. The suite hands the brick scenes a map with the floor's colour `[0.4, 0.38, 0.32]`; Blender still gets the plain HDRI. Wall luminance 0.5558 to 0.6125 (Cycles 0.6149).++| Scene (GPU, against Cycles) | before | after |+| --- | --- | --- |+| `brick-flat` | 0.1264 | 0.0636 |+| `brick-graph` | 0.1518 | 0.1109 |++Both are now closer to Cycles than EEVEE is (0.1098, 0.1221); against EEVEE they score 0.1117 and 0.1162 because EEVEE has no ground bounce on the wall. Every other scene is unchanged by construction: only `brickWallScene` calls the helper, and the full GPU run on main before the change gave the committed rows. Only these two scenes got the helper: the other scenes with a floor (`material-spheres`, `metal`, `character`, `outdoor-hdri` ...) were not tried, and their floors are not the infinite flat plane the term assumes. The floor's shadow under the wall is ignored, which is why a lower albedo is the way to correct a mostly shaded floor.++`render-blender.py` gained `--max-bounces <n>` and `--floor-color <v>` (Cycles only, like `--world-strength`). Bundle size: `entry:ground-bounce` is new (2832 bytes gzip, budget 2850). `entry:core` measured 85952 on main with or without the new entry, so its budget rose by 5 bytes to 85955.diff --git a/bench/reference/baseline.json b/bench/reference/baseline.jsonindex b0d0d868..de31f706 100644--- a/bench/reference/baseline.json+++ b/bench/reference/baseline.json@@ -101,20 +101,20 @@},"scores": {"brick-flat": {- "gpu-vs-cycles": 0.1264,- "gpu-vs-eevee": 0.0465,- "cpu-vs-cycles": 0.1261,- "cpu-vs-eevee": 0.0462,+ "gpu-vs-cycles": 0.0636,+ "gpu-vs-eevee": 0.1117,+ "cpu-vs-cycles": 0.0633,+ "cpu-vs-eevee": 0.112,"eevee-vs-cycles": 0.1099,- "gpu-vs-cpu": 0.0065+ "gpu-vs-cpu": 0.0066},"brick-graph": {- "gpu-vs-cycles": 0.1518,- "gpu-vs-eevee": 0.0844,- "cpu-vs-cycles": 0.1518,- "cpu-vs-eevee": 0.0844,+ "gpu-vs-cycles": 0.1109,+ "gpu-vs-eevee": 0.1162,+ "cpu-vs-cycles": 0.1109,+ "cpu-vs-eevee": 0.1162,"eevee-vs-cycles": 0.1221,- "gpu-vs-cpu": 0.0077+ "gpu-vs-cpu": 0.0072},"brick-room": {"gpu-vs-cycles": 0.5096,diff --git a/bench/reference/render-blender.py b/bench/reference/render-blender.pyindex d6428b76..3a336665 100644--- a/bench/reference/render-blender.py+++ b/bench/reference/render-blender.py@@ -4,6 +4,8 @@# (0 leaves the sun and the point lights), into <id>-cycles-world<scale>.npy. The EEVEE render and the timings are left alone.# ... -- <work directory> --sun-strength <scale> [scene ids] the same for the sun: Cycles only, the sun times <scale> (0 leaves the world and# the point lights), into <id>-cycles-sun<scale>.npy. Both switches together write <id>-cycles-world<a>-sun<b>.npy.+# ... -- <work directory> --max-bounces <n> [--floor-color <v>] [scene ids] Cycles only, with at most n light bounces (0 is direct light only)+# and/or the part named "floor" painted a grey of v (0 is black), into <id>-cycles-bounces<n>-floor<v>.npy. They show how much light the ground bounces.# Light units were measured on a white plane: sun strength equals irradiance, a point or spot light has 4 pi watts for each# unit of 67js intensity, and an area light has pi watts for each unit.import base64@@ -859,6 +861,24 @@ def scale_sun_light(scene, scale):light.data.energy *= scale+def limit_bounces(scene, bounces):+ """A measurement switch: every Cycles ray type stops after this many bounces (0 leaves direct light and the sky)."""+ scene.cycles.max_bounces = bounces+ scene.cycles.diffuse_bounces = bounces+ scene.cycles.glossy_bounces = bounces+ scene.cycles.transmission_bounces = bounces+++def paint_floor(scene, grey):+ """A measurement switch: the part named floor becomes a plain grey, so the light it bounces is known."""+ floor = scene.objects["floor"]+ for slot in floor.material_slots:+ principled = slot.material.node_tree.nodes["Principled BSDF"]+ for link in list(principled.inputs["Base Color"].links):+ slot.material.node_tree.links.remove(link)+ principled.inputs["Base Color"].default_value = (grey, grey, grey, 1)++def build_scene(description, root):clear_scene()scene_images[:] = description.get("images", [])@@ -892,6 +912,16 @@ def main():flag_index = arguments.index("--sun-strength")sun_scale = float(arguments[flag_index + 1])del arguments[flag_index:flag_index + 2]+ bounces = None+ if "--max-bounces" in arguments:+ flag_index = arguments.index("--max-bounces")+ bounces = int(arguments[flag_index + 1])+ del arguments[flag_index:flag_index + 2]+ floor_grey = None+ if "--floor-color" in arguments:+ flag_index = arguments.index("--floor-color")+ floor_grey = float(arguments[flag_index + 1])+ del arguments[flag_index:flag_index + 2]only = set(arguments[1:])root = os.getcwd()timings = {}@@ -903,8 +933,13 @@ def main():with open(os.path.join(scene_directory, file_name), encoding="utf-8") as file:description = json.load(file)scene = build_scene(description, root)- if world_scale is not None or sun_scale is not None:+ if world_scale is not None or sun_scale is not None or bounces is not None or floor_grey is not None:suffix = ""+ if bounces is not None:+ suffix += f"-bounces{bounces}"+ if floor_grey is not None:+ paint_floor(scene, floor_grey)+ suffix += f"-floor{floor_grey:g}"if world_scale is not None:scale_world_light(scene, world_scale)suffix += f"-world{world_scale:g}"@@ -912,6 +947,8 @@ def main():scale_sun_light(scene, sun_scale)suffix += f"-sun{sun_scale:g}"configure_cycles(scene)+ if bounces is not None:+ limit_bounces(scene, bounces)seconds = render_to_numpy(scene, work_directory, f"{scene_id}-cycles{suffix}")print(f"RENDERED {scene_id} as cycles{suffix}: {seconds:.1f} s")continuediff --git a/bench/reference/scenes.js b/bench/reference/scenes.jsindex 6e6fe848..85641693 100644--- a/bench/reference/scenes.js+++ b/bench/reference/scenes.js@@ -6,6 +6,7 @@ import { parseGltf } from '/src/gltf.js';import { createTree, scatterVegetation, selectLevels, vegetationParts } from '/src/vegetation.js';import { createNoiseHeight, createTerrain } from '/src/terrain.js';import { createAgentScene, loadAgentSceneModules } from '/src/agent-scene.js';+import { withGroundBounce } from '/src/ground-bounce.js';import { materialPatternTextures, normalizeMaterialPattern } from '/src/material-patterns.js';const HDRI_FILE = 'public/hdri/kloofendal_48d_partly_cloudy_puresky_1k.hdr';@@ -106,8 +107,12 @@ function averageLinearColor(colorImage) {return sums.map(sum => sum / pixelCount);}+const BRICK_FLOOR_COLOR = [0.4, 0.38, 0.32];+async function brickWallScene({ withGraph }) {- const lighting = await skyLighting();+ const sky = await skyLighting();+ const bouncedMap = withGroundBounce(sky.map, { albedo: BRICK_FLOOR_COLOR, keyColor: SUN_COLOR, lightDirection: DEFAULT_SUN_DIRECTION });+ const lighting = { ...sky, map: bouncedMap };const pattern = normalizeMaterialPattern({ type: 'graph', graph: brickGraph(), mapping: 'uv', bump: 1, resolution: 512 });const { map, normalMap, boxMapScale, boxMapAxis } = materialPatternTextures(pattern);const wall = withGraph@@ -118,7 +123,7 @@ async function brickWallScene({ withGraph }) {wall.material.graphBump = pattern.bump;}return {- parts: [floor([0.4, 0.38, 0.32]), wall], blenderWorld: lighting.blenderWorld,+ parts: [floor(BRICK_FLOOR_COLOR), wall], blenderWorld: lighting.blenderWorld,environment: environment(lighting, { keyColor: SUN_COLOR }),camera: { eye: [0, 2, 8.5], target: [0, 2, 0], up: [0, 1, 0], fov: 40, near: 0.1, far: 100 },shadow: shadowAlongSun(DEFAULT_SUN_DIRECTION, { target: [0, 1, 0], distance: 13.45, extent: 8, near: 0.1, far: 40 }),diff --git a/bench/size/budgets.json b/bench/size/budgets.jsonindex 77366f2f..f1d9b691 100644--- a/bench/size/budgets.json+++ b/bench/size/budgets.json@@ -6,7 +6,7 @@"agent-scene": 100000},"budgets": {- "entry:core": 85950,+ "entry:core": 85955,"entry:model": 14400,"entry:nature": 13200,"entry:motion": 13600,@@ -31,6 +31,7 @@"entry:grass": 4400,"entry:clutter": 5300,"entry:light-bake": 28500,+ "entry:ground-bounce": 2850,"entry:path-tracer": 14600,"entry:texture-set": 900,"entry:agent-scene": 77810,diff --git a/changes/244.md b/changes/244.mdnew file mode 100644index 00000000..4c529cd3--- /dev/null+++ b/changes/244.md@@ -0,0 +1 @@+- Add `withGroundBounce` (`67js/addons/ground-bounce`): the lower half of an environment map becomes the light a level ground sends back up, so a wall gets ground bounce with no bake and no frame cost; `brick-flat` moves from 0.1264 to 0.0636 against Cycles and `brick-graph` from 0.1518 to 0.1109 (closes #244).diff --git a/docs/light-bake.md b/docs/light-bake.mdindex ddae6e3e..de6e44de 100644--- a/docs/light-bake.md+++ b/docs/light-bake.md@@ -61,6 +61,10 @@ GLB export writes `lightUvs` as `TEXCOORD_1` and the light map as the emissive t`bakeSkyVisibility(parts, lighting, options)` (or `bakeLightmaps` with `skyOnly: true`) shoots one cosine ray per sample from each texel and writes only the occlusion map of the parts that see under 98 percent of the sky. It writes no light and shades nothing, so it takes a second where a bake takes seconds to a minute, and density barely matters (0.5 and 1.5 texels per unit scored the same). On `dark-shaft` and `temple-hall` it gives about half of the improvement a full bake gives (see "Closed rooms without a bake" in `bench/reference/README.md`). The recipe does not use it: a recipe asks for a closed room's bake because `scene_inspect` reports `closed-room-without-bake`.+## Ground bounce without a bake++`withGroundBounce(map, { albedo, keyColor, lightDirection })` from `67js/addons/ground-bounce` returns a copy of an environment map whose lower half is what a level, unshadowed ground sends back up: `albedo * (keyColor * max(lightDirection.y, 0) / pi + sky irradiance on a level surface)`. Hand it to `environment.map` and walls, figures and reflections get the ground's light through the same diffuse and reflection lookups as the sky, with no bake and no cost per frame. Pass the sun the environment already has; `albedo` is the linear colour of the ground. It assumes an infinite floor, so give a small or mostly shaded floor a lower albedo. On the `brick-flat` wall it moves the mean luminance from 0.556 to 0.613 (Cycles 0.615), see "Ground bounce" in `bench/reference/README.md`.+## Reflection probesA probe is the room around a point, traced once and prefiltered like an environment map (`createEnvironmentResources`), so a glossy part reflects the room and not only the sky. `src/reflection-probes.js` holds placement and the renderer link; `src/probe-trace.js` traces on the CPU with the bake's ray tracer (direct light, bounced light, emission; a ray that leaves the scene reads the environment map or the sky colours), 64 by 32 texels, 32 samples and 2 bounces, deterministic, about 0.2 to 0.3 s per probe. A part takes the nearest probe whose `radius` reaches the middle of its bounds, else the environment. A probe lights the specular term only: diffuse stays with the environment and the bake. No parallax correction (not built: a probe at the centre of a room is wrong near the walls).diff --git a/package.json b/package.jsonindex 5037f7cf..6720910d 100644--- a/package.json+++ b/package.json@@ -71,6 +71,7 @@"./addons/grass": "./build/grass.js","./addons/clutter": "./build/clutter.js","./addons/light-bake": "./build/light-bake.js",+ "./addons/ground-bounce": "./build/ground-bounce.js","./addons/path-tracer": "./build/path-tracer.js","./addons/texture-set": "./build/texture-set.js","./addons/agent-scene": "./build/agent-scene.js",diff --git a/src/ground-bounce.js b/src/ground-bounce.jsnew file mode 100644index 00000000..8f1ae40a--- /dev/null+++ b/src/ground-bounce.js@@ -0,0 +1,29 @@+import { computeIrradianceCoefficients, createEnvironmentMap, evaluateIrradiance } from './environment.js'++/**+ * Returns a copy of an environment map whose lower half is the light a flat ground sends back up: albedo times the+ * sun and the sky that reach it, over pi. A wall, a figure or a roof then gets ground bounce from the same diffuse+ * and reflection lookups as the sky, at no cost per frame. The ground is taken as unshadowed, level (y up) and+ * infinite, so a scene with a small or mostly shaded floor should give a smaller albedo.+ *+ * `albedo` is the ground's linear colour, `keyColor` and `lightDirection` are the environment's sun (direction+ * towards the sun, any length), as `environment` takes them.+ */+export function withGroundBounce(map, { albedo, keyColor = [0, 0, 0], lightDirection = [0, 1, 0] }) {+ const { width, height, channels, data, intensity } = map+ const sunLength = Math.hypot(...lightDirection)+ const sunOnGround = Math.max(lightDirection[1] / sunLength, 0)+ const skyOnGround = evaluateIrradiance(computeIrradianceCoefficients(map), [0, 1, 0])+ const groundRadiance = albedo.map((channel, index) => {+ const sun = intensity > 0 ? (keyColor[index] * sunOnGround) / (Math.PI * intensity) : 0+ return channel * (sun + skyOnGround[index])+ })+ const bounced = new Float32Array(data)+ for (let row = Math.ceil(height / 2); row < height; row++) {+ for (let column = 0; column < width; column++) {+ const offset = (row * width + column) * channels+ for (let index = 0; index < 3; index++) bounced[offset + index] = groundRadiance[index]+ }+ }+ return createEnvironmentMap({ ...map, data: bounced })+}diff --git a/tests/ground-bounce.test.js b/tests/ground-bounce.test.jsnew file mode 100644index 00000000..388025e8--- /dev/null+++ b/tests/ground-bounce.test.js@@ -0,0 +1,56 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { createEnvironmentMap, computeIrradianceCoefficients, evaluateIrradiance } from '../src/environment.js';+import { withGroundBounce } from '../src/ground-bounce.js';++const WIDTH = 8;+const HEIGHT = 4;++function uniformSky(value, extra = {}) {+ return createEnvironmentMap({ width: WIDTH, height: HEIGHT, data: new Float32Array(WIDTH * HEIGHT * 3).fill(value), ...extra });+}++function pixel(map, column, row) {+ const offset = (row * map.width + column) * map.channels;+ return Array.from(map.data.slice(offset, offset + 3));+}++test('the lower half becomes albedo times the sky and sun on the ground, and the upper half is kept', () => {+ const sky = uniformSky(0.5);+ const bounced = withGroundBounce(sky, { albedo: [0.4, 0.2, 0.1], keyColor: [Math.PI, Math.PI, Math.PI], lightDirection: [0, 2, 0] });+ const skyOnGround = evaluateIrradiance(computeIrradianceCoefficients(sky), [0, 1, 0]);+ assert.deepEqual(pixel(bounced, 3, 0), pixel(sky, 3, 0));+ assert.deepEqual(pixel(bounced, 3, 1), pixel(sky, 3, 1));+ const expected = [0.4, 0.2, 0.1].map((albedo, index) => albedo * (1 + skyOnGround[index]));+ pixel(bounced, 3, 3).forEach((value, index) => assert.ok(Math.abs(value - expected[index]) < 1e-5));+ assert.deepEqual(pixel(bounced, 0, 2), pixel(bounced, 7, 3));+});++test('a sun below the horizon, black albedo or no sun leaves only the sky term', () => {+ const sky = uniformSky(0.5);+ const skyOnGround = evaluateIrradiance(computeIrradianceCoefficients(sky), [0, 1, 0]);+ const night = withGroundBounce(sky, { albedo: [1, 1, 1], keyColor: [5, 5, 5], lightDirection: [0, -1, 0] });+ assert.ok(Math.abs(pixel(night, 0, 3)[0] - skyOnGround[0]) < 1e-5);+ const black = withGroundBounce(sky, { albedo: [0, 0, 0], keyColor: [5, 5, 5], lightDirection: [0, 1, 0] });+ assert.deepEqual(pixel(black, 0, 3), [0, 0, 0]);+});++test('the map keeps its intensity, rotation and size, and the input map is not changed', () => {+ const sky = uniformSky(0.5, { intensity: 2, rotation: 1, showBackground: true });+ const before = Array.from(sky.data);+ const bounced = withGroundBounce(sky, { albedo: [0.5, 0.5, 0.5], keyColor: [1, 1, 1], lightDirection: [0, 1, 0] });+ assert.equal(bounced.intensity, 2);+ assert.equal(bounced.rotation, 1);+ assert.equal(bounced.showBackground, true);+ assert.equal(bounced.width, WIDTH);+ assert.deepEqual(Array.from(sky.data), before);+});++test('the bounce lights a wall: a vertical normal gets more irradiance than the sky alone gave', () => {+ const sky = uniformSky(0.5);+ const sideways = [1, 0, 0];+ const plain = evaluateIrradiance(computeIrradianceCoefficients(sky), sideways);+ const bounced = withGroundBounce(sky, { albedo: [0.4, 0.4, 0.4], keyColor: [3, 3, 3], lightDirection: [0, 1, 0] });+ const lit = evaluateIrradiance(computeIrradianceCoefficients(bounced), sideways);+ assert.ok(lit[0] > plain[0] * 0.5);+});diff --git a/vite.lib.config.js b/vite.lib.config.jsindex b4fb73f2..7039b352 100644--- a/vite.lib.config.js+++ b/vite.lib.config.js@@ -39,6 +39,7 @@ export default defineConfig({grass: 'src/grass.js',clutter: 'src/clutter.js','light-bake': 'src/light-bake.js',+ 'ground-bounce': 'src/ground-bounce.js','path-tracer': 'src/path-tracer.js','path-tracer-worker': 'src/path-tracer-worker.js','kernel-worker': 'src/kernel-worker.js',