VolumetricSky.component
This package holds more than this page lists. See all of its files in its world.
README.md
VolumetricSky
Clouds in the sky, as a component. Add it to one entity and the sky gets a
volumetric cloud layer lit by the scene's own sun: a shell around the planet
between two altitudes that reaches the horizon in every direction, its clouds
formed where they stand in the world, cumulus by default. A weather map sets
the coverage, cloud type and density over each place, so a storm over one
valley and clear sky over the next stand in one frame. The volumetricSky
render feature it brings up draws the layer into every view the frame draws,
over the sky and over the surfaces under it. Adding the component is the whole
set-up: no composite is authored. The layer draws in edit mode as well as in
play, and drifts with the wind once play runs.
Usage
-- Defaults (fair-weather cumulus — `Sky.defaultPreset()` hands out a copy
-- of the same table this field defaults to)
local sky = entity.spawn("sky")
sky.component.add("VolumetricSky", {})
-- Or apply a captured preset:
preset.apply("cumulus_default", { entity = sky.id, component = "VolumetricSky" })
-- Inline tweak. `component.add` writes the `preset` field as it is given,
-- so a table handed here carries the whole configuration:
local p = require("@builtin::systems.volumetrics.volumetricSky").defaultPreset()
p.coverage, p.cloudType = 0.7, 1.0 -- towering, most of the sky
sky.component.add("VolumetricSky", { preset = p })
-- Weather that differs from place to place:
sky.component.get("VolumetricSky").weatherRegions = {
{ x = -6000, z = 0, radius = 5000, coverage = 0.9, cloudType = 1 },
{ x = 6000, z = 0, radius = 5000, coverage = 0.05 },
}
volumetricSky.module's M.spawn / M.configure take the same parameters
by name, folding each into the current configuration and leaving the rest
where they stand:
local Sky = require("@builtin::systems.volumetrics.volumetricSky")
Sky.spawn({ coverage = 0.6, cloudType = 0.8, maxSteps = 96 })
Schema (Field<T> / Sync / NoSync)
The shaping / weather / lighting params travel as ONE Sync field —
preset = Field.table(DEFAULT_PRESET, Sync) — so replicating a sky change
is one mutation, and copying a sky between scenes is copying one
field. Per-client quality knobs sit outside the preset as NoSync fields so
each client picks its own tier without disturbing peers.
SkyPreset and DEFAULT_PRESET are declared by volumetricSky.module,
which this component reads its default from and which routes an option by
that same key set — so the shape below and the module's M.spawn options
are one declaration.
| Field | Type | Sync | Default | Meaning |
|---|---|---|---|---|
preset | SkyPreset table | Sync | DEFAULT_PRESET (cumulus) | All shaping / weather / lighting (see below). |
weatherRegions | table | Sync | {} | Up to 16 { x, z, radius, falloff?, coverage?, cloudType?, density? }: the weather inside each, blending into the sky around it across falloff (a share of the radius, default 0.5). |
wind | vec3 | Sync | {0,0,0} | How far the wind has carried the clouds, in world units (advanced per frame from preset.windSpeed). |
stepSize | number | NoSync | 10 | The shortest ray step, in world units; steps grow with distance. |
maxSteps | number | NoSync | 128 | Ray-march step cap. |
shadowSteps | number | NoSync | 4 | Samples toward the sun for each lit sample. |
maxDistance | number | NoSync | 80000 | How far out each ray is marched; the layer thins into the horizon's haze over its last part. |
alphaCutoff | number | NoSync | 0.99 | Early-exit α threshold. |
jitter | number | NoSync | 1.0 | Ray-origin jitter strength. |
renderScale | number | NoSync | 2 | The layer renders at the target size divided by this. |
taaBlendAlpha | number | NoSync | 0.1 | TAA current-sample weight. |
targetWidth | number | NoSync | 0 | Render target width (0 = the width of the view the scene is drawn into). |
targetHeight | number | NoSync | 0 | Render target height (0 = the view's height). |
quality | string | NoSync | "auto" | The level the knobs above are traced at: auto follows the device's quality tier, high traces them as stated, medium and low a coarser layer with a share of the steps (below). |
shaderVariant, cloudSize, cloudHeight, noiseRegenRate | NoSync | Fields an earlier cloud layer read; a scene stored with them still loads, and the layer reads nothing from them. |
Preset (SkyPreset) shape
Weather: coverage (how much of the sky the clouds cover, 0..1),
cloudType (0 stratus, 0.5 cumulus, 1 cumulonimbus), densityGain
(extinction per world unit inside a cloud), weatherVariation (how far
coverage and type vary from place to place), weatherExtent (world units the
weather map covers before it repeats).
Cloud form, in world units whatever the layer reaches: shapeScale (one tile
of the shape noise; a cloud is about a quarter of it), detailScale (one tile
of the detail noise, 0 = shapeScale / 16), detailStrength, color,
windSpeed (world units per second), seed.
The layer: cloudBaseAltitude, cloudTopAltitude, altitudes over the ground
(PhysicalAtmosphere's groundLevelY), over a planet of the radius the
physical atmosphere integrates over.
Look (visual, not perf): phaseG.
Sun / sky: sunColor, sunIntensity, horizonColor, zenithColor, groundColor, ambient. The clouds are lit by the scene's own sun every frame: the sun's
direction, its colour, and its intensity up to a unit sun, which scales these
too, so a night leaves the clouds dark and a sun at zero leaves them black.
With a PhysicalAtmosphere in the scene the sun is the atmosphere's, reaching
each cloud through the air (gold and red as it sinks), the sky around the
clouds is the sky the atmosphere draws in place of horizonColor,
zenithColor and groundColor, and ambient states how strongly that sky
lights the clouds, as the share it holds of horizonColor and zenithColor;
sunColor and sunIntensity are then the tint and brightness of a high sun.
sunDir is deprecated and kept so a stored preset still loads.
A stored preset or a caller stating a key an earlier cloud layer read
(noiseScale, octaves, altitudeLow, altitudeHigh, anvilBias,
detailOctaves, detailThreshold, baseLowRemap, baseHighRemap,
worleyBlend, horizExtent, sunDiscSize) still loads and configures the
sky; the layer reads nothing from them.
See presets/cumulus_default.preset/preset.yaml for the canonical
full preset shape, and the module's DEFAULT_PRESET table for
the runtime defaults.
Where the frame time goes
-
The fills are one-off. The tiling noise (
cloud_noise, a 128^3 and a 64^3 RGBA8 texture) is filled once per render device; the weather map (cloud_weather, 256x256) again when the weather changes, a fraction of a millisecond. Coverage, cloud type,weatherRegionsand the wind refill no noise: the wind moves the clouds through the world by an offset.volumetricSky.volumeBakes()andweatherBakes()count the fills. -
The raymarch (
cloud_raymarch) runs for every view of every frame.maxSteps,shadowSteps,renderScale,maxDistance,stepSizeandtargetWidth/targetHeightset its cost, at the quality level in force:level renderScalemaxStepsshadowStepsstepSizehighas stated (2) all (128) all (4) as stated (10) mediumx1.5 (3) 75 % (96) 75 % (3) x1.25 (12.5) lowx2 (4) 50 % (64) 50 % (2) x1.5 (15) Under
autoa desktop's or a browser's high tier traceshigh, a handheld's high tier and every medium tiermedium, and the low tierlow(renderer.qualityTier());renderer.setQualityTiermoves it on the next frame the sky packs.volumetricSky.drawnLevel()reads the level in force and what the raymarch traces at it; thegraphics-qualityguide lists what each level costs.
profiler.gpuFrame() reports each as a compute.<shader> span.
Field-mutation gotcha (and why update() reassigns the whole vec3)
Under the new Field<T> / Sync / NoSync schema, public is not a
plain Lua table — it's wrapped in a proxy whose __newindex
metamethod performs type-checks, marks the field dirty, and queues
Sync replication. Writing public.wind = {x,y,z} triggers all four
steps. Writing public.wind[1] = x reads public.wind (getter),
mutates the returned table directly, and bypasses the setter —
no Sync replication, no dirty flag, no onPropertyChanged. Always
assign the whole vec3 / preset / color table; never index-mutate.
The same caveat applies to public.preset: public.preset.coverage = 0.2
won't replicate. To change one preset field, copy the table, mutate,
reassign:
local p = public.preset
local next = {}
for k, v in pairs(p) do next[k] = v end
next.coverage = 0.2
public.preset = next
Lifecycle
awake/onEnable: hold the cloud layer up (volumetricSky.holdLayer), which brings up the render feature that runs the layer's passes.update(dt): advanceswind(readingpreset.windSpeed), hands the weather tovolumetricSky.fillClouds, which fills the noise once and the weather map when the weather moved (see "Where the frame time goes"), then queues the raymarch dispatch for the frame's deferred phase.editorUpdate(dt): the same fill and dispatch in edit mode, so the editor viewport, an edit-mode capture and a probe baked in edit mode show the clouds. The wind stands where the scene holds it; drift runs in play.onDisable/onDestroy: let go of the layer (volumetricSky.releaseLayer). When the last sky lets go, the render feature comes down andM.destroyreleases the noise, the weather map, the render targets and the programs, so the next frame is drawn with no cloud layer and no cloud pass runs.onModuleReload(path): a reload ofvolumetricSky.modulestarts it with no holders, so a sky holding the layer holds it again on the reloaded module.
The layer is one per engine: every sky standing holds it, and it comes down with the last one.
Why the raymarch is dispatched from task.defer
The raymarch produces ONE full-screen layer for ONE view, and the frame
composites it over everything that frame drew — so it has to be rendered
from the view the frame ends up drawn with. Which view that is settles
only once the frame's script work is finished: a cutscene walking the
camera from a task loop, a camera controller, a component ordered after
this one, an editor tool — each writes the camera after update has
run, while the renderer reads the camera once all of them are done.
Taking the camera snapshot in the deferred phase reads what every one of
them has already written, and still queues the dispatch ahead of the
frame's render. Snapshotting in update instead renders the layer for
whatever the camera was midway through the frame; on a hard cut that is
a different place entirely, and the frame the cut lands on composites a
cloud layer belonging to the shot it just left.
A caller driving volumetricSky.dispatchRaymarch directly owes the same
discipline.
Related
volumetricSky.module— orchestration backend.presets/cumulus_default.preset— canonical full preset; copy to author named weather (storm, overcast, dawn, …).Volume.component— per-entity flow for non-cloud volumetric content.demo/sky.scene— worked example.