This repository provides tools and datasets for converting Tenhou mahjong game logs into the MJAI format, as well as tools for downloading and converting Mahjong Soul (雀魂) game records. It also includes preprocessed yearly Tenhou datasets for AI research, data analysis, and mahjong strategy modeling.

• Dataset Overview
• Release Structure
• Understanding the MJAI Format
• Tools
• Preparing Your Own Dataset
• Licenses
• Attribution

Complete collection of Tenhou phoenix room (鳳凰卓) game logs in MJAI format, spanning 2009–2026.

Total: ~12GB, 18 yearly archives, 2.5M+ games

All datasets contain only 4-player (四人麻雀) hanchan (半荘戦) games from the houou (phoenix) room. No 3-player or tonpuu (東風戦) matches are included.

Example structure of a yearly dataset:

2024.zip
 └── 2024/
     ├── 2024010100gm-00a9-0000-005a39ba.mjson
     ├── 2024010100gm-00a9-0000-00abc123.mjson
     └── ...

Each release also includes a corresponding YYYY.db file containing Tenhou game metadata.

The .mjson files use the MJAI protocol, a standard for Mahjong AI communication. Each file contains a sequence of JSON objects, with one object per line, representing the events of a single game.

Tiles are represented using the following string format:

Each JSON object has a type field that describes the game event. Here are some of the most common events you will find in the logs:

• start_kyoku: Signals the start of a new round.

  • Provides initial state: round wind (bakaze), round number (kyoku), dealer (oya), dora indicator (dora_marker), and each player's starting hand (tehais).
  • {"type":"start_kyoku","bakaze":"E","kyoku":1,"oya":0,"dora_marker":"7s", ...}

• tsumo: A player draws a tile from the wall.

  • actor is the player's ID (0-3). pai is the tile drawn.
  • {"type":"tsumo","actor":1,"pai":"3m"}

• dahai: A player discards a tile.

  • tsumogiri is true if the discarded tile was the one just drawn.
  • {"type":"dahai","actor":1,"pai":"7s","tsumogiri":false}

• pon / chi / daiminkan: A player makes an open call from another player's discard.

  • actor is the caller, target is the player who was called on. pai is the called tile, and consumed are the tiles from the actor's hand used to make the call.
  • {"type":"pon","actor":0,"target":1,"pai":"5sr","consumed":["5s","5s"]}

• ankan / kakan: A player makes a closed or added kan.

  • {"type":"ankan","actor":1,"consumed":["N","N","N","N"]}

• reach_accepted: A player's Riichi declaration is accepted.

  • Shows the 1000-point payment and updated scores.
  • {"type":"reach_accepted","actor":1,"deltas":[0,-1000,0,0], ...}

• hora: A player wins the hand (Tsumo or Ron).

  • Contains full win details: winning tile (pai), yaku (yakus), fu, fan, points (hora_points), score changes (deltas), and ura-dora indicators (uradora_markers).
  • {"type":"hora","actor":2,"target":2,"pai":"2m", ...}

• ryukyoku: The round ends in a draw.

  • Specifies the reason (reason) and score changes.
  • {"type":"ryukyoku","reason":"fanpai", ...}

For a complete and authoritative reference, please see the original MJAI Protocol Documentation (in Japanese).

git clone https://github.com/NikkeTryHard/tenhou-to-mjai.git
cd tenhou-to-mjai
cargo build --release

Main CLI binary for both Tenhou and Majsoul pipelines.

Quick start (Tenhou):

tenhou-scraper fetch --start 20250101 --end 20251231
tenhou-scraper download
tenhou-scraper convert --output mjai/ --players 4 --hanchan
tenhou-scraper package --input mjai/ --output houou-2025.zip

Multi-account Majsoul downloader and protobuf converter. See docs/tensoul-download.md.

cd tensoul-download && uv sync
uv run python async_downloader.py --accounts accounts.txt --password "pass" --todo todo.txt
uv run python convert_pb.py

Streaming validator for MJAI dataset archives. Validates all files inside .tar.zst archives without extracting to disk. See docs/mjai-validator.md.

cd dataset/mjai-validator && cargo build --release
mjai-validator /path/to/dataset/mjai     # validate
mjai-validator --clean /path/to/dataset  # remove invalid files

To build your own dataset from Tenhou logs, follow this multi-stage conversion process:

Obtain Tenhou logs from official sources or your own game archive. These will be in .xml format.

First, convert the raw Tenhou XML logs into an intermediate JSON format using a tool like mjlog2json.

# This creates a directory of .json files from your .xml files
mjlog2json "C:\path\to\tenhou_xml\2024" -o "C:\path\to\tenhou_json\2024"

Next, use the convlog utility from the mjai-reviewer repository to convert the JSON files into the final MJAI format. This will produce uncompressed .mjson files.

# Assuming you are in the mjai-reviewer project directory
# This converts .json files into uncompressed .mjson files
cargo run --release --bin convlog -- "C:\path\to\tenhou_json\2024" "C:\path\to\tenhou_mjai\2024"

Navigate to the output directory (e.g., tenhou_mjai/2024) and compress each .mjson file individually using gzip.

# This will compress each file, creating a .mjson.gz file and deleting the original
gzip *.mjson

Once the files are compressed and correctly named, create yearly zip archives.

# Example: zipping the 2024 folder
zip -r 2024.zip 2024

Keep the Tenhou .db file alongside the yearly archive for metadata reference.

This project’s code is licensed under the Apache License 2.0. See LICENSE for details.

The datasets are licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). See DATA_LICENSE for details. You may redistribute, remix, and build upon the data with proper attribution.

Data is derived from:

• Tenhou.net (天鳳) — Phoenix room (鳳凰卓) game logs

This dataset was prepared using the following open-source tools. We extend our gratitude to their authors and contributors.

• Mortal: https://github.com/Equim-chan/Mortal - The target AI engine for the MJAI format.
• mjai-reviewer: https://github.com/Equim-chan/mjai-reviewer - Specifically, the convlog utility for JSON to MJAI conversion.
• mjlog2json: https://github.com/tsubakisakura/mjlog2json - For converting raw Tenhou XML logs to JSON.
• Amae-Koromo: https://amae-koromo.sapk.ch - Mahjong Soul game record API.
• tensoul-py-ng: https://github.com/unStatiK/tensoul-py-ng - Majsoul protobuf to Tenhou JSON converter.

All rights to original game data remain with their respective owners. Converted datasets are redistributed for research and educational use under CC BY 4.0.