v0.1.0· initial public release · under active development
StormSync is a hydrology arcade game. You place moving storms over a watershed; the rain becomes runoff, the runoff races down a branching river network, and the flood wave you create at the outlet earns points, combos, and medals. Bigger, better-timed floods score more.
Purpose. StormSync is a research and education prototype: a playful way to build real intuition for rainfall–runoff and flood dynamics — how a storm's size, intensity, speed, direction, and timing shape the flood at a river outlet — aimed at students, classrooms, and anyone curious about water.
Requires Python 3.10+.
git clone https://github.com/Perez-HydroSystems/StormSync.git
cd StormSync
pip install -r requirements.txt
streamlit run stormsync_app/app.pyStreamlit starts a local server, prints its address, and opens the game in your browser:
Local URL: http://localhost:8501
If a browser tab doesn't open automatically, paste http://localhost:8501
into your browser. Stop the game with Ctrl+C in the terminal.
- Create a player (or stay as Guest) and select a level — basins grow from a small creek (Level 1) to a huge branching river system (Level 10).
- Each level has 5 rounds; round N deals you N storm cards. Storms in a round fire one after another, so their flood waves can stack downstream.
- Drag the storm cloud to aim it over the basin (its arrow shows the travel direction), then hit ⚡ LAUNCH before the timer runs out.
- Watch the storm rain out: runoff gathers on the hillslopes, the river network lights up, and the outlet hydrograph rises. Runoff earns points — flow joining the river earns 3×, and outlet surges earn 8×.
- Score Bronze / Silver / Gold medals; Bronze unlocks the next level.
Tip: storms that travel with the river toward the outlet stack the flood — that's the "sync" in StormSync.
Ten watersheds. Every level basin was drawn by hand and imported into the game at a 1 km hexagon resolution. Drainage areas grow from a 30 km² headwater creek to a 10,000 km² boss basin, each with a fully connected river network draining to a single outlet.
Three hydrological models. A selector (home screen and Testing Lab) changes how the basin turns rain into flood:
- 101 — Surface runoff. Rain that beats the soil's infiltration capacity runs off and is routed downstream. Simple and fast.
- 201 — Soil moisture + baseflow. Adds a soil store: early storms wet the soil, later storms meet wetter ground and flood harder — and the river keeps a gentle baseflow recession. Watch the soil-moisture shading on the hillslopes.
- 301 — Nonlinear channel velocity. Adds river hydraulics on top of 201: the channel flows slow when low and fast when full, producing flashier peaks and longer recessions. The live channel velocity is shown at the outlet.
Live dashboards while the flood unfolds:
- Outlet Hydrograph — streamflow in m³/s over time (in days), with live streamflow, channel velocity, volume, and the peak flow.
- Geomorphology — the basin's drainage area, river length, drainage density, Strahler stream order, perimeter, and elongation ratio.
- Storm Coverage — how much of the basin each storm (and all storms combined) have soaked.
- Storm ↔ River Direction — a compass comparing each storm's travel direction with the river network, with a synchrony score.
- Storm cards — each storm's footprint area (km²), areal intensity (mm/hr), speed (m/s), and duration (h).
Make it yours. On-board toggles switch 📏 real units (km², mm/hr, m³/s — with a map scale bar), ◫ screen layouts (dashboard, studio for laptop or phone, arcade, cinematic), 🎨 animation themes, ◳ hexagon vs. vector river rendering, 🏆 bonus effects, and 🔊 sound.
More to explore:
- 🎓 An animated, step-by-step Tutorial.
- 🌍 River Legends — play basins inspired by ten iconic world rivers (Blue Nile, Mississippi, Yangtze, Danube, Mekong, …), each with a historical flood briefing.
- 🧪 Testing Lab — a free-experimentation sandbox: design your own storms (size, intensity, speed, direction, timing), tune the hydrology model parameters, and compare flood responses on any basin.
- 🛠 Map Creation — paint your own basin and river network on a hex grid and play it.
This is an early release, and feedback is very welcome. It is being refined by coming updates, including:
- refined hydrologic models,
- more levels and real-world river basins,
- a classroom / education mode,
- mobile support and UI polish.
Found a bug or have an idea? Please open a GitHub issue.
This repository provides the open-source research and education prototype of StormSync. Future mobile, hosted, or extended application versions may include additional components distributed under separate terms.
- Code: Apache License 2.0
- Educational media (figures, manuals, teaching materials): CC-BY-4.0
If you use StormSync in research or teaching, please cite it — see
CITATION.cff (GitHub's "Cite this repository" button uses it).
All versions are archived on Zenodo under the DOI
10.5281/zenodo.21382593.
StormSync is developed by Dr. Gabriel Perez — Civil & Environmental Engineering, Oklahoma State University (profile · ORCID 0000-0003-3880-0874) — as part of the Perez-HydroSystems research lab.