3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Show water ramp colours as display colours (#2033)
Nguyen Xuan Anccd2e9b6d42a
diff --git a/changes/2033.md b/changes/2033.mdindex 5d135be1..8ac72474 100644--- a/changes/2033.md+++ b/changes/2033.md@@ -1 +1 @@-- Water: `waterRamp` paints a sea in 3 to 5 flat tones picked by wave height, facing and the sun, with a crest tint, off by default (#2033)+- Water: `waterRamp` paints a sea in 3 to 5 flat tones picked by wave height, facing and the sun, with a crest tint, off by default; its colours are display colours, so a hex stop shows as that hex (#2033)diff --git a/docs/agent-scene.md b/docs/agent-scene.mdindex 1aac2373..db9c2650 100644--- a/docs/agent-scene.md+++ b/docs/agent-scene.md@@ -109,7 +109,7 @@ The tag can be `surface`, `unlit`, `liquid`, `foam`, `water`, `foliage` or `gras`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 scene radiance (linear), so the view transform, distance haze and bloom change them before they reach the screen. Measured on 640x360 stills, a 3-tone ramp under the default view (ACES, haze and bloom on) came out lighter and greyer: `#19617c` measured `#5b90a4`, `#38aabc` measured `#49c1cc`, `#95edf3` measured `#b0e0e2`. `environment.viewTransform: "neutral"`, `environment.fogDensity: 0` and `effects.bloom.strength: 0` remove the haze, the bloom and the ACES shift, but Khronos Neutral still subtracts an offset from every channel (`min(channel) - 6.25 * min(channel)^2` below 0.08, else 0.04) and compresses a peak above 0.8, so the red of a dark tone drops most (`#19617c` measured `#095e78`). To see a colour exactly, add the offset to the colour you pass: raise every channel by `0.4 * sqrt(lowest) - lowest` when the lowest channel is under 0.04, else by 0.04, and keep the largest channel under 0.8. A 4-tone ramp built that way (requested linear 0.01,0.12,0.2 / 0.04,0.4,0.5 / 0.3,0.7,0.75 / 0.55,0.75,0.7, passed as 0.04,0.15,0.23 / 0.08,0.44,0.54 / 0.34,0.74,0.79 / 0.59,0.79,0.74) measured within 3 per channel on the three larger bands and within 6 on the small deep band, under `neutral`, no fog, no bloom.+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.`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/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex c5494704..f4feb86d 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -265,7 +265,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({]),materialTags: Object.freeze(['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']),// A flat water sheet; the largest sets the level. A bed d metres down keeps exp(-absorption * d) per channel (RGB per metre).- water: Object.freeze({ presets: WATER_PRESETS_SUMMARY, default: 'lake', note: 'absorption 0..20, turbidity 0..1 softens shadows below; opacity under 1 shows the bed. waterRamp {colors [3-5 rgb, deep to bright], drivers {height, facing, sun: weights 0-1; default height 1}, heightRange [low, high] world y (-1, 1), steps hard|soft (hard), crestTint {color, strength 0-1}} paints flat tones that own the colour (no sky reflection; foam and glint stay), off by default.' }),+ 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. waterRamp {colors [3-5 display colours, deep to bright: #rrggbb shows as that hex, rgb numbers as their sRGB encoding], drivers {height, facing, sun: weights 0-1; default height 1}, heightRange [low, high] world y (-1, 1), steps hard|soft (hard), crestTint {color, strength 0-1}} paints flat tones that own the colour (no sky reflection; foam and glint stay), off by default.' }),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/shaders.js b/src/shaders.jsindex a7de9a90..bfabe1fe 100644--- a/src/shaders.js+++ b/src/shaders.js@@ -924,7 +924,7 @@ ${featureCode("afterEmission")}${featureCode("worldAfterEmission")} if (TAG_FLOradiance = mix(radiance, vec3(0.018, 0.022, 0.026), fog);}${featureCode("worldFinal")} float fog = 1.0 - exp(-length(worldPosition - eye) * fogDensity);- // Additive light fades to black through fog; mixing it toward the fog colour would add a glow of fog.+${featureCode("worldFogScale")} // Additive light fades to black through fog; mixing it toward the fog colour would add a glow of fog.radiance = alphaMode > 2.5 ? radiance * (1.0 - fog * worldMode) : mix(radiance, fogColor, fog * worldMode);if (inspection > 0.5) radiance = normal * 0.5 + 0.5;vec3 displayedColor = displayRadiance(radiance);diff --git a/src/world-material-shader.js b/src/world-material-shader.jsindex 489a716d..33f7e28e 100644--- a/src/world-material-shader.js+++ b/src/world-material-shader.js@@ -54,7 +54,18 @@ const WATER_RAMP_FIELDS = Object.freeze(['colors', 'drivers', 'heightRange', 'stconst WATER_RAMP_STEPS = Object.freeze(['hard', 'soft']);const WATER_RAMP_DEFAULT_HEIGHT_RANGE = Object.freeze([-1, 1]);+const HEX_COLOR = /^#[0-9a-f]{6}$/i;++function srgbByteToLinear(byte) {+ const encoded = byte / 255;+ return encoded <= 0.04045 ? encoded / 12.92 : ((encoded + 0.055) / 1.055) ** 2.4;+}++/** A ramp colour: three linear numbers (0 to 16) whose sRGB encoding is the colour shown, or a `#rrggbb` hex shown as that hex. */function rampColor(value, name, toVector) {+ if (typeof value === 'string' && HEX_COLOR.test(value)) {+ return Object.freeze([1, 3, 5].map(offset => srgbByteToLinear(Number.parseInt(value.slice(offset, offset + 2), 16))));+ }const color = toVector(value, 3, name);if (color.some(component => !Number.isFinite(component) || component < 0 || component > 16)) {throw new RangeError(`${name} must be three numbers from 0 to 16, such as [0.1, 0.5, 0.6].`);@@ -496,7 +507,7 @@ void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMasvec3 rampTone = waterRampTone(worldPosition.y, 1.0 - max(dot(normal, viewDirection), 0.0), rampSun);float crestEdge = waterRampHead.y > 0.5 ? 0.15 : max(1.5 * fwidth(foamMask), 0.0001);float crestAmount = waterRampCrest.w * smoothstep(0.2 - crestEdge, 0.2 + crestEdge, foamMask);- waterRampRadiance = mix(rampTone, waterRampCrest.rgb, crestAmount);+ waterRampRadiance = waterRampRadianceFor(mix(rampTone, waterRampCrest.rgb, crestAmount));waterRampOwns = 1.0;}}@@ -578,6 +589,24 @@ void mossMasks(vec3 normal, float amount, out float sharpMask, out float softMasalpha = 1.0;}}+`,+ // The ramp colours are display colours: the radiance a ramp writes is the one the view transform maps back to the colour asked for.+ libraries: `// Radiance that exposure and the view transform turn into the display colour whose sRGB encoding is the asked linear colour.+// Newton steps on the renderer's own curve (ACES, AgX or Neutral), so a ramp stop given as a hex shows as that hex.+vec3 waterRampRadianceFor(vec3 asked) {+ vec3 encoded = mix(asked * 12.92, 1.055 * pow(max(asked, vec3(0.0031308)), vec3(1.0 / 2.4)) - 0.055, step(vec3(0.0031308), asked));+ vec3 target = pow(clamp(encoded, 0.0, 1.0), vec3(2.2));+ vec3 guess = target;+ for (int iteration = 0; iteration < 24; iteration++) {+ vec3 here = toneMap(guess);+ vec3 slope = (toneMap(guess + 0.002) - here) / 0.002;+ guess = max(guess + (target - here) / max(slope, vec3(0.05)), vec3(0.0));+ }+ return guess / max(exposure, 0.0001);+}+`,+ // A ramp stands clear of the distance haze, which would shift the colour it was asked to show.+ worldFogScale: ` if (waterRampOwns > 0.5) fog = 0.0;`,worldFinal: ` if (waterDepth > 0.0 && waterBody.w > 0.5 && alphaMode < 0.5) alpha = 0.5 + 0.498 * clamp(waterDepth / 8.0, 0.0, 1.0);if (TAG_FIRE) {diff --git a/tests/water-ramp.test.js b/tests/water-ramp.test.jsindex 3ed40f5c..f8bacb43 100644--- a/tests/water-ramp.test.js+++ b/tests/water-ramp.test.js@@ -92,3 +92,19 @@ test('a batch with a ramp sends it and a batch without one turns it off', () =>assert.deepEqual(sent.waterRampColors.slice(9), new Array(6).fill(0));assert.deepEqual(sentUniforms({ tag: 'water' }).waterRampHead, [0, 0, 0, 0]);});++test('a ramp colour given as a hex is stored as the linear colour that shows as that hex', () => {+ const ramp = rampOf({ colors: ['#19617c', '#38aabc', '#95edf3'], crestTint: { color: '#ffffff' } });+ const encode = linear => Math.round(255 * (linear <= 0.0031308 ? 12.92 * linear : 1.055 * linear ** (1 / 2.4) - 0.055));+ assert.deepEqual(ramp.colors.map(color => color.map(encode)), [[0x19, 0x61, 0x7c], [0x38, 0xaa, 0xbc], [0x95, 0xed, 0xf3]]);+ assert.deepEqual(ramp.crestTint.color, [1, 1, 1]);+ assert.throws(() => rampOf({ colors: ['#19617', COLORS[1], COLORS[2]] }), /colors\[0\]/);+});++test('the water shader maps the ramp back through the view transform and keeps the haze off it', () => {+ const shader = createFragmentShader(['water', 'vertexColors']);+ assert.match(shader, /vec3 waterRampRadianceFor\(vec3 asked\)/);+ assert.match(shader, /toneMap\(guess \+ 0\.002\)/);+ assert.match(shader, /waterRampRadiance = waterRampRadianceFor\(/);+ assert.match(shader, /if \(waterRampOwns > 0\.5\) fog = 0\.0;/);+});