# Minigolf Shot Simulator > Simulate one putt on a Puttopia hole: path, bounces, portals, water and whether it drops. 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. Part of usefulweb.app (https://usefulweb.app/). Part of [Puttopia](https://puttopia.usefulweb.app/) (ownerApp: puttopia). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows. ## Use it - Human interface: https://puttopiashotsimulator.usefulweb.app/ (interactive tool at https://puttopiashotsimulator.usefulweb.app/tool) - JSON API: POST https://puttopiashotsimulator.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://puttopiashotsimulator.usefulweb.app/api/v1/tool) - OpenAPI: https://puttopiashotsimulator.usefulweb.app/openapi.json - MCP (Streamable HTTP): https://puttopiashotsimulator.usefulweb.app/mcp - tool `puttopia_shot_simulator` ## Inputs - course (select): Course - hole (integer): Hole number (1–9) - customHole (textarea): Custom hole (JSON, only for “Custom hole”) - Tiles as text rows (. void, # block, g green, s sand, i ice, w water, B bridge, > < ^ v conveyor belts, E W N S slopes down toward east/west/north/south), start and cup as [x, y] in tiles, objects such as bumpers, windmills, portals and loops. - x (number): Ball x (tiles, empty = tee) - y (number): Ball y (tiles, empty = tee) - angle (number): Direction (degrees: 0 east, 90 south, 180 west, 270 north) - power (number): Power (0 to 1) - t0 (integer): Obstacle clock at the putt (ticks of 1/120 s) - Windmills, moving blocks and rafts depend on the time of the putt. ## Method - 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. ## Limits - A game model for Puttopia, not a physics simulation of a real golf ball, green or course.