Minigolf Shot Simulator
Simulate one putt on a Puttopia hole: path, bounces, portals, water and whether it drops.
How it works
Rolls one putt with Puttopia’s deterministic minigolf physics on a built-in hole (Candy Land, Pirate Cove, Space Station) or your own hole: friction per surface, slopes, conveyor belts, bounces off walls and bumpers, rotating windmills, moving obstacles, portals, loop-de-loops and water. Shows the path from above and where the ball stops — exactly as the game rolls it.
- One tile is one unit (about a metre on a real course). The ball has a radius of 0.11 tiles, the cup 0.2. The putt starts at 0.35 + power × 5.65 tiles per second in the given direction; 0° points east (+x) and angles grow clockwise in the top view, so 270° points north, away from the tee in most holes.
- The ball is integrated with a fixed time step of 1/120 s. Each step: forces (slopes 1.3 tiles/s² downhill, conveyor belts push up to 1.7 tiles/s, the cup pulls 4.5 tiles/s² toward its centre), rolling friction per surface (green and bridges 0.9, sand 3.4, ice 0.22 tiles/s²), movement, then collisions.
- Walls and blocks bounce with a restitution of 0.72 and a little grip along the wall; bumpers kick back with 1.12 and at least 1.2 tiles/s; windmill blades and moving obstacles bounce relative to their own speed. Portals keep the ball’s speed and direction. A loop needs the speed given on the hole (usually 2.6 tiles/s) when the ball enters it; slower balls roll back.
- The ball drops when it is over the cup slower than 1.35 tiles/s; faster balls lip out. Water and leaving the course cost a penalty stroke and the ball goes back to where the putt started. The putt ends when the ball is still or after 40 seconds.
- Windmills, moving blocks and rafts follow the obstacle clock; the same hole, ball position, direction, power and clock always give the same path. Sines and cosines are computed with plain arithmetic so every browser and the server agree bit for bit.
A game model for Puttopia, not a physics simulation of a real golf ball, green or course.
Sources
- Puttopia physics and course data (engine/physics.ts, engine/courses.ts) (UsefulWeb)
- Fixed-timestep integration (semi-implicit Euler) for deterministic game physics (Glenn Fiedler, “Fix Your Timestep!”)
Part of Puttopia
-
Puttopia Funny 3D minigolf game
Funny 3D minigolf: windmills, loops, portals and cheering gummy bears.
How to use the Minigolf Shot Simulator
Roll one putt on a Puttopia minigolf hole and see its path, every bounce, portal and splash, and whether the ball drops into the cup.
What it is for
The Minigolf Shot Simulator rolls a single putt with the same physics Puttopia uses in the game. You pick a hole from one of the three built-in courses (Candy Land, Pirate Cove, Space Station) or paste a hole you built in the editor, choose a direction and a power, and the tool shows the path from above, every event on the way and where the ball ends up.
It is handy when you design holes and want to know whether a bank shot is possible, when you wonder why a putt in the game lipped out, or when you want to explore a hole before a round with friends. Because the physics is deterministic, the same hole, ball position, direction, power and obstacle clock always give exactly the same path — in the game, on this page and through the API.
Worked example
Take the sample hole “Bumper alley”: a straight lane, 5 tiles wide and 8 long, with one bumper in the middle between the tee and the cup. Choose Custom hole, paste the JSON, set the direction to 260° and the power to 0.78.
The tool answers: The ball drops into the cup. Rolling time 3.017 s, 3 bounces, 1 stroke counted. The event list explains how: at 0.517 s the ball clips the bumper, at 1.225 s it bounces off the left wall, at 2.167 s off the top wall, and at 3.017 s it drops. A straight putt at 270° would have hit the bumper head-on — the 10° offset turns it into a pinball trick shot.
Now try Pirate Cove hole 1, “Walk the Plank”, at 262° with power 0.5. The ball leaves the narrow plank after 1.433 s: Splash, 2 strokes counted, and the ball goes back to where the putt started.
How to read the result
- Holed and Distance to the cup are the headline: distance is a straight line in tiles (one tile is roughly a metre on a real course).
- Strokes counted is 1, or 2 when the ball lands in water or leaves the course (penalty stroke).
- Bounces counts walls, blocks, bumpers, windmill sails and moving obstacles.
- The top view draws the path as a dotted line; the event tables list what happened and when, in seconds after the putt.
- Lip-outs mean the ball crossed the cup too fast. It can still drop later — the first example on Candy Land lips out, hits the back wall and rolls back in.
Tips and common mistakes
- Directions are compass-like but clockwise in the top view: 0° east, 90° south, 180° west, 270° north (away from the tee on most holes).
- The obstacle clock matters on holes with windmills, moving blocks or rafts. The same putt at clock 0 and clock 30 can hit a sail or slip through. In the game the clock keeps running while you aim.
- Leave Ball x / y empty to putt from the tee; fill them in to test the second putt from where the first one stopped.
- Loops need speed: on Candy Land hole 7 a putt with power 0.65 makes the loop; much softer putts roll back.
- Too much power is the most common miss. Balls faster than 1.35 tiles per second over the cup lip out.
FAQ
Is this how a real golf ball behaves?
No. It is a game model with simple rolling friction, bounces and slopes, tuned to be fun and fair. It is not a simulation of a real ball, green or course.
Why does the same putt give a different result in the game?
In the game the obstacle clock runs while you aim, and your ball may not start exactly at the tee. Copy the clock and position into the tool and you get the same path.
Can I test holes from the Puttopia editor?
Yes. Download the hole as JSON in the editor (or export it), choose Custom hole and paste it. The hole checker tells you first whether it is playable.
What do conveyor belts and slopes do?
Belts push the ball along their direction; slopes pull it downhill. Both are part of the same physics the game uses.
Guide last updated:
For scripts and AI agents
- JSON API:
POST https://puttopiashotsimulator.usefulweb.app/api/v1/calculate(same calculation as this page) - Interface description: OpenAPI 3.1 · AI guide: llms.txt
- MCP server (Streamable HTTP):
https://puttopiashotsimulator.usefulweb.app/mcp· tool nameputtopia_shot_simulator
Example request
curl -s -X POST https://puttopiashotsimulator.usefulweb.app/api/v1/calculate \
-H 'content-type: application/json' \
-d '{"course":"candy","hole":1,"angle":270,"power":0.78}'