---
name: threejs-volumetric-clouds
description: Build volumetric clouds in Three.js WebGPU/TSL. Use for weather-shaped density, bounded cloud raymarching, cloud optical-depth shadows, cloud-specific temporal reconstruction, or causal cloud precipitation emission.
---

# Volumetric Clouds

Build a bounded volume whose broad mass comes from weather-scale causes, whose
fine detail erodes that mass, and whose optical, shadow, and temporal errors are
measurable.

## Process

### 1. Select the claim and workload branches

State the claim first. Procedural weather, coverage, shape, and detail usually
form an authored appearance model. Beer-Lambert attenuation is physical for the
declared density and coefficients. Dual-lobe phase fits, octave
multiple-scattering compensation, powder, and simple ground bounce remain
approximations until validated against a transport reference.

Select each independent workload branch:

| Decision | Select | Evidence |
| --- | --- | --- |
| Local versus broad | full-resolution scissored march for a small projected bound; reduced-resolution march for broad coverage | complete-branch GPU cost and image error |
| Full versus reduced current grid | full current grid for low reuse; reduced grid plus reconstruction for coherent broad clouds | current-sample, bandwidth, and reconstruction error |
| Dense versus sparse | bounded adaptive march for dense occupancy; conservative macrocell DDA for sparse occupancy | saved samples exceed hierarchy build/traversal cost |
| Receiver shadow | none when no external receiver queries cloud shadow; full-column 2D optical depth for ground/opaque receivers; short sun march or depth-aware light product for in-cloud samples | admitted receiver query and transmittance error |
| Precipitation | appearance-only cues; or causal liquid/ice emission consumed by `$threejs-rain-snow-and-wet-surfaces` | dimensioned emission, support, transport delay, and conservation error |

For causal precipitation, publish liquid and ice mass flux in `kg m^-2 s^-1`,
or interval-integrated areal mass in `kg m^-2`, explicitly identified with its
sample time, sample interval, physics frame/origin, physical support,
area/Jacobian convention, fall delay or transport model, owner, contract
version, generation, validity, conservation gate, and error. Publish each
interval once to `$threejs-rain-snow-and-wet-surfaces`. The receiver converts
flux to interval mass once, preserves the declared support/Jacobian, and applies
the declared delay or transport before accumulation.

A density/emission recipe, incompatible physics frame/origin mapping,
support/Jacobian convention, or delay model change starts a new generation.
The receiver rejects stale or incompatible generations and never reinterprets
prior interval mass. An appearance-only branch remains visual-only and
publishes no receiver input.

Allocate no receiver-shadow product for the `none` branch.

**Complete when:** all five decisions name the selected representation and its
observable; every admitted workload has a falsifiable cost or error gate; a
`none` receiver-shadow branch records no receiver consumer and zero allocation;
appearance-only precipitation publishes no receiver input; causal precipitation
has one dimensioned generation accepted by one compatible consumer.

### 2. Define one optical and motion model

Choose dimensionless shape density with `beta_s` and `beta_a` in
`length^-1`, or physical mass density with mass-specific coefficients. Keep
the convention end to end:

In the equations below, beta names the coefficient matched to rho: inverse
length for shape density, or area per mass for physical mass density.

```text
sigma_s = rho * beta_s
sigma_a = rho * beta_a
sigma_t = sigma_s + sigma_a
tau = integral sigma_t ds
T_step = exp(-sigma_t*ds)
DeltaL = T_acc * (j/sigma_t) * (1-T_step)
```

Use the zero-extinction limit `DeltaL = T_acc*j*ds`. Here `j` is source
radiance per length. For direct light, distinguish finite-disc radiance, which
needs a solid-angle integral, from a declared collimated irradiance convention.

Normalize phase so `2*pi*integral_-1^1 p(mu)dmu=1`. Let
`rayDirection` point camera-to-sample and `toSun` sample-to-sun; then
`mu=dot(toSun,rayDirection)` makes `mu=1` forward scattering. Keep
dual-lobe weights nonnegative with unit sum.

Define one physics/render frame conversion, one metre scale, one cloud state
clock, and one macro air velocity. Integrate velocity over elapsed simulation
time; treat relative weather/shape/detail motion as bounded offsets from that
macro advection.

**Complete when:** a homogeneous slab is invariant to step partition and
reaches the zero-extinction limit, phase quadrature normalizes with the expected
forward direction, and two update cadences integrate the same motion trace
within tolerance.

### 3. Build bounded, conservative density

Keep active layers separate through altitude/profile, weather, shape, optical
properties, and motion. Let a low-frequency weather field and compact vertical
profile establish cloud mass. Apply shape at resolvable scales. Use detail as
height-dependent erosion; it may roughen occupied boundaries but must preserve
the weather/base-shape empty set used by the conservative bound.

Integrate one macro offset and add bounded relative offsets:

```text
macroOffset += integral u_air(t) dt
weatherOffset = macroOffset + relativeWeatherOffset
shapeOffset   = macroOffset + relativeShapeOffset
detailOffset  = macroOffset + relativeDetailOffset
```

Intersect rays with the selected spherical shell, slab, OBB, or sparse-volume
domain, then clamp the far end to the nearest opaque scene depth. Merge occupied
altitude ranges and skip only their complementary gaps. For horizontal
sparsity, build max-density macrocells that include weather, profiles, shape,
warp reach, and every density-increasing operation. Average mips are appearance
filters, not occupancy bounds.

Read [references/density-and-marching.md](references/density-and-marching.md)
for density equations, domain intersections, conservative skipping bounds, and
step selection.

**Complete when:** a debug view proves every skipped interval/cell is empty or
inside the declared omitted-radiance bound, and brute-force versus accelerated
marches agree on transmittance, HDR radiance, and first-contribution depth.

### 4. March and light the selected representation

Write current scene-linear cloud radiance, transmittance, and the depth data
needed by the selected temporal branch. Bound steps by optical depth, resolved
field bandwidth, cell/layer exits, opaque depth, and the remaining cloud
interval. Terminate when the maximum remaining HDR contribution fits the output
error gate.

On Three.js r185, run `await renderer.init()` and require
`renderer.backend.isWebGPUBackend === true` before allocating or submitting
compute/storage work. Then submit `Fn().compute(count)` through
`renderer.compute()`. Use `StorageTexture` for 2D current/history/shadow
products and `Storage3DTexture` only for writable volume fields. Treat
`computeAsync()` as enqueueing rather than a completion fence. A
`PassNode.setResolutionScale()` scales the whole pass, so keep the host scene
at its required resolution and place reduced clouds in their own pass/resources.

Compute cloud self-shadowing from cloud optical depth only. A ground receiver
can use the full sun-ray column. An in-cloud sample needs optical depth from its
own position, supplied by a short sun march, deep-opacity slices, or another
depth-aware representation.

Read
[references/lighting-and-shadows.md](references/lighting-and-shadows.md)
when the task includes scattering, atmosphere-derived light, phase fitting,
cloud shadows, or shadow filtering.

**Complete when:** step-halving and higher-light-sample controls fit the linear
HDR error gate, the cloud-off control returns unit transmittance and zero cloud
radiance, and each admitted shadow query decodes optical depth from its actual
receiver position.

### 5. Reconstruct broad clouds

For a reduced broad-coverage branch, store opacity-weighted representative
depth and depth spread:

```text
w_i = T_i * (1-T_step_i)
z_bar = sum(w_i*s_i)/sum(w_i)
variance_z = sum(w_i*(s_i-z_bar)^2)/sum(w_i)
```

Use one representative surface only for a unimodal contribution distribution.
Use front depth plus moments or split histories for broad/multiple layers.
Reproject an advected representative physical point into the previous camera.
Record immutable current-render-to-physics and
previous-physics-to-render transforms; map through them across an origin
rebase. Host surface velocity is a different signal.

Blend with frame-rate-independent current response:

```text
alpha_current = 1-exp(-dt/responseTime)
resolved = alpha_current*current + (1-alpha_current)*clippedHistory
```

Reject history outside the viewport or across depth/spread mismatch, camera
cuts, projection changes, weather/topology discontinuities, encoding changes,
resolution/tier changes, or a missing/incompatible previous origin mapping.
Raise current response for disocclusion and low confidence. Variance-clip
premultiplied linear HDR radiance and transmittance separately, then upsample
with scene/cloud depth agreement.

Read
[references/temporal-reconstruction.md](references/temporal-reconstruction.md)
when history, sparse phases, depth encoding, reset policy, or upsampling is in
scope.

**Complete when:** a translating-density control reprojects to the expected
previous pixel, a mapped floating-origin rebase preserves that pixel,
camera-cut/topology/incompatible-origin controls give history confidence zero,
measured ghost decay matches the response model, and depth-edge upsampling does
not cross the opaque surface.

### 6. Integrate the lighting and image handoffs

Choose one incident-light contract:

- an authored source that declares owner, revision, sample time and age, frame,
  quantity, unit, basis, direction or angular support, filter, included
  attenuation, validity, and error; or
- atmosphere lighting that declares the same tuple.

For the atmosphere branch, choose either direct light already attenuated by the
atmosphere or an unattenuated source plus atmosphere transmittance. Multiply
each admitted cloud-only transmittance and opaque-visibility factor separately.
Keep directional sky radiance distinct from hemispherical sky irradiance.

Composite clouds before the host tone map:

```text
C_out = L_cloud + T_cloud * C_scene
```

Use one `WebGPURenderer` and one host `RenderPipeline`. Write data resources
with explicit format/filter/mip policy and `NoColorSpace`. Let the host
`renderOutput()` or `outputColorTransform` own the one display conversion;
mark the pipeline dirty after replacing a diagnostic output node.

**Complete when:** the incident source has a complete contract, an attenuation
trace accounts for every admitted atmosphere, cloud, and geometry factor once,
cloud buffers remain linear HDR, and toggling clouds off returns the identical
host image path.

### 7. Verify the system

Verify:

- homogeneous-slab transfer, zero-extinction limit, and phase normalization;
- bounds, opaque-depth clamp, conservative skipping, and early-exit error;
- fixed-seed weather mass, erosion, octave filtering, and advection continuity;
- each admitted ground or in-cloud shadow decoder, cadence, and stale-product
  rejection;
- for causal precipitation, flux-to-interval integration, conserved mass under
  cadence repartition and physical-support/Jacobian area repartition, declared
  delay-to-arrival mapping, and stale-generation rejection; the appearance-only
  control publishes no receiver input;
- for each admitted temporal branch, translating density, depth encoding,
  history rejection, response time, and depth-aware upsample, including mapped
  and incompatible origin rebases;
- fixed-view HDR radiance, transmittance, silhouette, and halo against a
  higher-quality reference;
- create, GPU completion, disposal, and each admitted resize/tier-switch or
  history-reset lifecycle.

**Complete when:** every selected branch passes its numeric, temporal, visual,
and lifecycle gates, and diagnostics identify each retained density, shadow,
history, and causal-precipitation generation.

## Failure signatures

| Symptom | Inspect |
| --- | --- |
| Porous smoke or boiling | weather mass cause, detail erosion, octave filter, or shared advection |
| Brightness changes with step count | source units or transfer integration |
| Cost scales with camera far plane | volume bound or opaque-depth clamp |
| Density disappears under skipping | stale/nonconservative majorant |
| Camera-motion trails | representative depth, cloud velocity, or rejection |
| Flat/detached ground shadow | receiver representation, projection, or age |
| Color changes after cloud toggle | duplicate tone map or output transform |

## Routing boundary

This skill owns weather-shaped cloud density, bounded cloud transport,
cloud-only optical-depth shadows, and cloud-specific reconstruction. Use
`$threejs-sky-atmosphere-and-haze` for molecular/aerosol transport and the
shared sun/sky source, `$threejs-image-pipeline` for scene signals and final
output, `$threejs-rain-snow-and-wet-surfaces` for causal precipitation
transport and receiver accumulation, and `$threejs-scalable-real-time-shadows`
for opaque-geometry shadow maps.