Mahjong Game Type
Reference for the mahjong game type — a four-player tile game using Chinese Classical rules.
For platform-level configuration shared across all game types, see Shared Game Configuration.
Mahjong is a self-contained board game: unlike the adventure, mecha, and arena game types, it has no designer-authored content. The tile set, deal, and rules are fixed, so there is no game designers section for it — a published Mahjong game is ready to run as-is.
Game Parameter
Mahjong has no tunable game parameters. The tile set, hand size, and scoring are fixed by the rules below.
Overview
| Property | Value |
|---|---|
| Players | Exactly 4 — humans, with any empty seats filled by computer opponents when the run allows them |
| Ruleset | Chinese Classical Mahjong |
| Tiles | 136 |
| Turn processing | Sequential — one active player at a time, with reactive claims |
| Goal | Be the first to complete a legal winning hand of four melds + one pair |
At the start of a hand, seats and the dealer are assigned at random. The round wind starts at East. Play proceeds anticlockwise through the seat winds: East → South → West → North.
Computer Opponents & Invitations
Mahjong always seats exactly four players. When the run **allows computer opponents** (a run setting; see Shared Game Configuration), a joining player can use their join game turn sheet to:
- Invite other players — enter a name, email, and optional note for each
person to invite. Each invitee receives a link to the same run.
- Add computer opponents — choose how many computer opponents should fill
the remaining seats, capped at the seats still open.
The run starts once humans plus committed computer opponents reach four. Computer seats then take their turns automatically — drawing, discarding, and answering claims — so play never waits on them.
Named opponents with their own style. Computer seats are filled from a fixed cast of characters (Sparrow, Old Turtle, Lotus, Swift, Magpie, The Sage), each with a distinct, learnable play-style: the aggressor claims constantly, the defender stays concealed and passes, the purist chases a single-suit flush, the collector hoards honours. Their portraits sit around the board and their names appear in your turn recap. A computer opponent always takes a win when it can; when configured with an OpenAI API key the engine may play with an LLM, falling back to the character's built-in style otherwise.
Table talk. Opponents occasionally say a short line at the table (shown in your "Since Your Last Turn" recap), and on your draw/discard sheet you may optionally choose a phrase to say to the others. All phrases are drawn from a fixed, translated pool.
The Tiles
The wall is built from 136 tiles, with no flowers or seasons:
| Group | Tiles | Copies | Count |
|---|---|---|---|
Characters (man) | 1–9 | 4 each | 36 |
Dots / circles (pin) | 1–9 | 4 each | 36 |
Bamboo (sou) | 1–9 | 4 each | 36 |
| Winds | East, South, West, North | 4 each | 16 |
| Dragons | Red, Green, White | 4 each | 12 |
That gives 34 distinct tile faces and 136 tiles in total.
The Deal
| Step | Detail |
|---|---|
| Shuffle | The 136 tiles are shuffled into the wall |
| Dead wall | The last 14 tiles are set aside as the dead wall (used for kong replacement draws) |
| Starting hands | Each player is dealt 13 tiles |
| Dealer's extra | The dealer draws a 14th tile to begin, and takes the first turn |
How to Play
A hand is a state machine that cycles between the active player acting and the other players optionally reacting.
Melds
A meld is a set of tiles claimed as a group:
| Meld | Composition |
|---|---|
| Chow | A run of three consecutive tiles in the same suit (e.g. 3–4–5 bamboo) |
| Pung | Three identical tiles |
| Kong | Four identical tiles (draws a replacement tile from the dead wall) |
A winning hand is four melds plus one pair (two identical tiles).
The Active Player's Turn
On your turn you draw a tile, then choose one action on your draw / discard turn sheet:
| Action | Effect |
|---|---|
| Discard | Place a tile from your hand face-up as the discard; other players may then claim it |
| Tsumo | Declare a self-drawn win — only valid if your hand is already complete |
| Kong | Declare a kong from your hand and the drawn tile, then draw a replacement from the dead wall and discard again |
Claiming a Discard
When the active player discards, the other three players may react on a claim turn sheet:
| Claim | Requirement |
|---|---|
| Pass | Take no action |
| Chow | Complete a run with the discard — only the player seated immediately after the discarder may chow |
| Pung | You already hold two matching tiles |
| Kong | You already hold three matching tiles |
| Ron | The discard completes your hand — you win |
If a claim sheet is not submitted, it is treated as a pass.
Claim priority — when several players claim the same discard:
- Ron (a win) beats everything
- Pung / Kong beat a chow
- Chow is lowest priority
Ties between pungs/kongs are resolved in favour of the player nearest the discarder in turn order. The winning claimant takes the tile, forms the meld, becomes the active player, and play continues from them.
Winning
You win by completing four melds and a pair, either by:
- Tsumo — completing the hand on your own drawn tile, or
- Ron — completing the hand on another player's discard.
Ending a Hand
| Phase | Meaning |
|---|---|
| Dealing | Tiles are being dealt |
| Awaiting discard | The active player is choosing an action |
| Awaiting claims | A tile has been discarded and others may claim it |
| Scoring | A winning hand is being scored |
| Completed | The hand has ended |
If the live wall is exhausted before anyone wins, the hand ends in an exhaustive draw.
Scoring
A winning hand is scored in fan (1 fan = 1 point), Chinese Classical style. The engine awards:
| Fan | Points |
|---|---|
| Base win | 1 |
| Self-drawn win (tsumo) | +1 |
| All chows | +1 |
| All pungs | +3 |
| Each dragon triplet | +2 |
| Seat-wind triplet | +2 |
| Round-wind triplet | +2 |
| Half flush (one suit plus honours) | +1 |
| Pure flush (a single suit) | +3 |
| All terminals and honours | +2 |
Scores accumulate on each player across hands; there is no separate money settlement.
Turn Sheets
| Sheet | Purpose |
|---|---|
mahjong_game_join_game | Sent when a player joins; confirms their seat, and (when the run allows it) lets them invite other players and add computer opponents |
mahjong_game_draw_discard | The active player's sheet — draw and then discard, declare tsumo, or declare a kong |
mahjong_game_claim | The reactive sheet — pass, chow, pung, kong, or ron on the current discard |
mahjong_game_recap | Read-only summary of the completed hand |
Because Mahjong processes as soon as the required sheets are submitted, play moves on without waiting for a shared deadline.
Seeing what happened between your turns
At a physical table you watch every discard and claim as it happens. Because Mahjong is played by post, your draw / discard and claim sheets rebuild that view for you. Each of those sheets shows:
- The Table — a bird's-eye view of the board, drawn as a felt table with the four seats around a central wall and you at the bottom. It shows every seat's discard pond and exposed melds, the round wind, how many tiles are left to draw, and whose turn it is. Concealed hands are never shown — only what you would see across the table.
- Since Your Last Turn — a short recap of what the other seats did while you were away (for example, "West discarded 7-sou", "North claimed your 5-pin to form a pung"). Each item is shown once, then cleared.
Following the Game
The table can be viewed live through the management table view. The table state is read-only for spectating and rendering — all actions are taken through the turn sheets, never through a live API call. It shows the phase, the wall size (count only), the dealer seat, round wind, hand number, the discards, the last discard, and each player's seat wind, hand, melds, discards, and score.