cloudburst.package
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, downpour, thunderstorm, snow, sleet, hail, wind, 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. 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 in it
| Kinds | clear, cloudy (overcast), drizzle, rain, downpour, thunderstorm, snow, sleet, hail, wind (wind and gusts), 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 |
| 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: 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 (23) | clear_day, light_spring_rain, steady_rain, autumn_drizzle, tropical_downpour, night_storm_town, noir_rain, hailstorm, sleet_squall, alpine_snow, blizzard, misty_dawn, valley_fog, sea_fog, town_haze, gale, summer_heat_lightning, painted_showers, cartoon_rain, cartoon_snow, pixel_rain, pixel_snow, woodblock_rain |
Every preset is the same handful of settings, so swapping one for another is one change.
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 in the Lanternwake village street in the tropical downpour preset (the heaviest rain), camera on the street, 1920x1080, Cloudburst 1.4.4.
| Where | Drops drawn | Cloudburst's own CPU per frame | Whole frame, clear vs downpour |
|---|---|---|---|
| Desktop (Intel Arc B-series GPU, development build of the editor) | 64,000 rain + 3,600 splash slots | 1.1 to 1.3 ms | 15.9 ms vs 15.9 ms engine CPU, back to back; no difference above the run-to-run noise of about 1 ms |
Browser setting (quality = "medium", engine medium tier) on the same desktop | 38,400 rain | about 1.2 ms | no difference above the noise |
Tablet setting (quality = "low", engine low tier) on the same desktop | 22,400 rain | about 1.2 ms | no difference above the noise |
- The CPU cost does not grow with the rain: every drop moves on the GPU, so a drizzle and a downpour cost the same script time.
quality = "auto"(the default) picks the browser setting in a browser and the tablet setting on phones and tablets by itself.- Not measured yet: a real browser and a real Android tablet. The rows above are those devices' settings run on a desktop. Their own frame times, and a GPU time for the rain passes alone (the engine's GPU timer does not attribute those passes on this build), are still to be measured on the hardware. If you measure them, please leave the numbers in a comment on the kit.
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.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.