MahJax
A GPU-Accelerated Mahjong Simulator for Reinforcement Learning in JAX
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/.
For more details, please refer to the Documentation.
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.
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:
git clone https://github.com/nissymori/mahjax.git
cd mahjax
pip install -e .
Basic Usage
We basically follow the Pgx API design.
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:
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.
Playing Against Your Agent
Register your agent's act(state, key) -> action on the app before serving it:
### 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 with NO_RED |
≈ red_4p |
| Red Mahjong | red_4p |
✅ | mahjong_4p | ~1M |
| No-Red Mahjong (3-player) | no_red_3p |
✅ | mahjong_3p with NO_RED |
- |
| Red Mahjong (3-player) | red_3p |
✅ | mahjong_3p | - |
| Selective Rules | - | 🚧 | - | - |
red_4p implements standard 4-player riichi mahjong with red fives.
Its rules are designed to follow Tenhou, 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.
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 for the details.
You can configure the environment with:
id: the rule set:red_4p,no_red_4p,red_3porno_red_3pround_mode:singlefor a single round,eastfor tonpuusen (East-only), orhalffor hanchan (East-South)observe_type:dictfor transformer-style inputs or2Dfor CNN-style inputsorder_points: final placement bonuses (uma), in hundreds of points likescore. Defaults to no uma; pass[300, 100, -100, -300]for 10-30 uma
env = mahjax.make(
"red_4p",
round_mode="single",
observe_type="dict",
order_points=[0, 0, 0, 0],
)
See also
JAX-based environments
- Pgx: Board game environments such as Go, Chess, and Shogi.
- Brax: Robotics control.
- Gymnax: Popular small-scale RL environments such as CartPole or bsuite.
- Jumanji: A diverse suite of RL environments (packing, routing, etc.).
- Craftax: A JAX version of Crafter + Nethack.
- JaxMARL: Multi-agent environments such as Hanabi.
- Navix: A JAX version of MiniGrid.
Cite us
@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: For general advice on the development of MahJax based on his experience developing pgx.
- habara-k: For developing core JAX components such as shanten and Yaku calculation.
- OkanoShinri: For the initial implementation of MahJax and its SVG visualization.
- easonyu0203: For advice on PPO implementation in a multi-player imperfect-information game.
Metadata
Release files for mahjax 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mahjax-0.3.3.tar.gz | 1.2 MB | Without provenance | Details for mahjax-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mahjax-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for mahjax-0.3.3-py3-none-any.whl |
Total release size: 2.4 MB
Release files / mahjax-0.3.3.tar.gz
| Download URL | mahjax-0.3.3.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7484e0e45015ef3db8a87c1f85db4f32869d1f614a4d1240deafc3aee034c2c5
|
|
BLAKE2b-256 checksum How to use checksums |
84e25123b40209e9a572ae260c242a5b02ea50cc02c51cc9bdf661dbb0b0ec1d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.0
|
Release files / mahjax-0.3.3-py3-none-any.whl
| Download URL | mahjax-0.3.3-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4408a16a613a5a5af48dc0b095f9e28d33c9bf5f5737fad3dfdd9c5a6dd92f9
|
|
BLAKE2b-256 checksum How to use checksums |
46cafe5d1929adaa7711cc35fd299cf1e9b812372f881fcd45480a96d14ae5e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.0
|
Security for mahjax 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.