Log inGet started
Package

VolumetricSky.component

Newest version

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.

FieldTypeSyncDefaultMeaning
presetSkyPreset tableSyncDEFAULT_PRESET (cumulus)All shaping / weather / lighting (see below).
weatherRegionstableSync{}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).
windvec3Sync{0,0,0}How far the wind has carried the clouds, in world units (advanced per frame from preset.windSpeed).
stepSizenumberNoSync10The shortest ray step, in world units; steps grow with distance.
maxStepsnumberNoSync128Ray-march step cap.
shadowStepsnumberNoSync4Samples toward the sun for each lit sample.
maxDistancenumberNoSync80000How far out each ray is marched; the layer thins into the horizon's haze over its last part.
alphaCutoffnumberNoSync0.99Early-exit α threshold.
jitternumberNoSync1.0Ray-origin jitter strength.
renderScalenumberNoSync2The layer renders at the target size divided by this.
taaBlendAlphanumberNoSync0.1TAA current-sample weight.
targetWidthnumberNoSync0Render target width (0 = the width of the view the scene is drawn into).
targetHeightnumberNoSync0Render target height (0 = the view's height).
qualitystringNoSync"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, noiseRegenRateNoSyncFields 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, weatherRegions and the wind refill no noise: the wind moves the clouds through the world by an offset. volumetricSky.volumeBakes() and weatherBakes() count the fills.

  • The raymarch (cloud_raymarch) runs for every view of every frame. maxSteps, shadowSteps, renderScale, maxDistance, stepSize and targetWidth / targetHeight set its cost, at the quality level in force:

    levelrenderScalemaxStepsshadowStepsstepSize
    highas 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 auto a desktop's or a browser's high tier traces high, a handheld's high tier and every medium tier medium, and the low tier low (renderer.qualityTier()); renderer.setQualityTier moves it on the next frame the sky packs. volumetricSky.drawnLevel() reads the level in force and what the raymarch traces at it; the graphics-quality guide 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): advances wind (reading preset.windSpeed), hands the weather to volumetricSky.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 and M.destroy releases 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 of volumetricSky.module starts 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.