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)

uv venv
uv pip install -e .
uv run python main.py

Environment API

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

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

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

uv run python -m majiang_rl.ui.web --port 8000

Then open http://localhost:8000/index.html to watch the playback.

1.9 KiB Raw Permalink Blame History