3D engine that AI agents drive
Merge remote-tracking branch 'origin/main' into resolve-222
Nguyen Xuan An7633e704b09f
diff --cc bench/reference/README.mdindex f555a32b,650dbd35..3cdb098e--- a/bench/reference/README.md+++ b/bench/reference/README.md@@@ -635,21 -635,25 +635,40 @@@ Method: Cycles was rendered a second ti- Terrain sky visibility did read a little high. A brute-force march (48 azimuths, 8 m first step, 8 percent growth) gives 0.68 to 0.69 on the floor and `terrain-sky.js` gave 0.73, because the 1.3 step growth skips narrow peaks. A step growth of 1.1 gives 0.694 at about 0.03 s more build time. It moved the floor from 0.1117 to 0.1073 (nearer Cycles), but the slopes from 0.0258 to 0.0232 (further from Cycles 0.0394), and `mountain-valley` went from 0.2623 to 0.2743 against Cycles. Reverted. The slopes are already darker than Cycles, which has bounced light off the lit walls.- The sky radiance by elevation of the capped HDRI is nearly flat (the share of irradiance above a 40 degree horizon is 0.70 against 0.59 for a uniform sky), so a sky that is brighter near the horizon does not explain the floor.+ ### Where the valley floor's sun comes from (2026-11-03, part of issue #191, tracked in #206)++ Display luminance of the bottom 100 rows of `mountain-valley`, GPU column, stored Cycles and EEVEE renders, `--ambient 0` (sun only in 67js). Cycles reads 0.2753 and EEVEE 0.3082 with the whole sky on; the 67js frame with the sky on reads 0.3620. Each row changes one thing against the first row:++ | 67js, world light 0 | Floor | What it tells |+ | --- | --- | --- |+ | as drawn | 0.1822 | The sun alone lights the floor. |+ | sun term off (`keyColor * 0`) | 0.0015 | All of the 0.1822 is sun, not the fill lights. |+ | shadow term off (visibility 1) | 0.2287 | The shadow map takes only a fifth of the sun away. |+ | terrain left out of the shadow pass | 0.2274 | The shadow comes from the terrain; the trees add almost nothing at this size. |+ | depth bias `0.00002` (was up to `0.002`) | 0.1705 | Bias is not the cause. |+ | shadow LOD selection off | 0.1809 | Not the cause. |-| no culling in the shadow pass | 0.1809 | Not the cause. |++| no instance (frustum) culling in the shadow pass | 0.1809 | Not the cause. |+ | terrain `levels: 1` (no LOD at all) | 0.1822 | Not the cause. |+ | shadow map depth 2,000 m / 6,000 m (was 3,500 m) | 0.1720 / 0.2164 | Moves with the bias, which scales with the depth range; not the cause. |+ | receivers outside the map return 0 instead of 1 | 0.1822 | The floor is inside the map. |++ The geometry says the floor is dark: marching the height function toward the sun (`createNoiseHeight` with the scene's parameters, 336 floor points, 4 m steps to 5 km) finds a horizon above the sun at every point, with a margin of at least 0.295 in tangent (median 0.52) over the sun's 0.227. So the 1,100 m rim blocks the sun by a wide margin, Cycles agrees, and the single shadow map does not show it. The cause is still unknown, and none of the settings above closes it when tried alone. Sky visibility is not the cause: the crown now reads 0.2026 against 0.1762 in Cycles (green pixels above 60 percent of the frame height, EEVEE 0.2295), and the remaining gap on both scenes is the sun shadow of #206.++## The valley floor's sun: back faces in the shadow pass (2026-11-03, part of issue #206)++Probe: the sun shadow depth (2048 x 2048, 24 bit) was copied to a float target and read back, and 259 floor points were projected into it. A march over the terrain's own mesh blocks the sun at all 259; the map shadows 123 of them. For the others the texel holds the floor's own depth where the march's first hit, 1,000 to 1,500 m toward the sun and 300 m up, has a depth of 0.36 against the floor's 0.58. Nothing is drawn there. The cause is the cull state of the shadow pass: it culled back faces. A ray that enters the terrain sideways (the mesh has no wall on its outer edge, and a slope that climbs toward the sun faster than the sun's 13 degrees faces away from the light) meets only back faces, writes no depth, and the sun passes through the rock. In the readback the floor shows as an unoccluded patch under the rim. The ten single changes of #221 could not close it because each left the culling alone; a finest-level terrain (`lodDistance` large) also left the floor at 0.1727.++The shadow depth pass now draws both faces (`applyAlphaState` in `src/renderer.js`, `textured` false). A closed mesh gives the same map, because its front face is the nearest; only an open surface changes. Measured, GPU, 960 x 540:++| | before | after | Cycles |+| --- | --- | --- | --- |+| `mountain-valley` floor, world light 0, display, rows 400 to 540 | 0.1727 | 0.0000 | 0.0003 (linear) |+| `mountain-valley` against Cycles, FLIP | 0.2612 | 0.1792 | |+| every other scene, FLIP against Cycles and EEVEE | | unchanged to four digits | |+| shadow map redraw, median of 3 runs of 40 (RTX 3060) | `mountain-valley` 1.75 to 1.81 ms, `foliage` 0.25 to 0.27, `long-street` 0.15 to 0.18 | 1.81 to 1.88, 0.28 to 0.31, 0.19 | |++The map is redrawn only when a caster, the wind or the assembly changes, so a still scene pays nothing per frame. The floor is now lit by the sky alone, so a tree shadow cannot fall on it: the sun does not reach it, as in Cycles. The `foliage` crown leak is not this cause: its FLIP and picture did not move. The crown's sun-shadow rows (9,252 pixels sun-lit in 67js and shadowed in Cycles) stay open under #206; the depth bias is the remaining lead (a tenth of it removed 2,941 pixels).+## Fog valley against EEVEE (2026-11-03, part of issue #165)`fog-valley` scored 0.1967 against EEVEE's 0.1952. Measured by band of rows on the GPU render (FLIP against Cycles): 67js is better than EEVEE in the sky (0.1311 against 0.1608, and 0.0512 against 0.0815 within 40 pixels of the sun, so the glow is not the problem), and worse below the horizon (0.2437 against 0.2317 at rows 230 to 300, 0.2664 against 0.2576 at rows 300 to 400) and in the left third of the frame (0.2866 against 0.2556), where the shadowed face of the near tower and the ground shadow are darker than in Cycles. The fog's in-scatter inside the sun's shadow is the term that lifts them, and it keeps 15 percent of the ambient there, a constant fitted to closed rooms, where the air in shadow sees walls and not sky.