Hong Kong Mahjong Replay Dataset

What is in the sample

The rules being played are Hong Kong old style with no flowers or seasons, a 136 tile wall, and either no faan minimum or a 3 faan minimum. The two rulesets behave very differently and are worth treating as separate distributions rather than pooling them. If you are not familiar with the scoring, the faan table and the rules guide cover what the hand keys mean.

File format

One JSON file containing a single array. Each element is one complete game. Fields that do not apply to a game are simply absent rather than null, so read defensively.

[
  {
    "game_id": "game_0001",
    "ruleset": "advanced",
    "min_fan": 3,
    "is_bootcamp": false,
    "is_draw": false,
    "move_count": 118,
    "winner_seat": 2,
    "win_by_self_draw": true,
    "players": [ { "seat": 0, "wind": "E", "name": "Seat 0" }, ... ],
    "moves":   [ { "seq": 0, "actor": 0, "phase": "draw", ... }, ... ],
    "winning_hand":    [ { "s": "dots", "r": 3 }, ... ],
    "score_breakdown": { "2": { "total": 4, "items": [ ... ] } },
    "final_scores":    { "0": -8, "1": -8, "2": 24, "3": -8 }
  },
  ...
]

Game fields

Move fields

Every element of moves is a full snapshot of what the acting player could see at that instant, followed by what they actually did. This is the part that makes the file usable as supervised training data without any replay reconstruction: each row is already a state and action pair.

One consequence is worth spelling out, because it is the most useful property of the file and it is easy to miss. Every row carries the complete concealed hand of the seat that is acting, and a hand can only change on that seat's own draw, discard or claim, all of which are rows. So all four hands are known at every instant of every game. Nothing has to be reconstructed. That means you can derive labels no player at the table could have had, for example exactly what each opponent was waiting on at the moment somebody chose to fold, which is the supervision that defence models normally have no source for.

Tile encoding

Every tile anywhere in the file is the same two key object: s for suit and r for rank.

There are no flower or season tiles. The wall is 136 tiles, four copies of each of the 34 types.

Loading it

import json, collections

games = json.load(open("game_replays_sample_anon.json"))

# Every discard decision on 3 faan minimum tables, excluding tutorials.
rows = [
    (m["hand"], m["others"], m["wall_remaining"], m["tile"])
    for g in games
    if g["ruleset"] == "advanced" and not g["is_bootcamp"]
    for m in g["moves"]
    if m["phase"] == "discard"
]
print(len(rows), "discard decisions")

# Claim decisions come with their own action mask.
claims = [m for g in games for m in g["moves"] if m["phase"] == "claim"]
print(collections.Counter(m["action"] for m in claims))

Anonymisation: what is deliberately not here

Nothing in the file identifies a player, a session or a date. Specifically, the following were removed before export and are not recoverable from what remains:

• Database identifiers and every player account or guest identifier.
• Player display names. All four seats are the literal strings Seat 0 to Seat 3.
• Creation dates and wall clock timestamps. Only per game relative offsets remain.
• Every marker of whether a seat was a human or a bot. That includes the obvious per player flag, the per move flag, the human and bot counts, and the identifier prefixes that leaked the same information through the score dictionary keys. The score dictionaries are re-keyed to seat index for this reason.

The bot labels being gone is worth stating plainly, because it is the field people ask for first. A mix of human and bot play is in here and you cannot separate it. That is a real limitation for anyone wanting to train only on human demonstrations, and it is the main open question on this release: whether a coarse, non identifying quality signal would be more useful than the current clean removal.

Known gaps

Stated up front rather than discovered by whoever loads the file first.

• The wall is not stored, only mostly recoverable. Every draw is logged in order and wall_remainingdrops by exactly one each time, so the drawn portion of the wall reconstructs exactly, and for the 25 games that ended with an exhausted wall the whole live wall reconstructs. Two things do not: the order of the 16 tile reserve that is held back and never drawn, and kong replacement tiles, which come out of that reserve without being logged as draw rows and have to be inferred by diffing the actor's hand across the kong. The practical cost is that exact counterfactual continuation past the real end of a won game is not possible, only sampling over orderings consistent with what was observed. Storing the wall outright is under consideration for a second release.
• Scoring coverage is incomplete. score_breakdown appears on 42 of the 75 wins and final_scores on 56 games. Earlier recordings predate those fields. Where a breakdown is present it is only for the winning seat.
• Skill level is mixed and unlabelled. This is not strong play and it is not consistent play. Treat it as a distribution of real decisions, not as a source of correct answers.
• No hand ordering guarantees. The hand array is in internal order, not sorted. Sort it yourself before comparing hands.
• One table variant only. No flowers, no seasons, one specific set of faan values. Records from a playgroup with different table rules will not be directly comparable, which is the deeper problem this format does not yet solve.

Feedback on the format is the point

This is a sample rather than a corpus. Before recording changes are made and a larger dump is produced, the format should be one other people can actually use. The questions that matter most: is the per decision snapshot the right unit, or would a compact event log plus a replayer be better? How should table rule variation be expressed so records from different playgroups stay comparable? And is the complete removal of bot labels the right call, or does it destroy more value than it protects?

If you have opinions, they are wanted before the next version rather than after it.

The games in this dataset came from real play

Every record here was produced by people playing Hong Kong mahjong in the app, against each other and against machine learning opponents trained on exactly this kind of data. It is free on both platforms.

Frequently asked questions

What is in the Hong Kong mahjong replay dataset?

100 complete games and 11,749 decision points. Each decision point records the acting seat, their full concealed hand, their melds, every opponent visible melds and discard pile, tiles left in the wall, the legal actions available at that moment and the action actually taken.

Can I tell which players were bots?

No. Every identifier, name and bot flag has been removed. Players appear only as seat 0 to seat 3 with their seat wind.

Does the dataset include the wall order?

Not directly, but most of it is recoverable. Every draw is logged in order, so the drawn portion of the wall reconstructs exactly, and for the 25 games that ended with an exhausted wall the entire live wall reconstructs. What cannot be recovered is the order of the 16 tile reserve that is never drawn. Storing the wall outright is under consideration for a second release.

What licence is the dataset released under?

Creative Commons Attribution 4.0. Commercial use, model training and redistribution are all fine, with credit.

Why does Hong Kong mahjong need an open dataset at all?

Riichi has twenty years of freely available Tenhou records, which is why almost all of the analytical literature on mahjong is riichi literature. Hong Kong old style has no equivalent archive, so every developer rebuilds a private corpus from scratch and none of it is comparable. This sample is a first attempt at a shared starting point.

Related articles