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

This guide goes deeper than the overview in Environment of your world.

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 #

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 #

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.

{ "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.

{ "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.