Log inGet started
World

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

  1. Install Cloudburst from ZeroMind into your world.

  2. 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 with zero scene create --startup main player in the shell, then open scenes/main.scene/build.luau and add these two lines before its last end:

    local w = entity.spawnSynced("Weather")
    w.component.add("Cloudburst", { preset = "steady_rain" })
    
  3. 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 logs entity(...) returned nil errors (issue #7). The light reads check entity.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 new cloud bank 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) and ash (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 new dust fog bank goes with the sandstorm.
  • A better default. A Cloudburst with nothing set now starts on steady_rain, rain you clearly see in daylight, instead of the faint light_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 with Weather.cycle does.

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's lastChange()) 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 with Weather.cycle does). 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.bind hands it to your material only when its shader declares a landmap texture), 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 wind after a calm preset now gives a real gale (before, the preset's light breeze stayed behind). Set wind in 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 looksrealistic, cinematic heavy (glints round lamps), soft painterly, cartoon, pixel, ink / woodblock
Snow lookssoft realistic, big fluffy cartoon, fine powdery blizzard, pixel
Carried on the windblowing sand and dust, tumbling autumn leaves in red, orange, gold and brown, soft grey ash
Lightningstorm (forked and in-cloud), close forked strike, flash inside the clouds, distant silent heat lightning
Splashesrealistic crown, misty spray, cartoon, pixel, ink, none
Fog banksvalley 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
Watercb_pond and cb_puddle materials that ring where drops land; Weather.bind(material) for your own
Sounddrizzle 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.

PresetWhat it looks likeReach for it when
clear_dayA bright, breezy day with a few clouds.The weather should step aside; the calm between storms.
light_drizzleThe faintest fine rain under a pale grey sky; the ground darkens slowly.A damp, quiet mood without a storm.
light_spring_rainSoft, fine rain under a bright grey sky; puddles slowly form.A gentle, fresh rain in daylight.
steady_rainAn ordinary wet afternoon: rain you clearly see, splashes on the street.The default. Any game that just needs rain.
passing_showerA 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_drizzleGrey, gusty, cold drizzle blown in sideways.Bleak moors, coasts, a cold walk home.
tropical_downpourWarm, vertical, deafening rain; the far side of the street disappears.A sudden cloudburst; jungles and hot cities.
tropical_monsoonWarm rain blown in sheets off the sea, gusting hard, the horizon gone grey.Monsoon season, typhoons, island and harbour levels.
night_storm_townLamps glinting through sheets of rain, lightning over the roofs, thunder rolling in.The big set piece: a thunderstorm at night.
noir_rainHard rain in streetlight, every lamp haloed in falling glints.Detective streets, neon alleys, moody cut scenes.
hailstormHailstones bouncing off the cobbles, with close strikes.A violent summer storm; a hazard players feel.
sleet_squallA cold, sharp shower of icy rain.Late autumn and early spring; the edge of winter.
alpine_snowBig quiet flakes drifting down, snow settling on roofs and fences.Winter villages, mountains, Christmas.
blizzardFine snow driven sideways by a howling wind; you can barely see the next house.Survival, mountain passes, getting lost.
misty_dawnStill air, low sun, mist lying in the low ground.Mornings, graveyards, the start of a level.
valley_fogFog filling the low ground while the hilltops stand clear.Hills and valleys; climbing out of the fog.
sea_fogA cold grey fog rolling in off the water.Coasts, cliffs, a ship coming in.
foggy_harbourThick, wet sea fog over the quay; masts and lamps fade a few boats out.Ports, fishing villages, smugglers.
town_hazeA warm, smoky evening haze over the rooftops.Dusk in a town; summer evenings.
galeDry and wild: trees thrashing, gusts coming in waves.Coasts, heaths, a storm that never breaks.
autumn_leavesA crisp, breezy afternoon with red and gold leaves tumbling past on the gusts.Autumn forests, parks, harvest towns.
dust_stormA dry, gusty wind lifting dust off the road, the light gone hazy and warm.Westerns, farmland in a drought, dirt roads.
sandstormA 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_fallGrey ash drifting down from a fire or a volcano, the sun dim and orange.Volcanoes, burning cities, after a battle.
summer_heat_lightningA warm, dry night with silent flashes far off on the horizon.Summer nights; unease without rain.
painted_showersSoft brush-stroke rain for storybook worlds.Painterly and storybook art styles.
cartoon_rainChunky blue dashes and bouncy splashes.Cartoon and toon-shaded games.
cartoon_snowBig round flakes drifting down on a cosy evening.Cosy and cartoon winters.
pixel_rainRain that steps like sprites.Retro and pixel-art games.
pixel_snowSquare flakes for retro winters.Retro and pixel-art games.
woodblock_rainLong, 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's Wind (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.

SettingRain drops drawnCloudburst's own CPU per frameWhole engine CPU per frame
Clear sky, for comparisonnone0.94 ms17.1 ms (median 17.2)
Downpour, quality = "high" (desktop)64,000 + 3,600 splash slots1.27 ms18.5 ms (median 18.0)
Downpour, quality = "medium" (what a browser gets)45,5001.11 ms20.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,6000.96 ms18.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) picks medium in a browser and low on 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) and weather.wind (vector, m/s). values.get(id, "weather.rain") on any entity values.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, progress 0 to 1, settings it 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" and cb_ripples(...) in your water shader; Weather.bind(material) keeps its cb_rain input current. cb_pond and cb_puddle are 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.