Welcome to suzume!

Posted December 6, 2020 by Hamza El-Kebir ‐ 2 min read

Introducing suzume, a lightweight Riichi Mahjong engine written in C++14.

suzume aims to be a fast, bloat-free Mahjong engine, on which servers and game clients, AI testbeds, and more can be built eventually. suzume only depends on a C++14 compliant compiler, and has no external dependencies. Localization has been a top priority in this project, with extensive support for Japanese and English terminology (more languages can easily be added!).

Currently, the core game flow is being developed, after which the following items will be worked on:

  • Shanten/tenpai (向聴・聴牌) calculations;
  • Furiten (振り聴) checking;
  • Ryuukyoku (流局) condition checking;
  • Agari/yaku (和了・役) checking and score calculation;
  • Automatic grouping of koutsu, shuntsu, toitsu (刻・順・対子);
  • Automatic ranking of tile favorability (based on yakuhai (役牌), game’s/own wind (場・自風), state of the field (河)).

Features

The following features are (or will soon be) implemented:

  • Localized terminology (English & Japanese).
  • Detailed tracking of present and past tile states:
    • Closed/open tracking (暗・明);
    • Player possession history;
    • Tile location and how it was obtained.
  • Shuntsu (run, 順子) and partial shuntsu identification.
  • Koutsu (set, 刻子) and toitsu (対子) identification.
  • Waits (待ち) classification.
  • Hand ranking based on waits and discards.
  • Furiten (振り聴) checking.
  • Shanten (向聴) computation.

Getting Started

Dependencies

  • CMake;
  • A C++14 compliant compiler (really, that’s all).

Installing 

git clone https://github.com/helkebir/suzume
cd suzume
mkdir build && cd build
cmake ..
make

You First Round

To be completed.

./suzume

Help

Please open an issue (wiki pages and documentation will be added in the near future). Pull request are always welcome!

Authors

Version History

Still not quite at the stage of releasing anything…

License

This project is licensed under the BSD 3-Clause License. See LICENSE for details.

Acknowledgments

Initial inspiration was drawn from Alexey Lisikhin’s mahjong.

FAQ

Q: Where does the name come from?
A: In Japanese, Mahjong is written as 麻雀, where the second character means ‘sparrow’ (pronounced as ‘suzume’). Since we’re aiming for a nimble and moddable Mahjong engine, a sparrow seems to be the perfect symbol.

Q: Where is this project headed?
A: The main goal is to develop a lightweight AI and to eventually experiment with bot battles (à la FFT Battleground). As spin-offs to this main goal, we hope to develop an accessible cross-platform Mahjong client to play Mahjong on the go, besides coming up with analysis tools to study past matches and train AI models. An extension of this would be to allow online peer-to-peer multiplayer matches.