Cloudburst: Rain, Snow, Storms and Fog for Your Game
README.md
Cloudburst: rain, snow, storms and fog for your game
Weather that reads as weather. Not white lines on the screen: soft, see-through drops lit by your sky, your sun and your street lamps. They glint against a dark doorway and go darker against a bright sky, streak with their speed and with your own movement, crowd thick around you and turn into grey curtains down the lane before they fade into the fog.
The world answers the rain. Drops splash on the street and on the roofs, ring the pond and the puddles, drip from the eaves and the branches. The ground darkens and shines as hard as it rains, and under a roof it stays bone dry. Snow tumbles down and settles on everything that faces up, hail bounces, sleet falls as neither. Wind leans all of it and gusts come and go. Fog lies in banks in the low ground. Lightning lights the street without blinding anyone, and the thunder arrives later the further away the strike was. Step inside and the rain sounds duller.
Every player sees the same weather at the same moment: the same strike, the same change from clear to storm and back, including someone who joins in the middle of it.
Make it rain in two minutes
-
Install Cloudburst from ZeroMind into your world.
-
Add the weather to your scene, in
build.luau(or once from the console). A brand-new world has no scene yet: make one with ground, light and a player first withzero scene create --startup main playerin the shell, then openscenes/main.scene/build.luauand add these two lines before its lastend:local w = entity.spawnSynced("Weather") w.component.add("Cloudburst", { preset = "steady_rain" }) -
Press play. That's rain.
Change one word to change the weather: preset = "alpine_snow", preset = "night_storm_town".
That is the whole switch from rain to snow to a thunderstorm.
Any single setting can change while a preset runs: set rainLook = "pixel" (or snowLook,
lightning, splash, fogBank, kind, wind) and the weather keeps everything else the preset
had and changes just that, live, for every player. Or clear preset and pick a kind (clear,
cloudy, drizzle, rain, showers, downpour, thunderstorm, snow, sleet, hail, wind,
dust, leaves, ash, fog, mist) with one intensity dial from 0 to 1. A kind picked on its own comes in at its own natural
strength (rain 0.6, downpour 0.85, ...), whatever the weather before it, and while a preset runs the
fields always show the preset's own kind and looks, so picking a kind always brings that weather.
wind is a dial from 0 (still) to 1 (a gale), or
-1 for whatever the kind brings; picking a new kind brings its own wind back unless you set wind
in the same change. Changes fade in over changeSeconds. A name the kit does not know
is warned about once and falls back to clear.
From code, on any player:
local Weather = require("cloudburst.weather")
Weather.preset("night_storm_town", 30) -- fade into a storm over 30 s
Weather.set({ kind = "snow", intensity = 0.8, snowLook = "fluffy" })
Weather.cycle({ { "clear_day", 3 }, { "steady_rain", 2 }, { "night_storm_town", 4 } })
What's new in 1.5.4
- Quiet scene reloads. The atmosphere no longer calls
entity(id)on scene lights that are already gone, so a scene reload or play flip no longer logsentity(...) returned nilerrors (issue #7). The light reads checkentity.exists(id)first, the way the flash light already did. - Built on the current engine library (33551d3).
What's new in 1.5.3
- Fog banks that float as clouds.
FogBank.cloud(0-1) and the newcloudbank kind: a round, noise-ragged footprint and a puffy profile that thins toward the top and the underside, so a bank hanging in the air reads as a soft cloud from near and far instead of a pale box. Every other bank keeps its look, with its square corners now rounded.
What's new in 1.5.2
- The package's own description is current. The one-paragraph description ZeroMind shows for the package now lists all 16 kinds, 31 presets and 5 fog banks, and says how to install it and make it rain. The kit's code is the same as 1.5.1.
What's new in 1.5.1
A look pass over hail, mist and lightning, from near and far, at noon, dusk and night:
- Lightning keeps the night dark. A strike used to lift the whole scene to a flat grey: even a far one turned a night street into an overcast afternoon for a moment. A flash now tints the fog a cold blue and lifts the sky light less, so a far strike is a blue-white blink and a near one still lights the street. Daylight flashes still read.
- No hail bubbles on the lens. A hailstone falling right in front of the camera used to fill the frame as a large blurry grey ball. Stones now fade out before they reach the lens; the ones bouncing at your feet stay.
- Hail, mist and fog were checked at every distance and time of day and needed no change.
What's new in 1.5.0
- A downpour reads as a wall of rain from far away. Across a field in daylight, heavy rain and thunderstorms now stand as soft grey shafts of falling rain, darker than the sky behind them, instead of fading into flat fog. The fog in heavy rain is thinner, so the rain itself greys out the distance. Close up nothing changed, and no hard streaks came back.
- Four new kinds:
showers(passing showers that build, pour and clear on a shared loop),dust(sandstorms and dust storms that turn the air tan),leaves(autumn leaves tumbling on the wind) andash(ash falling under a dim sky). Sand, leaves and ash never settle like snow. - Eight new presets:
light_drizzle,passing_shower,tropical_monsoon,foggy_harbour,autumn_leaves,dust_storm,sandstorm,ash_fall. Each is the same one-field swap as the rest, and a newdustfog bank goes with the sandstorm. - A better default. A
Cloudburstwith nothing set now starts onsteady_rain, rain you clearly see in daylight, instead of the faintlight_spring_rain. - Pick a preset. A table below gives every preset with what it looks like and when to reach
for it, and the guides say what you should see after each step and show a storm intro that runs
once with
Weather.lastChange().
What's new in 1.4.12
Review fixes on top of 1.4.11 (docs only, no kit code changes):
lastChange()examples are safe for a player who has just joined. A joining player can run its scripts a moment before the shared weather reaches it, so the README and the how-to guide now ask again after a short wait before starting a storm, as the village example already did.- Forecasts are spelled out. The steps of a running forecast do not count as changes for
lastChange(); setting the forecast withWeather.cycledoes.
What's new in 1.4.11
Contributed back by a world that installed Cloudburst (pull request #4). 1.4.10 was never released on its own; its change ships here.
- Ask whether the weather already changed this session.
Weather.lastChange()(and the component'slastChange()) answers nil until someone changes the weather in this session, then when the change started, its fade and how far along it is. A change saved with the scene or made in edit mode before play does not count, and neither do the steps of a running forecast (setting the forecast withWeather.cycledoes). A storm intro now runs once, and a player who joins mid-storm no longer starts it over. - The village example reaches dusk without worldClockKit. Step 4 said its lamp-post code turned the scene's sun down, and it did not, so the storm came in under an afternoon sky. It now dims the starter scene's sun, ambient and sky, and gives the values for a full night.
What's new in 1.4.9
- Play and stop are quiet. Pressing play or stop prints nothing from Cloudburst. The storm
lighting no longer reaches for a scene light that is not there yet (two red "returned nil"
errors at every start), and the landing map now goes only to the shaders that read it (rain,
snow and splashes;
Weather.bindhands it to your material only when its shader declares alandmaptexture), so the curtain, mist, clouds, pond and puddle no longer warn about it. - Issue links you can follow. The known limits name the Zero engine's GitHub issues, zero#25852 and zero#24706 on OrigoZero/zero.
Earlier, in 1.4.7 and 1.4.8:
- Stopping play is clean. Leaving play or the world no longer fills the log with red clean-up errors: the weather checks a light or the lightning bolt still exists before handing it back.
- A picked kind brings its own wind. Choosing
windafter a calm preset now gives a real gale (before, the preset's light breeze stayed behind). Setwindin the same change to override it. - Honest docs. A Known limits section with the issue to follow for each, the downpour cost measured again with the true drop counts for each quality setting, and both guides matching what the kit does today.
What's in it
| Kinds (16) | clear, cloudy (overcast), drizzle, rain, showers (passing showers that come and go), downpour, thunderstorm, snow, sleet, hail, wind (wind and gusts), dust (sandstorm / dust storm), leaves (autumn leaves on the wind), ash (ash fall), fog, mist |
| Rain looks | realistic, cinematic heavy (glints round lamps), soft painterly, cartoon, pixel, ink / woodblock |
| Snow looks | soft realistic, big fluffy cartoon, fine powdery blizzard, pixel |
| Carried on the wind | blowing sand and dust, tumbling autumn leaves in red, orange, gold and brown, soft grey ash |
| Lightning | storm (forked and in-cloud), close forked strike, flash inside the clouds, distant silent heat lightning |
| Splashes | realistic crown, misty spray, cartoon, pixel, ink, none |
| Fog banks | valley fog, ground mist, sea fog, town haze, dust and sand: as the weather's own fog, or placed where you want one with the FogBank component |
| Water | cb_pond and cb_puddle materials that ring where drops land; Weather.bind(material) for your own |
| Sound | drizzle and steady rain beds, rain drumming on the roof when you stand under cover, thunder near and far; the wind beds come from Soundstage, which installs with Cloudburst |
| Presets (31) | see Pick a preset below |
Every preset is the same handful of settings, so swapping one for another is one change. With no
preset set at all, a new Cloudburst starts on steady_rain.
Pick a preset
Set preset to the name in the first column. The list is also the order the Weather Lab and
Weather.presets() give them in.
| Preset | What it looks like | Reach for it when |
|---|---|---|
clear_day | A bright, breezy day with a few clouds. | The weather should step aside; the calm between storms. |
light_drizzle | The faintest fine rain under a pale grey sky; the ground darkens slowly. | A damp, quiet mood without a storm. |
light_spring_rain | Soft, fine rain under a bright grey sky; puddles slowly form. | A gentle, fresh rain in daylight. |
steady_rain | An ordinary wet afternoon: rain you clearly see, splashes on the street. | The default. Any game that just needs rain. |
passing_shower | A shower builds, pours for a minute, then clears to a brighter break, over and over. | Open worlds and long sessions: rain that comes and goes by itself. |
autumn_drizzle | Grey, gusty, cold drizzle blown in sideways. | Bleak moors, coasts, a cold walk home. |
tropical_downpour | Warm, vertical, deafening rain; the far side of the street disappears. | A sudden cloudburst; jungles and hot cities. |
tropical_monsoon | Warm rain blown in sheets off the sea, gusting hard, the horizon gone grey. | Monsoon season, typhoons, island and harbour levels. |
night_storm_town | Lamps glinting through sheets of rain, lightning over the roofs, thunder rolling in. | The big set piece: a thunderstorm at night. |
noir_rain | Hard rain in streetlight, every lamp haloed in falling glints. | Detective streets, neon alleys, moody cut scenes. |
hailstorm | Hailstones bouncing off the cobbles, with close strikes. | A violent summer storm; a hazard players feel. |
sleet_squall | A cold, sharp shower of icy rain. | Late autumn and early spring; the edge of winter. |
alpine_snow | Big quiet flakes drifting down, snow settling on roofs and fences. | Winter villages, mountains, Christmas. |
blizzard | Fine snow driven sideways by a howling wind; you can barely see the next house. | Survival, mountain passes, getting lost. |
misty_dawn | Still air, low sun, mist lying in the low ground. | Mornings, graveyards, the start of a level. |
valley_fog | Fog filling the low ground while the hilltops stand clear. | Hills and valleys; climbing out of the fog. |
sea_fog | A cold grey fog rolling in off the water. | Coasts, cliffs, a ship coming in. |
foggy_harbour | Thick, wet sea fog over the quay; masts and lamps fade a few boats out. | Ports, fishing villages, smugglers. |
town_haze | A warm, smoky evening haze over the rooftops. | Dusk in a town; summer evenings. |
gale | Dry and wild: trees thrashing, gusts coming in waves. | Coasts, heaths, a storm that never breaks. |
autumn_leaves | A crisp, breezy afternoon with red and gold leaves tumbling past on the gusts. | Autumn forests, parks, harvest towns. |
dust_storm | A dry, gusty wind lifting dust off the road, the light gone hazy and warm. | Westerns, farmland in a drought, dirt roads. |
sandstorm | A wall of blowing sand: the sun a pale disc, the air tan, the far dunes gone. | Deserts; a storm that forces players to shelter. |
ash_fall | Grey ash drifting down from a fire or a volcano, the sun dim and orange. | Volcanoes, burning cities, after a battle. |
summer_heat_lightning | A warm, dry night with silent flashes far off on the horizon. | Summer nights; unease without rain. |
painted_showers | Soft brush-stroke rain for storybook worlds. | Painterly and storybook art styles. |
cartoon_rain | Chunky blue dashes and bouncy splashes. | Cartoon and toon-shaded games. |
cartoon_snow | Big round flakes drifting down on a cosy evening. | Cosy and cartoon winters. |
pixel_rain | Rain that steps like sprites. | Retro and pixel-art games. |
pixel_snow | Square flakes for retro winters. | Retro and pixel-art games. |
woodblock_rain | Long, even, inked lines of rain in the manner of an ukiyo-e print. | Ink, woodblock and Japanese-print styles. |
Why it looks right
- Each drop is a little lens. It shows the scene behind it, bent, and keeps a visible contrast against it: a touch brighter over a dark wall or tree, a touch darker over a bright sky. Sun, lamps and lightning add their own glint on top, so drops sparkle round a street lamp without the whole curtain turning white.
- No two drops alike. Sizes, brightness, speed and streak length vary per drop, and each one rides its own eddy of the wind. A near drop never smears into a scratch across the screen.
- Thick near, curtains far. A dense near layer, a wider far layer, then grey sheets of rain standing in the distance that melt into the fog.
- Soft where it meets things. Drops fade out where they meet a wall or the ground instead of being cut off by it, and they fade in from the lens so nothing pops in your face.
- Overcast means overcast. A rain deck takes the sun's hard shadows away and the sky light carries the scene; storms darken it further.
How it works (and why it is cheap)
- All falling weather lives on the GPU. Each layer is a static mesh of quads whose motion is in its shader; per drop there is no CPU work at all. A downpour costs the same CPU as a drizzle.
- The engine's own weather does the surfaces. Wetness, settled snow and dry ground under cover
come from
@builtin::systems.weather; fog from the engine's height fog; wind from the engine'sWind(so foliage and physics lean with the rain). Cloudburst keeps no second copy. - The landing map (
cloudburst.landing) is the one piece the engine lacked: the height of the top surface a drop meets coming down, cast around the camera a few rows a frame. Drops stop on roofs (none indoors), splashes sit on what they hit, and drips are found at every eave. - Multiplayer: the weather is a few synced fields plus the shared session clock. Lightning comes from a seeded schedule on that clock. Nothing streams per frame.
- Flash safety: two lightning strikes never start less than 2.6 s apart (a strike that would
land sooner after the one before is skipped, the same on every player's screen), so there is
never more than one flash in any 2.6 s. Each is a single soft pulse with capped
brightness.
Weather.setFlashComfort(0..1)lowers it further per player. - Quality:
quality = "low" | "medium" | "high"on the component scales the drop counts for phones and tablets.
What a downpour costs
Measured on Cloudburst 1.4.6 with engine library @builtin 28ef193, in the showcase village street (1.5.0 adds a few shader instructions to the distant curtains and new particle types, but no per-frame script work; the drop counts are unchanged) in the tropical downpour preset (the heaviest rain), camera on the street, 1920x1080, development build of the editor on a Linux desktop (Intel Arc B-series GPU), 6 to 8 seconds of frames each.
| Setting | Rain drops drawn | Cloudburst's own CPU per frame | Whole engine CPU per frame |
|---|---|---|---|
| Clear sky, for comparison | none | 0.94 ms | 17.1 ms (median 17.2) |
Downpour, quality = "high" (desktop) | 64,000 + 3,600 splash slots | 1.27 ms | 18.5 ms (median 18.0) |
Downpour, quality = "medium" (what a browser gets) | 45,500 | 1.11 ms | 20.1 ms (the desktop was busy: the engine waited for a core for half the frame) |
Downpour, quality = "low" (what a phone or tablet gets) | 26,600 | 0.96 ms | 18.3 ms |
- The rain itself costs the CPU almost nothing: every drop moves on the GPU, so going from a clear sky to the heaviest downpour adds about a third of a millisecond of script time. The whole-frame difference, about 1 ms, is the size of the run-to-run noise on this machine.
quality = "auto"(the default) picksmediumin a browser andlowon phones and tablets by itself. A heavier look draws more than its share (the downpour uses the cinematic look, 1.25 times the drops), which is why the medium and low rows are more than 60% and 35% of 64,000.- These are the browser's and the tablet's settings run on a desktop, not those devices themselves (see Known limits).
Known limits
Things you will run into, said plainly. Each names the open issue to follow on the Zero engine's GitHub tracker, OrigoZero/zero:
- Stepping under a roof switches to a second recording rather than muffling the storm (zero#25852 on OrigoZero/zero: audio has no low-pass filter). The engine cannot muffle (low-pass) a playing sound on its own yet, so Cloudburst fades the outdoor rain down and a recorded clip of rain drumming on a roof up. It sounds right under a roof or porch, but it is the roof clip's rain you hear, not a duller copy of the storm outside, and thunder and wind are only turned down, not dulled. When the engine gains a filter, the kit will use it.
- Frame time in a real browser and on a real Android tablet has not been measured (zero#24706 on OrigoZero/zero: reading frame time in a browser engine). The cost table above runs those devices' settings on a desktop. How long a frame takes on the devices themselves, and what the rain passes cost the GPU on their own (this build's GPU timer does not break those passes out), is still to be measured. If you measure it, please leave the numbers in a comment on the kit.
- Roofs you move while playing keep their old shelter for a moment: the landing map re-casts by
itself when things are added or removed, but a roof that slides needs
require("cloudburst.landing").rebake(cameraPosition)(see the how-to guide). - Skyclock brings the Cloudburst it was released with. Skyclock (worldClockKit) 1.7.1 was released alongside Cloudburst 1.4.5, so a world that installs only Skyclock gets 1.4.5 with it. Install Cloudburst itself to get this version. Skyclock asks for Cloudburst by name, so in this showcase both run on the one copy of Cloudburst 1.5.0.
- Rain follows the active camera. Drops are drawn in a box around whichever camera is drawing the screen; a camera far from the player sees rain around itself, not around the player.
For other kits
Weather.now(): the weather this frame (rain, snow, wind, fog and the rest from 0 to 1, wetness, wind vector).- Named values, for kits that should not depend on Cloudburst: every frame the weather entity
holds
weather.rain,weather.snow,weather.wetness(0 to 1) andweather.wind(vector, m/s).values.get(id, "weather.rain")on any entityvalues.entities()lists reads it; a water kit rings its lakes and puddles from it with no require of Cloudburst. Weather.lastChange(): the change of weather made this session (at,seconds,ago,progress0 to 1,settingsit is changing to), or nil when nothing has changed since the session began. The same answer on every player, a late joiner included, so a storm intro runs once. A player who has just joined may run its scripts a moment before the shared weather reaches it, so ask again after a short wait before changing anything:task.delay(5, function() if Weather.lastChange() == nil then Weather.preset("night_storm_town", 60) end end). The steps of a running forecast do not count as changes; setting the forecast does.Weather.onStrike(fn): every lightning strike, on every peer at once.Weather.landsAt(x, z),Weather.isSheltered({x,y,z}),Weather.landings(centre, r, dt): where rain lands.#include "cloudburst.shaderModules.cb_common"andcb_ripples(...)in your water shader;Weather.bind(material)keeps itscb_raininput current.cb_pondandcb_puddleare ready-made.
Guides inside
- How to make it rain in my game: adding weather, picking a kind, changing it over time, presets, shelter, sound, multiplayer.
- Example: a village thunderstorm at night: step by step from an empty world to a lamp-lit street going from dusk into a storm.
Works with
Skyclock (worldClockKit) for day, night and street lamps: its rain, snow and storms are drawn by Cloudburst, and storms dim whatever sun it sets. Cloudburst needs no clock kit of its own.