Marble Run — Snap-to-Grid 3D Track Pieces, Real Ball-on-Rail Physics
three.js workshop. Drag-drop rail pieces. Drop chrome marbles. Real ball-on-rail physics, parametric centerlines, brass-bell clinks, blooming ambient pad.
What this is
A quiet 3D workshop with a navy grid floor and warm directional sunlight. A palette on the side holds six rail pieces — straight, curve, spiral, jump, half-pipe, funnel. Click a piece, click in the scene to place; the piece snaps to a 1×1×1 grid. Scroll to rotate. Right-click to delete. Each piece has a parametric Catmull-Rom centerline; marbles parameterized by arclength accelerate along the tangent under gravity, decelerate under friction, sub-stepped three times per frame for stable physics. Spawn marbles by clicking the start; they corkscrew through your track in cyan, magenta, yellow, and green chrome. Web Audio drives brass-bell clink envelopes whose pitch tracks impact velocity, plus an ambient pad of detuned sines behind a lowpass filter — both volume and brightness swell with active marble count, so the soundscape literally blooms when the system fills. Three preset tracks loadable from a dropdown: simple drop, double helix, branching divider.
Why this is mind-blowing
Drag-drop construction tools usually fall apart at the connection geometry — pieces don't quite line up, balls fall off rails, the whole illusion breaks. Here every piece announces its entry and exit ports with outward tangents, and the snap rule requires both proximity and tangent agreement. Every preset chain was verified analytically before shipping. Drop a marble; the workshop sings.
Single-file marble run designer in three.js. Snap-to-grid 3D track pieces (straight, curve, spiral, jump, half-pipe, funnel). Drag-drop from palette. Real ball-on-rail physics with friction + gravity. Multiple marbles, color-coded. Audio = satisfying clink of marble-on-wood + dynamic ambient pad that swells with active marble count.Paste this into Claude, Cursor, or Copilot. Change one thing that matters to you.
What I learned shipping it
- Parameterize the marble by arclength s along a Catmull-Rom centerline, not by Cartesian position. The acceleration becomes -g·tangent.y minus friction, sub-step 3× for stability — and you never miss a corner.
- A port system (each piece declares entry/exit faces with outward tangents) is what makes snap-fit construction trustworthy. Match world-space positions within a tolerance AND require tangent.dot > 0.15 — the geometry refuses to lie to you.
- An ambient pad whose volume and lowpass cutoff are driven by active marble count makes the soundscape bloom with activity. The audio writes the feedback loop you want the user to chase.