# Clouds

How to put clouds in a scene's sky and shape them: the fields, what each one draws, recipes to copy, what it costs and
what it cannot do. Written for whoever composes a sky, a person or an agent. The engine side (how the clouds are built
and drawn, and how to add a new form) is docs/status/hd-clouds-sculpted.md.

## The short version

Clouds are one layer over an `atmosphere` sky, at `meta.environment.sky.clouds`. The HD renderer draws it.

```json
"sky": { "kind": "atmosphere", "intensity": 1, "rotation": 0,
         "clouds": { "preset": "broken", "style": "sculpted" } }
```

- No `clouds` block: a clear sky. On any other sky kind the block is ignored with the warning
  `render-clouds-without-atmosphere`.
- Every field is optional. Start from a `preset`, then change one number at a time.
- An agent writes the block with `scene.patch` (docs/AGENT.md) like any other scene setting. A value outside its range
  is refused with `sky-value-range`, naming the field and the range.
- Everyone in a session gets the same clouds in the same places. They drift with the simulation clock, so a paused
  game holds them still and a recording plays them back as they were.

## Two styles

| `style` | What it draws | Use it for |
|---|---|---|
| `noise` (default) | Clouds cut out of drifting noise: soft banks that fill the whole layer. | Skies seen from the ground; closed, grey weather (`overcast`, `storm`). The cheaper one. |
| `sculpted` | Built forms: a rolling deck with breaks, cumulus piles, towers with anvils. Lumps ride on every surface. | A camera that leaves the ground: flying over, past and beside clouds. Fair and broken skies. |

The other fields mean the same in both. Choose `noise` for `overcast` and `storm`: the sculpted style is not tuned for
closed decks and draws them as flat grey from below.

## The layer

| Field | Range | What it does |
|---|---|---|
| `preset` | `clear`, `fair`, `broken`, `overcast`, `storm` | The starting point for every number below. Default `fair`. |
| `style` | `noise`, `sculpted` | See above. Default `noise`. |
| `coverage` | 0..1 | Share of the sky that holds cloud. In the sculpted style it is where anything stands: a pile or a tower is there only where the cover reaches. |
| `altitudeM` | 0..20000 | Height of the cloud base over the ground, metres. |
| `thicknessM` | 100..10000 | Depth of the layer, metres. In the sculpted style it is the towers' ceiling. |
| `density` | 0..10 | Scale on the preset's density: higher is darker undersides and deeper shadows. |
| `windSpeedMps`, `windDirectionRad` | 0..100, any | How fast and which way the clouds drift. |
| `shadowStrength` | 0..1 | How much of the clouds' shadow reaches the ground. 1 is physical. |
| `forms` | object | What a sculpted layer is built of. Next section. |

What the presets give:

| `preset` | coverage | base, thickness (m) | Sculpted style builds |
|---|---|---|---|
| `clear` | 0.2 | 1500, 1500 | A few cumulus standing alone. |
| `fair` | 0.4 | 1500, 2000 | Cumulus standing alone, no towers. |
| `broken` | 0.65 | 1200, 2500 | A deck with breaks, a cumulus mound here and there on it, and two or three towers in 40 km. |
| `overcast` | 0.95 | 800, 1500 | A closed deck, few cumulus, no towers. Prefer `noise`. |
| `storm` | 1.0 | 350, 4500 | A closed deck with towers. Prefer `noise`. |

## Forms: composing your own sculpted sky

`forms` is read only with `"style": "sculpted"`. Each field replaces what the preset would have built; leave one out
and the preset's stays.

| Field | Range | Default | What it does |
|---|---|---|---|
| `deck` | 0..1 | 1 for `broken`, `overcast`, `storm`; about 0 for `fair`, `clear` | How much of a deck there is. 0: cumulus and towers stand alone, with flat bases. 1: a whole rolling deck, broken where `coverage` runs out. |
| `cumulus` | 0..1 | 0.42 (`clear`), about 0.36 (`fair`), about 0.1 on a deck (`broken`, `storm`, `overcast`) | Share of the 1.7 km grid cells that hold a cumulus pile. Most piles are small; a few are three times as wide. On a deck the default is a third of what stands alone: a deck is its own banks. |
| `towers` | 0..1 | 0.12 for `broken` and `storm`, else 0 | Share of the 8 km grid cells that hold a tower. 0.12 is two or three towers in 40 km; 1 is a tower in every cell. |
| `anvils` | 0..1 | 0.3 | Share of the tall towers that spread into an anvil. |
| `towerHeight` | 0.5..1.5 | 1 | Scale on the towers' height (2.2 to 3.5 km over the base at 1). `thicknessM` caps it: raise the layer for taller towers. |
| `lumps` | 0..1 | 1 | How much cauliflower relief is raised on every surface. 0 is the smooth built forms. |
| `seed` | 0..65535, whole | 0 | Which sky. Another seed moves the deck's banks and breaks and every pile and tower, and builds each another way. The same seed is the same sky. |

How they work together:

- `coverage` decides where. A pile or a tower stands where the cover reaches at its own middle, so a low `coverage`
  thins out everything, and the deck opens into breaks.
- `deck`, `cumulus` and `towers` decide what stands there. They are independent: a deck with nothing on it, towers with
  no deck, or all three.
- No two towers are built alike: each has its own width, taper, lean and side turrets. `seed` picks which set you get.
- A sky repeats every 40 km.
- A deck opens only where `coverage` runs out, in breaks. Inside covered sky it has a floor: no small holes.

## Recipes

Each is the whole `clouds` block. All use the sculpted style.

**A broken deck with towers, for flying over.** The layer the engine's own flight footage uses.

```json
{ "preset": "broken", "style": "sculpted", "coverage": 0.64, "altitudeM": 1500, "thicknessM": 3600, "density": 0.8 }
```

**Fair-weather cumulus, seen from the ground.**

```json
{ "preset": "fair", "style": "sculpted", "coverage": 0.6 }
```

**A rolling deck and nothing else.** No towers, few piles: a sea of cloud to fly over.

```json
{ "preset": "broken", "style": "sculpted", "coverage": 0.85, "altitudeM": 1500, "thicknessM": 3600, "density": 0.8,
  "forms": { "towers": 0, "cumulus": 0.05 } }
```

**A field of towers with no deck.** Tall cumulus standing on open air, half of them with anvils.

```json
{ "preset": "broken", "style": "sculpted", "coverage": 0.7, "altitudeM": 1200, "thicknessM": 4500, "density": 0.8,
  "forms": { "deck": 0, "cumulus": 0.15, "towers": 0.8, "anvils": 0.5 } }
```

**A crowded cumulus sky.** A pile in every cell, no deck, no towers.

```json
{ "preset": "fair", "style": "sculpted", "coverage": 0.8, "forms": { "deck": 0, "cumulus": 1, "towers": 0 } }
```

**Low turrets on a deck.** Many short towers and no anvils: a bubbling deck.

```json
{ "preset": "broken", "style": "sculpted", "coverage": 0.7, "altitudeM": 1500, "thicknessM": 3600, "density": 0.8,
  "forms": { "towers": 0.7, "towerHeight": 0.6, "anvils": 0 } }
```

**Smooth, stylised forms.** The same sky with the lumps nearly off.

```json
{ "preset": "broken", "style": "sculpted", "coverage": 0.64, "altitudeM": 1500, "thicknessM": 3600, "density": 0.8,
  "forms": { "lumps": 0.2 } }
```

**Another sky with the same weather.** Change only the seed.

```json
{ "preset": "broken", "style": "sculpted", "coverage": 0.64, "altitudeM": 1500, "thicknessM": 3600, "density": 0.8,
  "forms": { "seed": 7 } }
```

To design a sky: pick the nearest recipe, set `seed` until the towers stand where the shot wants them, then move
`coverage` for more or fewer breaks.

## How finely it is drawn (render quality)

These are quality settings, per machine, not part of the scene (docs/SKY.md, "Sculpted clouds"). They trade speed for
detail and change nothing about which clouds there are.

| Knob | Range | Effect |
|---|---|---|
| `clouds.resolution` | `quarter`, `half`, `full` | The biggest lever on cost. |
| `clouds.steps` | 16..128 | How finely each ray is walked: sharper edges for more cost. |
| `clouds.detail` | true, false | Steadier, finer clouds in motion. |
| `clouds.sharpness` | 0.5..2 | Sculpted only. How solid a cloud is drawn: 2 is crisp, hard-edged forms, 0.5 soft and deep. Free. |
| `clouds.fineDetail` | 0..1 | Sculpted only. The smallest lumps; 0 is a little faster. |

Measured on an RTX 3080 at 1920x1080, all cloud passes together, for the broken deck recipe from three views:

| Preset | Sculpted | Noise |
|---|---|---|
| Low | 0.24 to 0.51 ms | 0.09 to 0.17 ms |
| Medium | 0.32 to 0.69 ms | |
| High | 1.1 to 2.1 ms | 0.40 to 0.75 ms |
| Ultra | 1.3 to 2.7 ms | 0.53 to 1.81 ms |

The sculpted forms are baked once into two small volumes (14 MB of GPU memory). They are baked again when the layer's
`coverage`, `preset`, `thicknessM`, wind direction or any of `forms` but `lumps` changes, or when the sun or moon
turns. So set a sky and leave it: do not change `forms` every frame.

## How a sculpted cloud is drawn

Nothing here is a setting; it is what to expect in the picture.

- **Soft, not solid.** A cloud's edge is a shell about 35 m deep that the eye sees into, frayed by fine noise, so
  outlines are soft and thin parts glow against the light. `clouds.sharpness` sets how far in: at 2 a cloud is a crisp
  solid, at 0.5 softer still.
- **Haze between the clouds.** The air inside a cloud layer is hazy: a cloud 10 km off has lost about 40% of its
  contrast to the sky's colour, one 30 km off about 80%. Far towers stand as pale shapes, as they do from an aircraft.
- **Gentle shade.** The creases between lumps are shaded, not black; the big shadows come from the key light: the side
  of a bank away from a low sun or moon, the deck behind a tower. On a shaded face each lump is still modelled: its
  side toward the open sky is lighter than its lee.

## What it cannot do

- **Fly through a cloud.** Inside one the view is a flat haze. Over, past and beside is what it draws.
- **Storms and closed overcast in the sculpted style.** Use `noise` for those.
- **More than one layer.** There are no high cirrus above a cumulus deck.
- **Rain, lightning or fog banks.** None come with the clouds.
- **Close-up surfaces.** Within a few hundred metres a cloud's own shape goes soft; the lumps carry the near detail.
- **From the ground**, the sculpted cumulus have smooth undersides. They read best low in the frame or from the air.