3D engine that AI agents drive
Merge remote-tracking branch 'origin/main' into fix/water-shadows
Nguyen Xuan An9f7c74ad38be
diff --cc bench/reference/README.mdindex 3aec4357,ed3ff88f..712caa9b--- a/bench/reference/README.md+++ b/bench/reference/README.md@@@ -1535,27 -1551,22 +1551,47 @@@ Fix: `harness.js` renders the referenc`foliage` now sits 0.0086 under EEVEE against Cycles (was 0.0055 over). Every other default and grand scene has no leaf cards and was not re-rendered; the only score that rose is a GPU against CPU difference (`gpu-vs-cpu` of `foliage` 0.0095 to 0.0097, `mountain-valley-b` 0.0158 to 0.0164). The Cycles and EEVEE columns did not move, so this is a change on the 67js side of the comparison and not a new reference. The score no longer includes the wind, which a real scene still has by default (`wind` 0.3); that is by design and is not scored here.+ ## Reversed-Z depth (2026-11-03, issue #310)++ `installReversedDepth(renderer, mode)` (`src/reversed-depth.js`, an addon: the renderer core carries none of it, so a scene that does not install it pays nothing in size) makes the colour pass draw with reversed-Z where `EXT_clip_control` exists. `mode` is `true` (on at once), `false` (off) or `'auto'`, which switches it on, once, at the start of a frame, when that frame's far / near passes 10,000, or when `renderer.requestReversedDepth()` is called; `installDepthPrecision(renderer, { reversedDepth })` installs it together with the coplanar warning and calls that request when the coplanar check finds a flush pair more than 40 units from the eye (a 24-bit buffer with a 0.1 near plane cannot separate a 1 mm gap much beyond that). Switching on respecifies the two depth stores as float and adds one stage that turns the resolved depth back to standard depth for the passes that read it. What it does: clip depth 0 to 1 with the near plane at 1, depth cleared to 0, `GREATER`, and a `DEPTH_COMPONENT32F` multisample buffer and scene depth texture. Everything else keeps the standard path: shadow maps (the sun, cascades and the local atlas), the sky and environment backgrounds and the post passes switch clip control back before they draw, so their projections do not change. The reversed projection is the standard one with its third row replaced by `(w - z) / 2` (`src/reversed-depth.js`), used only by the draw (`renderer.rasterProjection`, `rasterViewProjection`); culling, fog, inverse matrices and the CPU rasterizer keep the standard matrices. The passes that read the depth texture (ambient occlusion, depth of field and the other camera effects, volume fog, line art outlines and lines) are unchanged: a stage right after the resolve copies the depth and writes `1 - depth` back with `gl_FragDepth`, which is exactly the standard 0 to 1 value. The water mirror, render passes (their depth pass is eye distance, not buffer depth), liquid and foam, blended parts and Gaussian splats run inside the reversed window. A decal's polygon offset flips sign with it. `installReversedDepth(renderer, false)`, benchmark mode and a browser without the extension keep the old path (`renderer.reversedDepth` and `renderer.capabilities.reversedDepth` say which one is in use).++ Measured by `node bench/reference/depth-precision.mjs [gpu|cpu]` (scene in `depth-precision.js`): two 2.2-times-distance-wide planes at 1, 50 and 500 m, the near one `gap` closer (0, 0.1 and 1 mm), seen at about 30 degrees from their normal with the default near 0.1 and far 600, 8 camera positions about 1 to 10 cm apart per case. The number is the share of the red or blue pixels where the far (blue) plane wins, mean of the 8; 0 is right. Before is the renderer as it is, after is `installReversedDepth(renderer, true)`, same build. GPU is the RTX 3060 through Chrome (ANGLE), where the extension is present; the run was made without the GPU queue lock because it was busy and takes seconds, and is to be repeated through `gpu-lock.sh`.++ | Distance | Gap | Before (24-bit) | After (reversed, float) |+ | --- | --- | --- | --- |+ | 1 m | 0, 0.1, 1 mm | 0, 0, 0 | 0, 0, 0 |+ | 50 m | 0 mm | 0 | 0 |+ | 50 m | 0.1 mm | 0.150 | 0.009 |+ | 50 m | 1 mm | 0.079 | 0.000 |+ | 500 m | 0 mm | 0 | 0 |+ | 500 m | 0.1 mm | 0.190 | 0.134 |+ | 500 m | 1 mm | 0.188 | 0.015 |++ The gap-0 pair is two identical boxes, so every pixel ties and the first one drawn keeps it; it never flickers, and a coplanar pair of different size is what `decal` and `resolveCoplanar` are for. The wrong share falls to 1 percent or less at 50 m (0.1 and 1 mm) and at 500 m with a 1 mm gap, but not to zero: at 500 m the 0.1 mm case is still wrong on 13 percent of pixels, because a Float32 world position has a step of 0.03 mm there and the vertex transform adds more, which no depth buffer format removes. The next step, not done here, is a camera-relative vertex transform (the view translation applied to the instance matrix in double precision before the projection). SwiftShader also has the extension (the same page ran there). Its numbers are noisier and are not a precision measure: before 0.20 and 0.10 (50 m, 0.1 and 1 mm), 0.10 and 0.41 (500 m); after 0, 0.16, 0 and 0, with whole frames wrong in some jitters at 50 m and 1 mm. Both sets are 8 frames per case and move with the camera positions.++ 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.+++## 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 2a6ef995,e5a197b0..01741dbe--- a/docs/agent-scene.md+++ b/docs/agent-scene.md@@@ -102,9 -102,8 +102,9 @@@ Shared resource IDs generate geometry oMaterials contain `id`, `tag`, `color`, `metallic`, `roughness`, `emission`, optional `emissiveColor`, `opacity`, `alphaMode`, `doubleSided` and `pattern`.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` or `water` and remains fixed during editing.-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 scripts/mcp-server.mjsindex 85637e7e,1c60a341..291946d5--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@@ -101,15 -104,17 +104,23 @@@ const materialLayerFields =};+const waterFields = {+ waterPreset: z.enum(['lake', 'sea', 'river']).optional().describe('Water tag.'),+ absorption: z.array(z.number().min(0).max(20)).length(3).optional().describe('Water tag: RGB per metre.'),+ turbidity: unit.optional().describe('Water tag: 0 clear to 1 murky.'),+};+ const subsurfaceTriple = ([minimum, maximum]) => z.tuple([0, 1, 2].map(() => z.number().min(minimum).max(maximum)));+ const subsurface = z.strictObject({+ weight: z.number().min(SUBSURFACE_RANGES.weight[0]).max(SUBSURFACE_RANGES.weight[1]).optional(),+ radius: subsurfaceTriple(SUBSURFACE_RANGES.radius).optional().describe('RGB mean free path in scale units.'),+ scale: z.number().min(SUBSURFACE_RANGES.scale[0]).max(SUBSURFACE_RANGES.scale[1]).optional().describe('Metres per radius unit.'),+ color: subsurfaceTriple(SUBSURFACE_RANGES.color).optional(),+ }).describe('Subsurface scattering (skin, wax, leaves) as Blender Principled BSDF; details in scene_capabilities materialSubsurface.');const materialFields = {+ ...waterFields,...materialLayerFields,+ subsurface: subsurface.optional(),pattern: materialPattern.optional(),color: color.optional().describe('Linear RGB base color, each component between zero and one.'),metallic: unit.optional(),@@@ -120,7 -125,7 +131,7 @@@alphaMode: z.enum(['opaque', 'blend']).optional().describe('blend draws after opaque geometry, sorted back to front.'),doubleSided: z.boolean().optional().describe('Draw and light both faces (thin sheets, leaves, cloth).'),};- const materialTag = z.enum(['surface', 'unlit', 'liquid', 'foam', 'water']).optional().describe('liquid refracts what lies behind it and absorbs by thickness: color is the light one metre lets through. foam is soft blended whitewater. water is a flat mirror sheet; scene_capabilities water has its fields.');-const materialTag = z.enum(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass']).optional().describe('liquid refracts what lies behind it and absorbs by thickness: color is the light one metre lets through. foam is soft blended whitewater. foliage and grass sway in environment.wind.');++const materialTag = z.enum(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']).optional().describe('liquid refracts what lies behind it and absorbs by thickness: color is the light one metre lets through. foam is soft blended whitewater. foliage and grass sway in environment.wind. water is a flat mirror sheet; scene_capabilities water has its fields.');const liquidOptics = z.strictObject({thickness: z.number().min(0).max(100).optional().describe('Metres of liquid where it faces the camera.'),ior: z.number().min(1).max(3).optional(),diff --cc src/agent-scene-capabilities.jsindex 8623db7a,5ff5e38a..34b6b201--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@@ -179,9 -171,7 +179,9 @@@ export const AGENT_SCENE_CAPABILITIES'add-geometry', 'remove-geometry', 'add-material', 'remove-material','set-environment', 'set-effects', 'set-shadow', 'set-motion', 'set-armatures', 'set-physics', 'set-cloth', 'set-timeline', 'set-particles', 'set-bake', 'edit-mesh', 'set-mesh-stack',]),- materialTags: Object.freeze(['surface', 'unlit', 'liquid', 'foam', 'water']),- materialTags: Object.freeze(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass']),++ materialTags: Object.freeze(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']),+ // A flat water sheet; the largest sets the level. A bed d metres down keeps exp(-absorption * d) per channel (RGB per metre).+ water: Object.freeze({ presets: WATER_PRESETS_SUMMARY, default: 'lake', note: 'absorption 0..20, turbidity 0..1 softens shadows below; opacity under 1 shows the bed.' }),materialLayers: Object.freeze(Object.fromEntries(MATERIAL_LAYER_FIELDS.map(field => [field, Object.freeze({range: MATERIAL_LAYER_SCALAR_RANGES[field] ?? MATERIAL_LAYER_COLOR_RANGES[field] ?? 'above 0',note: MATERIAL_LAYER_NOTES[field],diff --cc src/agent-scene.jsindex 8042b639,b17356c0..979ccb13--- a/src/agent-scene.js+++ b/src/agent-scene.js@@@ -23,9 -23,8 +23,9 @@@ const MAX_MESH_REPORTS = 16// Terrain meshes carry one more float for each vertex (sky visibility) than the 56 bytes the budget estimates.const 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', 'decal', 'depthLayer'];+ 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', ...MATERIAL_LAYER_FIELDS];+const WATER_MATERIAL_FIELDS = ['waterPreset', 'absorption', 'turbidity'];- const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', ...WATER_MATERIAL_FIELDS, ...MATERIAL_LAYER_FIELDS];++const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'subsurface', ...WATER_MATERIAL_FIELDS, ...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({diff --cc tests/agent-scene.test.jsindex b6643c27,933b8721..7adb4594--- a/tests/agent-scene.test.js+++ b/tests/agent-scene.test.js@@@ -93,7 -93,7 +93,7 @@@ test('shader arithmetic rejects cancell});test('recipes author liquid, foam and blended glass with batch-safe material handles', () => {- assert.deepEqual(AGENT_SCENE_CAPABILITIES.materialTags, ['surface', 'unlit', 'liquid', 'foam', 'water']);- assert.deepEqual(AGENT_SCENE_CAPABILITIES.materialTags, ['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass']);++ assert.deepEqual(AGENT_SCENE_CAPABILITIES.materialTags, ['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']);const input = recipe();input.materials.push({ id: 'water', tag: 'liquid', color: [0.56, 0.84, 0.88], roughness: 0.05 });input.materials.push({ id: 'glass', color: [0.9, 0.95, 1], opacity: 0.3, doubleSided: true });