ProceduralSky.component
This package holds more than this page lists. See all of its files in its world.
README.md
ProceduralSky
The editable atmospheric sky: a day/night gradient with a sun disc, glow, stars and a moon, all derived procedurally from the directional light's elevation. Add it to an entity like a light:
entity.spawn("sky").component.add("ProceduralSky", { timeOfDay = 18.5 })
entity.spawn("sky").component.add("ProceduralSky", { preset = "sunset" })
entity.spawn("sky").component.add("ProceduralSky", {
zenithColor = { r = 0.05, g = 0.1, b = 0.3 },
horizonColor = { r = 0.9, g = 0.4, b = 0.2 },
})
A ProceduralSky owns its material outright: it registers a runtime GPU
material of its own over the builtin procedural-sky shader and pushes every
visual parameter (colours, sun, stars, moon, turbidity, exposure) straight to
that record. The component's fields are the material definition — no
.material asset backs it, so retuning a scene's sky changes that scene's sky
and nothing else. The renderer reads the values from the material's group(1)
uniform like any other material — there is no sky-specific render path.
Those values also travel the native Sky bridge into the scene sky config,
alongside the time-of-day / auto-cycle / sun-sync controls. That config is what
sky.get() reports and what a saved scene records, so both name the sky being
drawn.
With syncSunToLight on (the default), the sky's timeOfDay is what the scene
is lit by: the scene's directional light takes its direction, colour and
intensity from the sun's position, so the sun in the sky and the sun the scene
is lit by are the same sun through a whole day/night cycle. Turn it off for a
light the sky leaves alone.
The intensity that arrives is the day/night curve: nothing while the sun is at
or below the horizon, climbing to sunPeakIntensity times the sky's daylight
(intensity 10) from thirty degrees up. sunPeakIntensity is 1.0, the sky's
own daylight, unless a scene asks for another: a harder sun on water or snow is
stated here, and a preset states its own (overcast veils the sun at 0.15).
Setting the light itself does not survive, because the sky writes over it every
time the hour moves. The sun disc drawn in the sky (sunSize, sunIntensity)
is a picture of the sun and leaves the light alone, so after any preset moving
timeOfDay to noon brings the daylight back. At night the scene is lit by its
night sky and the lights it places.
The sky's capture in the environment (what surfaces reflect and are lit by
where no probe reaches) follows the sky: a new preset, a new colour or a sun
that moved is retaken by the renderer, and renderer.reflectionEnvironment()
reports skyStale = true until it is.
Like the directional light, the sky is conceptually singular per scene. A
ProceduralSky fully defines its material on awake (every parameter from its
own fields), so switching scenes never inherits a previous scene's overrides.
Day/night comes from the sun's elevation, so evening presets render dark —
drive the look by timeOfDay (which orients the sun).
Fields
| Field | Type | Default | Meaning |
|---|---|---|---|
preset | string | "" | Named look applied before explicit fields: clear_day, sunset, sunrise, overcast, night. |
timeOfDay | number | 14.0 | 0..24 hours; orients the sun and the day/night gradient. |
autoCycle | bool | false | Advance timeOfDay each frame. |
cycleSpeed | number | 60.0 | Game-seconds per real-second for the auto cycle. |
syncSunToLight | bool | true | Drive the directional light from the sun. |
sunPeakIntensity | number | 1.0 | What the sun's light measures at noon, as a multiple of the sky's daylight (intensity 10); the day/night curve runs from nothing at the horizon up to this. |
zenithColor / horizonColor / groundColor | color | — | Sky gradient colours. |
sunSize / sunIntensity | number | 0.02 / 20.0 | Sun disc size + brightness, as drawn in the sky. |
starsIntensity | number | 1.0 | Night star-field intensity. |
starsTwinkle | number | 0.0 | How far each star's brightness swings over time; 0 holds the field still. The night preset twinkles at 0.3. A twinkling sky changes the picture on every frame, so the renderer keeps drawing under it. |
moonSize | number | 0.03 | Moon disc size. |
turbidity | number | 4.0 | Atmospheric haziness. |
exposure | number | 1.0 | Sky exposure multiplier. |
Methods
| Method | Description |
|---|---|
sky:setTimeOfDay(hours) | Set the time of day (0..24). |
sky:applyPreset(name) | Apply a named look. |
sky:setZenithColor(c) / setHorizonColor(c) / setGroundColor(c) | Set a gradient colour ({r,g,b} array or map; >1 auto-scales /255). |