What Mini Putt Putt Actually Is
Mini Putt Putt is essentially a simplified version of the classic arcade mini-golf game that runs on low-end hardware or in browser environments. It strips down the full physics simulation to something lightweight, which means you lose some accuracy but gain accessibility. The kind of thing you'd run on a Raspberry Pi or throw into a Kiosk setup. I built one of these into a small retail kiosk a while back. The client wanted a fun waiting-area game for a family entertainment center, and they didn't have the budget for a full Unity build. So I went with a stripped-down implementation. What follows is basically everything I learned from that project.
Mini Putt Putt setup and install
First, grab the source or the executable depending on what you're working with. Most implementations float around on GitHub as open-source projects, usually written in JavaScript or C#. If you're using the browser version, you just drop it onto a web server and point a tablet at it. If you're compiling from source, you need Node.js or a .NET runtime, and then you run the build script. It usually takes about 5 to 10 minutes depending on your machine. The config file is where things get interesting. You'll find it at config.json in the root directory. This is what controls course selection, physics parameters, input method, and display resolution. By default it's set for a 1920x1080 touchscreen, which works fine if you're running it on a standard monitor. If you're using a portrait-oriented tablet like I was, you need to change the resolution setting and flip the touch coordinates. The default orientation parameter is "landscape" and it doesn't auto-detect. One thing people miss: the touch calibration. The game uses raw touch events, not the OS-level pointer API. This means if you have a screen protector or a dirty screen, your inputs will be offset by a few pixels. On my kiosk build, the screen protector was causing about a 12-pixel drift on the X-axis. I fixed it by adding a manual offset in the config file. There's a touch_offset_x and touch_offset_y parameter you can adjust. Took me about 20 minutes to dial it in by watching test shots.
How the physics actually work
The core loop is simple: you tap and drag to set direction and power, then release and the ball rolls. But under the hood it's using a discrete collision system, not continuous physics. That's the main tradeoff. Continuous collision detection would prevent the ball from phasing through walls at high speeds, but it's more expensive computationally. Mini Putt Putt sacrifices that for performance. So here's the edge case that bit me: at high power settings, the ball can tunnel through thin obstacles. If you have a narrow wall segment that's less than about 8 pixels wide, a fully powered shot will sometimes pass right through it. This happened on course 3 of the default set, where there's a decorative pillar that's intentionally narrow. Players were complaining the ball was disappearing into the wall and respawning at the start of the hole. The workaround isn't in the config. It's in the level design. I increased the wall thickness in the level JSON file from 6 to 12 pixels, which resolved the tunneling issue entirely. If you don't have access to the level files, your other option is to cap the maximum power value. There's a max_power setting in config, and setting it to 0.7 (70% of full power) eliminates most tunneling cases without making the game feel broken.
Get the Full Details
Custom courses and level editing
This is where Mini Putt Putt gets useful. The level format is JSON-based, so you can write your own courses without touching any compiled code. Each level file defines the hole boundaries, obstacles, wind zones, and the ball spawn point. It's not the most intuitive format, but it's documented in the README and the structure is straightforward once you look at an existing level. A typical level has about 40 to 60 lines. The most common mistake people make when writing custom courses is placing the ball spawn inside a wall. The game doesn't validate this, so it just spawns the ball clipped into the obstacle and the player can't move it. Always run a quick visual check before testing. I learned that one the hard way on my second custom course. Another subtlety: wind zones. You can define areas where wind affects the ball's trajectory. The wind is specified as a vector with speed and direction. If you set the wind speed too high relative to the hole size, the course becomes nearly unplayable. I found that a wind speed above 0.5 in a standard-sized hole makes it very difficult to control the ball. For a challenging but fair custom course, keep wind values between 0.2 and 0.4.
Performance and deployment notes
On a Raspberry Pi 4, Mini Putt Putt runs at about 55 to 60 FPS with the default 4-course set. If you add custom courses with complex obstacle layouts, you might drop to 40 FPS. The bottleneck is the collision detection loop, not the rendering. If you're targeting low-end hardware, simplify your obstacle count per course. Each additional obstacle adds roughly 2 to 3 milliseconds per frame. For a kiosk deployment, I'd recommend disabling the pause menu and auto-advancing after each hole. This prevents users from getting stuck on menus and keeps the flow going. You can do this by setting auto_advance to true in the config. It also makes sense to disable sound if the kiosk doesn't have speakers or if audio feedback isn't necessary. That alone reduces CPU usage slightly. If you need something more robust than Mini Putt Putt — like proper continuous collision detection, networked multiplayer, or polished UI — you'd be better off looking at a full game engine project. This tool is best suited for lightweight deployments where the priority is getting something playable on screen quickly, not building the definitive mini-golf experience.
