Mahjong.
Official Mahjong Solitaire. Turtle layout. 144 tiles. Match two free tiles to clear the board. A tile is free when nothing is on top of it and its left or right side is open.
How to play
- Free tile: No tile directly on top + left OR right side open
- Match: Two identical tiles (same suit + number). Flowers match any Flower, Seasons match any Season
- Goal: Clear all 144 tiles
- Stuck? Hit Shuffle — it reshuffles the remaining tiles
Tiles
Dots 1-9 • Bamboo 1-9 • Characters 1-9 • Winds E/S/W/N • Dragons Red/Green/White • Flowers ×4 • Seasons ×4
4 copies of each suit tile. 144 total. Turtle layout: 88 base + 40 + 12 + 4 on top.
Backend
Right now this game is local-only — the deck, the Turtle layout, the timer and the pairs all live in this page. No save, no daily, no leaderboard. This backend is the map to make it real: same 144 tiles, same Turtle, but the seed lives on the server so Daily is the same for everyone and scores can be trusted. Proposed, not connected.
01 / Files to create
api/mahjong/new.php GET /api/mahjong/new?daily=1 api/mahjong/save.php POST /api/mahjong/save api/mahjong/finish.php POST /api/mahjong/finish api/mahjong/leaderboard.php GET /api/mahjong/leaderboard api/mahjong/daily.php GET /api/mahjong/daily sql/mahjong_tables.sql
Keep the tinyfiles PHP pattern: each endpoint loads /api/bootstrap.php, uses json_in() / json_out(), member session for auth, prepared PDO statements.
02 / Database tables
-- sql/mahjong_tables.sql
mahjong_games
id VARCHAR(40) PRIMARY KEY -- e.g. 'mj_2026-11-18_abc123'
member VARCHAR(80) NULL -- NULL = guest, else member name
seed VARCHAR(32) NOT NULL -- shuffle seed, server-generated
daily_date DATE NULL -- set for Daily, NULL for random
status ENUM('playing','won','abandoned') NOT NULL DEFAULT 'playing'
pairs INT NOT NULL DEFAULT 0 -- server-validated
seconds INT NOT NULL DEFAULT 0 -- server time, not browser time
moves INT NOT NULL DEFAULT 0
created_at DATETIME NOT NULL
finished_at DATETIME NULL
mahjong_scores
id INT AUTO_INCREMENT PRIMARY KEY
member VARCHAR(80) NOT NULL
game_id VARCHAR(40) NOT NULL
daily_date DATE NULL
seconds INT NOT NULL
moves INT NOT NULL
won_at DATETIME NOT NULL
FOREIGN KEY (game_id) REFERENCES mahjong_games(id)
Seed mahjong_games.seed from the server. The browser never picks its own shuffle for Daily or for ranked games.
03 / API endpoints & request flow
GET /api/mahjong/new?daily=1
- server picks seed: daily = YYYY-MM-DD hash, random = random_bytes
- returns { "ok": true, "game_id": "mj_...", "seed": "a1b2c3", "deck": [...] }
- deck is the shuffled 144 tiles in layout order (same buildLayout() order)
POST /api/mahjong/save
{ "game_id": "mj_...", "removed": [[12, 45], [3, 9]] }
- server replays removed pairs against the seeded deck
- rejects if a pair was not free or not matching at that point
- updates pairs / moves, returns { "ok": true, "pairs": 12 }
POST /api/mahjong/finish
{ "game_id": "mj_..." }
- server checks all 144 removed, computes seconds from created_at
- inserts into mahjong_scores (once per game_id), returns rank
GET /api/mahjong/leaderboard?daily=2026-11-18
- returns top 20 by seconds, then moves: { "ok": true, "scores": [...] }
Save must be idempotent — sending the same pair twice must not double-count. Use the removed list as the source of truth, not a browser counter.
04 / Rules & validation (server owns this)
// Server re-implements isFree() + matches() from this page. // Never trust the browser for time, pairs, or win. // isFree(tile, board): // no tile directly on top (same x,y, z+1) // AND left open (no tile at x-1, same y,z) OR right open (x+1) // matches(a, b): // same type.id, OR both FLOWER, OR both SEASON // Win check: // all 144 removed in valid order = won // server computes seconds = finished_at - created_at // leaderboard sorts by seconds ASC, moves ASC
If the browser says “won in 12 seconds” but the server replay says a pair was illegal, the game is rejected. That is the whole point of the backend.
05 / Frontend wiring
// Replace newGame() in this page:
async function newGame(){
const res = await fetch('/api/mahjong/new?daily=0');
const data = await res.json();
// data.deck is the server-shuffled 144 in layout order
// build tiles from data.deck instead of buildDeck()
// keep buildLayout(), isFree(), matches(), render() as-is
}
// After every cleared pair, save:
await fetch('/api/mahjong/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ game_id, removed: history })
});
// On win, finish:
await fetch('/api/mahjong/finish', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ game_id })
});
Keep the local game playable with no backend — if /api/mahjong/new fails, fall back to the current buildDeck() + buildLayout() in this page.
api/mahjong/ + sql/mahjong_tables.sql — no GitHub needed. The <pre> blocks are the backend spec: same Turtle layout (88 base + 40 + 12 + 4), same free-tile rule, server-owned seed + validation.