Metadata-Version: 2.4
Name: mahjax
Version: 0.3.0
Summary: GPU-accelerated vectorized mahjong simulators for reinforcement learning
Author-email: Soichiro Nishimori <gatikiti.630@gmail.com>
License-Expression: Apache-2.0
Project-URL: Source, https://github.com/nissymori/mahjax
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.128.0
Requires-Dist: jax>=0.4.28
Requires-Dist: typing-extensions>=4.2.0
Requires-Dist: uvicorn>=0.39.0
Dynamic: license-file

<div align="center">
<img src="https://raw.githubusercontent.com/nissymori/mahjax/main/docs/assets/logo.svg" width="35%">
</div>

<br>

<div align="center">
  <img src="https://raw.githubusercontent.com/nissymori/mahjax/main/docs/assets/red_mahjong_random_ja.gif" width="46%">
  <img src="https://raw.githubusercontent.com/nissymori/mahjax/main/docs/assets/red_mahjong_random_en.gif" width="46%">
</div>

# MahJax

[![PyPI](https://img.shields.io/pypi/v/mahjax.svg)](https://pypi.org/project/mahjax)
[![License](https://img.shields.io/pypi/l/mahjax.svg)](https://pypi.org/project/mahjax)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/mahjax.svg)](https://pypi.org/project/mahjax)
[![arXiv](https://img.shields.io/badge/arXiv-2605.20577-b31b1b.svg)](https://arxiv.org/abs/2605.20577)
[![Documentation](https://img.shields.io/badge/docs-available-8CA1AF?logo=readthedocs&logoColor=fff)](https://nissymori.github.io/mahjax/)

**A GPU-Accelerated Mahjong Simulator for Reinforcement Learning in [JAX](https://github.com/google/jax)**

> [!NOTE]
> Japanese Riichi Mahjong is a challenging multi-agent RL environment with *imperfect information*, *stochastic dynamics*, *more than two players*, and *high-dimensional observations*.
> MahJax aims to make Mahjong research more accessible to a broader RL community.
> For newcomers, please see our [basic introduction](https://nissymori.github.io/mahjax/mahjong-basics/) and the *bilingual visualization*.


## Overview

- 🚀 **Vectorized Environment:** Extremely fast (approx. **1M+ steps/sec** on 8x A100 GPUs).
- 🎨 **Rich Visualization:** a browser UI that also plays states back in notebooks, with bilingual tiles **for those unfamiliar with Kanji**.
- 🎮 **Playable Interface:** A web-based UI allows you to play directly against the agents you train.
- 📚 **RL Examples:** Simple examples for Behavior Cloning + PPO in the [`examples/`](https://github.com/nissymori/mahjax/tree/main/examples).

For more details, please refer to the [Documentation](https://nissymori.github.io/mahjax/).

## Quick Start
### Install
MahJax is available on PyPI. Please make sure that your Python environment has `jax` and `jaxlib` installed, depending on your hardware setup.
```bash
pip install mahjax
```

📣 MahJax is currently under active development. If you prefer to use the latest codebase with the newest features, please clone the repository and install it in editable mode:

```bash
git clone https://github.com/nissymori/mahjax.git
cd mahjax
pip install -e .
```

> [!NOTE]
> The current API is still provisional and under active development, so it may change in future releases.

### Basic Usage
We basically follow the [Pgx](https://github.com/sotetsuk/pgx) API design.

```python
import jax
import jax.numpy as jnp
import mahjax
from mahjax.ui import save_html

batch_size = 10
rng = jax.random.PRNGKey(0)

# Initialize environment
env = mahjax.make(
    "red_4p",
    round_mode="single", # "single", "east" (tonpuusen), or "half" (hanchan)
    observe_type="dict", # "dict" for Transformer, "2D" for CNN
    order_points=[0, 0, 0, 0], # Final score bonuses (uma), in hundreds of points
)

init_fn = jax.jit(jax.vmap(env.init))
step_fn = jax.jit(jax.vmap(env.step))
obs_fn = jax.jit(jax.vmap(env.observe))

# Initialize state
rng, subrng = jax.random.split(rng)
rngs = jax.random.split(subrng, batch_size)
state = init_fn(rngs)

# Step
rng, subrng = jax.random.split(rng)
rngs = jax.random.split(subrng, batch_size)
action = jnp.zeros((batch_size,), dtype=jnp.int8)
state = step_fn(state, action, rngs)

# Get observation
obs = obs_fn(state)

# Visualize the first game of the batch as a page that any browser opens
# (in a notebook, mahjax.ui.show draws it in the cell's output)
save_html(jax.tree_util.tree_map(lambda x: x[0], state), "state.html")
```

## User interface
MahJax includes a web-based UI (FastAPI + JS) that allows you to play against built-in or custom agents directly in your browser.

### Running the UI

Install MahJax and start the server:
```bash
pip install mahjax
uvicorn mahjax.ui.app:create_app --factory --host 127.0.0.1 --port 8000
```
Open http://localhost:8000 to play. The bundled agents are `rule_based` and `random`. Saved games can be replayed from the menu. `mahjax.ui.show(states)` plays back states from Python with no server, in a notebook or as one HTML file. See the [UI guide](https://nissymori.github.io/mahjax/ui/).

### Playing Against Your Agent
Register your agent's `act(state, key) -> action` on the app before serving it:

```py
### my_ui_app.py
from mahjax.ui.app import create_app

from my_agent import act

app = create_app()
app.state.registry.add_agent(name="My agent", act=act, description="A trained policy")
```
Run `uvicorn my_ui_app:app --port 8000`.

## Supported Rules

Currently, MahJax supports the following rules:

| Rule | id | Status | Code | Speed (steps/sec) |
|------|------|--------|------|--------|
| No-Red Mahjong | `no_red_4p` | ✅ | [mahjong_4p](https://github.com/nissymori/mahjax/tree/main/mahjax/mahjong_4p) with `NO_RED` | ≈ `red_4p` |
| Red Mahjong | `red_4p` | ✅ | [mahjong_4p](https://github.com/nissymori/mahjax/tree/main/mahjax/mahjong_4p) | ~1M |
| No-Red Mahjong (3-player) | `no_red_3p` | ✅ | [mahjong_3p](https://github.com/nissymori/mahjax/tree/main/mahjax/mahjong_3p) with `NO_RED` | - |
| Red Mahjong (3-player) | `red_3p` | ✅ | [mahjong_3p](https://github.com/nissymori/mahjax/tree/main/mahjax/mahjong_3p) | - |
| Selective Rules | - | 🚧 | - | - |

`red_4p` implements standard 4-player riichi mahjong with red fives.
Its rules are designed to follow [Tenhou](https://tenhou.net/), one of the most widely used online mahjong platforms in Japan, and we validate the implementation against downloaded Tenhou game logs.
For the detailed rule specification, see the [official Tenhou rules](https://tenhou.net/0/mj/mjlog/en/mjlog-en-rules.html).

`no_red_4p` is `red_4p` with the `NO_RED` rule preset: no red fives, no double ron, no pao and no special abortive draws (`特殊流局`).
It runs on the same engine and has the same observation and action space as `red_4p`.

`red_3p` is 3-player riichi mahjong (三人麻雀) with red fives, following Tenhou's 3-player rules: no 2m–8m, no chi, and norths set aside as dora (北抜き).
`no_red_3p` is `red_3p` with the `NO_RED` preset. See [3-Player Mahjong](https://nissymori.github.io/mahjax/mahjong_3p/) for the details.

You can configure the environment with:

- `id`: the rule set: `red_4p`, `no_red_4p`, `red_3p` or `no_red_3p`
- `round_mode`: `single` for a single round, `east` for tonpuusen (East-only), or `half` for hanchan (East-South)
- `observe_type`: `dict` for transformer-style inputs or `2D` for CNN-style inputs
- `order_points`: final placement bonuses (uma), in hundreds of points like `score`. Defaults to no uma; pass `[300, 100, -100, -300]` for 10-30 uma

```python
env = mahjax.make(
    "red_4p",
    round_mode="single",
    observe_type="dict",
    order_points=[0, 0, 0, 0],
)
```

> [!NOTE]
> The observation features are not yet finalized (though the current version suffices for RL with BC; see [examples/](https://github.com/nissymori/mahjax/tree/main/examples)).


## See also

JAX-based environments
- [Pgx](https://github.com/sotetsuk/pgx): Board game environments such as Go, Chess, and Shogi.
- [Brax](https://github.com/google/brax): Robotics control.
- [Gymnax](https://github.com/RobertTLange/gymnax): Popular small-scale RL environments such as CartPole or bsuite.
- [Jumanji](https://github.com/instadeepai/jumanji): A diverse suite of RL environments (packing, routing, etc.).
- [Craftax](https://arxiv.org/abs/2402.16801): A JAX version of Crafter + Nethack.
- [JaxMARL](https://github.com/FLAIROx/JaxMARL): Multi-agent environments such as Hanabi.
- [Navix](https://github.com/epignatelli/navix): A JAX version of MiniGrid.

## Cite us
```bibtex
@article{nishimori2026mahjax,
  title         = {Mahjax: A GPU-Accelerated Mahjong Simulator for Reinforcement Learning in JAX},
  author        = {Nishimori, Soichiro and Okano, Shinri and Habara, Keigo and Koyamada, Sotetsu and Yu, Eason and Sugiyama, Masashi},
  journal       = {arXiv preprint arXiv:2605.20577},
  year          = {2026},
}
```

## Acknowledgement
- [sotetsuk](https://github.com/sotetsuk): For general advice on the development of MahJax based on his experience developing pgx.
- [habara-k](https://github.com/habara-k): For developing core JAX components such as shanten and Yaku calculation.
- [OkanoShinri](https://github.com/OkanoShinri): For the initial implementation of MahJax and its SVG visualization.
- [easonyu0203](https://github.com/easonyu0203): For advice on PPO implementation in a multi-player imperfect-information game.
