Skip to content

3D engine that AI agents drive

Keep the gradient sky horizon glow in its own hue (#2038)

Nguyen Xuan An8da2472dae96
diff --git a/docs/agent-look.md b/docs/agent-look.md
index 84a71f22..d6818374 100644
--- a/docs/agent-look.md
+++ b/docs/agent-look.md
@@ -124,7 +124,7 @@ Sky colors use display RGB, matching the renderer's existing environment contrac
| `resolveCoplanar` | `'offset'` | Flush and near-flush faces, inside one mesh or across parts, are ranked per triangle and drawn with a small depth-only bias, so the face in front wins at every distance and nothing flickers. Geometry never moves. `false` opts out, and `scene_inspect` then lists each pair as a `coplanar-overlap` warning. Parts that set `decal` or `depthLayer` keep their own layer. Where an opaque face covers another on the same plane, or in front of it by at most a thousandth of the shared face (between a millimetre and a centimetre), the covered part is cut out of the drawn copy of the hidden face (the part and its geometry stay as you made them), so a stack of any depth is settled and the path tracer sees one face. What cannot be settled comes back as a `coplanar-overlap` warning with a `reason`: `rank-overflow` (more than 16 faces a wider gap apart), `double-sided-gap`, `unchecked` (past the triangle or pair budget, the part the search stopped at is named) or `collapsed-node` (an axis a millionth of the longest one; a 2 cm slab 400 m wide is a ground, not a collapse) |
| `objectReflections` | on | Absent unless set. Each smooth metal part (`metallic` 0.5 or more, `roughness` 0.6 or less; at most 8 such parts, in a scene with at most 1,024 other parts) gets a reflection probe of the scene around it, so a chrome sphere shows the floor and its neighbours. `false` turns it off. Probes are traced at rest, so a part that moves reflects the scene as it started. `scene_inspect` names them in `reflections` |
| `sky` | absent | Absent unless set. `{ type: 'physical', preset, sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective, ozone, sunDisc }`: one time-of-day control. `sunElevation` -90 to 90 degrees (default 45), `sunRotation` degrees clockwise from -Z seen from above (0), `turbidity` 1 to 10 haze (3), `groundAlbedo` 0 to 1 (0.3), `aerialPerspective` 0 to 4 scales the distance haze (1; 0 for none), `ozone` 0 to 10 Chappuis-band absorption (1), `sunDisc` boolean (true). `preset` is `golden-hour` (sun 4 degrees up), `sunset` (1 degree) or `blue-hour` (4 degrees below the horizon), each with the sun turned to rotation 250: it supplies the sun only, fields beside it win, and a preset in a `set-environment` patch starts the sky again from its own sun with the other fields at their defaults. A sun below 14 degrees is fitted to Blender's sky (checked at 2, 6 and 15 degrees, comparison in `docs/golden-hour-comparison.jpg`): a narrow saturated orange band forms along the horizon, the zenith dims and the key warms and strengthens; at 14 degrees and above the sky is unchanged. The sky sets `lightDirection`, `keyColor` (the sun reddens and dims with air mass and sets below the horizon), `skyTop`, `skyBottom`, `fogColor` and `fogDensity`, and replaces the setup's environment map with the sky, so those fields no longer take your values while a sky is set. `environment` motion tracks can animate `sunElevation`, `sunRotation`, `turbidity`, `groundAlbedo`, `aerialPerspective` and `ozone` for time-of-day arcs. A `set-environment` patch changes the fields it names and keeps the rest; `sky: null` in a patch keeps the last derived values as plain fields. It is an analytic single-scattering approximation (Rayleigh, aerosol and ozone, Kasten-Young air mass), not Blender's Nishita integration: no clouds. Raster first: the path tracer backends read the same environment map and key light, but are not yet checked against it. |
-| `sky` (gradient) | absent | `{ type: 'gradient', stops: [{ at, color }], horizonGlow: { color, width, intensity } }`: a sky whose colours you pick, for a mood that physics would not give (a teal anime sky with a bright cyan band at the horizon). `stops` holds 1 to 8 entries with `at` rising from 0 (horizon) to 1 (zenith, by elevation angle) and `color` as a `#rrggbb` hex in sRGB; below the horizon the first stop continues. `horizonGlow` is optional: `color` as hex, `width` 0.5 to 45 degrees of elevation (the half width of the band, default 6) and `intensity` 0 to 20 (default 1). The same colours are the background (with `world: true`), the light and reflections of the scene, and the water reflection. It sets `skyTop`, `skyBottom` and `fogColor` from the first and last stop and leaves the sun, the key light and the fog density to the setup and the recipe. A `set-environment` patch with `type: 'gradient'` replaces a physical sky; a patch without `type` edits the gradient in place. Raster first; the path tracer backends read the same map but are not checked against it. |
+| `sky` (gradient) | absent | `{ type: 'gradient', stops: [{ at, color }], horizonGlow: { color, width, intensity } }`: a sky whose colours you pick, for a mood that physics would not give (a teal anime sky with a bright cyan band at the horizon). `stops` holds 1 to 8 entries with `at` rising from 0 (horizon) to 1 (zenith, by elevation angle) and `color` as a `#rrggbb` hex in sRGB; below the horizon the first stop continues. `horizonGlow` is optional: `color` as hex, `width` 0.5 to 45 degrees of elevation (the half width of the band, default 6) and `intensity` 0 to 20 (default 1) multiplies the glow colour at the horizon, so 1 shows the colour as given; the band blends toward the glow colour, so it keeps its hue and does not wash to white until the colour itself is bright. The background goes through the scene's view transform like any sky (the default `aces` lifts mid tones: a flat `#0e5d73` shows as about `#0c6988`); set `viewTransform: 'neutral'` to see stop colours close to their hex. The same colours are the background (with `world: true`), the light and reflections of the scene, and the water reflection. It sets `skyTop`, `skyBottom` and `fogColor` from the first and last stop and leaves the sun, the key light and the fog density to the setup and the recipe. A `set-environment` patch with `type: 'gradient'` replaces a physical sky; a patch without `type` edits the gradient in place. Raster first; the path tracer backends read the same map but are not checked against it. |
| `floorSkyTrace` | on | Absent unless set. A closed room a sun lights gets the sky each floor texel sees traced into its floor (`applyFloorSkyVisibility`, strength 0.2), so shadowed floors under a roof or between walls get less world and sky light; it makes the dark end of halls closer to Cycles. Open scenes and rooms lit by lamps alone are left as they are. `false` turns it off; a value that is not a boolean is refused. It loads lazily with a recipe that names its sun (`keyColor` or `keyIntensity`), costs about 1 s of trace when the scene is built and adds triangles to the floor (0.1 to 0.4 ms per frame in the reference halls). |
| `specularAntiAliasing` | `1` | Absent unless set. `0` to `4`. Widens highlights where the shading normal or normal map detail changes within a pixel (geometric specular anti-aliasing plus a Toksvig term read from the filtered normal map length), so grainy or scanned metal stops sparkling from frame to frame at grazing angles. `0` gives a highlight that follows every texel; above `1` is softer. |
| `sunBounce` | `1` | Absent unless set. A number of 0 or more. A closed room a sun lights gets a few point lights at its sunlit patches (`withSunBounce`, found when the scene is prepared), so the floor, walls and pillars around a patch are lit by the light it bounces and the far end of the room less. `0` turns it off and gives the look without it; `1` is fitted to Cycles; above `1` is stronger. A value that is not a number of 0 or more is refused. Open scenes and rooms with no sun are left as they are. It loads lazily with the sun, and the lights take up to 6 of the 16 point light slots. |
diff --git a/skills/build-crucible-scene/references/look.md b/skills/build-crucible-scene/references/look.md
index e7e5ea5d..a95eedd3 100644
--- a/skills/build-crucible-scene/references/look.md
+++ b/skills/build-crucible-scene/references/look.md
@@ -35,7 +35,7 @@ target hex and scale `emission`.
Time of day comes from the sun alone: `"sky": { "type": "physical", "preset": "golden-hour" }` (also `sunset`, `blue-hour`) sets sun elevation and azimuth, and the key, sky and haze follow from one atmosphere, so a low sun reads warm with no grading. Put `sunElevation` or `sunRotation` beside a preset to move the sun; a preset starts the sky again, so earlier sky fields are dropped.
-For a mood that physics does not give, pick the colours: `"sky": { "type": "gradient", "stops": [{ "at": 0, "color": "#1a8a9c" }, { "at": 1, "color": "#0e5d73" }], "horizonGlow": { "color": "#7ff4ff", "width": 2.5, "intensity": 1.3 } }` runs from the horizon (`at` 0) to the zenith (1), adds a bright band at the horizon, and lights the scene and shows in water like any sky. It leaves the sun to the setup.
+For a mood that physics does not give, pick the colours: `"sky": { "type": "gradient", "stops": [{ "at": 0, "color": "#1a8a9c" }, { "at": 1, "color": "#0e5d73" }], "horizonGlow": { "color": "#19d0e8", "width": 1, "intensity": 1 } }` runs from the horizon (`at` 0) to the zenith (1), adds a bright band at the horizon, and lights the scene and shows in water like any sky. It leaves the sun to the setup. Add `"viewTransform": "neutral"` to the environment to see the stop colours close to their hex; the default curve lifts mid tones.
## HDRI from the catalog
diff --git a/src/gradient-sky.js b/src/gradient-sky.js
index 453db676..f7bc241c 100644
--- a/src/gradient-sky.js
+++ b/src/gradient-sky.js
@@ -10,9 +10,10 @@ export const HORIZON_GLOW_FIELDS = Object.freeze(['color', 'width', 'intensity']
export const MAXIMUM_GRADIENT_STOPS = 8;
const GLOW_DEFAULTS = Object.freeze({ width: 6, intensity: 1 });
+// intensity multiplies the glow colour at the horizon: 1 shows the colour itself, above 1 pushes it brighter.
const GLOW_LIMITS = Object.freeze({
width: [0.5, 45, 'the glow half width in degrees of elevation, such as 6'],
- intensity: [0, 20, 'a brightness multiplier from 0 to 20, such as 2'],
+ intensity: [0, 20, 'a multiplier of the glow colour from 0 to 20, 1 shows the colour as given, such as 1.5'],
});
const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
const COLOR_EXAMPLE = 'a hex colour such as "#0e5d73"';
@@ -124,11 +125,12 @@ function buildMapData(sky) {
// Each row is one elevation: the gradient and the glow depend on the angle above the horizon only.
const elevation = 90 - ((row + 0.5) / MAP_HEIGHT) * 180;
const base = colorAtHeight(stops, Math.max(0, elevation) / 90);
- const glowShare = glow ? glow.intensity * Math.exp(-((elevation / glow.width) ** 2)) : 0;
+ const glowShare = glow ? Math.exp(-((elevation / glow.width) ** 2)) : 0;
for (let column = 0; column < MAP_WIDTH; column++) {
const offset = (row * MAP_WIDTH + column) * 3;
for (let channel = 0; channel < 3; channel++) {
- data[offset + channel] = base[channel] + (glowColor ? glowColor[channel] * glowShare : 0);
+ // The band blends toward the glow colour instead of adding it, so it keeps its hue as it brightens and never washes to white.
+ data[offset + channel] = glowColor ? base[channel] + (glowColor[channel] * glow.intensity - base[channel]) * glowShare : base[channel];
}
}
}
diff --git a/tests/gradient-sky.test.js b/tests/gradient-sky.test.js
index 8fd2d17a..ae1b1416 100644
--- a/tests/gradient-sky.test.js
+++ b/tests/gradient-sky.test.js
@@ -7,7 +7,7 @@ import { agentEnvironmentMap, normalizeAgentLook } from '../src/agent-look.js';
import { linearColorFromHex } from '../src/gradient-sky.js';
const TEAL_STOPS = [{ at: 0, color: '#1a8a9c' }, { at: 1, color: '#0e5d73' }];
-const GLOW = { color: '#7ff4ff', width: 3, intensity: 2 };
+const GLOW = { color: '#19d0e8', width: 3, intensity: 1 };
function gradientEnvironment(sky, extra = {}) {
return normalizeAgentLook({ environment: { sky: { type: 'gradient', stops: TEAL_STOPS, ...sky }, ...extra } }).environment;
@@ -42,8 +42,10 @@ test('the horizon glow is a band: bright at the horizon and gone well above it',
const plain = agentEnvironmentMap(gradientEnvironment({}));
const glowColor = linearColorFromHex(GLOW.color);
const [atHorizon, high] = [mapPixel(map, 0.2), mapPixel(map, 30)];
- assert.ok(atHorizon[0] > mapPixel(plain, 0.2)[0] + glowColor[0] * 1.5);
- assert.ok(atHorizon[2] > glowColor[2] * 1.5);
+ atHorizon.forEach((value, channel) => assert.ok(Math.abs(value - glowColor[channel] * GLOW.intensity) < 0.02));
+ assert.ok(atHorizon[1] > mapPixel(plain, 0.2)[1] + 0.2);
+ // Hue is kept: the band is the glow colour scaled, so the red to green ratio of the peak is the glow's, not the sky's.
+ assert.ok(Math.abs(atHorizon[0] / atHorizon[1] - glowColor[0] / glowColor[1]) < 0.02);
assert.ok(Math.abs(high[1] - mapPixel(plain, 30)[1]) < 1e-4);
assert.ok(map.data.every(Number.isFinite));
});
@@ -68,6 +70,6 @@ test('set-environment switches between a physical and a gradient sky and edits o
assert.equal(session.environment.sky.type, 'gradient');
assert.equal(session.environment.sky.sunElevation, undefined);
session.apply([{ type: 'set-environment', environment: { sky: { horizonGlow: GLOW } } }], { expectedRevision: 1 });
- assert.equal(session.environment.sky.horizonGlow.color, '#7ff4ff');
+ assert.equal(session.environment.sky.horizonGlow.color, GLOW.color);
assert.equal(session.environment.sky.stops.length, 2);
});