3D engine that AI agents drive
Absorb sunlight along its refracted path and keep murky water shadows positive (#456)
Nguyen Xuan Ance6a61ddeb9a
diff --git a/bench/reference/README.md b/bench/reference/README.mdindex ff3cbbc4..c2ddbbbd 100644--- a/bench/reference/README.md+++ b/bench/reference/README.md@@ -1829,3 +1829,20 @@ Whole frame FLIP of 67js against Cycles (Cycles tone mapped like 67js), and the| river 4 m | 0.5408 | 0.4834 | -0.042, -0.036, -0.035 | 0.254, 0.247, 0.159 | 0.041, 0.027, 0.002 |Reading it: the FLIP of the dry pool is already 0.34 to 0.48, so most of the score is the dry pool (the bed, the post, the sun's penumbra and the sky are not the same picture in the two renderers), and water adds 0.0 to 0.2 on top. The shadow contrast agrees in trend. Cycles fades the clear lake faster than the formula because the sun's path to the bed is longer than the eye's (slant of 1/cos 59 degrees), which `exp(-absorption * depth)` does not count: the shadow difference is lit (two paths) against shadowed (the eye's path only). The murky river is where the two differ most: Cycles keeps 0.25 of the contrast at 4 m, where scattered light still reaches the shadow, and 67js reaches zero (slightly negative, -0.04: the lift overshoots the lit side). A river that clears to nothing at 4 m is a known simplification of the in-scatter lift; it is recorded here and not changed.++### The sun's path and the murky floor (2026-11-04, closes issue #438)++Two gaps in the table above, fixed in the world material chunk. The sun leg to the bed is now absorbed over the refracted path, `depth / cos(theta_t)` with Snell n = 1.33, so a shadowed bed keeps the eye's vertical leg and a lit bed adds the longer sun leg (the clear lake at 4 m was 0.227 red against 0.064 in Cycles). The turbidity lift that pulled the shadow toward the lit side is gone; the murky water instead adds a positive term, the scattered sunlight the post also shadows, so the contrast never goes below 0 and keeps a floor at depth (about a quarter at 4 m in a river). The sun leg also carries an extinction of `0.9 * turbidity * (1 - turbidity)` per metre, the part of the scatter that is not returned.++The contrast is now read at x = 0.9 m, not 0.65 m, for both renderers: at 4 m the post's foot puts 0.65 m on the edge of the shadow, where the wider murky penumbra and refraction blur make the number depend on the edge, in Cycles as much as in 67js. The Cycles renders are the ones of the section above, not re-rendered (their scene is unchanged). `node scripts/score-water-shadows.mjs --skip-blender` rescores against them. Contrast (red, green, blue) against Cycles, and whole frame FLIP:++| Pool | Before | After | Cycles | FLIP before | FLIP after |+| --- | --- | --- | --- | --- | --- |+| lake 0.2 m | 0.939, 0.971, 0.999 | 0.874, 0.974, 0.970 | 0.861, 0.969, 0.983 | 0.3027 | 0.3170 |+| lake 1 m | 0.698, 0.917, 0.931 | 0.493, 0.853, 0.894 | 0.465, 0.845, 0.903 | 0.4530 | 0.3634 |+| lake 4 m | 0.226, 0.696, 0.792 | 0.061, 0.520, 0.673 | 0.063, 0.523, 0.673 | 0.5628 | 0.4653 |+| river 0.2 m | 0.734, 0.723, 0.627 | 0.739, 0.706, 0.526 | 0.706, 0.679, 0.512 | 0.4654 | 0.3993 |+| river 1 m | 0.206, 0.179, 0.090 | 0.312, 0.280, 0.119 | 0.284, 0.264, 0.159 | 0.5890 | 0.4795 |+| river 4 m | -0.001, -0.002, -0.006 | 0.211, 0.210, 0.120 | 0.251, 0.242, 0.156 | 0.5408 | 0.4491 |++Every row is within 0.05 of Cycles in each channel (largest gap 0.040, river 4 m red). The dry pool scores 0.34 to 0.48 by itself, so FLIP moves less than the contrast. `tests/water-shadows-render.test.js` now expects the clear lake to follow `exp(-absorption * depth * (1 + 1 / cos(theta_t)))` and every preset's contrast to stay at or above 0; the river at 4 m, which it expected below 0.05, is expected between 0.1 and 0.35.diff --git a/bench/reference/water-shadows-score.py b/bench/reference/water-shadows-score.pyindex 7b5f09a9..bf8f05f6 100644--- a/bench/reference/water-shadows-score.py+++ b/bench/reference/water-shadows-score.py@@ -12,7 +12,7 @@ from PIL import ImageGAMMA = 2.2LIT_X = -1.4-SHADOW_X = 0.65+SHADOW_X = 0.9FOV = 40diff --git a/changes/438.md b/changes/438.mdnew file mode 100644index 00000000..be68d53c--- /dev/null+++ b/changes/438.md@@ -0,0 +1 @@+- Water shadows on the bed follow the sun's refracted path (issue #438). The sun leg to a submerged surface is absorbed over `depth / cos(theta_t)` with Snell n = 1.33, so the clear lake at 4 m keeps 0.06 of its shadow contrast in red, as in Cycles, not 0.23. In murky water the lift that pulled the shadow toward the lit side is replaced by a positive in-scatter term, so a shadow never inverts and a river at 4 m keeps about a quarter of its contrast. Contrast for the lake and river at 0.2, 1 and 4 m is within 0.05 of the Cycles reference.diff --git a/changes/438.size.md b/changes/438.size.mdnew file mode 100644index 00000000..b218616f--- /dev/null+++ b/changes/438.size.md@@ -0,0 +1,6 @@+- entry:world-material-shader: the refracted sun path and the murky in-scatter term, about 144 bytes gzip; they fix a shadow that inverted in murky water and a clear lake that faded too slowly.+- entry:vegetation: it imports world-material-shader (about 147 bytes gzip).+- entry:terrain: it imports world-material-shader (about 145 bytes gzip).+- entry:grass: it imports world-material-shader (about 141 bytes gzip).+- entry:clutter: it imports world-material-shader (about 147 bytes gzip).+- scene:agent-scene+lazy: the same chunk, loaded with world materials (124 bytes gzip).diff --git a/scripts/draw-water-sheet.mjs b/scripts/draw-water-sheet.mjsnew file mode 100644index 00000000..250fadb0--- /dev/null+++ b/scripts/draw-water-sheet.mjs@@ -0,0 +1,93 @@+// Draws a labelled before and after sheet of the water shadow pool: a checkout of main beside this one, same cameras.+// node scripts/draw-water-sheet.mjs --before <folder with src and scripts> [--output out/438-sheet.png]+// Rows: shallow clear water (lake, 0.2 m) and deep murky water (river, 4 m). Columns: main and this branch, each from an angle and from above.+import { mkdir, writeFile } from 'node:fs/promises';+import { dirname } from 'node:path';+import { openPage } from './measure-water-shadows.mjs';++const CELL = { width: 320, height: 180 };+const ROWS = [+ { label: 'shallow clear (lake, 0.2 m)', depth: 0.2, water: { waterPreset: 'lake' } },+ { label: 'deep murky (river, 4 m)', depth: 4, water: { waterPreset: 'river' } },+];+const VIEWS = [+ { label: 'angle' },+ { label: 'above' },+];++async function drawSide(root) {+ const { page, close } = await openPage(root);+ try {+ return await page.evaluate(async ({ rows, views, cell }) => {+ const scene = await import('/scripts/water-shadow-scene.js');+ const pictures = [];+ for (const row of rows) {+ for (const view of views) {+ const canvas = document.createElement('canvas');+ canvas.width = cell.width;+ canvas.height = cell.height;+ canvas.style.cssText = `width:${cell.width}px;height:${cell.height}px;display:block`;+ document.body.append(canvas);+ const camera = view.label === 'angle' ? { eye: [-5, 5, 6], target: [0.5, -row.depth, 0] } : { eye: [0, 12, 0], target: [0, 0, 0], up: [0, 0, -1] };+ const renderer = scene.drawPool(canvas, row.depth, row.water, camera);+ pictures.push(canvas.toDataURL('image/png'));+ renderer.dispose?.();+ canvas.remove();+ }+ }+ return pictures;+ }, { rows: ROWS, views: VIEWS, cell: CELL });+ } finally {+ await close();+ }+}++async function compose(sides, outputPath) {+ const { page, close } = await openPage(process.cwd());+ try {+ const dataUrl = await page.evaluate(async ({ sides, rows, views, cell }) => {+ const label = 22;+ const gap = 12;+ const columns = sides.length * views.length;+ const canvas = document.createElement('canvas');+ canvas.width = columns * cell.width + (sides.length - 1) * gap;+ canvas.height = rows.length * (cell.height + label);+ const context = canvas.getContext('2d');+ context.fillStyle = '#16181d';+ context.fillRect(0, 0, canvas.width, canvas.height);+ context.font = '13px sans-serif';+ context.fillStyle = '#e8eaf0';+ for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {+ for (let sideIndex = 0; sideIndex < sides.length; sideIndex++) {+ for (let viewIndex = 0; viewIndex < views.length; viewIndex++) {+ const x = (sideIndex * views.length + viewIndex) * cell.width + sideIndex * gap;+ const y = rowIndex * (cell.height + label);+ context.fillText(`${sides[sideIndex].name}, ${views[viewIndex].label}: ${rows[rowIndex].label}`, x + 4, y + 15);+ const image = new Image();+ image.src = sides[sideIndex].pictures[rowIndex * views.length + viewIndex];+ await image.decode();+ context.drawImage(image, x, y + label);+ }+ }+ }+ return canvas.toDataURL('image/png');+ }, { sides, rows: ROWS, views: VIEWS, cell: CELL });+ await mkdir(dirname(outputPath), { recursive: true });+ await writeFile(outputPath, Buffer.from(dataUrl.split(',')[1], 'base64'));+ } finally {+ await close();+ }+}++const option = name => (process.argv.includes(name) ? process.argv[process.argv.indexOf(name) + 1] : null);+const beforeFolder = option('--before');+if (!beforeFolder) {+ throw new Error('--before <folder with src and scripts of main> is required.');+}+const outputPath = option('--output') ?? 'out/water-sheet.png';+const sides = [+ { name: 'main', pictures: await drawSide(beforeFolder) },+ { name: 'PR', pictures: await drawSide(process.cwd()) },+];+await compose(sides, outputPath);+console.log(`wrote ${outputPath}`);diff --git a/scripts/score-water-shadows.mjs b/scripts/score-water-shadows.mjsindex ffb9a62b..650b1b1e 100644--- a/scripts/score-water-shadows.mjs+++ b/scripts/score-water-shadows.mjs@@ -13,7 +13,7 @@ setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);const WIDTH = 480;const HEIGHT = 270;const BLENDER = process.env.BLENDER_PATH ?? 'C:/Program Files/Blender Foundation/Blender 5.2/blender.exe';-const work = resolve(process.argv[2] ?? 'artifacts/water-shadows');+const work = resolve(process.argv.slice(2).find(argument => !argument.startsWith('--')) ?? 'artifacts/water-shadows');await mkdir(work, { recursive: true });const cases = [];@@ -57,9 +57,11 @@ try {}await writeFile(resolve(work, 'cases.json'), JSON.stringify({ width: WIDTH, height: HEIGHT, calibration, cases }));-const blender = spawnSync(BLENDER, ['-b', '--factory-startup', '-t', '6', '--python', resolve('bench/reference/water-shadows-cycles.py'), '--', resolve(work, 'cases.json'), work], { stdio: 'inherit' });-if (blender.status !== 0) {- throw new Error(`Blender exited with ${blender.status}`);+if (!process.argv.includes('--skip-blender')) {+ const blender = spawnSync(BLENDER, ['-b', '--factory-startup', '-t', '6', '--python', resolve('bench/reference/water-shadows-cycles.py'), '--', resolve(work, 'cases.json'), work], { stdio: 'inherit' });+ if (blender.status !== 0) {+ throw new Error(`Blender exited with ${blender.status}`);+ }}const score = spawnSync('uv', ['run', '--no-project', '--python', '3.12', '--with', 'flip-evaluator', '--with', 'pillow', '--with', 'numpy', 'python', '-I', resolve('bench/reference/water-shadows-score.py'), work], { stdio: 'inherit' });if (score.status !== 0) {diff --git a/src/world-material-shader.js b/src/world-material-shader.jsindex 64527367..bb591585 100644--- a/src/world-material-shader.js+++ b/src/world-material-shader.js@@ -237,11 +237,14 @@ float underwaterVisibility(float visibility, vec3 normal, float depth) {#ifndef shadowVisibilityif (scattering > 0.03) filtered = softShadowVisibility(normal, 1.5 + min(scattering * 6.0, 8.0));#endif- return mix(filtered, 1.0, (1.0 - exp(-scattering * 1.2)) * 0.9);+ return filtered;}`,worldVisibility: ` float waterDepth = 0.0;vec3 waterTransmittance = vec3(1.0);+ vec3 waterSunTransmittance = vec3(1.0);+ float waterScatterShare = 0.0;+ float waterShadowVisibility = 1.0;if (TAG_WATER) {// Only the light that enters the water and comes back is shadowed, and most of what the eye sees comes from deeper than// the shadow reaches, so a shadow on the surface is faint. The reflection mixed in later never sees the shadow.@@ -250,7 +253,13 @@ float underwaterVisibility(float visibility, vec3 normal, float depth) {waterDepth = waterBody.x - worldPosition.y;waterTransmittance = exp(-waterAbsorption * waterDepth);visibility = underwaterVisibility(visibility, normal, waterDepth);+ waterShadowVisibility = visibility;+ // The sun reaches the bed along the refracted ray, depth / cos(theta) with Snell n = 1.33, so its leg is absorbed over a longer path than the eye's.+ float sunSine = sqrt(max(1.0 - pow(normalize(lightDirection).y, 2.0), 0.0)) / 1.33;+ waterSunTransmittance = exp(-(waterAbsorption + 0.9 * waterBody.y * (1.0 - waterBody.y)) * waterDepth / sqrt(1.0 - sunSine * sunSine));+ waterScatterShare = waterBody.y * (1.0 - exp(-0.4 * waterBody.y * waterDepth));}+ vec3 keyColor = keyColor * waterSunTransmittance;`,// Spliced into the colour and shadow vertex shaders by shaders.js.worldVertexWind: `@@ -385,6 +394,8 @@ void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMas// The bed's light reaches the eye through the column, dimmed; the water adds the daylight it scattered toward the eye (clear water a little, murky water more), so deep objects fade into the water colour instead of going black.vec3 scatteredLight = (keyColor * max(normalize(lightDirection).y, 0.0) * 0.1 + vec3(0.04) * ambientIntensity) * exp(-waterAbsorption * 1.5);radiance = radiance * waterTransmittance + scatteredLight * (vec3(1.0) - waterTransmittance) * (0.25 + waterBody.y);+ // Murky water scatters sunlight toward the eye from the column above the bed, and the post shadows that column too, so a shadow keeps a floor of contrast at depth (Cycles keeps about a quarter at 4 m in a river). It never subtracts: the lit side only gains.+ radiance += color * keyResponse / max(waterSunTransmittance, vec3(0.0001)) * max(dot(normal, normalize(lightDirection)), 0.0) * waterShadowVisibility * waterScatterShare * 3.4 * exp(-waterAbsorption);}if (TAG_WATER) {float reflectivity = 0.20 + 0.65 * pow(1.0 - max(dot(normal, viewDirection), 0.0), 3.0);diff --git a/tests/water-shadows-render.test.js b/tests/water-shadows-render.test.jsindex 5d7b8010..50324c13 100644--- a/tests/water-shadows-render.test.js+++ b/tests/water-shadows-render.test.js@@ -9,16 +9,23 @@ import { WATER_PRESETS } from '../src/world-material-shader.js';const chromePath = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';const enabled = process.env.RENDER_TESTS === '1' && existsSync(chromePath);-test('bed shadow contrast follows exp(-absorption * depth) within 10% for clear water, and the surface shadow stays faint', { skip: !enabled, timeout: 240000 }, async () => {+test('bed shadow contrast follows the eye and refracted sun legs within 10% (or 0.05) for clear water, never goes negative, and the surface shadow stays faint', { skip: !enabled, timeout: 240000 }, async () => {const report = await measureWaterShadows();for (const row of report.rows.filter(candidate => candidate.preset === 'lake')) {row.contrast.forEach((measured, channel) => {- const expected = Math.exp(-WATER_PRESETS.lake.absorption[channel] * row.depth);- assert.ok(Math.abs(measured - expected) / expected < 0.1, `lake ${row.depth} m channel ${channel}: measured ${measured.toFixed(3)}, expected ${expected.toFixed(3)}`);+ // The eye's leg is vertical and the sun's leg is the refracted ray, depth / cos(theta_t), with the sun 0.6 off the vertical per metre up and n = 1.33.+ const sineAir = 0.6 / Math.hypot(0.6, 1);+ const cosineWater = Math.sqrt(1 - (sineAir / 1.33) ** 2);+ const expected = Math.exp(-WATER_PRESETS.lake.absorption[channel] * row.depth * (1 + 1 / cosineWater));+ assert.ok(Math.abs(measured - expected) <= Math.max(0.1 * expected, 0.05), `lake ${row.depth} m channel ${channel}: measured ${measured.toFixed(3)}, expected ${expected.toFixed(3)}`);});}+ for (const row of report.rows) {+ assert.ok(Math.min(...row.contrast) >= 0, `${row.preset} ${row.depth} m: the shadow never inverts (${row.contrast.map(value => value.toFixed(3)).join(', ')})`);+ }+ // Cycles keeps about a quarter of the contrast on a murky bed 4 m down (bench/reference/README.md), where Beer-Lambert alone would leave none.const murky = report.rows.find(row => row.preset === 'river' && row.depth === 4);- assert.ok(Math.max(...murky.contrast) < 0.05, 'a shadow on a murky bed 4 m down is gone');+ assert.ok(murky.contrast.every(value => value > 0.1 && value < 0.35), 'a shadow on a murky bed 4 m down keeps a floor of contrast');const surface = report.surface.lake;const darkening = view => Math.max(...surface[view].lit.map((value, channel) => 1 - surface[view].shadowed[channel] / value));assert.ok(darkening('grazing') < 0.01, 'the reflection at a grazing angle is not darkened by the shadow');diff --git a/tests/water-shadows.test.js b/tests/water-shadows.test.jsindex ebbc056e..5bf4f09e 100644--- a/tests/water-shadows.test.js+++ b/tests/water-shadows.test.js@@ -64,3 +64,11 @@ test('the refraction blur averages only the taps that saw the bed, so the bed edassert.ok(source.includes('return seen > 0.5 ? seenColor / seen : fallback;'));assert.ok(!source.includes('seen / 16.0'), 'a share of missed taps must not mix the water colour into the blur');});++test('the sun leg is absorbed over the refracted path and the murky scatter only adds light to the lit side', () => {+ const source = createFragmentShader(['water']);+ assert.ok(source.includes('/ 1.33;'), 'Snell with n = 1.33 sets the refracted sun angle');+ assert.ok(source.includes('/ sqrt(1.0 - sunSine * sunSine)'), 'the sun path is depth / cos(theta_t)');+ assert.ok(source.includes('waterScatterShare * 3.4'), 'the in-scatter is a positive term scaled by the shadow visibility');+ assert.ok(!source.includes('mix(filtered, 1.0'), 'the shadow is not lifted toward the lit side, which inverted it in a murky river');+});