Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Merge origin/main into feat/water-reflections

Nguyen Xuan An38a53e0fa8d3
diff --cc bench/reference/README.md
index 9b2fdcd3,f2cd714d..53e39f8a
--- a/bench/reference/README.md
+++ b/bench/reference/README.md
@@@ -244,65 -244,34 +244,93 @@@ A probe at the middle of the object an
Every other scene scored the same to four digits, GPU and CPU. `car-paint` has one reflective part, so it gains little: the clearcoat sphere reflects the floor and nothing else. The issue's second box holds (no frame cost without a reflective part); its first box does not (`metal` is 0.012 above EEVEE).
+## Reflections in still water (2026-11-02, issue #195)
+
+A lake, a river or a bay showed only the sky, where Cycles mirrors the shore, the trees and the towers. A large flat smooth surface now draws the scene from the mirror image of the camera into a target half the canvas size in each direction, and samples that picture. `mountain-valley-a` goes from 0.3530 to 0.2562 against Cycles and `megacity-dusk-b` from 0.1575 to 0.1377. `megacity-dusk-a` (a river between quays) does not improve: 0.1978 to 0.1985.
+
+### Options
+
+Both options ran on the three water options and the two default scenes that hold such a surface. FLIP against Cycles, GPU, full rescore; frame time is the median of three alternating rounds of 200 frames on the RTX 3060 (`node bench/reference/frame-time.mjs <id> gpu --water --grand`), shared with other jobs.
+
+| Option | `mountain-valley-a` | `megacity-dusk-b` | Frame, `mountain-valley-a` | Frame, `megacity-dusk-b` |
+| --- | --- | --- | --- | --- |
+| No reflection (before) | 0.3530 | 0.1575 | 6.37 ms | 2.78 ms |
+| Screen-space reflection (`bench/reference/ssr-water.js`, 80 steps and 6 refinements, full resolution) | 0.3310 | 0.1423 | 7.25 ms | 4.09 ms |
+| Planar reflection (`src/water-reflection.js`) | 0.2562 | 0.1377 | 10.70 ms | 4.82 ms |
+
+The planar reflection wins on the score and costs more: it draws the scene a second time, at a quarter of the pixels but with all of the geometry. The screen-space version can only show what the frame holds, so it loses the shore's far side and anything behind a nearer surface; in `mountain-valley-a` the far peaks and the trees against the sky are most of what the lake shows. It stays in the harness (`--ssr-water`) as the comparison and is not shipped. The planar cost is what a scene with water pays: +4.3 ms and +2.0 ms here. A scene without water pays nothing: `temple-hall-a` measured 2.00 ms off, 1.90 ms planar and 1.80 ms screen-space, which is the spread of the machine, and its shader is the same text.
+
+### What qualifies
+
+No recipe field. `findWaterSurface(parts)` picks parts whose material has `roughness` of at most 0.1 and is not `liquid`, `foam`, `unlit`, `fire`, `smoke` or `floor` and has no `transmission`; whose bounds are flat (taller by at most 2 percent of the wider side); and whose footprint is at least 0.2 percent of the scene's. Metal qualifies the same way as water, so a polished floor reflects too. The largest such part sets the plane, at the top of its bounds, and parts within 5 cm of that height join it. One plane per frame: a second water level is not reflected. A camera below the plane draws no reflection. A narrow river in a wide scene qualifies at 0.2 percent and not at the 1 percent first tried; at 1 percent `megacity-dusk-a` was untouched.
+
+### The look
+
+A mirror looked fake: the first version, a hard reflection mixed in by the shader's own Fresnel, scored 0.2099 on `megacity-dusk-b`, worse than none. Three changes fixed it, in this order of effect:
+
+1. The sky the lighting already adds to a smooth surface is taken out before the reflection is added, so the water does not get the sky twice (the reflection picture holds the sky).
+2. Fresnel from the reflectance of water (0.02 at normal incidence): strong at grazing angles, faint when looking down into the water.
+3. Small moving ripples shake the picture, more with distance, and eight taps smear it, more up and down than across, as ripples stretch a reflection.
+
+Blur alone did not help: 12 taps over a wider area scored worse than 8 over a narrower one on both scenes (0.1944 against 0.1893 on `megacity-dusk-b`, before the sky was taken out). Water colour and depth near the shore are not done: the surface is a box and carries no depth, so the water has the body colour of its material everywhere. By eye, in the image of `mountain-valley-a` the lake reads as real still water: dark, strongly mirrored near the far shore and fading toward the camera. The bay in `megacity-dusk-b` reads as water too, and its reflection of the lit windows is brighter than Cycles': there the band of water is 0.34 where Cycles has 0.10, with or without the reflection, so that part of the gap is the water's body colour or the haze, not the reflection.
+
+### Scores against Cycles (GPU, full rescore, 2026-11-02)
+
+| Scene | Before | After | CPU before | CPU after |
+| --- | --- | --- | --- | --- |
+| `mountain-valley-a` | 0.3530 | 0.2562 | 0.3539 | 0.2567 |
+| `megacity-dusk-b` | 0.1575 | 0.1377 | 0.1584 | 0.1371 |
+| `megacity-dusk-a` | 0.1978 | 0.1985 | 0.1972 | 0.1980 |
+| `mountain-valley-b` | 0.1839 | 0.1784 | 0.1840 | 0.1785 |
+| `foliage` (default suite) | 0.1290 | 0.1181 | 0.1287 | 0.1178 |
+| `mountain-valley` (default suite) | 0.3478 | 0.3490 | 0.3466 | 0.3478 |
+
+The other 19 default scenes and the other 4 grand options re-scored identically to four digits, on GPU and CPU (`--no-water` reproduces the old numbers). Those two default scenes hold a qualifying surface, so they changed. `mountain-valley` is worse by 0.0012 and `megacity-dusk-a` by 0.0007.
+
+### Size
+
+The core grew by 374 bytes gzip in a `lit-box` scene (limit 400): a material field that batches parts, a feature name, a slot in the shader, and the second draw's target and early return. The reflection itself is the addon `67js/addons/water-reflection` (25,403 bytes gzip as an entry, budget 26,000). The shipped archive is 709,306 bytes.
+
+### Use
+
+```js
+import { applyWaterReflection, attachWaterReflection } from '@codepawlhq/67js/addons/water-reflection';
+
+const water = applyWaterReflection(parts);
+const renderer = new Renderer67(canvas, water.parts, options);
+attachWaterReflection(renderer, water.surface);
+```
+
+`water.surface` is null when no part qualifies, and `attachWaterReflection` then does nothing. A recipe scene does not place it yet: the recipe path has no hook that loads the addon from the materials, and that is the next piece of work. `npm run reference -- --no-water` draws the harness scenes without it.
+
+ ## Fog on two more scenes, and a seam in baked rooms (2026-11-02, issues #164 and #165)
+
+ **New scenes.** `fog-valley` is open ground under the HDRI sky with a low sun ahead of the camera, 48 blocks from 25 m to 400 m away and `volumeFog` density 0.005 over the whole field. `fog-room` is a 5 m square room with a window, density 0.2, a constant 0.05 world and the sun coming through the window as a shaft; it declares a `brightRegion` (24.3 percent of the frame). Both are built from engine code, so Blender gets the same geometry. Scores against Cycles on 2026-11-02 (RTX 3060):
+
+ | Scene | 67js whole frame | EEVEE whole frame | 67js region | EEVEE region |
+ | --- | --- | --- | --- | --- |
+ | `fog-room` | 0.1953 | 0.3730 | 0.1682 | 0.3146 |
+ | `fog-valley` | 0.1967 | 0.1952 | | |
+
+ `fog-room` beats EEVEE by a wide margin with the constants of #161 unchanged. `fog-valley` is 0.0015 behind EEVEE, which is inside the CPU and GPU spread of that scene (`gpu-vs-cpu` 0.0122), so the constants hold on a scene they were not fitted to. Every other scene keeps its score to four digits.
+
+ **Constants derived from the scene (tried, not kept).** The ambient floor of 15 percent in shadow is the constant most likely to be wrong in an open scene, so I measured the share of the sky that the fog's air sees: a grid of 512 points in the volume, 48 rays each, and the sun's shadow of each point. The ambient is scaled by the share the sunlit points see, and the shadowed fog keeps the ratio of the two shares. Results against Cycles, region in brackets:
+
+ | Scene | Constants of #161 | Ambient times sunlit share | Same, with the shadow ratio |
+ | --- | --- | --- | --- |
+ | `temple-hall` no bake | 0.1436 (0.2305) | 0.1334 (0.2513) | 0.1329 (0.2519) |
+ | `temple-hall` baked | 0.0559 (0.2523) | 0.0741 (0.2702) | 0.0751 (0.2708) |
+ | `dark-shaft` no bake | 0.1430 (0.1273) | 0.1230 (0.1080) | 0.1226 (0.1080) |
+ | `dark-shaft` baked | 0.0607 (0.1769) | 0.0792 (0.2259) | 0.0798 (0.2259) |
+ | `fog-valley` no bake | 0.1967 | | 0.1998 |
+ | `fog-room` no bake | 0.1953 (0.1682) | | 0.1512 (0.1820) |
+
+ It improves the whole frame of three plain scenes and the region of `dark-shaft`, and worsens both baked rows, the region of `temple-hall`, `fog-valley` and the region of `fog-room`. The region of `temple-hall` is the pixels that Cycles shows bright, and there the fog wants more ambient, not less: a mean share per volume takes light from points that see the sky through the roof slots. A per-point share needs a 3D texture in the post shader, which is more than the 150 byte limit of the core entry, and I did not build it. The change was reverted, so `src/post.js` is as before and #164 is not fixed.
+
+ **The corner line in baked `dark-shaft` (#165).** Measured with a ridge detector on the dark pixels (a pixel brighter than the pixels 3 to 4 px away on both sides): the plain frame has none above 0.03 display luminance, and the baked frame had a 56 px diagonal ridge at the right wall and floor corner (x 767 to 797, y 316 to 337) plus thin lines along the tops of the slabs. It is a bake seam leak. The unwrap packs charts one texel apart, so the texel just outside a chart's edge is the gutter, and `dilate` filled it with the average of every covered neighbour, including the neighbouring chart. The wall's inner face sits next to the outer face, which sees the whole sky: its sky visibility texel read 128 of 255 where the interior reads 1 or 2, and the bilinear read at the wall's bottom edge took about 20 percent of it. `rasterizeTexels` now gives a texel within 0.75 texel of a chart to the nearest triangle, at the nearest point on its edge, so a chart edge is sampled at its own surface; the sky visibility mean counts only texels inside a chart, so the area weighting of `skyVisibility` is unchanged. After the change the edge texel reads 1 against 1 in the row above, and the ridges are gone. The baked rows moved as a side effect: `dark-shaft` 0.0653 (0.1847) to 0.0607 (0.1769) and `temple-hall` 0.0578 (0.2550) to 0.0559 (0.2523).
+
+ Region scores, before and after this change, against Cycles (EEVEE in brackets): `temple-hall` 0.2305 and 0.2523 baked (0.2455), `dark-shaft` 0.1273 and 0.1769 baked (0.2643). Only the baked rows moved, and they moved down.
+
## Baseline
Measured on 2026-10-30 with an RTX 3060, SwiftShader and Blender 5.2.2. The metric is [FLIP](https://github.com/NVlabs/flip) for LDR images: 0 means identical, and a higher score means a larger visible difference.