Metadata-Version: 2.4
Name: hk-mahjong
Version: 0.1.0
Summary: Hong Kong style mahjong in the terminal — play against 3 AI opponents
Project-URL: Homepage, https://github.com/aidancorrell/hk-mahjong
Project-URL: Repository, https://github.com/aidancorrell/hk-mahjong
Project-URL: Issues, https://github.com/aidancorrell/hk-mahjong/issues
Author-email: Aidan <aidanslav@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,game,hong-kong,mahjong,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.11
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# HK Mahjong

A terminal-based Hong Kong style mahjong game. Play against 3 AI opponents in your terminal.

## Features

- Full Hong Kong mahjong rules (4-player)
- Switchable Unicode/ASCII tile rendering (press `r` during game)
- Shanten-based AI opponents
- HK faan scoring with 3-faan minimum
- Special hands: Thirteen Orphans, Nine Gates, Great Dragons/Winds, and more

## Installation

```bash
pip install .
```

## Usage

```bash
# Run with Unicode tiles (default)
hk-mahjong

# Run with ASCII tiles
hk-mahjong --ascii

# Run as module
python -m hk_mahjong

# Reproducible game with seed
hk-mahjong --seed 42
```

## Controls

| Key | Action |
|-----|--------|
| `←` / `→` | Select tile |
| `Enter` | Confirm discard |
| `w` | Declare win |
| `p` | Claim pong |
| `k` | Claim/declare kong |
| `c` | Claim chow |
| `n` | Pass (skip claim) |
| `r` | Toggle Unicode/ASCII rendering |
| `q` | Quit |

## Scoring (Hong Kong Faan)

Minimum 3 faan required to win. Limit hand = 13 faan.

| Pattern | Faan |
|---------|------|
| Dragon Pong | 1 |
| Seat/Prevailing Wind | 1 each |
| Self Drawn | 1 |
| No Flowers | 1 |
| Fully Concealed | 1 |
| All Pongs | 3 |
| Mixed One Suit | 3 |
| Pure One Suit | 7 |
| Thirteen Orphans | 13 (limit) |
| Great Dragons | 13 (limit) |
| Great Winds | 13 (limit) |
| All Honors | 13 (limit) |
| Nine Gates | 13 (limit) |

## Development

```bash
# Install dev dependencies
pip install -e . pytest ruff mypy

# Run tests
pytest

# Lint
ruff check src/

# Type check
mypy src/
```

## License

MIT
