Sky and Weather

Sky and weather setup is stored as level objects, usually under a scene tree group such as sky_and_sun in main/items.level.json.

The usual outdoor setup is:

• TimeOfDay for the level clock, seasonal sun position, observer location, date, UTC offset, and optional sky profile selection.
• ScatterSky for atmospheric sky rendering, sky ambient, night-sky rendering, and sky art controls.
• CloudLayer for cloud appearance and cloud transmittance.
• LevelInfo for level-wide fog density, visible distance, gravity, and environment map settings.
• core_celestial for runtime sun, moon, stars, meteors, and profile application.

For the full lighting explanation, see Sky, Atmosphere, and Night Sky .

Minimal object group

A typical level contains one TimeOfDay, one ScatterSky, one CloudLayer, and one LevelInfo:

{"name":"tod","class":"TimeOfDay","startTime":0,"time":0,"play":false,"axisTilt":23.44,"latitude":47,"longitude":8,"year":2026,"month":6,"day":20,"utcOffset":"2","celestialProfile":"earth"}
{"name":"theLevelInfo","class":"LevelInfo","fogDensity":0.0006,"fogAtmosphereHeight":800,"visibleDistance":4500}
{"name":"sunsky","class":"ScatterSky"}
{"name":"clouds","class":"CloudLayer","coverage":0.2,"windSpeed":0.03,"windDirection":[1,0],"altitudeKm":4}

The exact fields saved by the World Editor depend on the level and engine version. Use the editor as the source of truth for object serialization.

For a first setup, keep ScatterSky simple and put the main choices on TimeOfDay: local time, latitude, longitude, date, UTC offset, and optional profile. Add more ScatterSky fields only for custom atmosphere, celestial bodies, night-sky art tuning, or debug overlays.

TimeOfDay

TimeOfDay controls the day/night clock and provides the place/date data used by the sky. New levels should always set longitude together with latitude; longitude affects astronomical orientation and local civil time conversion.

Important fields for current sky setup:

TimeOfDay does not render the sky by itself. It must be paired with a compatible sky object such as ScatterSky. The celestial runtime reads TimeOfDay and pushes the live sky state into ScatterSky.

ScatterSky

ScatterSky is the main sky object for current levels. Starting with update 0.39, author against the modern atmosphere fields, celestial fields, debug overlays, and sky profiles. Older day-sky fields may still appear in saved level files, but they are not the current authoring model.

The current sky is simulated from atmosphere and celestial data, not just a flat sky color. Atmosphere controls define how sunlight scatters through air, haze, and absorption layers. TimeOfDay provides observer location, date, and clock; the celestial runtime then places the sun, moon, stars, meteors, and optional profile bodies before rendering.

The renderer builds sky lookup textures for transmittance, multiscattering, aerial perspective, and visible sky color. Multiscattering preserves sky brightness and color near the horizon, in haze, and around low sun angles.

Moon phases and solar eclipses come from the same sun/moon placement. The moon’s lit fraction changes with its position relative to the sun, and sunlight is dimmed when the moon disc overlaps the sun disc from the level’s observer position.

For normal levels, use the first few groups below. The script functions, runtime fields, and debug overlays are advanced controls.

Current author-facing controls include:

• Atmosphere/profile: atmoRayleighScattering, atmoRayleighScaleHeight, atmoMieScattering, atmoMieExtinction, atmoMieScaleHeight, atmoMiePhaseG, atmoAbsorption, atmoGroundAlbedo, atmoSunIrradiance, atmoPlanetRadius, atmoThickness, atmoSunAngularSize, skyBrightness, exposure.
• Celestial bodies: profile bodies[], moonAlbedo, setCelestialBodies, brightnessEV, emissive, toSun, tint, albedo.
• Moon: moonAngularSize, moonBrightnessEV, moonEarthshine, moonShadowFloor, moonLimbDarkening, moonTerminatorSoftness, moonGlow, moonFlatten, moonLightColor, moonIllumination, moonOrbitNodeRad.
• Stars and Milky Way: starsEnabled, starCatalog, starBrightnessEV, starDensity, starNorthOffset, starAzimuthSign, starPulse, milkyWayEnabled, milkyWayBrightnessEV, milkyWayGalacticX/Y/Z, milkyWayDebug.
• Constellations: constellationsEnabled, constellationLines, constellationNamesEnabled, constellationLabels.
• Meteors: meteorsEnabled, meteorBrightnessEV, meteorTrailLength, meteorWidth, meteorSpeed, meteorRate, meteorShowerFraction, meteorRadiantRA, meteorRadiantDec, meteorInject.
• Debug overlays: gridEnabled, gridBrightness, gridThickness, gridColor, equatorialGridEnabled, meridianEnabled, moonPathEnabled.
• Response curves: setCelestialCurve(skyId, index, points).

Some sky fields are runtime-driven by the astronomical system, including sun and moon position, moon illumination, star orientation, star visibility, meteor rate, meteor radiant, and meteor shower state. Do not author those as fixed values for normal levels.

Night sky

The procedural astronomical night sky is the current default path for levels.

• Stars, Milky Way, the data-driven moon, meteors, and optional constellation data are rendered from time, date, location, and UTC offset.

Set time, latitude, longitude, date, and UTC offset when the night-sky result matters.

Sky profiles

Sky profiles are JSON presets loaded by core_celestial.

Use one of these setups:

• Set TimeOfDay.celestialProfile to a bare name such as earth. Bare names resolve to /art/skies/profiles/<name>.json.
• Set TimeOfDay.celestialProfile to a direct JSON path.
• Add a celestial.json next to the level’s mission file.

Profiles can set atmosphere values, moonAlbedo, and optional extra bodies. The stock earth profile documents the default Earth-like atmosphere and is the recommended starting point for custom level profiles.

CloudLayer

CloudLayer controls cloud appearance. In the current sky pipeline, clouds can also affect sun transmittance and ambient sky lighting.

The current path renders volumetric clouds by ray-marching through a cloud layer instead of drawing only a flat cloud dome. Cloud density comes from a generated weather map, 3D noise volumes, vertical height gradients, and wind-driven offsets. This gives clouds depth, soft edges, internal shadowing, and view-dependent opacity.

Cloud lighting is tied to the sky. Direct sunlight is reduced through cloud density, while sky ambient SH9 fills shadowed cloud areas. The cloud renderer also produces transmittance/shadow data for sun strength, ambient lighting, fog consistency, and flare occlusion.

Current volumetric cloud authoring fields include:

• coverage - large-scale cloud amount. Higher values create more filled cloud regions and increase the thin cirrus contribution.
• windSpeed - scalar speed for cloud movement.
• windDirection - horizontal direction for cloud movement.
• altitudeKm - base altitude of the main volumetric cloud layer.

Older CloudLayer fields can still appear in saved level files, but they are not useful controls for the current volumetric cloud path.

Cloud quality settings affect how clouds are sampled, reconstructed, and how often cloud shadow/transmittance data updates. Always check the level at the cloud quality presets you intend to support.

Fog and LevelInfo

LevelInfo still controls fog density and visible distance:

• fogDensity
• fogAtmosphereHeight
• visibleDistance

The current sky path derives sky and fog color from the atmosphere. Use LevelInfo for fog amount/range/visibility, and use the sky atmosphere or a sky profile for sky/fog color art direction.

Best practices

• Use one primary TimeOfDay and one primary ScatterSky per outdoor level.
• Set latitude, longitude, date, and UTC offset if the real sky matters.
• Use celestialProfile or a level-local celestial.json for custom sky presets.
• Tune exposure before increasing sky, moon, star, or local light brightness.
• Validate clouds and fog at Low, Normal, and High cloud quality.
• Use Lighting Quality Ultra when judging sun penumbra softness.

Related pages

• Sky, Atmosphere, and Night Sky
• TimeOfDay
• LevelInfo
• Night Lighting
• Ambient Lighting
• Lighting Quality