3D engine that AI agents drive
Merge origin/main into fix/probe-parallax
Nguyen Xuan An0ffc9871eea8
diff --cc bench/reference/README.mdindex cb3644c0,0b766ab1..df8ea9a4--- a/bench/reference/README.md+++ b/bench/reference/README.md@@@ -971,20 -971,28 +971,46 @@@ No scene got worse by more than 0.0002`metal` is still 0.0046 above EEVEE, so the first box of #167 stays open. Where the rest is, by 6 by 8 block of the FLIP map (measured): the largest error is the lower half of the chrome sphere, where 67js is 0.062 brighter in display luminance than Cycles (EEVEE 0.022). Cycles shows the floor there darkened by the sphere's own contact shadow, and the sphere's probe traces the scene without the sphere, so the floor it shows is lit all the way to its base (inferred; the "seeing through the part itself" try above, 0.1117, was the attempt at that and was not kept). The rest of the frame is 67js 0.01 to 0.03 darker than Cycles, and EEVEE is darker still, so there is little left to gain from the direct specular. The floor holds over half of the error (0.0639 of 0.1147 in the table above) and is not a reflector.+ ## The sphere's contact shadow in its probe, measured and not kept (2026-11-03, part of issue #167)++ The inference above, that the chrome sphere is too bright because its probe shows a floor with no shadow of the sphere, is right about the direction and wrong about the cure. Main reproduced `baseline.json` to four digits on the stored arrays first (`metal` 0.0962, `car-paint` 0.1028, `brushed-film` 0.1026, `material-spheres` 0.1185, `metal-room` 0.5071). Display luminance of the sphere's lower half, 67js minus Cycles, in four bands below the centre and three columns (GPU; the first column is the plain probe):++ | Band (top to bottom) | left | middle | right |+ | --- | --- | --- | --- |+ | 1 | -0.039 | -0.020 | -0.044 |+ | 2 | -0.038 | -0.024 | +0.048 |+ | 3 | +0.001 | +0.005 | +0.088 |+ | 4 (bottom edge) | +0.038 | +0.142 | +0.312 |++ The mean over the lower half is only +0.015 (Cycles 0.594, 67js 0.609, EEVEE 0.588); the excess sits in the bottom edge and on the right, where the sun's shadow falls in Cycles (sun from -x, +z). So the cause is the one inferred: a floor lit up to the base. Casting the sphere's shadow onto the probe's floor points fixed that edge (band 4 middle +0.142 to -0.092) and overshot everywhere else (band 3 middle +0.005 to -0.107, right +0.088 to -0.141). The probe sits at the sphere's centre, and a ray from the centre to the floor lands far from where the true reflected ray from the surface lands: for a pixel at the bottom of the sphere the true ray leaves the surface a few centimetres above the floor and meets it next to the contact point, while the centre ray meets it about a sphere radius further out. The shadow therefore moves to the wrong floor points.++ Scores against Cycles (GPU, the five scenes with a reflective part; every other scene has no object probe and is unchanged):++ | Variant | `metal` | `car-paint` | `brushed-film` | `material-spheres` | `metal-room` |+ | --- | --- | --- | --- | --- | --- |+ | Main | 0.0962 | 0.1028 | 0.1026 | 0.1185 | 0.5071 |+ | Shadow of the part on the probe's floor, full sun | 0.1038 | 0.1037 | 0.1036 | 0.1186 | 0.5077 |+ | Same, shadowed direct light weighted 0.35 | 0.0982 | 0.1029 | 0.1018 | 0.1184 | 0.5072 |+ | Same, weighted 0.2 | 0.0971 | 0.1028 | 0.1019 | 0.1184 | 0.5071 |++ Every weight is worse for `metal`, so the shadow is not kept and no engine file changed. A cure needs the lookup to account for where the ray leaves the surface (a parallax-corrected probe: the reflected ray intersected with a sphere or box proxy of the part and with the floor plane), which is a shader change with a per-pixel cost and its own issue.++ The floor, checked with the existing screen-space occlusion (`--ambient-occlusion <strength> --ambient-occlusion-radius <units>`, off by default): `metal` 0.0964 (0.5, 0.5), 0.0979 (1, 0.5) and 0.1097 (1, 1.5) against 0.0962 without it, so occlusion does not explain the floor's gap to Cycles either. It helps parts that sit on a floor with little reflection (`car-paint` 0.1028 to 0.1013, 0.1000 and 0.0960; `material-spheres` 0.1185 to 0.1181, 0.1174, then 0.1206), so it stays opt-in. The floor share of the `metal` error is therefore not contact darkening; the bounce light from the metal parts remains the candidate listed in the multiple scattering section.+++## Parallax-corrected object probes (2026-11-03, part of issue #167)++An object probe sits at its part's centre, so a ray reflected at a point on the surface was looked up as if it had left the centre. The probe now records the level floor under it (one ray straight down at trace time, kept only where the surface normal is within 0.99 of up), and the shader sends a reflected ray that heads down toward the point where it meets that plane, seen from the probe: `normalize(hit - probeCentre)`, the plane-projected cube map correction. A probe with no level floor, and every room probe, keeps the plain lookup. The code is compiled in only with the `probe` shader feature, so a scene with no reflective part has the same shader code as before.++Main reproduced `baseline.json` to four digits on the stored arrays first. Scores against Cycles, GPU:++| Variant | `metal` | `car-paint` | `brushed-film` | `material-spheres` | `metal-room` |+| --- | --- | --- | --- | --- | --- |+| Main | 0.0962 | 0.1028 | 0.1026 | 0.1185 | 0.5071 |+| Parallax | 0.0957 | 0.1021 | 0.1016 | 0.1180 | 0.5071 |+| Parallax, plus the part's shadow on the probe's floor (full sun) | 0.0984 | 0.1020 | 0.1000 | 0.1178 | 0.5072 |++Every other scene is unchanged (it has no object probe). The shadow on top of the parallax lookup helps the other three scenes and makes `metal` worse again (0.0957 to 0.0984), so it was not kept; the correction alone is. `metal` is still 0.0041 above EEVEE (0.0916), so the first box of #167 stays open. Parallax moved the sphere's bottom edge less than hoped, which points at the floor term and the bounce light from the other metal parts, not the lookup, as what is left (guessed, not measured).++Frame cost, RTX 3060 (`frame-time.mjs`, 200 frames): `brick-flat` plain 0.385 ms (0.375 to 0.39 before), `metal` plain 0.43 ms (0.44 to 0.45 before). SwiftShader `transparency` in `bench/runtime`: 350.3 ms (345.9 and 347.5 before; 15 frames, machine under load).++Bundle size: the floor trace and the lookup correction add about 250 bytes gzip to the three bundles that carry reflection probes (`entry:agent-scene+lazy`, `entry:agent-asset+lazy`, `scene:agent-scene+lazy`), so each budget in `bench/size/budgets.json` is raised by 280 bytes. Measured: they were over by 244, 239 and 253 bytes.