Day/Night Cycle

The day/night clock controls the sun, moon, moonlight, and star rotation. Supply a star texture when creating SkySystem to render the night panorama.

The Clock

sky.timeOfDay.time runs from 0 to 1 over one full day:

time	What you see
0.0	Midnight
0.25	Sunrise (east)
0.5	Noon
0.75	Sunset (west)

Set a specific time:

// noon
sky.timeOfDay.time.value = 0.5;

Set a cycle length to advance the clock through sky.update(dt):

// a full day every 10 minutes
sky.timeOfDay.autoAdvanceSecondsPerDay = 600;

Set it to 0 to pause.

Latitude and Azimuth

latitude controls the height and orientation of the celestial paths. At 0, the noon sun passes overhead. At 45, it reaches 45 degrees. At 90, the sun, moon, and stars circle parallel to the horizon. azimuth rotates all of these paths around the world's vertical axis.

// Nordic sky: low sun, steep star trails
sky.timeOfDay.latitude = 60;
// rotate the sky about the vertical axis
sky.timeOfDay.azimuth = 135;

There are no seasons: the sun always rises due east and sets due west.

The Moon

The moon sits opposite the sun — highest at midnight, below the horizon at noon. Phase changes its lit shape and brightness, not its position.

// full moon
sky.timeOfDay.moonPhase.value = 0.5;
// master gain
sky.timeOfDay.moonIntensity.value = 1.0;
sky.timeOfDay.moonColor.value.set('#b3c7f2');

Moon lighting has three components:

• The moon disc, shaded by phase.
• Sky ambient light (sky.timeOfDay.moonAmbient).
• A rim light on cloud edges facing the moon (sky.clouds.lighting.moonGain).

moonIntensity scales all three components. They also scale with the illuminated fraction of the moon.

The moon renders without a star panorama as a flat tinted disc. When nightSky is configured, Sky Pro applies its bundled lunar surface texture. Replace it with nightSky.moonTexture, or import the bundled texture URL:

import { BUNDLED_MOON_TEXTURE_URL } from "threejs-sky-pro";

Stars

The star panorama fades in across twilight. The texture is not bundled — pass your own to enable stars. Configuring nightSky also applies the bundled lunar surface texture:

const sky = await SkySystem.create({
  renderer,
  camera,
  scene,
  nightSky: {
    // URL or a preloaded THREE.Texture
    texture: '/textures/starmap_4k.jpg',
    // optional — overrides the bundled moon
    moonTexture: '/cdn/my-moon.jpg',
  },
});

Omit nightSky and stars are disabled (sky.nightSky === null); the flat tinted moon disc and its ambient light still render.

At runtime, sky.nightSky.intensity scales the stars' brightness and sky.nightSky.setTexture() swaps the panorama — see SkySystem.

Panorama Format

The star panorama must be:

• Equirectangular projection (X = longitude 0..2π, Y = latitude -π/2..π/2).
• sRGB-encoded JPEG or PNG.

The texture's top and bottom edges represent the celestial poles. timeOfDay.latitude tilts the rotation axis. The sources below use equatorial (RA/Dec) coordinates and require no coordinate conversion.

Ready-to-Use Starmaps

The following sources provide equirectangular star panoramas. Review the license and attribution requirements for each asset.

Source	Resolution	License	Link
NASA/Goddard SVS — Deep Star Maps 2020 (Tycho + Gaia)	up to 16K	Public domain	svs.gsfc.nasa.gov/4851
NASA/Goddard SVS — Tycho Catalog Skymap	up to 8K	Public domain	svs.gsfc.nasa.gov/3895
Solar System Scope — Milky Way starmap	8K	CC BY 4.0	solarsystemscope.com/textures
ESO — Milky Way panorama	gigapixel	CC BY 4.0	eso.org/public/images/eso0932a

Load one with a THREE.TextureLoader (or pass the URL directly as nightSky.texture):

const starmap = await new THREE.TextureLoader().loadAsync('/textures/starmap_4k.jpg');
const sky = await SkySystem.create({ renderer, camera, scene, nightSky: { texture: starmap } });

Notes

• God rays keep rendering after sunset — the shafts switch from the sun to the moon, scaled by sky.godRays.moonGodRayScale (default 0.4). Set it to 0 for no moonlight shafts.
• Water reflections include the moon disc, the ambient sky lift, and the stars.

See Also

• TimeOfDay
• Sun