A digital trainer for the card game Tai Pan!, the Dutch edition of Tichu. You play against three bots at four levels, with no account, and a coach tells you after each round which choices cost you points. Claude Code built it in six phases, to design documents the owner wrote down beforehand. This page shows how, and above all how the bots think: from a handful of rules of thumb to a search tree over worlds the bot cannot see.
Play Tai Pan! Trainer →Everything revolves around one game engine that knows the full state: all 56 cards and who holds them. Nobody else ever sees that state. Bots, coach and table only get a SpelerView (player view): your own hand plus whatever everyone at the table could see. From that they pick a move from the list of legal moves, and the engine checks that move. So a bot cannot cheat, not even by accident.
The order was set in advance: rules first, then the bots, then the screen, then the coach, then online play. Each phase started with a design document and ended with tests and measurements. Every step went through its own branch and pull request; the owner merged them.
First a rules specification: 76 numbered rules and 20 edge cases, such as what happens when you play the Dog while a wish is open. Then a game engine without a screen that carries out exactly those rules, with the list of legal moves for every state. Every test refers to a rule number, so a failing test can always be traced back to a rule. Tens of thousands of self-played rounds check that no illegal move ever slips through.
Four sub-steps. A heuristic bot with rules of thumb. A first stronger bot with determinization and a search tree, later frozen as a benchmark. Then the “strong bots v2”: first an evaluation harness to measure fairly, then card tracking, a calling model and ISMCTS. Finally adjustable difficulty with eight knobs and four levels. How that works is explained further down.
First playable against three bots in the browser. Then the design: Song ink, with China under the Song dynasty as its theme, and its own card design with the index in the corner. Then sorting and dragging in your hand. A fourth step, the pace of the bots, stayed at research. The last step split the app into two variants: Tai Pan - Train, always against bots and with the coach, and Tai Pan - Play, without a coach.
Six coaching steps, each with its own pull request: replaying a round move by move, a calling rule that weighs the match score, a calling coach, an evaluator that works out what each decision cost, drills, and a progress profile that sets each of your skills next to the bot levels. The analysis runs in the browser, in web workers, so the screen does not stutter.
A lobby, connections over WebSockets, recovery after a dropped connection, and bots that fill empty seats. The server is in charge: it sends each player only their own view. Online play exists only in Play. It is built and tested, but not yet hosted anywhere on the internet. The same day brought the English version of Train and its publication on this site; on October 21 passing cards also became possible by tapping, for phones.
Apps for phone and tablet that play through the same online layer: the same lobby and the same protocol, so mobile and web can sit at one table.
Writes down per phase what has to be built, decides on choices that affect the goal, reviews every pull request and merges it.
Turns the design documents into code, writes the tests, runs the measurements and records where the build deliberately departs from the design.
Five documents: rules, strong bots, bot difficulty, coaching layer and online play. A revised design gets a new version number; rule numbers never change.
Every new bot version had to beat its predecessor demonstrably. After that, every version stays frozen as a benchmark, so progress can still be proven later. That produced a ladder of five rungs. The chart shows how many points per deal each rung wins from the rung below.
The whisker on each bar is the 95% confidence interval. ISMCTS is expensive (about a second per round instead of a few milliseconds), so 300 deals were measured there instead of 4000, and the interval is wider. Bot names are the frozen version names in the code, which is in Dutch.
Picks one of the legal moves blindly. Never plays anything forbidden, but never anything clever either. It only exists to be the bottom rung of the ladder.
Plays like a beginner who knows the basics. Leads with the cheapest combination, beats just high enough, passes its three lowest cards, gives the Dragon to the opponent with the most cards and calls Tai Pan! above a fixed hand-strength threshold. No probabilities, no memory, no looking ahead. Already a huge jump over random.
Keeps track of which cards are gone and draws hard conclusions about who can no longer hold what. On top of that it counts exactly how many turns it still needs to go out, supports its partner and knows when a bomb pays off. The biggest gain after the rules of thumb, for little work.
Decides on Grand and Small Tai Pan! with a model that learned from 200,000 practice deals which hands are worth a call. Later came meld-v2, which also weighs the match score: whoever is far behind has to dare more often. It wins 53.4% of paired matches against meld-v1.
On top of everything above, a search tree: for each move it draws a possible distribution of the hidden cards hundreds of times, plays it out and keeps track of which move works out best most often. Median 128 ms of computing time per move, at most 0.9 seconds.
In the order in which they were built. Each term builds on the one before.
A heuristic is a rule of thumb: a quick way to make a reasonable choice without working everything out. “Lead with your lowest single card” or “give the Dragon to whoever has the most cards” are examples. A heuristic bot is a bot that only follows such rules. It is fast (a millisecond per round) but does not look ahead and cannot count.
The heuristic does not disappear when the bots get smarter. The search tree of the strongest bot uses it to play imaginary rounds out quickly, and it decides which eight moves are worth working out.
The measuring instrument that proves a new bot is better. In Tai Pan! the luck of the deal is enormous: a single Grand Tai Pan! is worth 200 points. “Bot B won 55 of 100 rounds” then means nothing. So the harness plays every deal twice with exactly the same cards, the second time with the teams swapped, as in duplicate bridge. What remains after averaging is the difference in play, not in cards.
Over thousands of deals that gives an average difference with a confidence interval. A new version only counts as better when that whole interval lies above zero. For bots that weigh the match score, the harness does the same with complete matches and measures the win rate. This harness was built first, before the bots it had to measure.
Bookkeeping, not artificial intelligence: keeping track of what has been played and drawing conclusions from it. A bot that does not do this burns its Ace while the Dragon is long gone. The bot only reads what everyone at the table saw, and keeps two kinds of knowledge strictly apart.
Hard knowledge is proof and may rule possibilities out. Soft knowledge only makes something more or less likely. A test ran the tracker alongside the real, hidden hands in 1000 practice rounds and checked after every move that no “proof” was ever wrong.
You call Grand Tai Pan! after eight cards, before the last six arrive. There is little to calculate ahead there; it is an estimate. The calling model estimates the chance that you go out first, based on features of your hand: the Dog (strongly against calling), the Dragon, the Phoenix and the number of aces (strongly for).
To learn, the computer played 200,000 deals, each deal several times with the same cards: once with a call, once without. The score difference is what that call really earned, including hidden costs such as a partner who sacrifices their own game. The threshold follows from those measurements: not “more than 50% chance” out of habit, but the point where calling starts to earn points on average.
Average change in team score from calling Grand Tai Pan!, measured on identical cards, per chance group of the model. For Small Tai Pan! the threshold is 47.5%.
The model is deliberately a logistic regression and not a neural network: it has to be able to explain why. The calling coach in the app uses the same explanation (“this hand is worth a call, mainly because of the Dragon and two aces”). The model is calibrated: of all hands it gives a 40–50% chance, 45% actually went out first.
Two related words. Deterministic means: the same input always gives the same outcome. Shuffling in the engine uses a fixed starting value (a seed), and every bot gets its own seed derived from the round's seed and its seat. That makes every round exactly replayable. It is needed for duplicate play (the same cards twice), for replays and for the coach. A bot never gets the round's own seed, because from that it could reconstruct the whole deck.
Determinization is a search technique for games with hidden cards. You pretend to know the other players' cards: you deal the unknown cards in a way that fits what you know, and work out that imaginary round as if everything lay open on the table. You repeat that hundreds of times and pick the move that works out best on average. Many bridge and Klaverjas bots work this way, and so did the first stronger bot in phase 2.
Its weak spot is called strategy fusion. In every imaginary round the search “knows” where the cards are and picks the perfect follow-up there. At the table you do not know that, and you have to make one choice for all possible distributions at once. So the bot overestimates itself, precisely with cards like the Phoenix that matter most.
The fix for strategy fusion. Monte Carlo Tree Search (MCTS) builds a tree of moves and improves it by repeatedly playing a round out and remembering how it ended. ISMCTS does that over information sets: a node in the tree is not one exact state, but everything the bot cannot tell apart with its knowledge. Each pass through the tree draws a new imaginary distribution, but all distributions share the same tree. So a move only scores high if it is good across many worlds at once.
One iteration of the search consists of four steps, which the bot repeats hundreds of times per move:
When the budget is spent, the bot picks the most visited move. Bombs out of turn, the wish and the Dragon it handles with rules of thumb, or the tree would explode. With too little computing time the search is worse than the heuristic alone (82 points per deal worse at 20 iterations); below 100 iterations the bot therefore keeps the heuristic's move.
A bot that always plays as strongly as possible is not a pleasant sparring partner. So eight knobs sit around the core, K1 to K8: memory, computing time, decision noise, calling noise, passing, partner play, bombs and the wish. The four levels are fixed settings of those knobs. Easy and Normal do not search and use the bot with card tracking and calling model; Hard and Expert use ISMCTS.
| Level | Memory | Computing time per move | Decision noise τ | Wins per deal from the level below |
|---|---|---|---|---|
| Easy | only Dragon, Phoenix, aces and bombs | no search | 25 | +101.1 (from random) |
| Normal | counts ranks, forgets 10% | no search | 6 | +85.6 |
| Hard | all hard knowledge | 200 ms · ± 400 iterations | 10 | +76.9 |
| Expert | hard and soft knowledge | 1000 ms · ± 2000 iterations | 0 | +101.3 |
Decision noise (τ, temperature) makes the bot sometimes pick a slightly worse move, with a probability that depends on how much worse: small slips often, blunders rarely. That feels more human than an occasional random move. The measurements showed which knobs really matter: decision noise alone costs Expert 134 points per deal and calling noise 47, while a worse memory or a random wish is barely measurable. Based on that the settings were adjusted until the four steps were roughly equal in size (88 points per deal on average).
The coach does not use the bots to play, but to check. For each decision it plays every reasonable option out in the same set of imaginary worlds, with the same seeds, so the options can be compared fairly. The difference from the best option is called Δ and is shown as “cost an estimated N points”, always with an uncertainty. When passing there are 2184 possibilities; there the coach picks the 20 best candidates plus your own choice.