TimeOfDay

Controls the day/night cycle. It positions the sun for the selected latitude, places the moon opposite the sun, rotates the star panorama, and fades stars in during twilight. SkySystem.update(dt) advances the clock.

Properties

autoAdvanceSecondsPerDay

Type: number
Default: 600
Units: seconds

Sets the real-time duration of one simulated day. 0 pauses the clock and preserves a direction set with sun.setFromAngles().

---

azimuth

Type: number
Default: 0
Units: degrees

Rotates the sun path, moon, and stars around the world's vertical axis. Use it to align the sky with your scene.

---

latitude

Type: number
Default: 45
Units: degrees

Tilts the sun and moon arcs and the axis the stars turn about. 0 puts the noon sun straight overhead; 45 peaks it halfway up; 90 sends the sun, moon, and stars circling parallel to the horizon. Clamped to −90–90.

---

moonAmbient.value

Type: uniform<float>
Default: 0.015
Units: -

Scales the moon's ambient contribution to the night sky. Typical range: 0–1.

---

moonAngularSize.value

Type: uniform<float>
Default: 0.0003
Units: -

Sets the angular size of the moon disc, measured as 1 - cos θ. Same convention as sun.discSize.

---

moonColor.value

Type: uniform<color>
Default: (0.7, 0.78, 0.95)
Units: linear RGB

Tints the moon disc, the sky ambient it casts, and the moonlight on cloud edges.

---

moonDiscBrightness.value

Type: uniform<float>
Default: 9.0
Units: -

Scales the moon disc brightness in addition to moonIntensity. It does not affect moonlight on the sky or clouds.

---

moonIntensity.value

Type: uniform<float>
Default: 1.0
Units: -

Scales everything the moon lights: the disc, the sky ambient, and the light on cloud edges. All three also scale with the moon's lit fraction, so a sliver moon stays dim on its own.

---

moonPhase.value

Type: uniform<float>
Default: 0.5
Units: -

Sets the moon's phase: 0 is new and dark, 0.5 is full, 1 is new again. Phase changes the disc's lit shape and brightness but not its position.

---

time.value

Type: uniform<float>
Default: 0.5
Units: -

Time within the day, from 0 to 1: 0 is midnight, 0.25 sunrise, 0.5 noon, and 0.75 sunset. Assign a value directly to jump to that time.

Driven Uniforms

The system updates moonDirection, skyDarkness, starRotation, moonPhaseIllumination, and moonPhaseTrig each frame. Treat these uniforms as read-only.

The sun rises due east at time = 0.25, reaches 90° − latitude at noon, and sets due west. The model does not include seasons, so the path is the same each day. Stars rotate around the same celestial pole. The moon remains opposite the sun, reaching its highest point at midnight.

Methods

applyParams(params)

Writes any subset of PartialTimeOfDayParams in one call. Omitted fields are left unchanged.

Returns: void

sky.timeOfDay.applyParams({
  time: 0.85,
  latitude: 60,
  azimuth: 120,
  moon: { phase: 0.25, intensity: 0.2 },
});

---

toParams()

Returns a new TimeOfDayParams containing the current clock, sky orientation, and moon settings. Pass it to applyParams to restore the state, or store it in a preset's time block.

Returns: TimeOfDayParams

const saved = sky.timeOfDay.toParams();
sky.timeOfDay.applyParams({ time: 0.1 });
sky.timeOfDay.applyParams(saved); // back to where it was

Types

TimeOfDayParams

Every field is required — what toParams() returns and the shape of a preset's time block.

Moon fields nest under moon and drop the prefix: phase writes the moonPhase uniform above, intensity writes moonIntensity, and so on.

interface TimeOfDayParams {
  // 0 = midnight, 0.5 = noon. Wrapped to [0, 1)
  time: number;
  // real seconds per simulated day; 0 pauses the clock
  autoAdvanceSecondsPerDay: number;
  // observer latitude in degrees, clamped to [-90, 90]
  latitude: number;
  // compass rotation of the celestial sphere, in degrees
  azimuth: number;
  moon: MoonParams;
}

MoonParams

interface MoonParams {
  // 0 = new, 0.5 = full, 1 = new again
  phase: number;
  // master brightness over disc, cloud key, and sky ambient
  intensity: number;
  // disc-only brightness, stacking on `intensity`
  discBrightness: number;
  // angular radius as `1 - cos θ`
  angularSize: number;
  // linear RGB — tints disc, sky ambient, and cloud moonlight
  color: THREE.Color;
  // night-sky ambient lift, [0, 1]
  ambient: number;
}

PartialTimeOfDayParams

What applyParams accepts: every field optional, including the fields inside moon.

type PartialTimeOfDayParams = Partial<Omit<TimeOfDayParams, 'moon'>> & {
  moon?: Partial<MoonParams>;
};

Every type here is importable by name:

import type {
  TimeOfDayParams,
  PartialTimeOfDayParams,
  MoonParams,
} from 'threejs-sky-pro';

See Also

• Day/Night Cycle
• Sun