# A world look that follows a number (world.atmosphere)

This guide goes deeper than the overview in [Environment of your world](guide:world-environment).

## What it is for

`world.atmosphere` makes the look of the world follow a number. The sky, the sun, the light, the grass and the weather glide
from one phase to the next as a variable of the game grows: a dead planet that turns blue and green as it is terraformed, a
land that darkens with corruption, a city that browns with pollution, a season that turns. The kit does not know what the
number means; it can be any variable, such as a `world.stages` counter, a score or the day count. It writes the look through
`world.lighting`, `world.grass` and `world.weather`, and tints whatever hour `world.daynight` shows.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "world.atmosphere" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "world.atmosphere",
                              config: { "driver": "counter.habitability", "smoothing": 4 } }
```

It requires `world.lighting` and `game.engine`. With `world.daynight`, set its `driveLighting` to `false` so that only this kit
writes the sky.

## First example

<!-- test: kits/game_engine/host/tests/world_atmosphere.rs::the_lighting_follows_the_driver -->
With the default phases and `smoothing` 0, the variable `counter.habitability` starts at 0: `atmosphere.phase` reads `Dead` and
the sky color of `world.lighting` is `#b0623f`. Once `counter.habitability` is set to 1000 and the game has run a few ticks,
`atmosphere.phase` reads `Alive` and the sky color is `#6fa9e6`.

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `driver` | string | `counter.habitability` | path of the numeric variable the look follows |
| `phases` | list of 1 to 16 | rust-colored dead world turning blue (at 0, 100, 400, 1000) | the looks along the way, by driver value |
| `smoothing` | number 0 to 600 | `6` | seconds the look takes to catch up with a jump of the driver |

A phase is `{ at, name?, skyColor?, skyAmount?, sunColor?, sunIntensity?, fillIntensity?, exposure?, grass?, weather? }`; only
`at` is required, and a phase names only what it changes.

| Field | Meaning |
|---|---|
| `at` | driver value where this look is fully reached |
| `skyColor`, `skyAmount` | sky color `#rrggbb`; `skyAmount` 0 to 1 says how much the visible sky takes it (1 by default) |
| `sunColor`, `sunIntensity` | sun light; intensity is a multiplier 0 to 4 |
| `fillIntensity`, `exposure` | multipliers on the sky fill light (0 to 4) and on exposure (0.2 to 3) |
| `grass` | share of the meadow that shows, 0 to 1 |
| `weather` | a `world.weather` preset set once when the driver enters the phase |

```json
{ "driver": "counter.habitability", "phases": [
  { "at": 0,    "name": "Dead",     "skyColor": "#b0623f", "sunColor": "#ffb38a", "grass": 0 },
  { "at": 400,  "name": "Clearing", "skyColor": "#93b6d6", "grass": 0.5, "weather": "rain" },
  { "at": 1000, "name": "Alive",    "skyColor": "#6fa9e6", "sunColor": "#fff6e6", "grass": 1 } ] }
```

## Services, events, variables

- `world.atmosphere` (service): `value()`; `phase()` returns `{ index, name, progress }`; `look()` is the blended look now;
  `sky()` is the visible sky `{ color, amount }` read by the renderer; `set(value | null)` holds the look at a value, or follows
  the driver again; `phases()`.
- `set_atmosphere` (action): `{ value }` holds the look (a cutscene, a dream); without a value, the driver is followed again.
  The held value is saved.
- `atmosphere.phase` (event): `{ index, name, value }` when the driver crosses into another phase (not for the first look
  after a start or a load).
- Variables: `atmosphere.phase` (phase name) and `atmosphere.value` (smoothed driver value).

## Hooks and modding

The hook `atmosphere.enter` is asked when the driver enters a phase, with `{ index, name, from, value, weather, seconds }`
(`from` is the phase left, -1 for the first look after a start or a load). `weather` and `seconds` (its fade) are mutable. It is
not cancellable: the look follows the driver, so hold it with `set` or `set_atmosphere`.

```json
{ "id": "snow_not_rain", "hook": "atmosphere.enter", "match": { "name": "Clearing" }, "set": { "weather": "snow" } }
```

A mod can override `driver`, `phases` and `smoothing`.

## Engines

The behaviour is one shared implementation for the web and native players; each engine shows the light, sky, grass and weather
that the other world kits produce.

## When it does not do what you expect

- The sky ignores the clock, or flickers: both `world.daynight` and this kit write the sky; set `driveLighting` to `false`.
- Nothing changes: the `driver` variable does not exist or never changes; check its path.
- The look lags behind: raise or lower `smoothing`.

## Limits

One driver at a time, up to 16 phases. The kit builds no weather or grass itself.

## Versions

Kit `world.atmosphere` 1.1.0 (the `atmosphere.enter` hook since 1.1.0), requires `world.lighting@^1` and `game.engine@^1`.