mahjong

A walkable 3D recreation of an automatic mahjong table in a sunlit room, where you play a full game of four-player Chinese mahjong against three computer opponents. It runs entirely in the browser: no install, no server, no accounts. Sit at the table and play, or press V to stand up and walk around the room while the game carries on.

Play it in your browser · 2D table

A hand in play	Winning and scoring

Features

• Full 144-tile set, including the eight flower tiles, which are replaced from the back of the wall and score bonus fan.
• Chi, peng, gang (exposed, concealed and added), hu on a discard or by self-draw, robbing the kong, kong bloom, and wall-exhaustion draws.
• Fan scoring with an itemised breakdown: seven pairs, thirteen orphans, all pungs, full and half flush, dragon and wind pungs, all simples, concealed hand and more.
• Three AI opponents that discard by shanten and tile acceptance, play a little defensively late in the hand, and claim discards when it helps them.
• A full game of four wind rounds with dealer rotation, running scores and a final ranking.
• An automatic table: tiles are dealt from four walls around a centre hub with a turn indicator, dice and a tile counter.
• Walk mode: press V (or 起身) to stand up, then WASD and the mouse to walk the room. Your seat waits for you.
• A separate 2D table (classic.html) that runs the same engine with CSS 3D instead of WebGL.
• Bilingual interface: Chinese tile and action names with English alongside.

How to play

Draw a tile, discard a tile; the first player to complete four sets and a pair wins. Click a tile twice to discard it. When a discard can be claimed, buttons appear for 吃 chi (a run, only from the player on your left), 碰 peng, 杠 gang or 胡 hu. In the 3D view, drag to look around, scroll to lean in, R to recenter and V to stand up. The ? button shows the rules and the fan table.

Run it locally

Everything is static files. Open index.html directly, or serve the folder with any web server:

git clone https://github.com/gregoryjayuk/mahjong.git
cd mahjong
python3 -m http.server 8000

Then open http://localhost:8000 for the 3D table, or http://localhost:8000/classic.html for the 2D one.

Tests

The rules engine has no DOM dependency and runs under Node:

node test.js        # unit tests plus a 300-game self-play soak test
node test.js 50     # a shorter soak

Single-file build

node build.js inlines Three.js and the game scripts into dist/mahjong3d.html, one self-contained HTML fragment for hosts that wrap pages in their own document.

How it is built

• engine.js — rules, win detection, shanten, fan scoring and the AI players. Pure logic; works in the browser and in Node.
• ui3d.js — the 3D room, table, tiles, camera, walk mode and game flow, using Three.js.
• scene.js — procedural artwork shared by both views: tile faces, the room, the plants and the view through the window. Every texture is drawn in code; the game itself loads no image files.
• ui.js and classic.html — the 2D table.
• three.min.js — Three.js r147, vendored so the game works offline.

Status

A hobby project. The engine is complete and tested; the 3D interaction is built for a mouse and keyboard, and touch support is not there yet.

Licence

GPL-2.0, see LICENSE. Three.js is vendored under its own MIT licence.