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: SVG-based visualization with bilingual support 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 import save_svg

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 (save_svg renders a single, unbatched state)
single_state = env.init(jax.random.PRNGKey(1))
save_svg(
    single_state,
    "state.svg",
    tile_style="bilingual",  # default is "standard"
)

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 dependencies and start the server:

pip install mahjax
uvicorn mahjax.ui.app:create_app --host 0.0.0.0 --port 8000

Open http://localhost:8000 to start playing. The default agents are the random and rule_based ones.

Playing Against Your Agent

You can register your trained agent to appear in the UI's agent selector. Create a Python script (e.g., my_app.py) and register your agent's act function:

### my_app.py
from pathlib import Path
from mahjax.ui.app import create_app

app = create_app()

# Load your custom agent
app.state.manager.registry.load_callable_from_path(
    file_path=Path("path/to/my_agent.py"),
    attribute="act", # The function name to call: act(state, rng) -> action_id
    description="My Custom Agent",
)

Run uvicorn my_ui: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
Selective Rules - 🚧 - -
3-player Mahjong - 🚧 - -

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.

You can configure the environment with:

  • id: the rule set, such as red_4p or no_red_4p
  • 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.2.0

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.2.0
File Size Uploaded Provenance Actions
mahjax-0.2.0.tar.gz 1.0 MB Without provenance Details for mahjax-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 2.2 MB

Release files / mahjax-0.2.0.tar.gz

Download URL mahjax-0.2.0.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
8c5128acb63ecf10414fbe1dc140ed23c3edb4ee3687abe2da2308a3e662237d
BLAKE2b-256 checksum
How to use checksums
367de3cdd0dfa4ccdff5f908dad09701fda92cd49c19abe3fd4f40bcf0903307
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.2.0-py3-none-any.whl

Download URL mahjax-0.2.0-py3-none-any.whl
Size 1.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
dfa7bced09ead8066f54d857e5ab2ec51610a950cd1555d90730957a73b21c49
BLAKE2b-256 checksum
How to use checksums
5b1c4e4b19ca842cd902575338a7f7fc9c015c8aee85f27a5d1f39757126ac3f
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.2.0

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