- Play now: https://riichiadvanced.com/
- Discord (join us!): https://discord.gg/5QQHmZQavP
Riichi Advanced is an infinitely extensible mahjong web client featuring the following:
- 28+ base rulesets, including:
- Riichi,
- Hong Kong Old Style,
- Sichuan Bloody Rules,
- Zan Sanma,
- MCR,
- Taiwanese,
- Super Bingo Sanma,
- you can even play Riichi Mahjong with Saki powers!
- A variety of mods for each ruleset! Play with:
- head bump,
- sequences wrapping from 9 to 1
- a "ten" tile for each suit
- every local yaku in existence
- every joker tile in existence
- transparent Washizu tiles
- every tile is aka dora
- and more!
- Multiplayer lobby system with public/private rooms! Invite your friends, or play against AI!
- Infinitely customizable ruleset! Beyond mods, you can change the rules by writing MahjongScript to make minute changes to a game!
- Localization support! 中文支持！ 日本語対応！
Join the Discord for development updates and bug reporting! (There are a lot of funny bugs, don't miss out!)
If interested in contributing, check out the contributing doc!
- Changelog
- Supported rulesets
- Custom rulesets
- How can I contribute?
- Repository breakdown
- Running the server locally
- Technical notes
- Links to all documentation
- Acknowledgments
See CHANGELOG.md.
- Riichi: The classic riichi ruleset, now with an assortment of mods to pick and choose at your liking.
- Sanma: Three-player Riichi.
- Space Mahjong: Riichi, but sequences can wrap (891, 912), and you can make sequences from winds and dragons. In addition, you can chii from any direction, and form open kokushi (3 han).
- Cosmic Riichi: A Space Mahjong variant with mixed triplets, more yaku, and more calls.
- Galaxy Mahjong: Riichi, but one of each tile is replaced with a blue galaxy tile that acts as a wildcard of its number. Galaxy winds are wind wildcards, and galaxy dragons are dragon wildcards.
- Kansai Sanma: Sanma, but you draw until the last visible dora indicator. In addition, all fives are akadora, fu is fixed at 30, there is no tsumo loss, and scores are rounded to the nearest 1000. Flowers act as nukidora in place of north winds, which are now yakuhai. Exhaustive draws in south round always result in a repeat regardless of who's tenpai.
- Zan Sanma: Kansai Sanma, with rules focused entirely on winning shuugi (chips).
- Speed Tonpuu: A house variant of riichi with red fives, blue sevens, a gold five, and three shiro pocchi tiles. Everything earns chips.
- Super Bingo: A wild sanma variant where the sevens in the deck are doubled, and there are also rainbow sevens which are worth lots of chips. In addition, winning with riichi or yakuman lets you continuously flip tiles from the wall, gaining chips for flipped tile matching your discards.
- Chinitsu: Two-player variant where the only tiles are bamboo tiles. Try not to chombo!
- Minefield: Two-player variant where you start with 34 tiles to make a mangan+ hand, and your remaining tiles are your discards.
- Sakicards v1.3: Riichi, but everyone gets a different Saki power, which changes the game quite a bit. Some give you bonus han every time you use your power. Some let you recover dead discards. Some let you swap tiles around the entire board, including the dora indicator.
- Hong Kong: Hong Kong Old Style mahjong. Three point minimum, everyone pays for a win, and win instantly if you have seven flowers.
- Sichuan Bloody: Sichuan Bloody mahjong. Trade tiles, void a suit, and play until three players win (bloody end rules).
- MCR: Mahjong Competition Rules. Has a scoring system of a different kind of complexity than Riichi.
- Taiwanese: 16-tile mahjong with riichi mechanics.
- Bloody 30-Faan Jokers: Bloody end rules mahjong, with Vietnamese jokers, and somehow more yaku than MCR.
- American (NMJL): American Mah-Jongg. Assemble hands with jokers, and declare other players' hands dead.
- Vietnamese: Mahjong with eight differently powerful joker tiles.
- Malaysian: Three-player mahjong with 16 flowers, a unique joker tile, and instant payouts.
- Singaporean: Mahjong with various instant payouts and various unique ways to get penalized by pao.
- Tianjin: Mahjong except the dora indicator actually indicates joker tiles.
- Ningbo: Includes Tianjin mahjong joker tiles, but adds more winning patterns and played with a 4-tai minimum.
- Hefei: Mahjong with no honor tiles, but you must have at least eight tiles of a single suit to win.
- Custom: Create and play your own custom ruleset. (See documentation.md for a tutorial.)
Each ruleset has optional mods like chombo and aotenjo, you'll have to check out each one to discover its variants!
Once you enter the lobby or room for a ruleset you can scroll down to view the JSON object defining the ruleset.
If you're looking to make a custom ruleset using the game's MahjongScript ruleset language, that documentation is available here. To play a custom ruleset, simply select Custom on the main page, click Room Settings, and paste and edit your ruleset in the box provided.
Otherwise, click Room Settings and the Config tab to reveal a MahjongScript editor, where any MahjongScript you write will be applied to the game.
Mostly we need people to play and report bugs, of which there are likely many. We also accept pull requests so if you see an issue you'd like to tackle, feel free to do so!
Also if you know of any English-based mahjong rulesets available online, do tell us in Discord and we'll add it to the list!
Check out CONTRIBUTING.md for more details.
Monetary contributions are not accepted at this time.
First, install Elixir (≥ 1.14), npm, z3, jq, and the Rust toolchain via rustup.
Then run:
git clone "https://github.com/EpicOrange/riichi_advanced.git"
cd riichi_advanced
# Get Elixir dependencies
mix deps.get
# Generate self-signed certs for local https
mix phx.gen.cert
# Get Node dependencies (there aren't many)
(cd assets; npm i)
# Start the server
HTTPS_PORT=4000 iex -S mix phx.server
This should start the server up at https://localhost:4000. (Make sure to use https! http doesn't work locally for some reason.) Phoenix should live-reload all your changes to Elixir/JS/CSS files while the server is running.
If it complains about a daemon not running, open a separate terminal and run epmd (Erlang Port Mapper Daemon), and try again.
If you want to run your own instance of Riichi Advanced, see INSTALL.md for instructions and troubleshooting.
If you're interested in the technicals, there are basically five moving parts to Riichi Advanced, each solving one of the five main challenges that came up during its development:
- Custom DSL to define rulesets! Originally, mahjong rulesets were represented by rigid JSON objects with various
jqquery files acting as 'mods'. To avoid technical overhead and allow players to write their own mods without possible vulnerabilities from writing rawjq, a DSL called MahjongScript was created to compile down to a safe subset ofjq. Its compiler can be found here. - Solving for joker tiles via constraint solving! The challenge was to encode these custom rulesets into SMT, generating SMTLIB2 constraints and sending it to Z3 to enumerate all joker tile assignments. If you're a SMT nerd you should definitely give the encoding a once-over, it can be found here.
- Profiling and optimization! Riichi Advanced used to be a lot laggier than it is now! Profiling using Elixir's
:fprofrevealed that a single function (match) was the hot loop. Rewriting It In Rust (actually, several algorithmic improvements, but also Rust) resolved many performance problems to the point of playability. The Rust package can be found here. - Automated deploy! All games are in-memory (no database) so updates pushed to GitHub will automatically spin up a fresh server and push all game state to it, so that those running in-memory games do not terminate. It's basically scuffed blue-green cutover. Most of the deploy code is server-side (private) but the discovery and cutover part can be found here.
- Fault tolerance! It's an Elixir project, so any crashing subprocess (like game states) just get restarted. Writing a usable supervision tree took several design iterations, but has settled on
Application->GameSessionSupervisor-> (many)GameSupervisor->GameState. The application root is here.
A longer version of this can be found in technical_notes.md. If you like solving these kinds of problems, consider joining the Discord! We have a lot of problems.
Riichi Advanced: all about programming the game engine.
- Ruleset tutorial + documentation (MahjongScript)
- Ruleset tutorial + documentation (old JSON version)
- MahjongScript language reference
- Mod creation reference
- Tutorial creation reference
- Tiles reference
- Technical notes (engine internals)
Rulesets (for nerds): Most of the rules can be accessed in-game by clicking on Rules after entering a room. Note that there are also in-game rules tabs! Otherwise, here are links to all the writeups stored in the /documentation directory of this repository.
- Riichi variants
- Non-Riichi variants
The basic tileset used in this game is taken from this repository. Thank you to @FluffyStuff!
Many of the more unique tiles in the game (read: joker tiles) were created using the Hanyi Senty Tang font.
In addition, special thanks to the following sites for offering English-based rulesets:
A big thank you to our beta testers on Discord:
- #yuriaddict
- 5𝔷ł𝔬𝔱𝔶𝔠𝔥-𝔨𝔲𝔫
- Anton00
- averyoriginalname
- BluePotion
- Buckwheat
- Caballo
- DragonRider JC
- GameRaccoon
- Glassy
- GOAT^
- Hyperistic
- JustKidding
- KlorofinMaster
- L_
- lorena.davletiar
- Miisuya
- Nehalem
- nilay
- schi
- Sophie
- stuf
- tomato
- UltimateNeutrino
- モカ妹紅（MochaMoko）