65 lines
1.9 KiB
Markdown
65 lines
1.9 KiB
Markdown
# majiang-rl
|
|
|
|
A minimal Mahjong (Guobiao) simulation environment and reinforcement learning scaffold built on gymnasium.
|
|
|
|
## Features
|
|
- 4-player Guobiao tile set (144 tiles, including flowers)
|
|
- Draw/discard turn loop with flower replacement
|
|
- Basic calls: win (ron/tsumo), pong, chi, kong
|
|
- Win checking for standard hands, seven pairs, and thirteen orphans
|
|
- Gymnasium-style environment API with action masks (type/discard/pong/kong/chi)
|
|
- Simple RL loop and random agent
|
|
|
|
## Limitations
|
|
- No scoring or 8-fan enforcement
|
|
- NPC players use simple greedy claims and random discards
|
|
- No detailed round rules (winds/seat rotation, riichi, etc.)
|
|
|
|
## Quick start (uv)
|
|
```bash
|
|
uv venv
|
|
uv pip install -e .
|
|
uv run python main.py
|
|
```
|
|
|
|
## Environment API
|
|
```python
|
|
from majiang_rl import MahjongEnv
|
|
|
|
env = MahjongEnv()
|
|
obs, info = env.reset()
|
|
|
|
# action format
|
|
# type: 0 discard, 1 declare win, 2 declare kong, 3 pass, 4 declare pong, 5 declare chi
|
|
# tile: tile id (0-41)
|
|
# chi: 0 left, 1 middle, 2 right
|
|
action = {"type": 0, "tile": 0, "chi": 0}
|
|
obs, reward, terminated, truncated, info = env.step(action)
|
|
```
|
|
|
|
## RL scaffold
|
|
```python
|
|
from majiang_rl import MahjongEnv
|
|
from majiang_rl.rl import RandomAgent, run_training
|
|
|
|
env = MahjongEnv()
|
|
agent = RandomAgent()
|
|
results = run_training(env, agent, episodes=10)
|
|
print(results[0])
|
|
```
|
|
|
|
## GRPO self-play training
|
|
```bash
|
|
uv run python -m majiang_rl.rl.grpo --updates 20 --group-size 16 --device auto
|
|
uv run python -m majiang_rl.rl.grpo --updates 20 --group-size 16 --device auto --pong-reward 0.1 --closest-bonus 1.0
|
|
uv run python -m majiang_rl.rl.grpo --updates 20 --group-size 16 --device auto --swanlab --swanlab-project majiang-rl --swanlab-run-name grpo-demo
|
|
```
|
|
|
|
Reward uses a simplified fan breakdown (thirteen orphans, seven pairs, pure/half flush, all pungs, all honors).
|
|
|
|
## Simple web UI
|
|
```bash
|
|
uv run python -m majiang_rl.ui.web --port 8000
|
|
```
|
|
Then open `http://localhost:8000/index.html` to watch the playback.
|