3D engine that AI agents drive
Make shadows on and under water follow absorption and turbidity (part of #349)
Nguyen Xuan An079b110ce751
diff --git a/changes/349.md b/changes/349.mdnew file mode 100644index 00000000..59318bfb--- /dev/null+++ b/changes/349.md@@ -0,0 +1 @@+- Water shadows follow the water (issue #349). A sun shadow on a `water` surface is faint and never darkens the reflection, and everything below the water level fades by `exp(-absorption * depth)` per colour, with shadows lifted and softened by depth times `turbidity`. Recipes take the `water` material tag with `waterPreset` (`lake`, `sea`, `river`), `absorption` (RGB per metre) and `turbidity` (0 to 1), listed in `scene_capabilities` under `water`. The code sits in the world material addon, so a renderer without water does not carry it, and the MCP tool count is unchanged.diff --git a/changes/349.size.md b/changes/349.size.mdnew file mode 100644index 00000000..e7b07973--- /dev/null+++ b/changes/349.size.md@@ -0,0 +1,7 @@+- entry:world-material-shader: the water body code (presets, level search, uniform binding) and the underwater shadow GLSL load only with world materials, about 1.3 KB gzip.+- entry:vegetation: it imports world-material-shader, which now carries the water optics (about 1.1 KB gzip).+- entry:terrain: it imports world-material-shader, which now carries the water optics (about 1.1 KB gzip).+- entry:grass: it imports world-material-shader, which now carries the water optics (about 1.1 KB gzip).+- entry:clutter: it imports world-material-shader, which now carries the water optics (about 1.1 KB gzip).+- scene:agent-scene: the recipe water fields and the preset summary in the capabilities (270 bytes gzip).+- scene:agent-scene+lazy: the water optics in the world material chunk plus the recipe fields (about 1.6 KB gzip).diff --git a/docs/agent-scene.md b/docs/agent-scene.mdindex b8813ed4..2a6ef995 100644--- a/docs/agent-scene.md+++ b/docs/agent-scene.md@@ -102,8 +102,9 @@ Shared resource IDs generate geometry once, regardless of the number of mesh nodMaterials 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` or `foam` and remains fixed during editing.+The tag can be `surface`, `unlit`, `liquid`, `foam` or `water` 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 --git a/out/349-preview.png b/out/349-preview.pngnew file mode 100644index 00000000..dc068d9cBinary files /dev/null and b/out/349-preview.png differdiff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 3724319a..85637e7e 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -101,7 +101,14 @@ 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 materialFields = {+ ...waterFields,...materialLayerFields,pattern: materialPattern.optional(),color: color.optional().describe('Linear RGB base color, each component between zero and one.'),@@ -113,7 +120,7 @@ const materialFields = {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']).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.');+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 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 --git a/scripts/measure-water-shadows.mjs b/scripts/measure-water-shadows.mjsnew file mode 100644index 00000000..40cde96f--- /dev/null+++ b/scripts/measure-water-shadows.mjs@@ -0,0 +1,138 @@+// Measures the water shadow scene (scripts/water-shadow-scene.js) in Chrome and can draw a before and after picture.+// bash ~/.agents/tools/gpu-lock.sh node scripts/measure-water-shadows.mjs [--preview out/349-preview.png --before <folder with src and scripts>]+// Without --preview it prints the shadow contrast of the bed at 0.2, 1 and 4 m for each preset, against exp(-absorption * depth).+import { mkdir, writeFile } from 'node:fs/promises';+import { dirname } from 'node:path';+import { pathToFileURL } from 'node:url';+import { chromium } from 'playwright';+import { createServer } from 'vite';++export const WATER_DEPTHS = [0.2, 1, 4];+const PRESETS = { lake: { waterPreset: 'lake' }, sea: { waterPreset: 'sea' }, river: { waterPreset: 'river' } };+const CELL = { width: 213, height: 120 };++async function openPage(root) {+ const server = await createServer({ root, server: { host: '127.0.0.1', port: 0 }, logLevel: 'silent' });+ await server.listen();+ const browser = await chromium.launch({ executablePath: process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe', headless: true, args: ['--enable-webgl', '--ignore-gpu-blocklist', '--use-angle=d3d11'] });+ const page = await browser.newPage({ viewport: { width: 1400, height: 800 } });+ await page.route('**/water-shadow-page.html', route => route.fulfill({ contentType: 'text/html', body: '<body style="margin:0;background:#222"></body>' }));+ await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/water-shadow-page.html`);+ return { page, close: async () => { await browser.close(); await server.close(); } };+}++/** Bed contrast and surface shadow numbers, drawn in the checkout at `root`. */+export async function measureWaterShadows(root = process.cwd()) {+ const { page, close } = await openPage(root);+ try {+ return await page.evaluate(async ({ depths, presets }) => {+ const scene = await import('/scripts/water-shadow-scene.js');+ const makeCanvas = (width, height) => {+ const canvas = document.createElement('canvas');+ canvas.width = width;+ canvas.height = height;+ canvas.style.cssText = `width:${width}px;height:${height}px;display:block`;+ document.body.append(canvas);+ return canvas;+ };+ const canvas = makeCanvas(200, 120);+ const rows = [];+ for (const [name, water] of Object.entries(presets)) {+ for (const depth of depths) {+ const dry = scene.measureBed(canvas, depth, null);+ const wet = scene.measureBed(canvas, depth, water);+ const contrast = channel => (wet.lit[channel] - wet.shadowed[channel]) / (dry.lit[channel] - dry.shadowed[channel]);+ rows.push({ preset: name, depth, dry, wet, contrast: [0, 1, 2].map(contrast) });+ }+ }+ const surface = {};+ for (const [name, water] of Object.entries(presets)) surface[name] = scene.measureSurface(canvas, water);+ return { rows, surface };+ }, { depths: WATER_DEPTHS, presets: PRESETS });+ } finally {+ await close();+ }+}++// One side of the picture: three pool depths in each of two waters, and the opaque surface from a steep and a grazing view.+async function drawSide(root) {+ const { page, close } = await openPage(root);+ try {+ return await page.evaluate(async ({ depths, cell }) => {+ const scene = await import('/scripts/water-shadow-scene.js');+ const cells = [];+ const capture = (drawer) => {+ const canvas = document.createElement('canvas');+ canvas.width = cell.width;+ canvas.height = cell.height;+ canvas.style.cssText = `width:${cell.width}px;height:${cell.height}px;display:block`;+ document.body.append(canvas);+ const renderer = drawer(canvas);+ cells.push(canvas.toDataURL('image/png'));+ renderer.dispose?.();+ canvas.remove();+ };+ for (const water of [{ waterPreset: 'lake' }, { waterPreset: 'river' }]) {+ for (const depth of depths) capture(canvas => scene.drawPool(canvas, depth, water, { eye: [-4.5, 4, 5.5], target: [0.4, -depth * 0.5, 0] }));+ }+ for (const view of [{ eye: [1.5, 9, 3], target: [0, -0.05, 0.5] }, { eye: [4, 0.8, 6], target: [0, -0.05, 0.5] }]) {+ capture(canvas => scene.drawPool(canvas, 1, { waterPreset: 'sea' }, view, true));+ }+ return cells;+ }, { depths: WATER_DEPTHS, cell: CELL });+ } finally {+ await close();+ }+}++async function composePreview(beforeCells, afterCells, outputPath) {+ const { page, close } = await openPage(process.cwd());+ try {+ const dataUrl = await page.evaluate(async ({ beforeCells, afterCells, cell }) => {+ const gap = 16;+ const label = 24;+ const sideWidth = cell.width * 3;+ const sideHeight = cell.height * 3;+ const canvas = document.createElement('canvas');+ canvas.width = sideWidth * 2 + gap;+ canvas.height = sideHeight + label;+ const context = canvas.getContext('2d');+ context.fillStyle = '#16181d';+ context.fillRect(0, 0, canvas.width, canvas.height);+ context.font = '14px sans-serif';+ context.fillStyle = '#e8eaf0';+ context.fillText('before: lake, river by depth 0.2 / 1 / 4 m, opaque surface steep and grazing', 4, 16);+ context.fillText('after', sideWidth + gap + 4, 16);+ for (const [side, cells] of [[0, beforeCells], [1, afterCells]]) {+ for (let index = 0; index < cells.length; index++) {+ const image = new Image();+ image.src = cells[index];+ await image.decode();+ context.drawImage(image, side * (sideWidth + gap) + (index % 3) * cell.width, label + Math.floor(index / 3) * cell.height);+ }+ }+ return canvas.toDataURL('image/png');+ }, { beforeCells, afterCells, cell: CELL });+ await mkdir(dirname(outputPath), { recursive: true });+ await writeFile(outputPath, Buffer.from(dataUrl.split(',')[1], 'base64'));+ } finally {+ await close();+ }+}++if (import.meta.url === pathToFileURL(process.argv[1]).href) {+ const option = name => (process.argv.includes(name) ? process.argv[process.argv.indexOf(name) + 1] : null);+ const previewPath = option('--preview');+ if (previewPath) {+ const beforeFolder = option('--before');+ const [beforeCells, afterCells] = [await drawSide(beforeFolder), await drawSide(process.cwd())];+ await composePreview(beforeCells, afterCells, previewPath);+ console.log(`wrote ${previewPath}`);+ } else {+ const report = await measureWaterShadows();+ for (const row of report.rows) {+ console.log(row.preset, row.depth, 'contrast', row.contrast.map(value => value.toFixed(3)).join(' '));+ }+ console.log(JSON.stringify(report.surface));+ }+}diff --git a/scripts/water-shadow-scene.js b/scripts/water-shadow-scene.jsnew file mode 100644index 00000000..7b6cfcde--- /dev/null+++ b/scripts/water-shadow-scene.js@@ -0,0 +1,89 @@+// The water shadow test scene, shared by scripts/measure-water-shadows.mjs and the preview. It runs in the browser page:+// a post stands in a pool, its shadow falls on the bed, and the camera looks straight down (or along the water for the reflection).+import { Renderer67 } from '../src/renderer.js';+import { box } from '../src/geometry.js';+import '../src/world-material-shader.js';++const SUN_DIRECTION = [-0.6, 1, 0];+const POST_TOP = 1.5;+const POOL_SIZE = 12;+const unitBox = box(0, 1);++function placed(name, center, size, material, castShadow) {+ const matrix = new Float32Array([size[0], 0, 0, 0, 0, size[1], 0, 0, 0, 0, size[2], 0, center[0], center[1], center[2], 1]);+ return { name, geometry: unitBox, matrix, material, ...(castShadow === undefined ? {} : { castShadow }) };+}++const SURFACE = { tag: 'surface', color: [0.3, 0.3, 0.3], metallic: 0, roughness: 0.9, emission: 0 };++/** The parts of a pool `depth` metres deep. `water` is the water material fields; `visible` makes the sheet opaque. */+export function poolParts(depth, water, { visible = false } = {}) {+ const sheet = { tag: 'water', color: [0.02, 0.05, 0.08], metallic: 0, roughness: 0.1, emission: 0, ...water, ...(visible ? {} : { opacity: 0.001, alphaMode: 'blend' }) };+ return [+ placed('bed', [0, -depth - 0.5, 0], [POOL_SIZE, 1, POOL_SIZE], SURFACE),+ placed('post', [0, (POST_TOP - depth) / 2, 0], [0.5, POST_TOP + depth, 0.5], { ...SURFACE, color: [0.6, 0.4, 0.3] }),+ placed('water', [0, -0.05, 0], [POOL_SIZE, 0.1, POOL_SIZE], sheet, false),+ ];+}++function drawFrame(canvas, parts, { eye, target, up = [0, 1, 0], fov = 30, hdr = false }) {+ const renderer = new Renderer67(canvas, parts, { hdr, depth: false, world: false, ground: false, pixelRatio: 1, samples: 1, environment: { lightDirection: SUN_DIRECTION, keyColor: [3, 3, 3] } });+ renderer.render({ eye, target, up, fov, time: 0, environment: { lightDirection: SUN_DIRECTION } });+ return renderer;+}++function inverseToneMap(value) {+ let low = 0;+ let high = 40;+ const acesCurve = color => Math.min(Math.max((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), 0), 1);+ for (let step = 0; step < 40; step++) {+ const middle = (low + high) / 2;+ if (acesCurve(middle) < value) low = middle; else high = middle;+ }+ return (low + high) / 2;+}++function readLinear(renderer, canvas, worldPoint) {+ const matrix = renderer.viewProjection;+ const clip = [0, 1, 2, 3].map(row => matrix[row] * worldPoint[0] + matrix[4 + row] * worldPoint[1] + matrix[8 + row] * worldPoint[2] + matrix[12 + row]);+ const pixelX = Math.round((clip[0] / clip[3] * 0.5 + 0.5) * canvas.width);+ const pixelY = Math.round((clip[1] / clip[3] * 0.5 + 0.5) * canvas.height);+ const context = renderer.context;+ const bytes = new Uint8Array(4);+ context.readPixels(pixelX, pixelY, 1, 1, context.RGBA, context.UNSIGNED_BYTE, bytes);+ return [0, 1, 2].map(channel => inverseToneMap(Math.pow(bytes[channel] / 255, 2.2)));+}++const OVERHEAD = { eye: [0, 12, 0], target: [0, 0, 0], up: [0, 0, -1] };+const SHADOW_OFFSET = 0.65;+const LIT_OFFSET = -1.4;++/** Linear RGB of the lit and the shadowed bed at the bottom of a pool, seen from above. `water` null draws the pool dry. */+export function measureBed(canvas, depth, water) {+ const parts = water ? poolParts(depth, water) : poolParts(depth, { tag: 'surface' }).filter(part => part.name !== 'water');+ const renderer = drawFrame(canvas, parts, OVERHEAD);+ const lit = readLinear(renderer, canvas, [LIT_OFFSET, -depth, 0]);+ renderer.render({ ...OVERHEAD, fov: 30, time: 0, environment: { lightDirection: SUN_DIRECTION } });+ const shadowed = readLinear(renderer, canvas, [SHADOW_OFFSET, -depth, 0]);+ renderer.dispose?.();+ return { lit, shadowed };+}++const GRAZING = { eye: [4, 0.8, 6], target: [0, -0.05, 0.5] };++/** Linear RGB of an opaque water surface in and out of the post's shadow, from a grazing and from a steep view. */+export function measureSurface(canvas, water) {+ const result = {};+ for (const [label, view] of [['grazing', GRAZING], ['steep', { eye: [1.5, 9, 3], target: [0, -0.05, 0.5] }]]) {+ const renderer = drawFrame(canvas, poolParts(1, water, { visible: true }), { ...view, fov: 30 });+ result[label] = { lit: readLinear(renderer, canvas, [LIT_OFFSET, -0.05, 2]), shadowed: readLinear(renderer, canvas, [SHADOW_OFFSET, -0.05, 0]) };+ renderer.dispose?.();+ }+ return result;+}++/** One frame of the pool for a picture; the caller reads the canvas before the next frame. `visible` draws the water sheet opaque. */+export function drawPool(canvas, depth, water, view = { eye: [-5, 5, 6], target: [0.5, -depth, 0] }, visible = false) {+ const renderer = drawFrame(canvas, poolParts(depth, water, { visible }), { ...view, fov: 40 });+ return renderer;+}diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 15eb2cb0..8623db7a 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -16,6 +16,14 @@ export const AGENT_SCENE_DEFAULT_LIMITS = Object.freeze({maxOperations: 256, maxCheckpoints: 8, maxRecipeBytes: 1024 * 1024,});+// The values of the water presets (src/world-material-shader.js holds the same numbers; a test keeps them in step), written out+// here so the capabilities do not pull the shader addon into every agent scene.+const WATER_PRESETS_SUMMARY = Object.freeze({+ lake: Object.freeze({ absorption: Object.freeze([0.35, 0.07, 0.04]), turbidity: 0.02 }),+ sea: Object.freeze({ absorption: Object.freeze([0.4, 0.06, 0.02]), turbidity: 0.1 }),+ river: Object.freeze({ absorption: Object.freeze([0.8, 0.9, 1.6]), turbidity: 0.75 }),+});+// What each recipe material layer does, beside its range; the MCP schema keeps one short line per field.const MATERIAL_LAYER_NOTES = Object.freeze({clearcoat: 'Lacquer lobe over the base, surface tag.',@@ -171,7 +179,9 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({'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']),+ materialTags: Object.freeze(['surface', 'unlit', 'liquid', 'foam', '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 --git a/src/agent-scene.js b/src/agent-scene.jsindex 7cf8f587..8042b639 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -24,7 +24,8 @@ const MAX_MESH_REPORTS = 16;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 MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', ...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 PATTERN_TEXTURE_FIELDS = ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap', 'boxMapScale', 'boxMapAxis'];const CAMERA_FIELDS = Object.keys(CAMERA_DEFAULTS);const LOOK_OPERATION_FIELDS = Object.freeze({@@ -197,6 +198,17 @@ function copyMaterialLayers(value, result) {if (result.toon > 0) agentSceneModule('lineArt');}+// Water optics (src/world-material-shader.js): a water material always carries the resolved absorption, turbidity and preset.+function copyWaterFields(value, result) {+ const given = WATER_MATERIAL_FIELDS.filter(field => value[field] !== undefined);+ if (result.tag !== 'water') {+ if (given.length > 0) throw new RangeError(`${given.join(', ')} need the water tag.`);+ return;+ }+ const fields = agentSceneModule('worldMaterials').resolveWaterMaterial({ ...value, absorption: value.absorption === undefined ? undefined : vector(value.absorption, 3, 'absorption') });+ Object.assign(result, fields);+}+function materialFrom(value) {knownKeys(value, ['id', 'tag', ...MATERIAL_FIELDS], 'material');// A pattern brings its own colours, so the color field tints it and leaves it unchanged by default.@@ -245,6 +257,7 @@ function materialFrom(value) {}}copyMaterialLayers(value, result);+ copyWaterFields(value, result);const emissiveColor = result.emissiveColor ?? result.color;for (const component of emissiveColor) {const radiance = Math.fround(component) * Math.fround(result.emission);@@ -778,7 +791,7 @@ function materialHandle(snapshot) {}function immutableMaterial(snapshot) {- for (const field of ['color', 'emissiveColor']) {+ for (const field of ['color', 'emissiveColor', 'absorption']) {if (snapshot[field]) {Object.freeze(snapshot[field]);}diff --git a/src/shaders.js b/src/shaders.jsindex 9d384535..f13787ae 100644--- a/src/shaders.js+++ b/src/shaders.js@@ -580,7 +580,7 @@ ${featureCode("mainSetup")} if (ENVIRONMENT_ENABLED && !LIGHT_SHADING) {directSpecularGain = multipleScatterGain(brdfLookup, baseReflectance);}float visibility = shadowVisibility(normal);- vec3 radiance = illuminate(normal, viewDirection, normalize(lightDirection), keyColor * visibility${featureCode("linkSun")}, color, metallic, roughness);+${featureCode("worldVisibility")} vec3 radiance = illuminate(normal, viewDirection, normalize(lightDirection), keyColor * visibility${featureCode("linkSun")}, color, metallic, roughness);if (FILL_ON) {radiance += illuminate(normal, viewDirection, normalize(vec3(4.0, 2.0, -3.0)), mix(vec3(0.8, 2.0, 1.8), vec3(0.12, 0.17, 0.20) * daylight, worldMode) * fillIntensity * mix(1.0, vertexSkyVisibility, worldMode), color, metallic, roughness);radiance += illuminate(normal, viewDirection, normalize(vec3(1.0, 2.0, 5.0)), vec3(0.6, 0.7, 0.8) * mix(1.0, 0.25 * daylight, worldMode) * fillIntensity * mix(1.0, vertexSkyVisibility, worldMode), color, metallic, roughness);diff --git a/src/world-material-shader.js b/src/world-material-shader.jsindex e3d1c779..0efc3d48 100644--- a/src/world-material-shader.js+++ b/src/world-material-shader.js@@ -1,4 +1,118 @@-import { registerShaderFeatureCode } from './shader-registry.js';+import { layerTextureSupport, registerShaderFeatureCode } from './shader-registry.js';++// Water bodies. A material with the water tag can carry `absorption` (RGB per metre: how fast each colour fades going down) and+// `turbidity` (0 clear to 1 murky: how much light the water scatters into shadows). The largest flat water part of a scene sets+// the water level. Every surface below it is dimmed by Beer-Lambert absorption of the column above it, and its shadows are lifted+// by in-scatter and widened with depth times turbidity (worldVisibility below). Absorption folds the way down and the way back up+// into one coefficient, so a bed `depth` metres down keeps exp(-absorption * depth) of its light.+/** Water the way people name it: where the light goes and how far a shadow stays sharp. */+export const WATER_PRESETS = Object.freeze({+ lake: Object.freeze({ absorption: Object.freeze([0.35, 0.07, 0.04]), turbidity: 0.02 }),+ sea: Object.freeze({ absorption: Object.freeze([0.4, 0.06, 0.02]), turbidity: 0.1 }),+ river: Object.freeze({ absorption: Object.freeze([0.8, 0.9, 1.6]), turbidity: 0.75 }),+});+export const WATER_DEFAULT_PRESET = 'lake';+export const WATER_MAXIMUM_ABSORPTION = 20;+// A water part counts as one level when it is this flat: thickness against its wider side.+const WATER_MAXIMUM_THICKNESS_RATIO = 0.02;++/** Resolves a material's water fields: an explicit absorption or turbidity beats the preset, which beats the default lake. */+export function resolveWaterMaterial({ waterPreset, absorption, turbidity } = {}) {+ const preset = waterPreset ?? WATER_DEFAULT_PRESET;+ if (!Object.hasOwn(WATER_PRESETS, preset)) {+ throw new RangeError(`waterPreset must be one of ${Object.keys(WATER_PRESETS).join(', ')}.`);+ }+ const resolvedAbsorption = absorption ?? WATER_PRESETS[preset].absorption;+ const absorptionValid = Array.isArray(resolvedAbsorption) && resolvedAbsorption.length === 3+ && resolvedAbsorption.every(channel => Number.isFinite(channel) && channel >= 0 && channel <= WATER_MAXIMUM_ABSORPTION);+ if (!absorptionValid) {+ throw new RangeError(`absorption must be three numbers from 0 to ${WATER_MAXIMUM_ABSORPTION} (per metre).`);+ }+ const resolvedTurbidity = turbidity ?? WATER_PRESETS[preset].turbidity;+ if (!Number.isFinite(resolvedTurbidity) || resolvedTurbidity < 0 || resolvedTurbidity > 1) {+ throw new RangeError('turbidity must be within zero and one.');+ }+ return { waterPreset: preset, absorption: [...resolvedAbsorption], turbidity: resolvedTurbidity };+}++function partBounds(part) {+ const { positions } = part.geometry;+ const { matrix } = part;+ const minimum = [Infinity, Infinity, Infinity];+ const maximum = [-Infinity, -Infinity, -Infinity];+ for (let vertex = 0; vertex < positions.length; vertex += 3) {+ for (let axis = 0; axis < 3; axis++) {+ const value = matrix[axis] * positions[vertex] + matrix[4 + axis] * positions[vertex + 1] + matrix[8 + axis] * positions[vertex + 2] + matrix[12 + axis];+ minimum[axis] = Math.min(minimum[axis], value);+ maximum[axis] = Math.max(maximum[axis], value);+ }+ }+ return { minimum, maximum };+}++const boundsCache = new WeakMap();++// A part's bounds are read again only when its matrix changed.+function cachedBounds(part) {+ const cached = boundsCache.get(part);+ if (cached && cached.matrix.every((value, index) => value === part.matrix[index])) {+ return cached.bounds;+ }+ const bounds = partBounds(part);+ boundsCache.set(part, { matrix: Float32Array.from(part.matrix), bounds });+ return bounds;+}++/**+ * The water body of a set of parts, or null: the largest flat part with the water tag sets the level (its top) and the optics.+ * A water mesh that is not flat (a stream following the terrain) has no single level, so it sets none.+ */+export function findWaterBody(parts) {+ let best = null;+ for (const part of parts) {+ if (part.material.tag !== 'water') {+ continue;+ }+ const { minimum, maximum } = cachedBounds(part);+ const wider = Math.max(maximum[0] - minimum[0], maximum[2] - minimum[2]);+ const footprint = (maximum[0] - minimum[0]) * (maximum[2] - minimum[2]);+ const flat = wider > 0 && maximum[1] - minimum[1] <= wider * WATER_MAXIMUM_THICKNESS_RATIO;+ if (flat && (!best || footprint > best.footprint)) {+ best = { footprint, level: maximum[1], material: part.material };+ }+ }+ if (!best) {+ return null;+ }+ const { absorption, turbidity } = resolveWaterMaterial(best.material);+ return { level: best.level, absorption, turbidity };+}++const waterLocations = new WeakMap();++function bindWaterBody(renderer) {+ if (!renderer.shaderFeatures?.has('water')) {+ return;+ }+ const context = renderer.context;+ let locations = waterLocations.get(renderer);+ if (locations?.program !== renderer.program) {+ locations = { program: renderer.program, body: context.getUniformLocation(renderer.program, 'waterBody'), absorption: context.getUniformLocation(renderer.program, 'waterAbsorption') };+ waterLocations.set(renderer, locations);+ }+ const waterParts = renderer.batches.flatMap(batch => (batch.parts[0].material.tag === 'water' ? batch.parts : []));+ const body = findWaterBody(waterParts);+ // The mirror and the render passes skip the underwater look: the mirror is clipped above the water, a pass reads raw surface data.+ const active = Boolean(body) && !renderer.renderingPass && !renderer.mirrorCulling;+ context.uniform4f(locations.body, active ? body.level : 0, active ? body.turbidity : 0, active ? 1 : 0, 0);+ context.uniform3f(locations.absorption, ...(active ? body.absorption : [0, 0, 0]));+}++const previousBind = layerTextureSupport.bind;+layerTextureSupport.bind = (renderer, mapState) => {+ previousBind?.(renderer, mapState);+ bindWaterBody(renderer);+};// Wind for the foliage (4) and grass (7) tags, shared by the colour and shadow vertex shaders so both// move identically. It depends only on local position, the card's uv, world position and time.@@ -12,6 +126,50 @@ import { registerShaderFeatureCode } from './shader-registry.js';// (water's reflection) and worldFinal (fire and smoke, which replace the lit colour). Other optional features can use the// same slots, or stub them out in shaders.js, to leave their code out of renderers that do not draw them.export const worldMaterialSlots = {+ // The water body (level, turbidity, 1 when a flat water part sets one) and its absorption per metre, sent by bindWaterBody.+ // Shadow of a surface under murky water: the classic shadow map read over a wider disc. A cascaded map is read through+ // its own macro and keeps its filter.+ declarations: `uniform vec4 waterBody;+uniform vec3 waterAbsorption;+#ifndef shadowVisibility+float softShadowVisibility(vec3 normal, float radiusTexels) {+ vec3 projected = shadowPosition.xyz / shadowPosition.w * 0.5 + 0.5;+ if (projected.z > 1.0 || projected.z < 0.0 || any(lessThan(projected.xy, vec2(0.0))) || any(greaterThan(projected.xy, vec2(1.0)))) return 1.0;+ float cosine = max(dot(normal, normalize(lightDirection)), 0.05);+ float bias = shadowBiasPerSlope * clamp(sqrt(1.0 - cosine * cosine) / cosine, 0.25, 4.0);+ vec2 texel = 1.0 / vec2(textureSize(shadowMap, 0));+ float lit = 0.0;+ for (int tap = 0; tap < 12; tap++) {+ float angle = float(tap) * 2.39996;+ vec2 offset = vec2(cos(angle), sin(angle)) * sqrt((float(tap) + 0.5) / 12.0) * radiusTexels;+ lit += texture(shadowMap, vec3(projected.xy + offset * texel, projected.z - bias));+ }+ return lit / 12.0;+}+#endif+// Sunlight under water: in-scatter lifts the shadow (the water scatters light into it) and widens its edge, both with+// turbidity times the depth of the column above the surface.+float underwaterVisibility(float visibility, vec3 normal, float depth) {+ float scattering = waterBody.y * depth;+ float filtered = visibility;+#ifndef shadowVisibility+ if (scattering > 0.03) filtered = softShadowVisibility(normal, 1.5 + min(scattering * 6.0, 8.0));+#endif+ return mix(filtered, 1.0, (1.0 - exp(-scattering * 1.2)) * 0.9);+}+`,+ worldVisibility: ` float waterDepth = 0.0;+ vec3 waterTransmittance = vec3(1.0);+ if (TAG_WATER) {+ // Only the light that enters the water and comes back is shadowed, and most of what the eye sees comes from deeper than+ // the shadow reaches, so a shadow on the surface is faint. The reflection mixed in later never sees the shadow.+ visibility = mix(visibility, 1.0, 0.7 + 0.2 * waterBody.y);+ } else if (waterBody.z > 0.5 && worldPosition.y < waterBody.x) {+ waterDepth = waterBody.x - worldPosition.y;+ waterTransmittance = exp(-waterAbsorption * waterDepth);+ visibility = underwaterVisibility(visibility, normal, waterDepth);+ }+`,// Spliced into the colour and shadow vertex shaders by shaders.js.worldVertexWind: `// Grass bends by how far up the blade a vertex is (uv.y is 1 at the root), so it ignores terrain height.@@ -134,7 +292,12 @@ void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMasradiance += color * vec3(1.1, 1.25, 0.55) * towardSun * thinness * 1.4 * keyResponse * visibility;}`,- worldAfterEmission: ` if (TAG_WATER) {+ worldAfterEmission: ` if (waterDepth > 0.0) {+ // The bed's light reaches the eye through the column, dimmed; murky water adds the daylight it scattered toward the eye.+ vec3 scatteredLight = (keyColor * max(normalize(lightDirection).y, 0.0) * 0.1 + vec3(0.04) * ambientIntensity) * exp(-waterAbsorption * 1.5);+ radiance = radiance * waterTransmittance + scatteredLight * (vec3(1.0) - waterTransmittance) * waterBody.y;+ }+ if (TAG_WATER) {float reflectivity = 0.20 + 0.65 * pow(1.0 - max(dot(normal, viewDirection), 0.0), 3.0);vec3 reflection = mix(vec3(0.12, 0.24, 0.28), vec3(0.40, 0.63, 0.78), clamp(reflect(-viewDirection, normal).y, 0.0, 1.0));radiance = mix(radiance * 0.6, reflection * daylight * ambientIntensity, reflectivity);diff --git a/tests/agent-scene.test.js b/tests/agent-scene.test.jsindex 0d68ff14..b6643c27 100644--- a/tests/agent-scene.test.js+++ b/tests/agent-scene.test.js@@ -93,7 +93,7 @@ test('shader arithmetic rejects cancelling product overflow and nonfinite emissi});test('recipes author liquid, foam and blended glass with batch-safe material handles', () => {- assert.deepEqual(AGENT_SCENE_CAPABILITIES.materialTags, ['surface', 'unlit', 'liquid', 'foam']);+ assert.deepEqual(AGENT_SCENE_CAPABILITIES.materialTags, ['surface', 'unlit', 'liquid', 'foam', '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 });diff --git a/tests/water-shadows.test.js b/tests/water-shadows.test.jsnew file mode 100644index 00000000..610286ac--- /dev/null+++ b/tests/water-shadows.test.js@@ -0,0 +1,60 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene, AGENT_SCENE_CAPABILITIES } from '../src/agent-scene.js';+import { WATER_PRESETS, findWaterBody, resolveWaterMaterial, worldMaterialSlots } from '../src/world-material-shader.js';+import { box } from '../src/geometry.js';+import { createFragmentShader } from '../src/shaders.js';++const unitBox = box(0, 1);++function waterPart(size, centre, material = { tag: 'water' }) {+ const matrix = new Float32Array([size[0], 0, 0, 0, 0, size[1], 0, 0, 0, 0, size[2], 0, centre[0], centre[1], centre[2], 1]);+ return { name: `water-${size.join('x')}`, geometry: unitBox, matrix, material };+}++test('the capabilities list the same water presets as the shader addon', () => {+ assert.deepEqual(JSON.parse(JSON.stringify(AGENT_SCENE_CAPABILITIES.water.presets)), JSON.parse(JSON.stringify(WATER_PRESETS)));+ assert.ok(AGENT_SCENE_CAPABILITIES.materialTags.includes('water'));+});++test('water fields resolve as explicit value, then preset, then the default lake', () => {+ assert.deepEqual(resolveWaterMaterial({}).absorption, WATER_PRESETS.lake.absorption);+ assert.equal(resolveWaterMaterial({ waterPreset: 'river' }).turbidity, WATER_PRESETS.river.turbidity);+ const mixed = resolveWaterMaterial({ waterPreset: 'sea', turbidity: 0.5 });+ assert.deepEqual(mixed.absorption, WATER_PRESETS.sea.absorption);+ assert.equal(mixed.turbidity, 0.5);+ assert.throws(() => resolveWaterMaterial({ waterPreset: 'puddle' }), /waterPreset/);+ assert.throws(() => resolveWaterMaterial({ absorption: [1, 1] }), /absorption/);+ assert.throws(() => resolveWaterMaterial({ turbidity: 1.5 }), /turbidity/);+});++test('the largest flat water part sets the level and optics; a ribbon that is not flat sets none', () => {+ const pool = waterPart([40, 0.1, 40], [0, -0.05, 0], { tag: 'water', waterPreset: 'river' });+ const puddle = waterPart([2, 0.1, 2], [0, 3, 0], { tag: 'water' });+ const body = findWaterBody([puddle, pool]);+ assert.equal(body.level, 0);+ assert.equal(body.turbidity, WATER_PRESETS.river.turbidity);+ assert.equal(findWaterBody([waterPart([4, 3, 40], [0, 0, 0])]), null);+ assert.equal(findWaterBody([]), null);+});++test('a recipe water material carries resolved optics and other tags refuse them', () => {+ const recipe = (material) => ({ format: '67js.scene', schemaVersion: 1, geometries: [{ id: 'sheet', type: 'box', bevel: 0 }], materials: [{ id: 'water', ...material }], nodes: [{ id: 'sheet', geometry: 'sheet', material: 'water', scale: [10, 0.1, 10] }] });+ const scene = createAgentScene(recipe({ tag: 'water', waterPreset: 'sea', turbidity: 0.3 }));+ const material = scene.parts[0].material;+ assert.equal(material.tag, 'water');+ assert.equal(material.turbidity, 0.3);+ assert.deepEqual([...material.absorption], [...WATER_PRESETS.sea.absorption]);+ assert.throws(() => createAgentScene(recipe({ tag: 'surface', turbidity: 0.3 })), /need the water tag/);+});++test('the shader keeps the sun shadow off the reflection and applies the column only below the level', () => {+ const source = createFragmentShader(['water']);+ assert.ok(source.includes('uniform vec4 waterBody;'));+ assert.ok(source.includes('visibility = mix(visibility, 1.0, 0.7 + 0.2 * waterBody.y);'));+ const water = worldMaterialSlots.worldAfterEmission.split('if (TAG_WATER)')[1];+ assert.ok(!/visibility/.test(water.split('radiance = mix(')[0]), 'the reflection term is computed without the shadow');+ assert.ok(source.includes('exp(-waterAbsorption * waterDepth)'));+ assert.ok(!createFragmentShader([]).includes('waterBody'));+});