mahjax - GPU 加速麻将模拟器

项目说明

<di="center">
<img src=" width="35%">
</div>

<br>

<di="center">
<img src=" width="46%">
<img src=" width="46%">
</div>

MahJax

![PyPI]()
![License]()
![Supported Python ]()
![arXiv]()
![Documentation]()

A GPU-Accelerated 麻将 Simulator for Reinforcement Learning in JAX

> [!NOTE]
> Japanese Riichi 麻将 is a challenging multi-agent RL en with *imperfect information*, *stochastic dynamics*, *more than two players*, and *high-dimensional obser*.
> MahJax aims to make 麻将 research more accessible to a broader RL community.
> For newcomers, please see our basic introduction and the *bilingual *.

O

🚀 En: Extremely fast (approx. 1M+ steps/sec on 8x A100 GPUs).

🎨 Rich : S 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 a on PyPI. Please make sure that your Python en has jax and jaxlib installed, depending on your hardware setup.

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

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

Basic Usage

We basically follow the Pgx API design.

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 服务端:

Open 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:

Run u 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_mahjong | ✅ | no_red_mahjong | ~2M |
| Red Mahjong | red_mahjong | ✅ | red_mahjong | ~1M |
| Selecti | - | 🚧 | - | - |
| 3-player Mahjong | - | 🚧 | - | - |

red_mahjong implements standard 4-player riichi 麻将 with red fives.
Its rules are designed to follow Tenhou, one of the most widely used online 麻将 platforms in Japan, and we the implementation against downloaded Tenhou 游戏 logs.
For the detailed rule specification, see the official Tenhou rules.

no_red_mahjong implements 4-player riichi 麻将 without red fives.
This is intentionally simplified for speed, and excludes some rules such as aborti (特殊流局), pao, and double ron.
If throughput is your priority, no_red_mahjong is the recommended option (roughly 2x faster).

You can configure the en with:

id: the rule set, such as red_mahjong or no_red_mahjong

round_mode: single for a single round, east for tonpuusen (East-only), or half for hanchan (East-South)

obser: 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

> [!NOTE]
> The obser features are not yet finalized (though the current suffices for RL with BC; see examples/).

See also

JAX-based en

Pgx: Board 游戏 en such as Go, 象棋, and Shogi.

Brax: Robotics control.

Gymnax: Popular small-scale RL en such as CartPole or bsuite.

Jumanji: A diverse suite of RL en (packing, routing, etc.).

Craftax: A JAX of Crafter + Nethack.

JaxMARL: Multi-agent en such as Hanabi.

Navix: A JAX of MiniGrid.

Cite us

Acknowledgement

sotetsuk: For general advice on the de of MahJax based on his experience de pgx.

habara-k: For de core JAX components such as shanten and Yaku calculation.

OkanoShinri: For the initial implementation of MahJax and its S.

easonyu0203: For advice on PPO implementation in a multi-player imperfect-information 游戏.

技术栈

开发语言：Python

项目类型：GPU 加速麻将模拟器

Star 数：70

功能特点

这是一套GPU 加速麻将模拟器，代码结构清晰，适合开发者学习游戏的客户端渲染、服务端逻辑、场景管理与资源加载。项目涵盖了游戏的核心玩法、界面交互、地图与角色系统等模块，对理解游戏开发的完整流程具有较高的参考价值。

从技术实现角度看，游戏项目的难点在于：游戏循环与状态管理、资源加载与渲染优化、客户端与服务端的协议同步、以及多平台适配。本项目在这些方面提供了可运行的实现，开发者可以在此基础上进行二次开发或学习研究。

部署说明

1. 下载源码压缩包，解压到本地开发环境。

2. 根据项目类型准备对应的运行环境（Node.js / Go / C# / Unity / Godot 等）。

3. 按照 README 中的步骤配置依赖、数据库和配置文件。

4. 先启动服务端，再运行客户端，即可进入游戏进行测试。

注意：本项目仅供学习研究使用，请勿用于商业或非法用途。

学习价值

对于想进入游戏开发领域的开发者来说，这套源码是一个很好的入门参考。通过阅读代码，可以学习到游戏的核心玩法实现、场景与资源管理、网络协议设计、以及渲染优化等关键技术点。

同时，项目中的代码组织方式和模块划分，也展示了游戏项目在工程化方面的实践经验，值得开发者深入研究和借鉴。理解一个完整游戏项目的架构，对后续开发其他类型游戏也很有帮助。

免责声明

本资源来源于开源社区，仅供学习研究和技术交流使用，请勿用于任何商业或违法违规用途。使用本项目产生的一切后果由使用者自行承担。若涉及第三方权益，请联系删除。