麻将 - C++ 日麻实现

项目说明

pymahjong

![PyPI ]()
![Python ]()
![Documentation]()
![Build Status]()

A Japanese Riichi 麻将 en for decision AI research, featuring a high-performance C++ backend with Python bindings.

Features

Complete Rule Implementation - Full Japanese Riichi 麻将 rules including all standard yaku

Gymnasium Compatible - Ready-to-use single-agent en with pretrained opponents

Multi-agent Support - 4-player en for multi-agent research

Oracle Obser - Access to hidden information (opponents' hands) for oracle-guided learning

High Performance - C++ 游戏 引擎 with efficient Python bindings

Cross-platform - Pre-built wheels for Linux, macOS, and Windows (Python 3.10-3.14)

Installation

Using uv (recommended):

Or using pip:

the installation:

Quick Start

Single-Agent En

Play against 3 opponents with a gym-like interface:

Multi-Agent En

4 agents compete in a full game:

Documentation

Full documentation is a at

Installation Guide

Quick Start

Live Demo — try it in your browser

API Reference

Ad Topics

(Web UI)

A full-featured web interface is included for human vs AI, 4-AI battle, and paipu replay.

Then open in your browser:

| Page | Route | Description |
|------|-------|-------------|
| Human vs AI | / | Play against 3 AI opponents |
| 4 AI Battle | /ai_battle | Watch 4 AI agents compete in real time |
| Paipu Replay | /replay | Step through a Tenhou XML paipu file |

For a quick preview without installing, see the Live Demo (embedded in the documentation).

Pretrained Models

Pretrained opponent models are a from the GitHub releases:

Offline Dataset

Human demonstration data from Tenhou.net (6 dan+ players) is a for offline RL research. Download from releases.

Incremental paipu pipeline

To build your own training cache from raw Tenhou paipu, use the resumable
pipeline driven by a single append-only manifest:

Properties:

Resumable: re-running run is a no-op once e is encoded.

Each shard is flushed atomically and only then recorded in the manifest,
so a crash mid-shard simply re-encodes the affected paipu next time.

Integrity: every paipu is hashed with sha256 on every startup and

compared against the manifest; identical content under different 游戏
ids is recorded as duplicate and the redundant XML is removed.

Self-healing: check --repair deletes corrupt XMLs and emits

corrupt events; the next run will re-fetch / re-encode them.

Hand-dropped XMLs: drop files into <work>/xml/<game_id>.txt and

they will be adopted automatically.

See docs/ad/paipu_pipeline.md
for the full manifest schema, layout on disk, and recovery flows.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Project Policies

Contribution guide: CONTRIBUTING.md

Security policy: SECURITY.md

Bug reports and feature requests: GitHub Issues

Citing

If you use pymahjong in your research, please cite:

License

This project is licensed under the Apache License 2.0.

Contact

Email:

QQ Group: 608064044

Acknowledgements

The shanten rewrite prompted by issue #30 benefited from the practical feedback by Apricot-S, who explicitly called out the limitations of meld/taatsu-counting shortcuts and pointed to stronger exact approaches.

When re the design, I also consulted the following open-源码 repositories as algorithm references and prior art surveys. No 代码 from them is into this repository, but they were useful in e tradeoffs, testing strategy, and direction:

tomohxx/shanten-number

Cryolite/nyanten

Apricot-S/xiangting

MahjongRepository/mahjong

技术栈

开发语言：Python

项目类型：C++ 日麻实现

Star 数：135

功能特点

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

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

部署说明

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

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

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

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

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

学习价值

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

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

免责声明

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