Sky and lighting

#The built-in sky

WaterSystem.create() adds a sky dome to your scene. It follows the camera and scales itself to 0.9 × camera.far. It's the analytic sky from the original page: a sun arc from time, zenith and horizon colours, an fbm cloud deck with self-shadowing and silver lining, stars and a moon.

water.setParams({ time: 18.2 });                       // eases toward sunset
water.setParams({ clouds: 0.9, cloudDarkness: 0.6 });  // a darkening sky
water.stats.sunElevation;                              // degrees

These params only drive the built-in sky. With an external sky, time, clouds, cloudDarkness and overcast do nothing, and fogDensity still fogs the water.

#Lights that follow the sky

const sun = new THREE.DirectionalLight();
const hemi = new THREE.HemisphereLight();
scene.add(sun, sun.target, hemi);

renderer.setAnimationLoop(() => {
  water.update(dt);
  water.bindLights(sun, hemi, { distance: 250, intensity: 1.3 });
  water.render();
});

bindLights(directional?, hemisphere?, opts?) copies the water's current key light: the sun by day, the moon once the sun is down, from the built-in sky or an external one.

• The directional light is placed opts.distance (250) metres from its target along the light direction, so move the target to where your shadows should be. Its colour times opts.intensity (1.3) equals the key light.
• The hemisphere light takes the zenith and horizon colours for the sky, and the sky's ground colour.

#Scene fog

With manageFog: true (the default) the water keeps scene.fog as a THREE.FogExp2, coloured by the sky's horizon, with the fogDensity param as its density. Your objects then fade into the same haze as the sea. Pass manageFog: false to manage scene.fog yourself.

const water = await WaterSystem.create({ renderer, scene, camera, manageFog: false });

#Use a different sky

setSky() replaces the built-in sky with any object that has a sun, and optionally an environment map, cloud shadows, a fog colour, ambient light and a moon. The built-in dome is removed from the scene, and setSky(null) puts it back.

water.setSky(skySystem);   // naturegl-sky's SkySystem fits as is
water.setSky(null);        // back to the built-in sky

The full contract, the options and the NatureGL Sky setup are on With other packs.

#BuiltinSky on its own

BuiltinSky is exported, and water.builtinSky is always there, even while an external sky is active.