TimeOfDayComponent struct in Thread

A world clock that drives the sun. It advances the time of day while the game runs and, from that one number, sets the rotation, colour and intensity of the directional light, the sky gradient, and the ambient fill.

Put it on the same entity as the DirectionalLightComponent it drives. That pairing is the rule, not a convention: it lets a scene state which light is the sun instead of leaving the answer to entity iteration order, so a level can also hold a fill light, a moon or an interior lamp that the clock leaves alone. A clock with no directional light beside it drives nothing and says so in the log.

Properties

EnabledboolMaster switch. Off leaves the light exactly as authored.
TimeOfDayfloatHours in [0, 24). Decimal, so 6.5 is half past six. The authored value is where a new game starts.
DayintWhole days elapsed. Incremented on every midnight crossed; what a day means is the game's business.
PausedboolFreeze the clock without disabling the lighting it drives.
ProceduralSkyboolReplace the skybox cubemap with a gradient that follows this clock. On by default.
SettingsDayNightSettingsEverything about the shape of the day — see below.

DayNightSettings

DayLengthMinutesfloatReal minutes per in-game day. 0 freezes the clock instead of dividing by zero.
SunriseHour / SunsetHourfloatWhen the sun crosses the horizon. Sunset before sunrise is permanent night, not an error.
DayColor / HorizonColor / NightColorVec3Sun colour at midday, at the horizon, and after dark.
DayIntensity / NightIntensityfloatSun brightness at either end. Night is moonlight and deliberately not zero.
SkyZenithDay / SkyHorizonDayVec3Daytime sky gradient, straight up and at eye level.
SkyZenithNight / SkyHorizonNightVec3The same two, after dark.
AmbientDayIntensity / AmbientNightIntensityfloatFill light at either end — see Making night dark.
NorthYawRadiansfloatTurns the whole arc, so a level can face its sunrise wherever the terrain wants it. Changes the compass, never the shape of the day.
ArcTiltDegreesfloatThe latitude knob. Highest elevation of the day is exactly 90 − this.

Making night dark

The sun on its own cannot do it, and this is the setting people go looking for when night stays bright. Every ambient term in the lit shader — image-based light off the skybox, SH irradiance, the irradiance volume, and the flat fallback — is multiplied by the scene's ambient colour and intensity. A fill that stays put therefore keeps a cubemap's noon light on the ground at midnight, and the whole cycle reads as a sun sliding across an evenly lit world.

So the clock drives an AmbientLightComponent as well — on its own entity, same pairing rule as the sun. This is opt-in by construction: a scene with no ambient light beside the clock keeps exactly the ambient it was authored with, so adding a clock cannot silently re-light a finished level.

The colour it writes is a tint of unit luminance, not a colour to use on its own — all of the brightness lives in the intensity. Handing over the raw night sky (around 0.03 luminance) and then multiplying by an already-small night intensity would land on 0.001, which is not darkness, it is a black screen.

Notes

ArcTiltDegrees = 0 is a singularity. It sends the sun exactly through the zenith at midday, where azimuth is undefined — the sun's direction snaps through half a turn as it crosses, and on screen the light appears to twist. Only the equator at an equinox does this. The default, 35, arcs the sun across one side of the sky, peaking at 55°, which is what a sun looks like almost everywhere.

Sun colour, sky and ambient all cross the horizon on one shared twilight band rather than branching on the sign of the elevation, so none of the three can disagree with the others about whether it is night, and none of them steps in a single frame.

The clock applies in the editor viewport too, without advancing — scrubbing the Time slider moves the sun immediately, so lighting can be judged at any hour without entering Play.

Pair it with PersistentComponent if the time of day should survive a save. Without it, every load starts at the authored hour.

TimeOfDayComponent struct w Thread

Zegar świata, który steruje słońcem. Przesuwa porę dnia w trakcie gry i z tej jednej liczby ustawia rotację, kolor i jasność światła kierunkowego, gradient nieba oraz światło otoczenia.

Umieść go na tej samej encji co DirectionalLightComponent, którym steruje. Ta para to reguła, nie konwencja: dzięki niej scena mówi, które światło jest słońcem, zamiast zostawiać to kolejności iteracji encji — więc poziom może mieć też światło wypełniające, księżyc czy lampę w pomieszczeniu, których zegar nie rusza. Zegar bez światła kierunkowego obok niczym nie steruje i pisze o tym w logu.

Właściwości

EnabledboolGłówny przełącznik. Wyłączony zostawia światło dokładnie takie, jak ustawione.
TimeOfDayfloatGodziny w [0, 24). Dziesiętnie, więc 6.5 to wpół do siódmej. Ustawiona wartość to start nowej gry.
DayintPełne minione dni. Zwiększany przy każdej północy; co dzień znaczy, to sprawa gry.
PausedboolZatrzymuje zegar bez wyłączania oświetlenia, którym steruje.
ProceduralSkyboolZastępuje cubemapę skyboxa gradientem podążającym za zegarem. Domyślnie włączone.
SettingsDayNightSettingsWszystko o kształcie doby — patrz niżej.

DayNightSettings

DayLengthMinutesfloatPrawdziwe minuty na dobę w grze. 0 zatrzymuje zegar zamiast dzielić przez zero.
SunriseHour / SunsetHourfloatKiedy słońce przecina horyzont. Zachód przed wschodem to wieczna noc, nie błąd.
DayColor / HorizonColor / NightColorVec3Kolor słońca w południe, przy horyzoncie i po zmroku.
DayIntensity / NightIntensityfloatJasność słońca na obu krańcach. Noc to światło księżyca i celowo nie zero.
SkyZenithDay / SkyHorizonDayVec3Dzienny gradient nieba, w zenicie i na wysokości oczu.
SkyZenithNight / SkyHorizonNightVec3Te same dwa po zmroku.
AmbientDayIntensity / AmbientNightIntensityfloatŚwiatło wypełniające na obu krańcach — zob. Ciemna noc.
NorthYawRadiansfloatObraca cały łuk, żeby poziom miał wschód słońca tam, gdzie pasuje terenowi. Zmienia kompas, nigdy kształt doby.
ArcTiltDegreesfloatPokrętło szerokości geograficznej. Najwyższa wysokość słońca w ciągu dnia to dokładnie 90 − ta wartość.

Ciemna noc

Samo słońce tego nie zrobi — i tego ustawienia ludzie szukają, gdy noc zostaje jasna. Każdy człon światła otoczenia w shaderze — oświetlenie z obrazu skyboxa, irradiancja SH, wolumen irradiancji i płaski fallback — jest mnożony przez kolor i jasność otoczenia sceny. Wypełnienie, które się nie zmienia, trzyma więc o północy południowe światło cubemapy na ziemi, a cały cykl wygląda jak słońce przesuwające się nad równo oświetlonym światem.

Dlatego zegar steruje też AmbientLightComponent — na jego własnej encji, z tą samą regułą pary co słońce. Z konstrukcji jest to opcjonalne: scena bez światła otoczenia obok zegara zachowuje dokładnie to otoczenie, z jakim ją zrobiono, więc dodanie zegara nie przeoświetli po cichu gotowego poziomu.

Kolor, który zapisuje, to odcień o jednostkowej luminancji, a nie kolor do użycia samodzielnie — cała jasność siedzi w intensywności. Przekazanie surowego nocnego nieba (ok. 0,03 luminancji) i pomnożenie przez już małą nocną intensywność dałoby 0,001, a to nie ciemność, tylko czarny ekran.

Uwagi

ArcTiltDegrees = 0 to osobliwość. Słońce przechodzi wtedy dokładnie przez zenit w południe, gdzie azymut jest nieokreślony — kierunek słońca przeskakuje o pół obrotu, a na ekranie światło wydaje się skręcać. Tak jest tylko na równiku w czasie równonocy. Domyślne 35 prowadzi słońce łukiem po jednej stronie nieba ze szczytem 55° — tak wygląda słońce prawie wszędzie.

Kolor słońca, niebo i otoczenie przechodzą przez horyzont jednym wspólnym pasmem zmierzchu, zamiast rozgałęziać się na znaku wysokości, więc żadne z trzech nie może się z resztą nie zgadzać, czy jest noc, i żadne nie przeskakuje w jednej klatce.

Zegar działa także w viewporcie edytora, bez upływu czasu — przesunięcie suwaka Time od razu przestawia słońce, więc oświetlenie ocenisz o każdej porze bez wchodzenia w Play.

Połącz go z PersistentComponent, jeśli pora dnia ma przetrwać zapis. Bez tego każde wczytanie startuje od ustawionej godziny.