Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 nod
Materials 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.png
new file mode 100644
index 00000000..dc068d9c
Binary files /dev/null and b/out/349-preview.png differ
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 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.mjs
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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 softMas
radiance += 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.js
index 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.js
new file mode 100644
index 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'));
+});