About
Mortal is a powerful, open source AI for Japanese Mahjong (Riichi Mahjong) that leverages deep reinforcement learning to achieve professional-level play. Licensed under the GNU AGPL v3, the project is fully open and hosted on GitHub, inviting contributions from data scientists, Rust developers, designers, and mahjong players alike. At its core, Mortal is compatible with Tenhou's standard ranked rules for four-player mahjong and can be used both as a standalone AI opponent and as a review engine backend through the mjai-reviewer integration. Its Rust-based emulator (libriichi) is extraordinarily efficient — capable of simulating up to 40,000 hanchans per hour on modern hardware — while exposing a clean Python interface for neural network inference. The mjai protocol interface makes Mortal straightforward to plug into existing mahjong tooling. Users can run Mortal via Docker for quick deployment, run head-to-head emulation experiments (Mortal vs. Mortal, Mortal vs. akochan), and even train their own models using the provided offline and online training pipelines with pre-trained weights available as a starting point. Mortal is ideal for mahjong AI researchers studying reinforcement learning in imperfect-information games, competitive players who want deep post-game analysis, and developers building mahjong tools or bots. Its combination of strong playing strength, speed, and open architecture makes it one of the most capable and transparent mahjong AIs publicly available.
Key Features
- Deep Reinforcement Learning Engine: Mortal is trained via deep RL and plays at a strong level compatible with Tenhou's standard four-player ranked rules.
- Blazing-Fast Rust Emulator: libriichi is a Mahjong emulator written in Rust with a Python interface, capable of simulating up to 40,000 hanchans per hour on high-end hardware.
- mjai Protocol Interface: Mortal supports the mjai protocol, making it easy to integrate with existing mahjong tooling and use as a review backend for mjai-reviewer.
- Custom Model Training: Full training pipeline available with pre-trained model weights, offline and online training phases, and configurable hyperparameters.
- Docker Quick Start: Get Mortal running in minutes using the official Docker setup, with no need to compile Rust or configure complex environments from scratch.
Use Cases
- Competitive Mahjong players using Mortal as a post-game review tool to identify strategic mistakes and improve their play.
- AI researchers studying deep reinforcement learning in imperfect-information games using Mortal as a benchmark or baseline model.
- Developers building Mahjong bots or tools who need a reliable, fast AI backend compatible with the mjai protocol.
- Academics and students exploring game AI, running controlled simulations between Mortal and other AIs like akochan.
- Open source contributors looking to extend Mortal's capabilities in Rust, Python, or by providing new training data from real game logs.
Pros
- Completely Free and Open Source: Released under GNU AGPL v3, Mortal's full codebase — including training infrastructure and model architecture — is publicly available on GitHub.
- Exceptional Simulation Speed: The Rust-based emulator achieves up to 40K hanchans/hour, enabling rapid large-scale training and experimentation.
- Strong Playing Strength: Benchmarked against other top mahjong AIs, Mortal demonstrates competitive performance at or near the level of top human players on Tenhou.
- Extensible and Well-Documented Architecture: Modular design with clear separation of components (libriichi, mjai interface, emulator) makes it easy for contributors to extend or audit.
Cons
- Documentation Still in Progress: Many sections of the official documentation are incomplete or placeholder, making onboarding harder for new contributors.
- Requires Technical Expertise to Self-Host: Running or training Mortal locally requires familiarity with Docker, Rust, and Python ML workflows, which may be a barrier for casual users.
- Narrow Domain Applicability: Mortal is purpose-built for Japanese Mahjong (Riichi), so it has no utility outside this specific game variant.
Frequently Asked Questions
What type of Mahjong does Mortal support?
Mortal is designed specifically for Japanese Mahjong (Riichi Mahjong) and is compatible with Tenhou's standard four-player ranked rules.
Is Mortal free to use?
Yes, Mortal is completely free and open source, licensed under the GNU Affero General Public License v3 (AGPL-3.0).
How do I get started with Mortal?
The easiest way is to use the Docker Quick Start guide in the documentation. For custom training or development, you can clone the GitHub repository and follow the build instructions.
Can I use Mortal to review my Mahjong games?
Yes, Mortal can serve as a backend for mjai-reviewer (previously akochan-reviewer), allowing you to get AI-powered analysis of your game logs.
Can I train my own model using Mortal?
Yes. Mortal provides a full training pipeline including pre-trained model weights, configurable training parameters, and both offline and online training phases. GPU hardware is recommended for efficient training.
