Log inGet started
Package

ProceduralSky.component

Newest version

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

FieldTypeDefaultMeaning
presetstring""Named look applied before explicit fields: clear_day, sunset, sunrise, overcast, night.
timeOfDaynumber14.00..24 hours; orients the sun and the day/night gradient.
autoCycleboolfalseAdvance timeOfDay each frame.
cycleSpeednumber60.0Game-seconds per real-second for the auto cycle.
syncSunToLightbooltrueDrive the directional light from the sun.
sunPeakIntensitynumber1.0What 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 / groundColorcolor—Sky gradient colours.
sunSize / sunIntensitynumber0.02 / 20.0Sun disc size + brightness, as drawn in the sky.
starsIntensitynumber1.0Night star-field intensity.
starsTwinklenumber0.0How 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.
moonSizenumber0.03Moon disc size.
turbiditynumber4.0Atmospheric haziness.
exposurenumber1.0Sky exposure multiplier.

Methods

MethodDescription
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).