Guides

Composing with other packs

Every NatureGL library renders into a scene you own. NatureGL Sky is the light source; the others read its sun, environment, cloud shadows and exposure.

#The contract

A library in the series never takes over your render loop or your scene graph:

The sky is a mesh in your scene. It's a fullscreen triangle rasterised at the far plane, with depth test on and depth write off, drawn last among the opaques. Any geometry occludes it, and transparent objects blend over it.
Offscreen work happens in update(dt). The sky-view LUT, the jittered low-res cloud march and its temporal resolve, the cloud shadow map, the time-sliced env bake and the PMREM refresh all run there.
What other libraries need is a property. That covers sun, moon, ambient, envMap, environment, cloudShadow, fogColor and displayExposure.

#With NatureGL Water

import { SkySystem } from 'naturegl-sky';
import { WaterSystem } from 'naturegl-water';

const sky = await SkySystem.create({
  renderer, scene, camera,
  maxExposure: 2.4, nightExposure: 5,   // keep moonlit nights dark
});
const water = await WaterSystem.create({ renderer, scene, camera, sky });   // or water.setSky(sky)

// the sky swaps env / shadow textures on quality changes: re-plug
sky.addEventListener('quality', () => water.setSky(sky));

renderer.setAnimationLoop(() => {
  sky.update(dt);
  water.update(dt);
  water.render();          // water tone-maps itself, matched to sky.displayExposure
});

setSky reads sun, moon, ambient.color, envMap, cloudShadow, fogColor and, since 1.1, displayExposure, so the ocean and the sky agree on brightness at every hour.

#Water + the sky's post pass

const post = sky.createPostPass();
renderer.setAnimationLoop(() => {
  sky.update(dt);
  water.update(dt);
  const hdr = water.renderHDR();                       // scene + ocean, linear HDR + depth
  post.composite(hdr.texture, hdr.depthTexture, camera); // fog, god rays, clouds over, bloom
});

#With Grass, Weather and NatureGL Island

Library	What it reads from the sky
NatureGL Grass	`setLighting({ sunDirection: sky.sun.direction, sunColor: sky.sun.color, ambient: sky.ambient.color })`, plus `patchMaterial` for cloud shadows on the terrain
NatureGL Weather	`weather.setLighting({ sunDirection: sky.keyLight.direction, sunColor: sky.keyLight.color, sunIntensity: sky.keyLight.intensity, ambient: sky.ambient.color, skyHorizon: sky.fogColor, skyZenith: sky.ambient.skyColor })` every frame. Weather only applies `skyHorizon` together with `skyZenith`
NatureGL Island	All of it: the game drives its day/night cycle, weather and water lighting from one `SkySystem`

#Your own renderer passes

Reflection and cube cameras can render the scene normally. They see sky.envMap in place of the screen-space clouds.
sky.setCamera(other) switches which camera gets the cloud reconstruction (history resets).
sky.clouds.texture (rgb in-scatter, a transmittance) and sky.clouds.depthTexture (r depth in metres, g transmittance) are available for custom compositing.
sky.uniforms is the shared sky uniform block. It's advanced, but it's what the backdrop and post pass bind.

NatureGL WaterGerstner ocean, shorelines, buoyancy and diving NatureGL WeatherRain, snow, lightning, fog and wet surfaces NatureGL GrassA million instanced blades with wind and trampling NatureGL IslandAn explorable island built on the whole series