Skip to content

3D engine that AI agents drive

Merge main into 2033-water-ramp

Nguyen Xuan Anba512ea5a09c
diff --cc docs/agent-scene.md
index db9c2650,cc1b49bc..c9854cda
--- a/docs/agent-scene.md
+++ b/docs/agent-scene.md
@@@ -107,10 -107,7 +107,10 @@@ The defaults are `surface`, `[0.5, 0.5
The tag can be `surface`, `unlit`, `liquid`, `foam`, `water`, `foliage` or `grass` (the last two sway in `environment.wind`) and remains fixed during editing.
`liquid` refracts and tints what lies behind it: its color is the light one metre lets through, so `[0.56, 0.84, 0.88]` is clear water. `foam` draws soft blended droplets.
`water` is a flat mirror sheet (a plane or thin box). The largest one sets the water level: everything below it fades by `exp(-absorption * depth)` per colour channel (`absorption` is RGB per metre), and its shadows are lifted and softened with depth times `turbidity` (0 clear to 1 murky). `waterPreset` fills both: `lake` (default), `sea` or `river`. A shadow on the surface is faint and never darkens the reflection; give the sheet an `opacity` below one when the bed should show. The sun's leg to a bed is bent at n = 1.33 and absorbed over `depth / cos(theta_t)`, so a clear lake keeps little shadow contrast on a bed 4 m down, and a murky river keeps about a quarter.
+`waterRamp` (off by default) paints the sea in flat anime tones: `{ colors: [3 to 5 RGB, deep to bright], drivers: { height, facing, sun } (weights 0 to 1, default height 1), heightRange: [low, high] (world y, default -1 to 1), steps: hard (default) or soft, crestTint: { color, strength } }`. A weighted mix of the drivers picks the tone: `height` is world y across `heightRange`, `facing` rises toward the horizon, `sun` is how squarely a wave face meets the key light. The ramp owns the colour, so the sky reflection and the lit shading are not drawn; foam and the sun glint still add on top. `crestTint` colours the folded crests the `foam` group marks, wider than the foam itself. It needs the water tag; depth and a shallow and deep pair are not drivers yet.
+
+Ramp colours are display colours. A stop given as `#rrggbb` shows on screen as that hex; three numbers show as the sRGB encoding of those linear values (`[0.04, 0.4, 0.5]` shows as `#38aabc`). The shader maps each stop back through the exposure and the view transform (ACES, AgX or Neutral), so the tone curve does not shift it, and the distance haze (`fogDensity`) stays off the ramp. Measured on 640x360 stills under the default view: `#19617c` and `#38aabc` measured exactly as requested; a bright stop `#95edf3` measured `#99eef4` on lit faces. Things that run after the shader still change the picture: bloom, grade, vignette, grain, a look and the volume fog step, and foam, the sun glint and the crest tint add on top by design.
- Any `opacity` below one draws the material blended after opaque geometry, which suits glass, windows and visors. `alphaMode` accepts `opaque`, `blend` or `add` (additive light for sparks, trails and glow); cutout masking needs a texture and is not available in procedural recipes.
+ Any `opacity` below one draws the material blended after opaque geometry, which suits glass, windows and visors. `alphaMode` accepts `opaque`, `blend` or `add` (additive light for sparks, trails and glow); the MCP tools accept the same three, and `scene_capabilities` topic `alphaModes` lists them. Cutout masking (`mask`) 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.
Set liquid optics with `environment.liquid`: `thickness`, `ior`, `refraction`, `scattering`, `foamOpacity` and `foamSoftness`.
diff --cc scripts/mcp-server.mjs
index e03eecfc,f9e54a2b..6969711a
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@@ -195,7 -197,7 +198,7 @@@ const materialFields =
};
const materialTag = z.enum(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']).optional().describe('Surface kind; liquid, foam, foliage, grass and water change how it renders: see scene_capabilities materialTags and water.');
const materialCore = coreOf(materialFields, ['color', 'metallic', 'roughness', 'emission', 'opacity']);
- const materialMore = 'More fields: tag, alphaMode, doubleSided, emissiveColor, map, pattern, subsurface, snippet, wear, retro, waterPreset, absorption, turbidity, waterRamp and the layers clearcoat, clearcoatRoughness, transmission, thickness, ior, attenuationColor, attenuationDistance, sheenColor, sheenRoughness, specular, specularColor, anisotropy, anisotropyRotation, iridescence, iridescenceIor, iridescenceThickness, toon, toonColors; see scene_capabilities materialFields.';
-const materialMore = 'More fields: tag, alphaMode, doubleSided, emissiveColor, map, pattern, subsurface, snippet, wear, retro, waterPreset, absorption, turbidity and the layers clearcoat, clearcoatRoughness, transmission, thickness, ior, dispersion, attenuationColor, attenuationDistance, sheenColor, sheenRoughness, specular, specularColor, anisotropy, anisotropyRotation, iridescence, iridescenceIor, iridescenceThickness, toon, toonColors; see scene_capabilities materialFields.';
++const materialMore = 'More fields: tag, alphaMode, doubleSided, emissiveColor, map, pattern, subsurface, snippet, wear, retro, waterPreset, absorption, turbidity, waterRamp and the layers clearcoat, clearcoatRoughness, transmission, thickness, ior, dispersion, attenuationColor, attenuationDistance, sheenColor, sheenRoughness, specular, specularColor, anisotropy, anisotropyRotation, iridescence, iridescenceIor, iridescenceThickness, toon, toonColors; see scene_capabilities materialFields.';
const materialListed = (strictSchema, description, extraCore) => listed('materialFields', strictSchema, `${description} ${materialMore}`, { ...extraCore, ...materialCore });
const liquidOptics = z.strictObject({
thickness: z.number().min(0).max(100).optional().describe('Metres of liquid where it faces the camera.'),
diff --cc src/agent-scene-modules.js
index ace5029d,a8ec1389..99c29a23
--- a/src/agent-scene-modules.js
+++ b/src/agent-scene-modules.js
@@@ -83,9 -84,10 +84,10 @@@ const MODULE_MARKERS =
liquidShader: ['"transmission"', '"liquid"', '"foam"'],
subsurfaceShader: ['"subsurface"'],
retroShader: ['"retro"'],
+ glitterShader: ['"waterGlint"'],
// Any mention loads it, because an edit can set the density through a path or the environment of an operation.
fogShader: ['volumeFog', 'localVolumes', '"add-explosion"'],
- worldMaterials: ['"tag":"water"', '"waterPreset"', '"absorption"', '"turbidity"', '"vegetation":{', '"tag":"foliage"', '"tag":"grass"', '"tag":"terrain"', '"tag":"fire"', '"tag":"smoke"', '"moss"'],
+ worldMaterials: ['"tag":"water"', '"waterPreset"', '"absorption"', '"turbidity"', '"waterRamp"', '"vegetation":{', '"tag":"foliage"', '"tag":"grass"', '"tag":"terrain"', '"tag":"fire"', '"tag":"smoke"', '"moss"'],
terrain: ['"type":"terrain"'],
// No recipe text asks for it, only the path option of scene_inspect does, so a host loads it with loadAllAgentSceneModules.
navigation: [],
diff --cc src/agent-scene.js
index 63fd99a0,bb735a34..0771bf2c
--- a/src/agent-scene.js
+++ b/src/agent-scene.js
@@@ -61,9 -61,11 +61,11 @@@ const CAMERA_DEFAULTS = Object.freeze(
const RENDER_FLAG_FIELDS = ['visible', 'castShadow', 'receiveShadow', 'holdout', 'shadowCatcher', 'shadowOnly'];
const PART_FLAG_FIELDS = RENDER_FLAG_FIELDS.slice(1);
const NODE_FIELDS = ['translation', 'rotation', 'scale', 'parent', 'label', 'geometry', 'material', 'skin', 'relations', 'asset', 'vegetation', 'decal', 'depthLayer', 'blend', 'rayVisibility', ...RENDER_FLAG_FIELDS];
-const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'map', 'subsurface', 'snippet', 'waterPreset', 'absorption', 'turbidity', 'aov', 'wear', 'retro', 'emissionMask', 'toonColors', ...MATERIAL_LAYER_FIELDS];
+const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'map', 'subsurface', 'snippet', 'waterPreset', 'absorption', 'turbidity', 'waterRamp', 'aov', 'wear', 'retro', 'emissionMask', 'toonColors', ...MATERIAL_LAYER_FIELDS];
const PATTERN_TEXTURE_FIELDS = ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap', 'layerMaps', 'transmissionMap', 'aovMap', 'emissionFresnel', 'boxMapScale', 'boxMapAxis'];
const CAMERA_FIELDS = [...Object.keys(CAMERA_DEFAULTS), ...CAMERA_LENS_FIELDS];
+ // Fields of an optional shader module join the list here, so the long list above stays a line each material feature does not rewrite.
+ MATERIAL_FIELDS.push('waterGlint');
const LOOK_OPERATION_FIELDS = Object.freeze({
'set-environment': 'environment',
'set-effects': 'effects',