Metadata-Version: 2.2
Name: mahjong-learner
Version: 0.1.0
Summary: Offline riichi mahjong learning tools, drills, and desktop games
Keywords: mahjong,riichi,tkinter,learning,desktop
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Natural Language :: Japanese
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: THIRD_PARTY_NOTICES.txt
Requires-Dist: Pillow>=9.1
Requires-Dist: torch>=2.2

# 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

```sh
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.0

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