atmosphere

Physically-based atmospheric scattering — aerial perspective on distant geometry, and a sky whose colour follows from the sun's elevation.

local atmosphere = require("@builtin::systems.atmosphere.atmosphere")

atmosphere.set({ aerial = 1, sky = true, worldUnitsPerKm = 1000 })
atmosphere.get()      --> the settings in force
atmosphere.active()   --> are the scattering passes running
atmosphere.clear()    --> off, settings kept for the next set()

set takes any subset — omitted fields keep their current value, so adjusting one knob does not mean restating the rest. With aerial at 0 and sky off nothing is wanted and the passes are released rather than run at zero strength.

worldUnitsPerKm is the one number that has to match the scene. Scattering is computed in kilometres against Earth's coefficients, so it is what maps a scene onto real atmospheric distance. At the default 1000 a world unit is a metre.

sunDirection / sunIntensity follow the scene's sun unless the call pins them. Sun elevation is what drives the entire appearance of a physical sky, so that is what lets a day cycle reach the sky with nothing else authored.

sunColor defaults to white on purpose: the warm colour of a low sun comes out of the transmittance through a longer air path, not out of a tint.

For an atmosphere a scene should simply have, author the PhysicalAtmosphere component instead — it carries the same settings, persists with the scene, and edits live in the inspector. This module is for code that changes the atmosphere at runtime: a weather system, a cutscene, a quality slider.

The full description of what each knob does and how the passes work is in the package readme: guides { path = "systems/atmosphere" }.