How it Works: Physics in the Browser
The simulator is built on MapLibre GL JS, utilizing a custom physics engine that runs in real-time within your browser. When you click the map, the application identifies your coordinates and immediately begins querying the elevation data of the surrounding terrain.
By calculating the gradient vector the direction of the steepest descent – the marble is assigned a velocity. We use a method of finite differences to look at the elevation slightly to the north, south, east, and west of the marble to determine which way gravity would pull it. With added momentum and friction variables, the marble doesn't just slide; it rolls, gains speed down cliffs, and orbits around peaks before finally coming to rest in a basin.
The Secret Sauce: The Mapterhorn Pipeline
The precision of the marble's path is entirely dependent on the quality of the terrain data. The simulator leverages the Mapterhorn open-source terrain data pipeline.
Mapterhorn is a sophisticated workflow that transforms raw Global Digital Elevation Models (DEMs) into highly optimized, web-ready tiles. Because the data is tiled, the map only needs to download the elevation info for the area where the marble is currently rolling, keeping the experience fast and lightweight even on mobile devices.
Marble Simulator vs. River Runner
Many readers will be familiar with the excellent River Runner map by Sam Learner. While both maps explore the “downhill” path, they differ significantly in their intent and execution.
River Runner is a masterpiece of storytelling and environmental data. My Terrain Marble Simulator is merely a sandbox for physics. It’s less about where the water goes and more about how a physical object interacts with the literal shape of the Earth.
