volumetricLighting

The settings behind the VolumetricLighting component, and the way to drive the scene's participating medium from a script — fog that rolls in over a cutscene, a quality slider that drops the step count, a room that fills with smoke.

local volumetricLighting = require("@builtin::systems.volumetrics.volumetricLighting")

volumetricLighting.set({ density = 0.06, anisotropy = 0.7 })
volumetricLighting.get()        -- a copy of the settings in force
volumetricLighting.active()     -- whether the march is running
volumetricLighting.clear()      -- empty the air, keep the settings

set takes any subset of the fields; whatever is omitted keeps its current value. A density of 0 releases the render feature rather than marching a medium that scatters nothing, and clear is the named way to say the same thing.

sunDirection tracks the scene's sun on its own. Pin it through set when a scene wants the medium lit from somewhere else.

The module packs the settings into the vol_params buffer the passes read, so a change lands on the next frame without recompiling anything.

Cost

The march is the expensive part, and its cost is steps × (shadowSteps + the number of live scene lights) per marched pixel. Those are the two knobs to reach for on a budget: steps controls how cleanly a beam's edge resolves, and shadowSteps controls whether the sun's contribution is shadowed at all. Setting shadowSteps to 0 removes the per-sample visibility work entirely, which is the single largest saving available — at the cost of the shafts, since the medium is then lit evenly wherever it reaches.