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.

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).

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

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.

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

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