3D engine that AI agents drive
Merge remote-tracking branch 'origin/main' into fix/water-shadows
Nguyen Xuan An48491bc36148
diff --cc bench/reference/README.mdindex 712caa9b,667ad46a..902d3987--- a/bench/reference/README.md+++ b/bench/reference/README.md@@@ -1571,27 -1619,35 +1619,60 @@@ The gap-0 pair is two identical boxes,Pictures: `glass`, `brick-flat`, `outdoor-hdri` and `mountain-valley` drawn by SwiftShader with `render-gpu.mjs --cpu` (standard depth, then reversed through the installed addon), with and without `--reversed-depth`: the first three are byte for byte the same; `mountain-valley` differs on 0.055 percent of its pixels by more than 2 of 255 (largest step 31), the edges of far trees where the depth test breaks a tie differently. With `--ambient-occlusion 1` (which reads the depth texture) `brick-flat` is identical and `mountain-valley` differs on 0.13 percent, largest step 28. The GPU renders of the same four scenes are queued behind a path-tracer job and are not in these numbers.+ ## Sky visibility traced from the floor texels, measured and kept opt-in (2026-11-04, issue #197)++ The attempt the volume section named: trace the sky from the floor itself. `applyFloorSkyVisibility(parts, options)` (`src/floor-sky-visibility.js`, `67js/addons/floor-sky-visibility`, nothing in core) finds the floor parts (thin, at least 2 percent of the scene's footprint, opaque, plain, at least 30 percent of the area facing up, no light map and no baked `skyVisibility`), cuts their upward triangles by the longest edge to about 24,000 texels in total, and from each texel shoots 64 cosine-weighted rays (a fixed set, so the same scene gives the same bytes) against every other opaque part with the bake's BVH tracer. The share that escapes goes into the geometry's `skyVisibility`, which the shader already multiplies into the world and sky light of that surface, so the shader and the core entry are unchanged. `strength` blends the share toward 1 (`1 - strength * (1 - share)`). The trace is capped at 20 s and leaves the parts as they were past it, above 200,000 triangles, or when the scene has no floor. A closed room (the ray test of the ground bounce) is left alone unless `includeClosedRooms` is set. Harness: `npm run reference -- --floor-sky [<strength>] [--floor-sky-rooms]`, `frame-time.mjs --floor-sky=<strength>`.++ Main at `8153626`, GPU, 960 x 540, FLIP against the stored Cycles arrays, 24 scenes of the default suite and the nine grand options; change from a fresh render of main on the same machine (it reproduces the committed rows: `long-street` 0.1121, `material-spheres` 0.0954, `metal` 0.0944). Scoring is the `score.py` FLIP of each GPU frame; no `baseline.json` row is rewritten.++ | Variant | Better than -0.002 | Worse than +0.002 | Worst |+ | --- | --- | --- | --- |+ | Strength 1, rooms traced too | `brick-flat` -0.0067, `brick-graph` -0.0073, `brushed-film` -0.0090, `car-paint` -0.0143, `material-spheres` -0.0103 | 13 | `lit-interior` +0.1207, `brick-room` +0.1157, `metal-room` +0.1044, `long-street` +0.0368, `dark-shaft` +0.0176 |+ | Strength 0.5, closed rooms left alone | `brick-flat` -0.0041, `brick-graph` -0.0039, `brushed-film` -0.0063, `car-paint` -0.0090, `material-spheres` -0.0099 | 4 | `long-street` +0.0135, `megacity-dusk` +0.0032, `emissive-sign` +0.0027, `light-linking` +0.0023 |+ | Strength 0.5, rooms traced too | the five above and `temple-hall` -0.0030 | 8 | `brick-room` +0.0561, `lit-interior` +0.0532, `metal-room` +0.0510, `long-street` +0.0135, `dark-shaft` +0.0073 |++ Grand options (strength 0.5): `megacity-dusk-b` +0.0033, `-c` +0.0017, `-a` -0.0002; the three valley options are untouched (`mountain-valley-a` and `-b` pass the triangle limit, `-c` has no floor part); the three temple options are closed rooms and unchanged, and traced as rooms they improve: `temple-hall-a` 0.1642 to 0.1536, `-b` 0.1564 to 0.1355, `-c` 0.1177 to 0.1016.++ Box 2 (`shadow-depth.py`, display luminance, 67js before > after / Cycles; strength 0.5, rooms traced):++ | Scene | p1 | p5 | p25 | contrast (log2) |+ | --- | --- | --- | --- | --- |+ | `dark-shaft` | 0.0437 > 0.0322 / 0.0293 | 0.0437 > 0.0350 / 0.0313 | 0.0468 > 0.0400 / 0.0430 | 2.46 > 2.51 / 1.96 |+ | `temple-hall-a` | 0.0487 > 0.0423 / 0.0334 | 0.0557 > 0.0507 / 0.0363 | 0.0669 > 0.0555 / 0.0466 | 1.16 > 1.17 / 1.33 |+ | `temple-hall-b` | 0.0709 > 0.0555 / 0.0339 | 0.0717 > 0.0583 / 0.0370 | 0.0787 > 0.0661 / 0.0449 | 0.78 > 0.78 / 1.80 |+ | `temple-hall-c` | 0.0386 > 0.0282 / 0.0163 | 0.0394 > 0.0319 / 0.0184 | 0.0552 > 0.0398 / 0.0222 | 1.33 > 1.34 / 2.02 |+ | `megacity-dusk-a` (not a room) | 0.0494 > 0.0494 / 0.0461 | 0.0628 > 0.0600 / 0.0603 | 0.1124 > 0.1124 / 0.1082 | 2.74 > 2.76 / 2.32 |+ | `long-street` (not a room) | 0.2006 > 0.2006 / 0.1378 | 0.3642 > 0.2986 / 0.3223 | 0.5072 > 0.5072 / 0.4793 | 1.11 > 1.20 / 1.59 |++ The dark end moves toward Cycles in every hall (p1 down by 0.006 to 0.015, p25 down by 0.007 to 0.015) and in `dark-shaft`, but the contrast does not: it moves by at most 0.1 log2 step, and `temple-hall-b` stays at 0.78 against 1.80. Reading (inferred): the light is lowered everywhere on the floor, lit and shadowed tiles alike, because the sky light does not separate them; the contrast needs the sun's shadow to be deeper, which a sky term can not give.++ Which scenes fail, and why (inferred, not isolated): `long-street` (+0.0135 at 0.5) and `megacity-dusk` (+0.0032) are lit by the sun and by light that comes back from the walls and the lit street; the term removes sky from a floor that Cycles still lights from the facades, so the street gets too dark. The rooms lit by lamps alone (`lit-interior`, `brick-room`, `metal-room`) lose their whole ambient floor light, which the lamps' bounce gave; they are why closed rooms are skipped.++ Cost, measured (GPU, `frame-time.mjs --plain`, median of 3 runs in two rounds): the trace takes 0.5 to 1.7 s for the usual 33,000 to 56,000 texels (2.1 to 3.6 million rays, 64 per texel; `brick-room` 6.4 s for 253,000 texels because its floor part is large). Frame time rises because the floor goes from 2 triangles to about 66,000: `long-street` 0.40 to 0.61 ms, `material-spheres` 0.52 to 0.63 ms, `temple-hall-a` 1.50 to 1.80 ms (+0.1 to +0.3 ms; the shadow pass draws the triangles too). A 2D texture read in the shader would avoid that and needs a core hook; it was not tried.++ Box 4 fails: four default scenes pass the 0.002 limit at the best variant (`long-street` +0.0135 is the worst), so the term is not on by default. It stays as an opt-in addon, off unless a scene calls `applyFloorSkyVisibility` or the harness flag is given, so the default frames, `baseline.json` and `grand.json` are unchanged. It helps `car-paint`, `brick-flat`, `brick-graph`, `brushed-film`, `material-spheres` (-0.004 to -0.010) and the three temple options (-0.011 to -0.021), and costs the street and city scenes. Next idea, if taken up: a per-texel map that also carries the light that comes back from the lit walls (the sun-lit side of the facades seen from the floor texel), so a street is darkened by the sky it loses and lit by what the facades give, instead of by sky visibility alone.+++## Water shadows (2026-11-03, part of issue #349)++A post stands in a 12 m pool and the camera looks straight down (`scripts/water-shadow-scene.js`, run by `node scripts/measure-water-shadows.mjs`). Shadow contrast is the lit minus the shadowed bed, per channel, against the same pool dry, so the absorption of the column is what is left. Measured in Chrome with 8 bit output, inverted to linear:++| Preset | Depth | Red | Green | Blue | `exp(-absorption * depth)` for the clear lake (red, green, blue) |+| --- | --- | --- | --- | --- | --- |+| lake | 0.2 m | 0.928 | 0.978 | 1.010 | 0.932, 0.986, 0.992 |+| lake | 1 m | 0.699 | 0.907 | 0.948 | 0.705, 0.932, 0.961 |+| lake | 4 m | 0.227 | 0.694 | 0.785 | 0.247, 0.756, 0.852 |+| sea | 4 m | 0.139 | 0.520 | 0.619 | |+| river | 1 m | 0.204 | 0.190 | 0.087 | |+| river | 4 m | 0.005 | 0.005 | 0.000 | |++The clear lake stays within 10 percent of the formula (the largest gap, 8 percent at 4 m, is the in-scatter of turbidity 0.02). `RENDER_TESTS=1 node --test tests/water-shadows-render.test.js` checks it. On an opaque water surface the post's shadow darkened the steep view by 9.5 to 14 percent before and darkens it by 3 to 4 percent now (river 1.5 percent); the grazing view, which is nearly all reflection, shows 0 percent both times, so the shadow never reaches the mirrored sky.++The reference scenes draw their water as a smooth `surface` part with the planar reflection, not the `water` tag, and the shader code they run is unchanged, so they were not rescored. The Blender Cycles reference of the pool (volume absorption and scatter) and its FLIP score are not taken yet; they wait for a look at the preview.++### Refraction and a dark band (2026-11-04, part of issue #349)++Blended water (a `water` part with opacity below one) now draws its own background: the opaque pass leaves the depth below the water level in the alpha channel of every submerged surface, the water bends the view ray at the surface (n = 1.33, with the wave normal), reads the frame texture where the bent ray meets the bed, and blurs it with a disc of radius turbidity times depth. Where nothing submerged is seen it keeps its own colour. A submerged surface also gets a share of the daylight the water scattered toward the eye, so it fades into the water colour instead of going dark. The bed contrast numbers above hold (lake 4 m: 0.226, 0.688, 0.787 against 0.247, 0.756, 0.852).++The dark band at the foot of a shadow in the first preview was not a doubled shadow: the bed point takes its sun visibility once and the surface lift applies only to water fragments. Along the shadow the bed is even (green channel 0.178 to 0.173 at 1 m, 0.157 to 0.152 at 4 m, seen from above), and a close render shows no band. The band was the shaded side of the submerged post, which got darker with depth and had no scattered light, so it joined the shadow. The scattered light fixes it.++The new preview uses Poly Haven CC0 assets (boulder_01, rock_07, modular_wooden_pier and the gravel_ground_01 material) read from `out/assets`, which is ignored by Git.diff --cc docs/agent-scene.mdindex 01741dbe,12c622af..9dfd4607--- a/docs/agent-scene.md+++ b/docs/agent-scene.md@@@ -100,11 -100,10 +100,11 @@@ Modeling point inputs have a maximum oAn extrusion has at most 128 holes and 4096 total contour points.Shared resource IDs generate geometry once, regardless of the number of mesh nodes.- Materials contain `id`, `tag`, `color`, `metallic`, `roughness`, `emission`, optional `emissiveColor`, `opacity`, `alphaMode`, `doubleSided` and `pattern`.+ Materials contain `id`, `tag`, `color`, `metallic`, `roughness`, `emission`, optional `emissiveColor`, `opacity`, `alphaMode`, `doubleSided`, `pattern` and `map`.The defaults are `surface`, `[0.5, 0.5, 0.5]`, `0`, `0.5`, `0`, opacity `1`, `opaque` and `false`.-The tag can be `surface`, `unlit`, `liquid`, `foam`, `foliage` or `grass` (the last two sway in `environment.wind`) and remains fixed during editing.+The tag can be `surface`, `unlit`, `liquid`, `foam`, `water`, `foliage` or `grass` (the last two sway in `environment.wind`) and remains fixed during editing.`liquid` refracts and tints what lies behind it: its color is the light one metre lets through, so `[0.56, 0.84, 0.88]` is clear water. `foam` draws soft blended droplets.+`water` is a flat mirror sheet (a plane or thin box). The largest one sets the water level: everything below it fades by `exp(-absorption * depth)` per colour channel (`absorption` is RGB per metre), and its shadows are lifted and softened with depth times `turbidity` (0 clear to 1 murky). `waterPreset` fills both: `lake` (default), `sea` or `river`. A shadow on the surface is faint and never darkens the reflection; give the sheet an `opacity` below one when the bed should show.Any `opacity` below one draws the material blended after opaque geometry, which suits glass, windows and visors. `alphaMode` accepts `opaque` or `blend`; cutout masking needs a texture and is not available in procedural recipes.`doubleSided` draws and lights both faces of thin sheets.Changing the tag, opacity, blending, sidedness or pattern replaces the affected parts in the renderer; color, metallic, roughness and emission edits keep them.diff --cc src/agent-scene.jsindex 6a939033,5387cb93..a3d4f394--- a/src/agent-scene.js+++ b/src/agent-scene.js@@@ -24,7 -24,7 +24,7 @@@ const MAX_MESH_REPORTS = 16const TERRAIN_SKY_VISIBILITY_BYTES = 4;const CAMERA_DEFAULTS = Object.freeze({ eye: [4, 3, 5], target: [0, 0, 0], up: [0, 1, 0], fov: 45, near: 0.1, far: 1000 });const NODE_FIELDS = ['translation', 'rotation', 'scale', 'parent', 'label', 'geometry', 'material', 'skin', 'relations', 'asset', 'vegetation', 'decal', 'depthLayer'];- const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'subsurface', 'waterPreset', 'absorption', 'turbidity', ...MATERIAL_LAYER_FIELDS];-const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'map', 'subsurface', ...MATERIAL_LAYER_FIELDS];++const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'map', 'subsurface', 'waterPreset', 'absorption', 'turbidity', ...MATERIAL_LAYER_FIELDS];const PATTERN_TEXTURE_FIELDS = ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap', 'boxMapScale', 'boxMapAxis'];const CAMERA_FIELDS = Object.keys(CAMERA_DEFAULTS);const LOOK_OPERATION_FIELDS = Object.freeze({