卡纳雀 - 日麻 AI 框架

项目说明

*"It's time to get me in."* - Kana Ikeda

kanachan

Announcements

Brief Guide

This repository provides an annotation 工具 for 游戏 records of 麻将 Soul, and programs training some types of 麻将 AI models. However, this repository does not provide any crawler for 游戏 records of 麻将 Soul, any training data, nor any trained models. Therefore, users are assumed to prepare their own training data and computation resources.

The first thing users should do in order to use this repository is to collect 游戏 records of 麻将 Soul. The format of 游戏 records must be the same as the WebSocket response message that is returned from the 麻将 Soul API 服务端 when you hit a URL of the format . Data in this format can be obtained by capturing WebSocket messages exchanged with the 麻将 Soul's API 服务端, using a 网络 sniffering tools such as mitmproxy or Wireshark, browser extensions, or other tools. Again, this repository does not include such a 工具. Therefore, please look for one on 代码 hosting services including GitHub, or implement one yourself.

After collecting 游戏 records, the next step is to use annotate to convert the 游戏 records into annotations in a format suitable for learning.

Finally, the trained model can be obtained by running the training programs under the kanachan Python module with the annotations as input.

Goal of This Project

The goal of this project is to create a 麻将 AI for a of rules of 4-player Japanese Riichi 麻将 that can beat existing top-tier 麻将 AIs, including NAGA and Suphx, and even top professional human players.

This project is a personal one by myself. This is in contrast to some of the top 麻将 AI projects today, which are run by corporations. This project is also intended to show the world that top-class 麻将 AI can be built by personal projects.

Currently, Japanese chess (Shogi, 将棋) AI has been already considered to be far superior to the level of top human professionals. I believe that the driving force behind this situation in Japanese 象棋 is the fierce competition among Shogi AI by personal projects. I expect for this project to be a pioneer to cause such situation in the field of 麻将 AI, too.

Key Features of This Project

Extremely Large Data Set from 麻将 Soul

This project supposes to use 游戏 record (牌譜) data set crawled from 麻将 Soul. This would become an extremely large data set, which differs in order of magnitude in both quantity and generation speed from the existing representative, i.e., the one from the Phoenix Table (houou-taku, 鳳凰卓) of Tenhou (天鳳).

Let me show you concrete numbers. 游戏 records consisting of 17 million rounds, which were generated in 11 years from 2009 to 2019, can be obtained from the Phoenix Table of Tenhou. On the other hand, I have been crawling 游戏 records from 麻将 Soul since July 2020, and the amount of 游戏 records for 4-player 麻将 played in the Gold Room (kin-no-ma, 金の間) or the higher rooms has reached about 65 million rounds as of the end of August 2021. This number will surely surpass 100 million rounds by the end of 2021.

This critical difference in data will allow us to use models that are orders of magnitude larger and/or more powerfully expressive than those used in existing 麻将 AIs. For example, while NAGA and Suphx ha the ResNet with the Tenhou dataset, this project aims to take ad of the huge amount of data to train large scale models based on more powerfully expressi (e.g., transformer).

No Human-crafted Features

The inputs to models in this project, the features in other words, are almost devoid of processing based on human experience and intuition about 麻将. All tiles are represented as mere tokens, which are indexes to the corresponding embeddings. The token representing the 1 Circle (一筒) tile is not directly associated with the number "1", nor it does indicate one of Circle tiles. The tokens that represent the 1 Circle tile in one's hand and ones that represent the 1 Circle tile in their discarded tiles (河) are not directly related at all. There is no feature that directly represents the relationship between the dora-indicating tile (ドラ表示牌) and the dora (ドラ) tile. There is no feature that represents the number of tiles of a certain type. While there are a total of 90 types of chows (chi, チー, 吃) in the standard rule of 麻将 Soul, each chow is represented by only one of completely independent 90 tokens... and so on.

The situation at a given time in a 游戏 is represented very simply as follows. Aspects of 游戏 situation that ha to do with the order in which the 游戏 is played, such as the 游戏 wind (chang, 場), the round number (ju, 局), the dora tiles, the hand tiles, etc., are represented as a set of abo tokens. The discarded tiles (打牌) and the meldings (fulu, 副露) played by each player are represented as a sequence of abo tokens representing the order in which they occur. The number of points, the number of riichi deposits, and other numerically meaningful features are represented as numbers themselves.

To be more specific, see Training Data Format for Beha Cloning.

Some readers may be seriously wondering whether such feature design is really capable of proper learning. Don't worry. Even in the very early stages of learning, the behavior of the model trained with the abo feature design already shows that it has acquired basic concepts of 麻将. It seems to acquire concepts including dora, the red tiles, the Dragon Tiles (箭牌), the game wind tile (圏風牌), the player's wind tile (門風牌), 断幺九, melding (鳴き) for fans (役) including 断幺九, 三色同順, 一気通貫, 混全帯么九, and 対々和, value of 混一色 and 清一色, merely formal ready hands (形式聴牌), getting out of the game, 現物 (gen-butsu, the concept that tiles discarded after a riichi is absolutely safe against that riichi), 筋 (suji, the concept that, for example, if 5s is discarded after a riichi, 2s and 8s are relatively safe against that riichi), Liuju Manguan (流し満貫)... and so on.

However, it goes without saying that such an end-to-end feature design requires large data sets and highly expressi to function properly. It is a fundamental trade-off in machine learning whether to use human wisdom to devise appropriate feature designs, or to prepare large datasets and highly expressi and leave them to large-scale computational resources. This project chooses the latter, because the essence of the success of deep learning is the liberation from feature engineering, and because I have been engaged in machine learning since the early 2000s and struggled with feature engineering in those days.

Step-by-step Curriculum Fine-tuning

There are objectives in 麻将 AIs, including imitation of human behavior, maximization of round delta of the score, higher final ranking, and maximization of delta of the grading point (段位戦ポイント). Since these objecti more abstract and comprehensive in this order, the latter learning we move to, the more difficult it becomes to learn.

The idea behind this project is to learn mappings from action selections to these objectives step by step, from the easiest to the hardest. This would be equi to Curriculum Learning. Moreover, when a mapping for one objective has been learned and then starting learning a mapping for one more harder objective, the *encoder part* of the model trained in the former step is reused in the training of the latter mapping, and only the *decoder part* of the model is replaced to tailor to the new harder objective. The information learned in the former step is stored in the encoder part and transferred to the latter step. By doing so, it is intended that uni knowledge about 麻将 that is independent of objectives will be retained in the encoder part. In this project, this idea is called *curriculum fine-tuning*.

Components

prerequisites (For de only)

Make prerequisite packages and tools a for use in other components. This component is built and a as a public Docker image, and implicitly used by other components. Therefore, there is no need for non-de to build or directly use this component.

src/annotation

A C++ program that extracts almost all the *decision-making points* from 游戏 records of 麻将 Soul, and converts the 游戏 situation at each decision-making point together with the player's action and round's/游戏's final results into annotations suitable to learning.

src/xiangting

A C++ program that generates a LOUDS-based TRIE data structure used to calculate shanten (xiang ting, 向聴) numbers.

src/simulation

A C++ library implementing a 麻将 simulator that perfectly mimics the standard 游戏 rule of 麻将 Soul, including even many unstated corner cases of the rule. The functionality of this library can be also accessed via the kanachan.simulation.simulate Python function.

src/paishan

A C++ program that restores the entire tile wall (pai shan, 牌山) from a 游戏 record of 麻将 Soul. Note that the tile wall restored by this program can be used for testing purposes (input to test/annotation_) only, and not for any other purpose.

test/annotation_

A testing 框架 called *annotation-* that checks if there is any discrepancy between the annotation implementation and the simulation implementation.

kanachan/training

Implementations of learning programs and prediction modules with PyTorch.

技术栈

开发语言：Python

项目类型：日麻 AI 框架

Star 数：346

功能特点

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

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

部署说明

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

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

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

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

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

学习价值

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

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

免责声明

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