Guides

Time, sun and moon

The sun follows a real track for a latitude and a season. The moon rides the same track a set number of days behind, so its phase always matches the clock.

clock.speed = 1.35: roughly 19 hours of sky in 14 seconds, from the hill view.

#Setting the time

sky.setTime(18.5);                        // 18:30 — eases the short way round
sky.setTime(6, { immediate: true });      // jump, no easing

sky.clock.running = true;
sky.clock.speed = 0.5;                    // hours per real second (default 24/144: a day in 2.4 min)

sky.timeOfDay is the eased hour actually rendered, and sky.dayPhase names it ('Golden hour', 'Blue hour', 'Nautical dusk' and so on). formatClock(hours) gives you 18:30.

#Placing the sun by angle

Most scenes are composed around a sun position, not a clock time. setFromAngles works backwards. It picks the afternoon time at which the sun has that elevation, for the current latitude and declination. Then it rotates northOffset so the sun sits at that world azimuth. The moon and stars follow.

sky.sun.setFromAngles(12, 30);            // 12° up, azimuth 30° (0 = −Z, 90 = +X)
sky.setSunAngles(12, 30, { immediate: true });

#Latitude, season and moon

Param	Default
`latitude`	`34`	degrees; sets how high the sun climbs and how long twilight lasts
`declination`	`11`	−23.4 (December solstice) … 23.4 (June solstice)
`northOffset`	`112.58`	world azimuth of north: rotates sun, moon and stars together
`lunarAge`	`18.3`	days since new moon (0 – 29.53). `lunarAgeNow()` returns tonight's

import { lunarAgeNow, phaseName } from 'naturegl-sky';

sky.setParams({ lunarAge: lunarAgeNow() });
phaseName(sky.params.lunarAge);  // 'WAX GIB', 'FULL', …
sky.moon.illumination;           // lit fraction 0–1

#Night

After the sun drops 6° below the horizon, sky.keyLight switches to the moon. The stars turn about the celestial pole, and the milky way has a warm core. The moon has a lunar aureole that dims correctly behind cloud.

The night preset with the clock running: waning gibbous moon, star field and milky way.

#Keep nights dark

The metered exposure runs from about 1.3 at noon to 30–60 on a moonlit night. That's physically right, but it makes night look like a dim day. Version 1.1 adds two ceilings in toneMappingExposure units:

const sky = await SkySystem.create({
  renderer, scene, camera,
  maxExposure: 2.4,     // never brighten beyond this
  nightExposure: 5,     // ceiling at full night; blends through dusk in log space
});
sky.night;              // 0 by day … 1 at full night
sky.meteredExposure;    // the raw meter, before the ceilings

The moon, stars and lightning stay scaled by the exposure actually applied. The landscape goes dark, but the sky stays readable.