3D engine that AI agents drive
Give the water tag a fresnel sky, sun glint, foam and a 180 degree ocean smoothAngle (#819)
Nguyen Xuan An77ec996f3246
diff --git a/changes/819.md b/changes/819.mdnew file mode 100644index 00000000..199336cb--- /dev/null+++ b/changes/819.md@@ -0,0 +1 @@+- The `water` tag reads the sea's foam, mirrors the sky with a fresnel term, shows a sun glint and goes deeper at grazing angles, and an `ocean` mesh smooths over 180 degrees by default (#819)diff --git a/changes/819.size.md b/changes/819.size.mdnew file mode 100644index 00000000..386ddcef--- /dev/null+++ b/changes/819.size.md@@ -0,0 +1,6 @@+- entry:terrain: the water shader code in the shared world-material block grows every entry that carries it by about 230 bytes gzip; the water look is the fix for #819.+- entry:grass: same shared world-material block as entry:terrain.+- entry:clutter: same shared world-material block as entry:terrain.+- entry:world-material-shader: fresnel sky reflection, a narrow sun glint, a grazing-angle body colour and foam are the look #819 asks for; 230 bytes gzip of GLSL.+- scene:agent-scene+lazy: the shader block plus the foam and smoothAngle helpers in the lazy mesh chunk (414 bytes gzip).+- goal:agent-scene: 24 bytes gzip, one guarded call that hands a water part its foam; the foam helper itself lives in the lazy mesh chunk.diff --git a/docs/mesh.md b/docs/mesh.mdindex 973b183e..df12daaf 100644--- a/docs/mesh.md+++ b/docs/mesh.md@@ -255,7 +255,7 @@ Normals stay those of the base mesh. Test: `tests/mesh-shape-keys.test.js`.| `bounding_box` | none | Replaces the mesh with the axis-aligned box around all its vertices: 8 vertices and 6 quads. Tags and attributes are dropped. || `convex_hull` | none | Replaces the mesh with its convex hull, outward triangles on the extreme vertices only, from at most 8192 vertices. A mesh whose vertices lie on one line or in one plane has no hull and is refused. Tags and attributes are dropped. || `build` | `order` (index, random or axis), `seed` (0, random only), `axis` (y, axis only), `frame` (0), `start` (0), `length` (60 frames, above 0), `reverse` (false) | Shows the first faces in that order: none before `start`, all from `start + length`, linear between; `reverse` unbuilds. Unused vertices drop, tags and corner attributes follow their faces, and while no face shows the mesh is one zero-area triangle. Same fields and frame give the same bytes on every seek. Works on imported meshes. |-| `ocean` | `axis` (y, the up axis), `windSpeed` (10 m/s, above 0 to 60), `direction` (0 degrees from +x toward +z), `choppiness` (1, 0 to 4), `size` (100 m, 1 to 10000), `seed` (0), `time` (0 s), `resolution` (8, 1 to 16) | A seeded sea like Blender's Ocean modifier, without the FFT: a sum of travelling waves on a lattice of wave vectors with a Phillips spectrum for the wind, so the surface repeats every `size` metres and the same seed and time give identical vertices. Waves lift the up axis; choppiness pulls vertices toward the crests along the other two. The squeeze of that move is written as the vertex group `foam` (0 flat, 1 folded). Waves cost (2 x resolution + 1)^2 - 1 per vertex, capped at 50 million evaluations. A box base has few vertices across a flat face (bevel 0 has none inside it), so run `subdivide_edges` with `cuts` first, or the waves have nothing to move. For an open sea: delete every face but the top, `subdivide_edges` with 16 cuts, `subdivide` 4 levels (about 74,000 vertices), scale the sheet to hundreds of metres, then `ocean` with a `size` of 50 (smaller than the wind's longest wave, so the sea has short chop), and a `vertex_color` field that mixes deep blue to white by `{ "attr": "group", "name": "foam" }`. |+| `ocean` | `axis` (y, the up axis), `windSpeed` (10 m/s, above 0 to 60), `direction` (0 degrees from +x toward +z), `choppiness` (1, 0 to 4), `size` (100 m, 1 to 10000), `seed` (0), `time` (0 s), `resolution` (8, 1 to 16) | A seeded sea like Blender's Ocean modifier, without the FFT: a sum of travelling waves on a lattice of wave vectors with a Phillips spectrum for the wind, so the surface repeats every `size` metres and the same seed and time give identical vertices. Waves lift the up axis; choppiness pulls vertices toward the crests along the other two. The squeeze of that move is written as the vertex group `foam` (0 flat, 1 folded). Waves cost (2 x resolution + 1)^2 - 1 per vertex, capped at 50 million evaluations. A box base has few vertices across a flat face (bevel 0 has none inside it), so run `subdivide_edges` with `cuts` first, or the waves have nothing to move. For an open sea: delete every face but the top, `subdivide_edges` with 16 cuts, `subdivide` 4 levels (about 74,000 vertices), scale the sheet to hundreds of metres, then `ocean` with a `size` of 50 (smaller than the wind's longest wave, so the sea has short chop), and a `vertex_color` field that mixes deep blue to white by `{ "attr": "group", "name": "foam" }`. A part with the `water` tag needs none of that: its shader reads the `foam` group itself and draws white rough foam on the folded crests, with a fresnel sky reflection, a sun glint and a deeper body colour at grazing angles. The mesh smooths over 180 degrees unless `smoothAngle` is set, so choppiness does not split the normals. |`triangulate` and `edge_split` check their output size before building it, against the same vertex and face limits as the other edits. Each op has cases in `tests/fixtures/blender/cases.json` and matches Blender 5.2 with no listed difference. `screw` and `wireframe` have cases in the same fixtures (the volume of the open screw strips differs by winding, listed in `differences.json`); `wave` matches Blender on two cases; `skin`, `lattice`, `curve` and `hook` are not compared with Blender, because each needs a second object there. The two normal modifiers are tested by their own properties, because the Blender comparison does not measure normals. Not yet: `shrinkwrap` and `scatter_on_surface` as stack nodes (`instances` already scatters), and cast shapes other than the sphere.@@ -548,7 +548,7 @@ A recipe geometry of type `mesh` starts from a primitive or profile and replays] }```-Edges bending more than `smoothAngle` degrees (default 30) render hard. `mesh_edit` appends edits to such a+Edges bending more than `smoothAngle` degrees (default 30, or 180 for a mesh with an `ocean` edit or stack node, so a choppy sea keeps its smooth normals) render hard. `mesh_edit` appends edits to such ageometry (or replaces its log with `replace: true`) as one atomic revision, so checkpoints and `expectedRevision`work as for `scene_apply`. It returns the render status and the mesh report below, including one result per edit.diff --git a/src/agent-mesh-engine.js b/src/agent-mesh-engine.jsindex 91ee8216..042a0749 100644--- a/src/agent-mesh-engine.js+++ b/src/agent-mesh-engine.js@@ -1,5 +1,5 @@// Everything the agent scene needs for mesh geometry, behind one on-demand import (see agent-scene-modules.js).-export { meshReport, generateMeshGeometry, taggedFacePositions } from './agent-mesh.js';+export { meshReport, generateMeshGeometry, taggedFacePositions, waterFoamGeometry } from './agent-mesh.js';export { normalizeMeshEdits, normalizeMeshStack } from './mesh-recipe.js';export { normalizeShapeKeys } from './mesh-shape-keys.js';export { generateMeshLods, generateGeometryLods, generateAssetLods } from './mesh-lod.js';diff --git a/src/agent-mesh.js b/src/agent-mesh.jsindex 88aafc72..5d8a0b0e 100644--- a/src/agent-mesh.js+++ b/src/agent-mesh.js@@ -80,13 +80,35 @@ export function meshCacheStats() {return { hits: evaluationCache.hits, misses: evaluationCache.misses, entries: evaluationCache.entries.size, bytes: evaluationCache.bytes };}+const foamGeometries = new WeakMap();++/**+ * The geometry a water part draws: when it carries the ocean's `foam` vertex group, a copy whose sky visibility channel holds+ * 1 - foam, which the water shader reads as the foam mask (a plain water part keeps 1, so no foam). One copy per geometry.+ */+export function waterFoamGeometry(geometry, material) {+ const foam = material.tag === 'water' ? geometry.vertexGroups?.foam : undefined;+ if (!foam || geometry.skyVisibility) return geometry;+ if (!foamGeometries.has(geometry)) foamGeometries.set(geometry, { ...geometry, skyVisibility: Float32Array.from(foam, weight => 1 - weight) });+ return foamGeometries.get(geometry);+}++/** Degrees of the smoothing default for ocean output. Choppiness folds the surface, and the default 30 would split its normals. */+export const OCEAN_SMOOTH_ANGLE_DEFAULT = 180;++/** The smoothAngle a mesh gets when the recipe sets none: 180 for a sea (an ocean edit or stack node), else the shared default. */+export function defaultSmoothAngle(edits = [], stack = []) {+ const makesOcean = operation => operation?.op === 'ocean';+ return edits.some(makesOcean) || stack.some(makesOcean) ? OCEAN_SMOOTH_ANGLE_DEFAULT : MESH_SMOOTH_ANGLE_DEFAULT;+}+/*** Build render geometry for a recipe `mesh` geometry: convert the base, run the edit log, evaluate the modifier* stack, and extract triangles with edges sharper than smoothAngle (degrees) kept hard, as Blender's auto smooth* does. `cacheKey` identifies the base; the edit result and every stack prefix are cached under it.*/export function generateMeshGeometry(baseGeometry, edits, {- maxVertices, smoothAngle = MESH_SMOOTH_ANGLE_DEFAULT, resolveCutter, stack = [], cacheKey, shapeKeys = [],+ maxVertices, stack = [], smoothAngle = defaultSmoothAngle(edits, stack), resolveCutter, cacheKey, shapeKeys = [],}) {const realized = cacheKey && realizedGeometry(cacheKey);if (realized) {diff --git a/src/agent-scene.js b/src/agent-scene.jsindex 31f27fc8..0790fea8 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -6,7 +6,7 @@ import { applyProjection, validateCameraShift, CAMERA_LENS_FIELDS } from './cameimport { normalizeAgentLook, environmentPatchWithSetup, environmentLinksLights, agentEnvironmentMap, VOLUME_FOG_FIELDS } from './agent-look.js';import { postStepSupport } from './shader-registry.js';import { agentSceneModule, agentSceneModuleLoaded } from './agent-scene-modules.js';-import { MESH_SMOOTH_ANGLE_DEFAULT, CURVE_TEXT_LIMITS, AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, MAX_MATERIAL_PATTERNS, RECIPE_ALPHA_MODES } from './agent-scene-capabilities.js';+import { CURVE_TEXT_LIMITS, AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, MAX_MATERIAL_PATTERNS, RECIPE_ALPHA_MODES } from './agent-scene-capabilities.js';import { ALL_LIGHTS_MASK, MATERIAL_LAYER_FIELDS, validateMaterialLayers } from './material-layers.js';import { recipeDiagnostics, closedRoomDiagnostic } from './agent-diagnostics.js';import { closedRoomShare, CLOSED_ROOM_SHARE } from './closed-room.js';@@ -716,7 +716,7 @@ function generateGeometry(value, maxVertices, scope) {const cutterScope = meshCutterScope(value, scope);const dependencies = scope ? checkedCutterDependencies(value, scope.definitions) : '';return agentSceneModule('mesh').generateMeshGeometry(() => generateGeometry(value.base, maxVertices), value.edits ?? [], {- maxVertices, smoothAngle: value.smoothAngle ?? MESH_SMOOTH_ANGLE_DEFAULT,+ maxVertices, smoothAngle: value.smoothAngle,stack: value.stack ?? [], shapeKeys: value.shapeKeys ?? [],// The edits only name a cutter geometry, so that geometry's own record joins the key: editing it changes the key.cacheKey: dependencies ? `${JSON.stringify(value.base)}|cutters|${dependencies}` : JSON.stringify(value.base),@@ -1446,7 +1446,8 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {const usesVisibility = recipeUsesVisibility(recipe);const nextParts = recipe.nodes.filter(node => node.geometry !== undefined).map(node => {const binding = skinBindings.get(node.id);- const geometry = binding?.geometry ?? geometries.get(node.geometry);+ const sourceGeometry = binding?.geometry ?? geometries.get(node.geometry);+ const geometry = sourceGeometry.vertexGroups?.foam ? agentSceneModule('mesh').waterFoamGeometry(sourceGeometry, materialHandles.get(node.material).output) : sourceGeometry;const material = materialHandles.get(node.material).output;const assetExtras = assetRuntime.partExtras.get(node.id);// Shape keys of a recipe mesh are morph targets with their own weights per part; an imported asset brings its own pose.diff --git a/src/world-material-shader.js b/src/world-material-shader.jsindex bb591585..24050af4 100644--- a/src/world-material-shader.js+++ b/src/world-material-shader.js@@ -332,15 +332,21 @@ void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMas}`,- worldSurface: ` if (TAG_WATER) {- normal = normalize(vec3(-cos(worldPosition.x * 1.4 + time * 0.8) * 0.035, 1.0, -cos(worldPosition.z * 1.8 - time) * 0.036));+ worldSurface: ` float waterFoam = 0.0;+ if (TAG_WATER) {+ // Small ripples tilt the surface's own normal, so a sea mesh keeps its waves; a flat sheet (normal up) gets the same ripples as before.+ vec3 rippleTilt = vec3(-cos(worldPosition.x * 1.4 + time * 0.8) * 0.035, 0.0, -cos(worldPosition.z * 1.8 - time) * 0.036);float radius = length(worldPosition.xz - waterRipple.xz);float age = time - rippleTime;float wave = sin(radius * 11.0 - age * 8.0) * exp(-abs(radius - age * 1.4) * 1.5) * exp(-age * 0.7) * step(0.0, age);- normal.xz += normalize(worldPosition.xz - waterRipple.xz + 0.001) * wave * 0.07;- normal = normalize(normal);- color = mix(color, vec3(0.10, 0.23, 0.25), pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.0));- roughness = 0.16;+ rippleTilt.xz += normalize(worldPosition.xz - waterRipple.xz + 0.001) * wave * 0.07;+ normal = normalize(normal + rippleTilt);+ // The body is deeper at grazing angles; the foam mask (the ocean's, stored as 1 - foam in the sky visibility channel) turns it white.+ waterFoam = smoothstep(0.15, 0.85, clamp(1.0 - vertexSkyVisibility, 0.0, 1.0));+ float grazing = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.0);+ color = mix(color, vec3(0.04, 0.12, 0.16), grazing * 0.85);+ color = mix(color, vec3(0.92, 0.95, 0.97), waterFoam);+ roughness = mix(0.16, 0.8, waterFoam);}if (CANOPY_TAG) {float leaves = sin(worldPosition.x * 13.0 + sin(worldPosition.y * 9.0)) * sin(worldPosition.z * 11.0 - worldPosition.y * 5.0);@@ -398,10 +404,19 @@ void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMasradiance += color * keyResponse / max(waterSunTransmittance, vec3(0.0001)) * max(dot(normal, normalize(lightDirection)), 0.0) * waterShadowVisibility * waterScatterShare * 3.4 * exp(-waterAbsorption);}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);- radiance += vec3(1.0, 0.85, 0.55) * pow(max(dot(reflect(-normalize(lightDirection), normal), viewDirection), 0.0), 220.0) * 2.0 * keyResponse;+ // Fresnel (Schlick, water F0 0.02) of the sky or environment the surface mirrors; foam is rough and reflects little.+ float cosine = max(dot(normal, viewDirection), 0.0);+ float reflectivity = (0.02 + 0.98 * pow(1.0 - cosine, 5.0)) * (1.0 - waterFoam);+ vec3 mirrorDirection = reflect(-viewDirection, normal);+ mirrorDirection.y = max(mirrorDirection.y, 0.02);+ vec3 skyColor = ENVIRONMENT_ENABLED ? surroundingsColor(mirrorDirection, 0.05) : mix(vec3(0.12, 0.24, 0.28), vec3(0.40, 0.63, 0.78), clamp(mirrorDirection.y, 0.0, 1.0)) * daylight;+ radiance = mix(radiance * 0.6, skyColor * ambientIntensity, clamp(reflectivity, 0.0, 1.0));+ // Sun glint: a narrow lobe around the mirror direction, the width of open water slopes, bright enough to bloom.+ vec3 halfVector = normalize(normalize(lightDirection) + viewDirection);+ float glintShape = pow(max(dot(normal, halfVector), 0.0), 900.0);+ float glintFresnel = 0.02 + 0.98 * pow(1.0 - max(dot(halfVector, viewDirection), 0.0), 5.0);+ radiance += vec3(1.0, 0.9, 0.7) * glintShape * (0.5 + 40.0 * glintFresnel) * 6.0 * keyResponse * (1.0 - waterFoam);+ radiance += vec3(0.85, 0.9, 0.95) * waterFoam * (max(dot(normal, normalize(lightDirection)), 0.0) * keyResponse + 0.35 * daylight * ambientIntensity);if (waterBody.w > 0.5 && alphaMode > 1.5) {// Blended water draws its own background: the opaque scene refracted and blurred, not the one behind it unbent.radiance = radiance * alpha + refractedBackground(radiance, worldPosition, normal, viewDirection) * (1.0 - alpha);diff --git a/tests/water-ocean-look.test.js b/tests/water-ocean-look.test.jsnew file mode 100644index 00000000..13c9e4d2--- /dev/null+++ b/tests/water-ocean-look.test.js@@ -0,0 +1,56 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene } from '../src/agent-scene.js';+import { defaultSmoothAngle, OCEAN_SMOOTH_ANGLE_DEFAULT } from '../src/agent-mesh.js';+import { MESH_SMOOTH_ANGLE_DEFAULT } from '../src/agent-scene-capabilities.js';+import { createFragmentShader } from '../src/shaders.js';+import '../src/world-material-shader.js';++function seaRecipe({ tag, smoothAngle, inStack = false }) {+ const edits = [+ { op: 'delete', select: { not: { normal: [0, 1, 0], maxAngle: 10 } } },+ { op: 'subdivide_edges', edges: { all: true }, cuts: 4 },+ { op: 'subdivide', levels: 2 },+ { op: 'set_position', position: { mul: [{ attr: 'position' }, [100, 1, 100]] } },+ ];+ const ocean = { op: 'ocean', windSpeed: 16, choppiness: 1.5, size: 50, seed: 3, resolution: 3 };+ return {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'sea', type: 'mesh', base: { type: 'box', bevel: 0 }, edits: inStack ? edits : [...edits, ocean], stack: inStack ? [ocean] : [], ...(smoothAngle === undefined ? {} : { smoothAngle }) }],+ materials: [{ id: 'surface', color: [0.1, 0.2, 0.3], ...(tag ? { tag } : {}) }],+ nodes: [{ id: 'sea', geometry: 'sea', material: 'surface' }],+ };+}++test('a water part of an ocean mesh carries 1 - foam in its sky visibility channel', () => {+ const water = createAgentScene(seaRecipe({ tag: 'water' })).parts[0].geometry;+ const foam = water.vertexGroups.foam;+ assert.ok(foam.some(weight => weight > 0.05), 'the sea folds somewhere');+ assert.equal(water.skyVisibility.length, foam.length);+ assert.ok(water.skyVisibility.every((value, index) => Math.abs(value - (1 - foam[index])) < 1e-6));+});++test('a part that is not water keeps its geometry untouched', () => {+ const plain = createAgentScene(seaRecipe({})).parts[0].geometry;+ assert.equal(plain.skyVisibility, undefined);+});++test('ocean output smooths over 180 degrees unless the recipe says otherwise', () => {+ assert.equal(defaultSmoothAngle([{ op: 'ocean' }], []), OCEAN_SMOOTH_ANGLE_DEFAULT);+ assert.equal(defaultSmoothAngle([], [{ op: 'ocean' }]), 180);+ assert.equal(defaultSmoothAngle([{ op: 'subdivide' }], []), MESH_SMOOTH_ANGLE_DEFAULT);+ const defaulted = createAgentScene(seaRecipe({ tag: 'water' })).parts[0].geometry;+ const stacked = createAgentScene(seaRecipe({ tag: 'water', inStack: true })).parts[0].geometry;+ const split = createAgentScene(seaRecipe({ tag: 'water', smoothAngle: 0 })).parts[0].geometry;+ assert.equal(defaulted.positions.length, stacked.positions.length, 'edit and stack give the same welded render mesh');+ assert.ok(split.positions.length > defaulted.positions.length, 'an explicit smoothAngle is still honoured');+});++test('the water shader reads the foam mask, a fresnel sky and a sun glint', () => {+ const shader = createFragmentShader(['water', 'vertexColors']);+ assert.match(shader, /waterFoam = smoothstep\(0\.15, 0\.85, clamp\(1\.0 - vertexSkyVisibility/);+ assert.match(shader, /float reflectivity = \(0\.02 \+ 0\.98 \* pow\(1\.0 - cosine, 5\.0\)\)/);+ assert.match(shader, /pow\(max\(dot\(normal, halfVector\), 0\.0\), 900\.0\)/);+ assert.match(shader, /normal = normalize\(normal \+ rippleTilt\)/);+});