Mahjong

Active Side Project

Having married into a Chinese family, it was only a matter of time before they taught me mahjong. It's a great game, so I figured I'd try to find it on the App Store so I could practice. Unfortunately, most mahjong apps are actually just the single-player tile-matching game, which has basically nothing to do with the real thing. So I did what any vibe-coder would do in that situation and made my own 4-player Hong Kong mahjong game, playable against computer opponents on a 3D table.

Scoring a winning hand is counted out on the table, one faan at a time

It plays the same way it would in person: a dice roll to break the wall, replacing flowers and seasons, then taking turns drawing and discarding until someone completes a hand. I'm not going to get into all the rules of mahjong here.

Since I wanted to make this playable on a phone, legibility has been one of the bigger design challenges to deal with. There are a lot of tiles on the table at once, so it's important to be able to read what everyone else has thrown away. Finding the right default angle was important, as well as animating each discard in a way that reveals it cleanly to the player before it's placed on the table. If part of the wall ever obscures a played tile, those tile materials automatically turn to glass so nothing is ever covered up. The camera can also be zoomed in as needed.

The tile art went through a lot of rounds too. All 42 tile faces are drawn from vector art, and the bamboo tiles in particular took a lot of iterations to get right.

This project was built by teams of AI agents, but with a lot more structure than most of my previous projects. It was my first time trying a Gauntlet Loop, Matt Shumer's builder-critic technique. Basically an orchestrator agent breaks the goal into small tasks for builder subagents, then for each task a deliberately harsh critic agent reviews and sends the work back until it passes. The critic grades against a written Hong Kong rule book that the code cites section by section, and it has to actually run the code before it's allowed to weigh in. It only works well when the goal is clear, but in those scenarios it's very effective. Mahjong rules are complicated enough that several of the "bugs" I reported while playtesting turned out to be the rules working exactly as intended. Now the game explains those rules when they come up, so nobody else has to go through the same confusion.

It's fully playable from start to finish on my phone, and it passed the first round of testing with my father-in-law. Next up: sound, music, difficulty levels, pass-and-play mode, and then the App Store. Online play will come later if it gets picked up by enough people.