MarbleRunBuilder

Marble Run Builder is a physics playground for building marble runs in a browser. You drag pieces onto a board, drop marbles, and hear them hit bells and chimes on the way down. It’s laid out for a tablet held sideways. I made it for my son, and for kids in general.

The problem

My son loves real marble runs. A marble run is a toy you build, knock down and build again. On a screen, that takes physics that behaves the same way from one run to the next, touch controls where a drag always moves a piece, and a way to save a board you like.

What I built

The tray holds thirty-five pieces, counting mirrored versions, from ramps, funnels and loops to lifts, cannons, spinners, bells, xylophone bars and a windmill. Pieces snap to a grid of 17 by 9 squares. Tapping a piece rotates it, dragging moves it, and dropping it back on the tray removes it. A tap in the sky drops a marble, in one of eight colors, up to twenty at a time, and marbles can be grabbed and flung.

There are six built-in tracks to start from (Big Cascade, Zigzag Falls, Loop City, Round & Round, Music Mountain and Spin Factory), or an empty board.

Every piece is a physics body in Matter.js. Sound comes from the browser’s audio engine; there isn’t a single audio file. Boards save on their own a second after each change, and into named slots with thumbnails when a player wants to keep one. If a slot can’t be saved because storage is full, the game says so and suggests deleting an old save. Turned to portrait, the game pauses its physics, quiets the sound and asks for the tablet to be turned sideways.

Key decisions

Fixed-step physics, apart from drawing

The simulation steps at a fixed 120 times a second, separate from drawing, so a slow frame doesn’t change how a marble falls. Each frame runs at most four steps. After a long stall the game drops the time it couldn’t simulate instead of trying to catch up all at once. The cost is that the run slows down for a moment during a stall.

One fixed size, scaled to fit

The game is laid out at 1133 by 744, an iPad mini’s landscape size in CSS pixels, and scaled to fill the window. Pinch-zoom and long-press menus are switched off so a drag always moves a piece. That rules out zooming the page, and portrait mode stops play.

Sound made in code, with a cap on voices

Every sound is synthesized with Web Audio, and the audio starts on the first tap, which iOS requires. Rolling sound comes from a pool of eight voices, handed each frame to the loudest marbles, with pitch and volume following each marble’s speed. Impacts get ten voices and chimes six, and past those caps a hit goes unheard. Everything runs through a compressor, so a board full of marbles can’t clip. The caps keep a pile-up from rattling like a machine gun, and they keep the audio work from growing with the number of marbles.

Saves stay in the browser

Boards are saved to the browser’s local storage as documents with a version number. A failed write is caught instead of breaking the game. The cost is that a saved board lives on one device, in one browser.

A closer look

The start screen offers six built-in tracks and Start Your Own.

On Round & Round, marbles run the loop, ride the lift and fly past the cannons.

Pieces dragged from the tray snap onto the grid. This course uses ramps, straight track and two loops.

A tap in the sky drops a marble onto the new course. These ran both loops on their way to the bell, the chimes and the basket.

The save window stores the course as Marble Run 1, with its thumbnail and the date.

How I checked it

A debug overlay, switched on with the D key or three quick taps in a corner, shows frame time, the number of physics bodies and marbles, and how many rolling sounds are playing. The page also exposes the world, the board and the save module to the browser console as a handle for debugging and testing. The walkthrough on this page is a real recording of the game, made from a local copy. The board holds 20 marbles at most; dropping another removes the oldest. I’ve tested it on an iPad.