Skip to main content

MahJax

PyPI License Supported Python versions arXiv Documentation

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_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
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.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mahjax 0.3.2
File Size Uploaded Provenance Actions
mahjax-0.3.2.tar.gz 1.2 MB Without provenance Details for mahjax-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mahjax 0.3.2
File Interpreter ABI Platform Actions
mahjax-0.3.2-py3-none-any.whl Python 3 none any Details for mahjax-0.3.2-py3-none-any.whl

Total release size: 2.4 MB

Release files / mahjax-0.3.2.tar.gz

Download URL mahjax-0.3.2.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
853bcd8de0ca97eeb7116ba373456632cd6c2ae81df24e5208578006b2ecd0f2
BLAKE2b-256 checksum
How to use checksums
a320f24c0ddda83f7b1eb4ee635ee26f6dcee5e3d1690d05c15f14048bdf039d
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.2-py3-none-any.whl

Download URL mahjax-0.3.2-py3-none-any.whl
Size 1.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f32c93899d7ddb34d286bd4da6287280a762d3109be2039dff6035ff7e484b95
BLAKE2b-256 checksum
How to use checksums
84df7981c0f779fa4ad6f297982f4193c7eb53e5d7d0523c02fbcd3ad5076c48
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.2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page