Apps Part of Puttopia

Minigolf Hole Checker

Check a minigolf hole: playable, estimated par and how many putts a perfect caddie needs.

More options

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.

Try an example: · ·

More about this tool

How it works

Checks a Puttopia hole — built-in or made in the hole editor — for problems (start or cup off the course, cup unreachable, portal exits in the water), estimates its par from the route length and the hazards on it, counts surfaces and obstacles, and lets the caddie play it with the real physics to prove it can be holed.

  • Errors: the start or the cup is not on playable floor, they are closer than 1.5 tiles, a portal exit is not on playable floor, or no route leads from the start to the cup. The route search walks through floor tiles (8 directions, no corner cutting), over bridges and the water a raft covers, and takes portals and loops as short cuts.
  • Estimated par = 2, plus 1 for every 8 tiles of route beyond the first 6, plus 1 when the hole has two or more hazards (windmills, moving blocks, loops, rafts, gates, water, sand), between 2 and 6.
  • The caddie tries 72 directions × 10 power levels with the real physics for each putt and plays the one that ends nearest the cup along the route (holed first, water last). It knows the physics exactly, so it is better than any person — treat its strokes as the best case.

Par is an estimate for fun play, not an official minigolf rating.

Sources

Part of Puttopia

How to use the Minigolf Hole Checker

Check a Puttopia minigolf hole for problems, get an estimated par and let a perfect caddie prove that the hole can be holed.

What it is for

Building a minigolf hole is fun until your friends find out the cup can never be reached. The Minigolf Hole Checker looks at a Puttopia hole — one of the 27 built-in holes or one you made in the hole editor — and answers three questions: can it be played at all, what par is fair, and how many putts does a caddie with perfect knowledge of the physics need?

Use it before you share a course link, when a hole feels too easy or too mean, or simply to see how the built-in holes are put together: the tool counts surfaces (green, sand, ice, water, bridges, belts, slopes) and objects (bumpers, windmills, portals, loops, rafts and more).

Worked example

Choose Pirate Cove, hole 9 (“Whirlpool”) and keep Let the caddie play the hole switched on.

The answer: Whirlpool is playable. Estimated par 3; the caddie holes it in 1. The route from the tee to the cup is 7 tiles long. The surfaces table shows 80 green tiles, 8 water tiles and 20 tiles of conveyor belt (6 east, 4 south, 4 north, 6 west) that form the whirlpool. The caddie's only putt goes at 275° with power 0.78 and rides the current into the cup.

Now a broken hole: choose Custom hole and paste the example “Soggy”, where the cup sits on a water tile. The tool says Soggy cannot be played yet: The cup is not on playable floor. There is no estimated par and no caddie round until you fix it.

How to read the result

  • Playable is No when there is at least one error: start or cup off the floor, start and cup closer than 1.5 tiles, a portal that ends off the course, or no route from the tee to the cup.
  • Hints are not errors: the cup right next to water, for example, is allowed — it is just mean.
  • Estimated par grows with the length of the route and with hazards such as windmills, moving blocks, loops, rafts, water and sand. It is a starting point; set your own par in the editor if your hole is harder than it looks.
  • Route length follows the floor around walls and uses portals and loops as short cuts, so it can be shorter than you expect.
  • Caddie strokes shows how a perfect player does. People need more — if even the caddie needs more than par + 1, the hole is probably too hard.

Tips and common mistakes

  • Check after every bigger change in the editor; a single block tile can close the only route.
  • A caddie hole in one does not mean the hole is too easy: the caddie knows the exact speed and timing a person has to find by feel.
  • Portals must land on floor; water under the exit counts as off the course.
  • Keep at least one fair line on holes with moving obstacles. If the caddie needs many strokes, the window is probably too small.
  • Big holes (up to 30 × 30 tiles) take a little longer to check because the caddie tries 720 putts per stroke.

FAQ

How does the caddie choose its putts?

It tries 72 directions and 10 power levels with the real physics and plays the putt that ends nearest the cup along the route, preferring putts that drop and avoiding water.

Is the estimated par official?

No. Minigolf associations rate real courses differently; this estimate is for fun play in Puttopia.

Can I check holes made outside the editor?

Yes, as long as they follow the same JSON format: rows of tile letters, start and cup positions in tiles, and an optional list of objects. The field help lists every tile letter.

Why is my hole playable but the caddie did not hole it?

The route search only proves that a path exists. Strong belts, slopes or tight windmill timing can still beat the caddie within 8 strokes — a sign to make the hole a little friendlier.

Guide last updated:

For scripts and AI agents

  • JSON API: POST https://puttopiaholecheck.usefulweb.app/api/v1/calculate (same calculation as this page)
  • Interface description: OpenAPI 3.1 · AI guide: llms.txt
  • MCP server (Streamable HTTP): https://puttopiaholecheck.usefulweb.app/mcp · tool name puttopia_hole_check
Example request
curl -s -X POST https://puttopiaholecheck.usefulweb.app/api/v1/calculate \
  -H 'content-type: application/json' \
  -d '{"course":"custom","customHole":"{\"name\":\"Bumper alley\",\"par\":3,\"theme\":\"candy\",\"tiles\":[\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\"],\"start\":[2.5,6.5],\"cup\":[2.5,1.2],\"objects\":[{\"type\":\"bumper\",\"x\":2.5,\"y\":4,\"r\":0.35}]}","caddie":true}'
Feedback · ideas & bug reports welcome