Boundary of stateless blabbery


Summer is coming! And every summer one must have a project so here is mine: mahjong software suite (from scratch) (in Haskell, of course). Specifically I will be devoting to the following (in decreasing priority order):

  1. Encode riichi mahjong mechanics
  2. API to the multiplayer game
  3. CLI program to play the game
  4. Web application
  5. Wahjongbot, an ircbot to play in IRC
  6. Riichi AI and virtual players

In what follows I step through each of these parts in more detail. I assume basic knowledge of the game itself to keep this post in topic. If you are completely unfamiliar with riichi mahjong, you should learn the basics somewhere before proceeding.

Riichi mechanics

This is the very core of the project and the first thing to implement. This consists of basically two parts: the game state including events that alter it and the rules.

The main component of the game state are the tiles. It consists of:

  • Round info
  • The wall
  • Players’ hands, discards and point saldo

This is all quite trivial. The rules are more interesting, though:

  • The game flow (draws and discards, pon/kan/chi, etc.)
  • Detect mahjong, riichi, furiten, yaku etc. in a hand
  • Calculate points for a hand

Considering that the rules are rather complex and in the real world they may differ radically between matches, I think I want some easily extensible implementation of them right from the beginning (EDSL’s FTW!).


The plan is to have a bare server application with a single API that can be used by the different clients: cli, web, scripts, your C# mobile app or, hey, how about telnet mahjong?

(Now I’m thinking why have a centralized solution? A decentralised mahjong-blockchain sounds cool! There would be a big problem to solve, though: Where and how the game is initialized, and how only some parts of the game state are accessible to each player. My intuition says a non-playing entity would be required anyway. But unfortunately that idea out of the question for this summer… but perhaps the subject of the next one!)

An integral component of the server application is player identification. I’m not familiar enough with web api design to tell how to this could be done neatly and in satisfaction of the paranoid (a per-game unique player token would probably work).

Connections between the server and clients must inherently be bidirectional: after all, the game is between the players, not a player and the server. A little more thought must be done here. In addition to playing the game, it would be great (if not downright necessary) for the players to be able to communicate between each other. A text chat is a minimum, but maybe WebRTC or something similar could be used too?

An interesting twist in the API and motor are pon/kan/ron – actions that can only be taken while the next player has not drawn a tile from the wall. Should there be a time limit before the next player can draw? How is it assured that everyone has had a chance to shout (interruptions in network connection being of main concern)? Should everyone be required to explicitly acknowledge a discard? That would be laborsome. What if they were required to acknowledge only if they were able to shout the tile in the first place? How are these acknowledgements made visible to others? Would too fast or slow acknowledgments potentially give out information of other’s hands? Perhaps some combination of minimum wait time, time limit and acknowledging no-shouts is the solution. Unfortunately this will be a limiting factor in the API’s flexibility, for it will have to depend heavily on time.

Too bad I haven’t had the motivation to register in the popular online japanese mahjong site (whose name I can’t remember now). I could probably get some ideas from that platform.


This will be the reference client for the server. One of the easier parts of this project, as the heavy lifting is done server-side. The application only has to display current game state, receive and send events, receive elemantary user input and possibly feature a text chat.

Web Application

One cannot have cool graphical tiles in a CLI. That’s where the web client comes to play. Of course, additional advanced and useful features can be added to it. I’m not giving examples here; use your imagination and tell me what you would like to have in it in the comments section below!


IRC bots are nice, so why not have a mahjong ircbot? Playing mahjong anywhere with internet and a terminal has to be one of the best instances of procrastination ever. This will require a lot of novel UI design to be even remotely user-friendly, though. More on that some other time. If you just had an epiphany of an mahjong IRC-UI I would like to hear you out in the comments section below.

Mahjong AI

A computer mahjong player shall be the culmination of this summer project. Or that’s what I hope for… It will be the last thing I am to work on, and may not do it at all. So don’t worry about having to face any omnipotences in the game. At least not any time soon.

P.S: I “forgot” (read: was too lazy) to write anything of minimal music as I promised in my previous post. I will not do it in this post scriptum either. but I’ll give you one relevant name instead: Jeroen Van Veen. On minimal music in general will have to wait yet a while longer.

comments powered by Disqus