scher.nl
Personal project · September–October 2026

Tai Pan! Trainer

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 →
Opponents
3 bots
Bot levels
4
Bot versions on the ladder
5
Build phases
6
Languages
NL and EN
At a glance

Who sees what

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.

Who sees what The game engine knows the full state. Bots, coach, table and online server only receive a SpelerView with the legal moves. The chosen move goes back to the engine, which checks it. Game enginefull state · 56 cards SpelerView + legal moves Bots4 levels Coachdoes the maths Tableyour screen Online serverone view each chosen move back to the engine, which checks it
How it was built

Six phases, in a fixed order

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.

  1. 1

    Rules and engine

    September 2026

    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.

    TypeScriptvitestrules spec v1.2
  2. 2

    Bots

    September 2026

    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.

    ladder of 5 versions200,000 practice deals for the calling model4 levels, 8 knobs
  3. 3

    Web app

    September–October 2026

    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.

    ViteReactweb workers
  4. 4

    Coaching layer

    October 10–11, 2026

    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.

    replay from the event streamΔ per decisiondrills and puzzles
  5. 5

    Online play

    October 11, 2026

    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.

    Node.jswsshared password
  6. 6

    iOS and Android

    next

    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.

Who does what

Design, build and benchmark

Owner

Sets the design and the order

Writes down per phase what has to be built, decides on choices that affect the goal, reviews every pull request and merges it.

Claude Code

Builds, tests and measures

Turns the design documents into code, writes the tests, runs the measurements and records where the build deliberately departs from the design.

Design documents

The single source for 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.

How the bots work

From basic bot to strong bot

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.

Gain per rung on the bot ladder Paired difference in points per deal against the previous version, with 95% interval. Heuristic against random +203.7; card tracking against heuristic +48.9; calling model against card tracking +10.7; ISMCTS against calling model +17.9. 0 50 100 150 200 points per deal gained over the previous version heuristisch-v1vs willekeurig-v1 heuristisch-v1 vs willekeurig-v1: +203.7 per deal, 95% interval 201.8 to 205.7 (4000 deals) +203.7 tracking-v1vs heuristisch-v1 tracking-v1 vs heuristisch-v1: +48.9 per deal, 95% interval 45.4 to 52.4 (4000 deals) +48.9 meld-v1vs tracking-v1 meld-v1 vs tracking-v1: +10.7 per deal, 95% interval 8.2 to 13.2 (4000 deals) +10.7 ismcts-v1vs meld-v1 ismcts-v1 vs meld-v1: +17.9 per deal, 95% interval 6.1 to 29.7 (300 deals) +17.9

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.

  1. 0

    willekeurig-v1 (random)

    baseline

    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.

  2. 1

    heuristisch-v1: rules of thumb

    +203.7 per deal

    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.

  3. 2

    tracking-v1: + card tracking

    +48.9 per deal

    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.

  4. 3

    meld-v1: + calling model

    +10.7 per deal

    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.

  5. 4

    ismcts-v1: + looking ahead

    +17.9 per deal

    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.

Terms explained

Six words that keep coming back

In the order in which they were built. Each term builds on the one before.

heuristic · rule of thumb

Heuristic

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.

duplicate play · paired comparison

Evaluation harness

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.

Duplicate play A deal is played twice with the same cards. In run 1 bot X sits north and south, in run 2 east and west. The score difference between X and Y is computed per run and then averaged into the paired difference for that deal. Example: +60 and −20 gives an average of +20. Deal 17fixed seed Run 1X sits N–S · Y sits E–W Run 2teams swapped: X sits E–W X − Y+60 points X − Y−20 points Pairedavg. +20

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.

card knowledge · counting

Card tracking

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 · proof
  • Wish. An 8 has been wished, the player is on turn and does not play an 8: then they had no 8 they could beat with.
  • Exhaustion. All four Kings have been seen: nobody holds a King any more.
  • Hand sizes. How many cards each player still has.
  • Own passing. The three cards you passed are with the receiver until they are played.
  • Mahjong. Whoever led first held the Mahjong.
Soft knowledge · suspicion
  • Grand Tai Pan! The caller probably has aces, Dragon, Phoenix or a bomb.
  • Small Tai Pan! Same direction, weaker.
  • Passing. A low card you received says something about what the giver kept.
  • Passing on a trick. Weak: you may always pass, even when you could beat it.

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.

when do you call Tai Pan!?

Calling model

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.

What Grand Tai Pan! earns per chance Measured average score change from calling Grand Tai Pan!, per predicted chance of going out first. 10–20%: −162; 20–30%: −103; 30–40%: −73; 40–50%: −26; 50–60%: +15; 60–70%: +62; 70–80%: +133. The threshold is at 50%. +150 +100 +50 0 −50 −100 −150 10–20% chance: calling costs 162 points on average (16,294 hands) 20–30% chance: calling costs 103 points on average (54,371 hands) 30–40% chance: calling costs 73 points on average (46,629 hands) 40–50% chance: calling costs 26 points on average (29,631 hands) 50–60% chance: calling earns 15 points on average (6,496 hands) 60–70% chance: calling earns 62 points on average (1,963 hands) 70–80% chance: calling earns 133 points on average (174 hands) −162 −103 −73 −26 +15 +62 +133 threshold: call from 50% 10–20% 20–30% 30–40% 40–50% 50–60% 60–70% 70–80% predicted chance of going out first
calling costs pointscalling earns points

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.

deterministic · determinization

Deterministic and determinization

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.

Information Set Monte Carlo Tree Search

ISMCTS

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.

Determinization versus ISMCTS Left: with determinization each imaginary world gets its own search tree and the outcomes are averaged per move. Right: with ISMCTS all worlds feed one shared tree; a move that is not legal in every world is only judged in the worlds where it was possible. Determinization ISMCTS world 1 world 2 world 3 average per moveeach world its own tree world 1 world 2 world 3 not legal in every world one shared treestatistics over all worlds

One iteration of the search consists of four steps, which the bot repeats hundreds of times per move:

One ISMCTS iteration Draw a world that fits the card knowledge, pick a move in the tree with UCB1 and availability, play the round out with the heuristic, and feed the outcome back into the tree as a team difference. Then the next iteration follows with a new world in the same tree. 1 · Draw a worldfits card knowledge 2 · Pick a moveUCB1 · available 3 · Play outwith the heuristic 4 · Back upteam difference next iteration: new world, same tree
  1. Draw a world. The unknown cards are dealt according to the soft knowledge. A deal that violates hard knowledge is thrown away; otherwise the bot would reason about a Grand Tai Pan! caller holding nothing but threes.
  2. Pick a move. With the UCB1 formula, which balances moves that have worked out well so far against moves that have hardly been tried. The characteristic detail: a move is only counted in the worlds where it was actually possible. A move that is legal in only 10% of worlds is not penalised for the other 90%.
  3. Play out. The round is finished by the heuristic bot, not at random. A random player throws its bomb away on a trick without points; that would pollute every outcome. This turned out to be the biggest lever.
  4. Back up. The outcome is the point difference between the teams (not just win or loss, because 60 points beats 40), and it is added to every node visited.

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.

From strong bot to opponent

Four levels, eight knobs

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.

LevelMemoryComputing time per moveDecision noise τWins per deal from the level below
Easyonly Dragon, Phoenix, aces and bombsno search25+101.1 (from random)
Normalcounts ranks, forgets 10%no search6+85.6
Hardall hard knowledge200 ms · ± 400 iterations10+76.9
Experthard and soft knowledge1000 ms · ± 2000 iterations0+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).

Computing time is a number of iterations, not a clock. A budget of 200 ms is translated into about 400 iterations. So the same bot plays exactly the same moves on a fast and a slow phone, and every game stays reproducible.
The coach

The same bots, now as calculators

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.

How sure is the coach? It works with simulations and attaches an uncertainty (±) to every number. If you see no verdict, the difference is not demonstrable.
Ground rules

What always holds

Technology

What is used

Language and structure

  • TypeScript in six packages (npm workspaces): engine, bots, coach, web, online and server. Everything is in Dutch, including the names in the code.
  • vitest for the tests; every test refers to a rule or design number.

Bots and measurements

  • Own ISMCTS, card tracking and logistic regression (IRLS), without external AI libraries.
  • Duplicate play spread over all processor cores; measurement reports are generated by scripts.

App

  • Vite and React, in two variants (Train and Play) and two languages.
  • Web workers for the coach's analysis, so the screen stays smooth.

Online

  • Node.js with ws for WebSockets; built and tested, not yet hosted.

Build and publish

  • Claude Code for the build, with GitHub for branches and pull requests.
  • Cloudflare serves this site and the app as static files.
Play Tai Pan! Trainer →