About this project
This is a final year project on investigating deep learning models for Hong Kong Mahjong.
The project consists of 2 stages.
In the 1st stage, various models were implemented. These include heuristics based, Monte-Carlo tree search based, Deep Q learning based and Deep policy gradient based models.
In the 2nd stage, the models were benchmarked by making them compete with each other. A Telegram bot was also built to benchmarking against human players.
The reports of the project could be downloaded here:
Dependencies (main module)
- C++ 11 compiler
- cython
- tensorflow (1.8)
- (optional) pillow
Dependencies (Telegram bot server module)
- all libraries required in the main module
- python-telegram-bot
- pymongo
Environment Setup
- Install C++ 11 compiler.
- Install Python dependencies by
pip3 install cython tensorflow==1.8 pillow python-telegram-bot pymongo. - Issue the command
maketo compile the C++ scripts for the Monte Carlo Tree Search model.
List of Test Scripts
During the project, different test scripts were coded for experiments. The scripts are located under /test_cases.
In general, to invoke a test script, issue the command python3 test.py [script_name] [..args for the script].
The use of each script could be found here.
Setting Up the Telegram Bot
- Retrieve a Telegram Bot token by talking to BotFather in Telegram.
- Set up a MongoDB.
- Edit
/resources/server_settings.json.
Change mongo_uri according to the host, username and password of the MongoDB.
Replace the value of tg_bot_token by the token you retrieved from BotFather.
(Ignore tg_server_address and tg_server_port since by default the bot is in polling mode.)
- Start the bot by
python3 start_server.py.
Development Documentation
These are the functions of the modules:
| Module Name | Functions |
|---|---|
| Game | Implements the Hong Kong Mahjong main game logic, such as turn taking and victory condition checking, etc. The module consists of the Game class and the TGGame class. TGGame is rewritten from Game to facilitate pausing and resuming a game. |
| MLUtils | Implements different machine learning models, mainly deep learning models implemented in Tensorflow. |
| MoveGenerator | Acts as an interface between the Player class and the corresponding AI model in MLUtils. |
| Player | Encapsulate the information of a player, including tiles held and discaded tile history. |
| ScoringRules | Implements the score calculation and victory hand detection mechanism. |
| TGBotServer | Implements the communication with Telegram bot users and game state storing. |
| TGLanguage | Wraps the lamguage pack as Python functions for the Telegram bot. |
| Tile | Encapsulates the information of a tile, such as tile symbol and name. |
[Outdated, for reference only] For the detail API documentation, please refer to here.