Time of Day

A day is a path the sun takes and what the light, the sky and the fog are because of where it is. TimeOfDay places the sun with the astronomy that fits in four lines — an hour angle, a latitude and a season — so a day has the right shape (a long high arc in summer, a short low one in winter, sunrise toward the east) from three numbers a person can understand. Everything else is the same idea as Weather: multipliers of what the scene already says, so the same hour fits any project.

The component

Add a TimeOfDay component to one entity.

Field	What it does
hour	The hour, 0–24 (12 is noon). The game advances it; set it in the editor to preview an hour.
daySeconds	Seconds a whole day takes while the game runs. 0 holds the hour where it is.
latitude	Where on the planet, in degrees (positive is north): how high the noon sun climbs.
declination	The season, −23.5 to 23.5: positive is summer in the north.
north	How far the world is turned from compass north (+Z) toward +X, in degrees — which way the sun rises.
drive	What the time drives: Lights, Sky, Fog, Exposure, Reflections.

In the editor

Select the entity and the Details panel shows the day instead of a list of numbers: the sun’s height across 24 hours, drawn from this component’s own latitude and declination (a winter day is a low short arc, a polar summer one never sets), with a hand you drag to set the hour — or click the dial and use the arrow keys, 15 minutes a step, an hour with Shift. Beside it are the sun’s height, the daylight and the key light’s scale at that hour, and below, a switch for each thing the clock drives. The hour you set is what the editor previews; it only advances in Play.

What an hour changes

• The key light. The scene’s directional light (the one that follows a panorama’s sun or casts shadows, else the first) is aimed at the sun and scaled by a day’s curve: warm and weak near the horizon, gone a little below it. While the sun is down it is aimed at the moon and given a few hundredths of the sun’s strength and a blue tint, so a night has shadows that fall away from the moon. The crossover happens where both are dark, so nothing pops.
• The ambient light is scaled and tinted — blue by night, warm at dusk — and baked reflection probes are dimmed and drained of colour, since they were baked under a daytime sky.
• The sky. A Sky Atmosphere effect scatters the sun’s light through a planet’s atmosphere — Rayleigh for the blue of the air, Mie for the haze and the glare round the sun — so the blue of noon, the red of a sunset and the afterglow after it come out of one calculation. It draws the sun (white overhead, red at the horizon), the moon, the stars, and volumetric clouds the sun lights and the wind moves. It takes the sun from the clock, so it never mistakes the moon-lit key light for the sun.
• Fog. Height Fog’s colour is lit as the day is (dark at night, orange at dusk), and its glow follows the key light.
• Exposure. Auto Exposure’s compensation is raised at night so it stays readable (a scene without one gets it on its Colour Grade).

In the editor the scene’s lights are left alone — as with Weather, previewing an hour never changes the scene you save — so the effects that follow the sun (sky, fog) are told where the clock’s sun is instead. The lights move while the game runs.

With the weather

Both scale the same lights, each from what the author set, so they compose: a rainy dusk is the dusk’s colour times the rain’s strength. The weather also greys the sky (overcast), hiding the sun, moon and stars as it clouds over.

Reading and driving it from code

import { timeOfDayAt, currentTimeOfDay, TimeOfDay } from 'esengine';

// Where the sun is at 18:30 at latitude 51, in midsummer.
const evening = timeOfDayAt(18.5, 51, 23);
evening.sunDir;        // unit vector toward the sun
evening.daylight;      // 0 at night, 1 by day

// Set the hour: the system does the rest.
world.insert(clockEntity, TimeOfDay, { hour: 6, daySeconds: 600 });

Limits

The baked lighting and the baked reflection probes are one moment’s: the bake is of a daytime sky, so the lighting that is not from lights (lightmaps, probe volumes) does not move with the sun. A scene that is meant to pass through a whole day wants its sun and its sky live — a lit-by-lights scene, or a baked one whose bake is mostly the sky’s soft light — and the dimming and tinting above do the rest. Windows and lamps do not light themselves at night; give them an emissive material or a light you turn on with currentTimeOfDay().daylight.