# Weather in your game (world.weather)

## What it is for

`world.weather` holds the current weather without any interface of its own: six presets (`clear`, `snow`, `blizzard`, `rain`,
`storm`, `fog`) that fade into each other, an optional cycle, rules that set the weather from the state of the game, gusts of
wind, snow cover and wetness that build up and fade, lightning, and an optional cold exposure for players near warmth sources.
Other kits read it: vehicles multiply their grip by `traction`, enemy perception can scale with `visibility`. The renderer draws
the falling snow or rain, fog and flashes. It is part of the environment kits: see [Environment of your world](guide:world-environment).

## Turn it on

Install `world.weather` (it requires `game.engine@^1`) and choose the starting weather in its config, or in a scene through
`layers["world.weather"]` (a `preset` there is applied at once on entry).

```json
{ "preset": "snow", "intensity": 0.7, "cycle": true, "cyclePresets": ["clear", "snow", "blizzard", "fog"], "cycleMinutes": 6 }
```

## First example

<!-- test: kits/game_engine/host/tests/world_weather.rs::a_weather_fades_into_the_next -->
With the default config the game starts in `snow`. Calling `set("rain", 1)` fades the weather over one second: halfway,
`snapshot()` answers `preset: "rain"`, `from: "snow"` and `blend: 0.5`; once done the `blend` is `1`, `precipitation` is `"rain"`
and `wetness` is above 0. `set("lava")` is refused, the live setting `intensity` is clamped to `1`, and a save then a load keeps
the rain.

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `preset` | string | `snow` | Weather at start. |
| `intensity` | number | `0.7` | Scales precipitation, wind and fog (0 to 1). |
| `cycle` | boolean | `false` | Pick a new weather from `cyclePresets` every `cycleMinutes`. |
| `cyclePresets` | list | `clear, snow, blizzard, fog` | Presets the cycle draws from (1 to 6). |
| `cycleMinutes` | number | `6` | Minutes between two draws. |
| `transitionSeconds` | number | `20` | Duration of a fade. |
| `windDirection` | number | `30` | Degrees from +Z towards +X. |
| `gusts` | number | `0.4` | Random gust strength on top of the preset wind. |
| `accumulation` | number | `0.5` | How fast snow covers the ground. |
| `slippery` | number | `0.45` | Grip lost on full snow cover or heavy rain (0 to 0.9). |
| `fogVisibility` | boolean | `true` | Fog and blizzard lower the visibility. |
| `cold` | boolean | `false` | Players freeze in snow and blizzard. |
| `coldRate` | number | `1` | Multiplier of the cold gained per second. |
| `warmthTag` | string | `warmth` | Entities with this tag warm what is within `warmthRadius`. |
| `warmthRadius` | number | `6` | Metres around a warm entity. |
| `rules` | list | `[]` | Weather on conditions (up to 32). |

A rule is `{ when, preset, priority?, minSeconds? }`. Rules are checked four times a second: the rule with the highest
`priority` that holds sets its preset (with `transitionSeconds`, a tie going to the first) and keeps it for at least
`minSeconds`. While a rule holds, the cycle waits; with no rule holding, the cycle or the fixed `preset` applies again.

```json
{ "when": { "type": "counter_between", "counter": "pressure", "min": 60, "max": 200 }, "preset": "rain" }
```

## Services, events, variables

- `world.weather` (service): `snapshot()` (`preset`, `from`, `blend`, `precipitation`, `rate`, `wind`, `fog`, `overcast`,
  `snowCover`, `wetness`, `visibility`, `lightning`), `set(preset, seconds?)`, `traction(pos?)` (`1 - slippery x max(snow cover,
  wetness x 0.6)`, never below `0.1`), `exposure(entity)`, `addWarmth(source)`, `removeWarmth(id)`.
- `world.weather.settings` (service): `keys()`, `get(key)`, `set(key, value)`; the only key is `intensity`, and
  `world.bindings` can drive it from a variable.
- `weather.changed` (event): `{ from, to, seconds }` when a new weather starts fading in.
- `weather.lightning` (event): `{ count }`, a flash during a storm.
- `weather.cold` (event): `{ entity, exposure, level }` when a player crosses 0.5, 0.8 or 1 (`chilled`, `freezing`, `frozen`) or
  drops under 0.2 (`warm`). The consequence (damage, slowdown, an overlay) is for another kit.

A warmth source is `{ id, position, radius }`, from the `warmth_sources` collection or added with `addWarmth`.

## Hooks and modding

The hook `weather.change` runs before every change with `{ from, to, seconds, cause }` (`cause`: `set`, `cycle`, `rule` or
`scene`). `to` and `seconds` are mutable; cancelling keeps the weather.

```json
{ "id": "no_blizzard", "hook": "weather.change", "match": { "to": "blizzard" }, "set": { "to": "snow" } }
```

A mod can override every config key above, and change the `warmth_sources` collection and the setting `intensity`.

## Engines

The web player and the Rust host run the same simulation. Godot, Unity and Unreal deliveries draw the particles, fog, flashes and
snow or wet surfaces natively; they do not evaluate `rules` or run the hook yet.

## When it does not do what you expect

- `set` fails with `Unknown weather: <name>`: use one of the six presets.
- `addWarmth` fails with `Invalid warmth source` or `Warmth source limit exceeded`.
- `exposure(entity)` stays at 0: `cold` is off.
- The weather keeps going back: a rule holds, or the cycle is on.

## Limits

The kit draws nothing itself and applies no cold damage. The save keeps the weather, fade, cycle timer, snow cover, wetness, cold
exposure, added warmth sources, gusts and the random stream, so a loaded game continues as the saved one would.

## Versions

Kit 1.5.1, service `world.weather` 1.1.0. Rules since 1.4.0, the hook since 1.5.0, and the saved `intensity` setting since 1.5.1.