Introduction

From Riichi Advanced Blog: link to original post

Welcome! I’m Sophie, and you’re reading a blog post about Riichi Advanced, an open-source mahjong client that supports many different mahjong variants, and lots of variant house rules!

By mahjong, we mean the 4-player rummy-family game, not the solitaire pair-matching game (also known as “Mahjong solitaire”). If you were picturing the second kind, sorry to disappoint. But if you’d like to learn more about mahjong, read on.

An Introduction To Mahjong

So what is mahjong? It’s a sub-family of tile-based rummy-family games, which generally share the following rules:

• The game is played with a set of mahjong tiles, which comprises four copies of the 1 to 9 of each of three suits, plus four copies each of some unsuited unnumbered tiles (called “winds” and “dragons”).
• Each player has a hand of 13 tiles; on each player’s turn, that player draws a tile, checks if they’ve won, and if not, they discard a tile.
• A player wins when their hand is made of four melds and a pair. A meld is either three of the same tile, or three numbered tiles in sequence; a pair is two of the same tile.
• Players can call other player’s discards to complete their entire hand, in which case they win; or to complete a meld in which case the meld is revealed to everyone, and is frozen in place for the rest of the game.

Like poker or dominoes, mahjong is a family of games, meaning that there are many different variants of mahjong, which differ in their rules. Some variants have 16 tiles instead of 13 and require five melds and a pair to win; some variants have additional win conditions that must be satisfied before a player can win; some variants include jokers, or lack winds and dragons; some variants allow players to pass tiles to each other; and all variants score their hands differently. Further, for each variant, some playgroups play with their own house rules.

Riichi Advanced

So, that brings us to Riichi Advanced. As previously mentioned, we’re an open-source mahjong client that supports many different mahjong variants and variant house rules. Most of the engine is geared towards Riichi, the main variant of Japan, due to our familiarity with said variant. That said, the vision is that Riichi Advanced should be able to support every mahjong variant whose rules are publicly documented. Washizu Mahjong? Yep. Parlour riichi with red threes, kindora, and shuugi? It’s all there. Hong Kong Old Style? You betcha. American Mah-Jongg? Somehow, we support that too. Australian Navy Mahjong (aka Pussers Bones)? We don’t have that variant yet, but we’re working on it! Our philosophy is that if we don’t have a given mahjong variant, that’s a bug.

Riichi Advanced is written in Elixir, and uses LiveView to display all the game screens. Variants are coded as either JSON files, or our own custom scripting language, MAJS. Either way, these variant files are interpreted by our Elixir code as scripts, and run. Variant house rules are defined as “mods”, which modify the JSON/MAJS files. These mods are written in JQ or MAJS.

The main developer is Dani (EpicOrange); they’re the one who does almost all of the Elixir magic. Sophie (edderiofer; that’s me!) tends to work more on variant-specific code in JSON and MAJS, bugtesting, and marketing. There’s also many of us who have made smaller contributions here and there, especially bugtesting and documentation.

If you would like to contribute, check out the GitHub repo (especially CONTRIBUTING.md)! Even if you can’t code, or only have rudimentary coding skills, there’s still a lot of ways to contribute: bugtesting, documentation, marketing, bugfixing the relatively-simpler JSON or MAJS code, writing tutorials (in JSON), providing UI/UX improvements, …

We don’t run ads, and we don’t require signing up for an account. Indeed, there’s no way to sign up for an account, because collecting and storing user data would be a liability for us. We also have no way of accepting donations, though this may change if we eventually get popular enough that we need to start paying for a better compute server.

Why A Blog?

At the moment, despite having been out for over a year and a half, Riichi Advanced is considerably less popular than we would like. To get popular, we need marketing, so we’ve created this blog for SEO reasons.

We also don’t really have a way to let players know that things have updated, unless they’re tracking the version number, the repo, or the Discord. Having a public-facing blog, with regular update posts, will hopefully let people know what we’ve been working on and what we’re planning next.

Most importantly, though, with a blog comes an RSS feed, which can be aggregated and picked up by sites like FGD Planets. (Yes, the GitHub repo already comes with an RSS feed, but the repo receives minor updates every couple of days and we don’t want to flood people.) If you’re one of those people who use RSS (I miss Google Reader), that means you can keep track of Riichi Advanced’s updates without getting absolutely flooded.

What’s Next? (As of 2026-04-17)

Dani has just released the new scoring system, which allows ruleset-coders to show a breakdown of how the scores are calculated per hand. With every big change like this comes lots of bugs, which we are currently ironing out. When we have ironed out as many bugs as we think is appropriate, our version number will tick up to v1.4. We’ll write a post about this update then, along with a trailer!

Dani is also working on an in-interface scoring tool that should hopefully allow players to directly test the score of a hand in any variant, as well as some other updates which are scheduled for release in v1.5.

Meanwhile, aside from bughunting and bugfixing, I have in the pipeline a few other mahjong variants which are close to being added to Riichi Advanced. I am also diligently trying to spread the word of Riichi Advanced everywhere I go. Hence, this blog. I seem to be getting particularly good reception in FOSS game communities. Hooray for open-source!

Far off in the future, we’re looking at:

• Improving dice-based interactions
• Improving the log viewer
• Adding more tutorials
• Better mod support
• In-game chat of some kind, to facilitate matchmaking.
• Better UI/UX