Mahjong Learner / 麻将学习室

An offline Tkinter desktop application for learning four-player riichi mahjong. The interface is primarily Chinese, with Japanese mahjong terminology.

Install and run

python -m pip install mahjong-learner
mahjong-learner

Alternatively use python -m mahjong_learner. Run mahjong-learner --help for direct tool shortcuts, for example mahjong-learner --tool point-drill.

Python 3.10 or newer, Tcl/Tk, and a graphical desktop are required. On Windows, use a Python installation that includes Tcl/Tk. Linux users may need their distribution's python3-tk package. This is not a browser or headless application. The release was verified on Windows with Python 3.12. PyTorch is a runtime dependency for the existing four-player game engine; the download can be large even though no trained weights are distributed.

Nine tools

• Four-player east-round game against rule-based AI.
• AI spectator mode with pause and speed controls.
• Tile-efficiency practice with discard and acceptance analysis.
• Hand score calculator with waits, yaku, han, fu, and payments.
• Fu calculation practice.
• Yaku identification quiz.
• Point calculation practice: han/fu, dealer/non-dealer, ron/tsumo, answer explanations, and session accuracy statistics.
• Seventeen-step mahjong.
• Two-player wait-guessing game inspired by Ten, using the rules shown in the application rather than claiming a complete manga reproduction.

Scoring does not use kiriage mangan: 3 han 60 fu and 4 han 30 fu remain below mangan. Point drills use four-player payments, zero honba, and no riichi sticks. The rules are project-specific and are not a certified tournament ruleset.

Data and model files

The package contains the local tile artwork and works offline after installation. No trained .pt checkpoints, local credentials, or user practice data are included. Missing neural checkpoints use the existing rule-based AI strategies. Tile artwork comes from FluffyStuff/riichi-mahjong-tiles and is dedicated to the public domain under CC0; see the bundled THIRD_PARTY_NOTICES.txt.

0.1.1

The hand calculator now supports separate dora and ura-dora indicator inputs, with tile previews, removal, clearing, and undo. Enter indicators, not the actual bonus tiles. Ura-dora scores only with closed-hand riichi or double riichi. Known indicators count toward the four-copy limit and reduce remaining waits and acceptance counts. Ordinary dora and ura-dora appear separately in the score.

0.1.0

First PyPI release: nine desktop tools, shared scoring and rule fixes, light UI theme, responsive layouts, and local point-calculation exercises.