collin/mahjong

963c4b92f7592f5587ee0f1864c1e95f974cd2ce / README.md

1	# 台灣麻將 — four-player mahjong, on one touchscreen or over the wire
2
3	Sixteen-tile Taiwanese mahjong for four people sitting around a single laptop.
4	All four hands are on screen at once, each rotated to face its own edge and
5	each face down until its player taps it — the piece of card everybody used to
6	lay over their strip, done by the table itself. Every label is Chinese with
7	English underneath; the tiles themselves stay Chinese, because that is what the
8	tiles say.
9
10	四人同桌 on the lobby is that table, and it is one mode rather than two:
11	four people at one screen, and any of them free to take their own hand onto
12	their phone from the QR in their gear — the tiles leave the screen and the
13	throw comes back over the wire. Nobody has to, and nothing has to be decided up
14	front. See [one table](#one-table).
15
16	Nobody else around? 單人對局 Single player gives you the bottom seat and
17	hands the other three to the computer — same rules, same table, same scoring.
18	See [computer players](#computer-players).
19
20	Everybody somewhere else? 線上對戰 Online game puts the four of you at the
21	same table from four devices, each turned so your own seat is the near edge —
22	see [playing online](#playing-online).
23
24	```
25	npm install
26	npm run dev # then open the browser full-screen (F11)
27	npm test # rules engine, the bots, and 200 randomly-played hands
28	```
29
30	## Screen layout
31
32	```
33	┌──── 對家 (rotated 180°) ────┐
34	上家 (rotated 90°) │ wall, and the discard pool │ 下家 (rotated −90°)
35	└──── 自家 (upright, near you) ┘
36	```
37
38	Seat 0 is the bottom edge, and play runs 0 → 1 (right) → 2 (top) → 3 (left),
39	which is the normal counter-clockwise 東南西北 order.
40
41	Each strip shows, from the player's edge inwards: nameplate (seat wind, 莊
42	marker, 聽 badge, chip count) → concealed hand → action buttons → melds and
43	flowers. Discards are not in the strips: they are thrown into the middle and
44	stay there for the hand, the way they would be on a table. (A phone has no
45	middle to throw into, so the compact layout keeps a discard row per seat — see
46	[on a phone](#on-a-phone).)
47
48	## Playing
49
50	- Your hand is face down at a shared screen, and a tap turns it over. It
51	covers itself again when the hand is dealt and when your turn ends — the two
52	moments the tiles stop being needed, and without them a hand turned over once
53	stays turned over all evening, which is the same as never having covered it.
54	蓋牌 beside 理牌 puts it back sooner. While it is covered the only button the
55	strip has is 看牌: every other one names a tile — 打出五萬, 吃 with these two
56	— and would say through the card what is under it. The 看牌 of whoever the
57	table is waiting on wears a gold ring, since whose go it is was never a
58	secret. Nothing is covered where the screen belongs to one player: solo, and
59	online, where everybody has a device of their own.
60	- The tile you just drew is held apart from the sorted hand with a gold ring
61	and a 摸 label, instead of being sorted invisibly into it. It merges into the
62	hand once you discard. 補花 replacements and kong replacements are marked the
63	same way.
64	- The wall is drawn in the centre as a square of four staggered sides, laid
65	out like a `#` the way it is built on a real table — every corner covered by
66	one wall carrying past the end of the next. All 144 tiles, at the size of the
67	tiles in your hand, because they are the same tiles. The gold stack is the
68	break point you draw from, and where that is depends on what the dealer threw:
69	stacks shrink to a single tile and then vanish as they are used, so the gap
70	opens wherever the dice opened the wall and grows from there. The 16-tile 底牌
71	tail at the other end is where kong and flower replacements come from, so the
72	square is eaten from both directions at once. See
73	[擲骰](#擲骰--where-the-wall-is-broken).
74	- Discard — drag a tile out of your row and it comes up out of your hand and
75	follows your finger anywhere on the table; let go and it goes in, from where
76	you let go and at the speed you let go at. Dragging along the row is still
77	arranging your hand — which of the two you meant is decided once, from whether
78	the movement is mostly along the row or out of it, and then it sticks. Let go
79	back over your own hand and the tile goes back. Tapping a tile twice, or the
80	打出 button, still works and lobs it in for you.
81	- The discard pool — every tile thrown lands in the middle and stays there
82	until the hand ends, with real weight: it skids, turns, knocks the tiles
83	already there out of its way, and comes to rest against them. Nothing is ever
84	stacked on anything — tiles are solved as rectangles, so two lying at an angle
85	lean on each other rather than overlapping. The tile still to be claimed is
86	the lit one.
87	- Over the wall or across the table — which of the two ways a tile goes in is
88	not a setting, it is whatever the wall allows. At the start of a hand the
89	square is a solid barrier and a discard has to be lobbed over it, so the
90	flick's speed decides how far across the pool it lands. As the wall is eaten
91	away, gaps open in front of one seat and then another, and from then on that
92	seat can slide a tile in instead — flat across the cloth at exactly the speed
93	it was flicked. Which it will be is a ray cast at the stacks actually standing
94	there, so a gap off to one side counts, and a stack worn down to a single tile
95	is low enough to go over. A seat whose wall is still up says 牆未開 on its
96	nameplate, so a lob is never a mystery.
97	- Throw it badly and it ends up in somebody's tiles — the middle stops
98	exactly where their hand starts, so a tile that comes off the pool arrives in
99	their lap, and one that falls short lands out by their seat. Either way their
100	row takes the knock and rocks back, and with 報牌 on they tell you about it —
101	喂，小心點 if you are lucky, 是在哈囉 or 你牌品很差欸 if you are not, and
102	never the same line twice running. How hard it got there only decides how
103	loudly. Never your own edge: you cannot be barged by your own discard.
104	- Arranging — drag any tile in your hand to reorder it; 理牌 sorts it back
105	into suit order. Hands are never auto-sorted after the deal, so an arrangement
106	you set up survives draws, claims and kongs.
107	- Rules — the `?` on your nameplate opens a bilingual rules panel anchored to
108	your own edge of the table and rotated to face you.
109	- Claiming — after a discard, every seat that can claim gets 胡 / 槓 / 碰 /
110	吃 / 過 buttons on their own strip, and they resolve by priority (胡 > 槓/碰 >
111	吃; ties go to the player nearest the discarder in turn order).
112	The table never blocks on a claim. The next player gets a 摸牌 button and
113	may draw whenever they like, which shuts the window on anyone who hasn't
114	called — exactly like shouting 碰 before the next player picks up. A claim
115	already declared still stands, so calling in time always wins the tile. If
116	everyone answers first, play advances on its own without the extra tap.
117	The seat that draws next gets no separate 過 button, because for them the two
118	are the same move: picking up is how you decline. Their button says 摸牌
119	either way; what they would be giving up by pressing it is the 碰 or the 吃
120	sitting next to it on the bar, so it does not have to be spelled out on the
121	tile as well. Wanting to decline but leave the window open for everyone else
122	is just waiting, which is what not pressing anything already does. (On a
123	phone the button still reads 過．摸牌 — a phone's bar is a row with room to
124	write on, and the hand it belongs to is not on the same screen as the table.)
125	- On your turn — 自摸, 暗槓 and 加槓 appear automatically when legal.
126	加槓 offers everyone else a 搶槓 chance.
127	- Where the buttons go — on the same row as your tiles, at the right-hand end
128	of it, where the tile you are about to throw already is. The bar is out of the
129	strip's flow, so a button arriving moves nothing: 打出五萬 appearing when you
130	lift a tile used to shove the melds and flowers above it up the strip. Every
131	button on the bar is given one height for the same reason.
132	- On the keys — ← and → walk the selection along your hand and space throws
133	the tile that is lifted. How long you hold space is how hard it goes: the
134	tile draws back out of the hand while the key is down and leaves when you let
135	go, so a tap slides it in and a long hold sends it across the square. Escape
136	puts it back. The wall still decides whether it can be slid or has to be
137	lobbed, exactly as with a finger.
138	- When a hand ends — a big arrow drops onto the winner's edge of the table.
139	It lives inside their strip, so it turns with the seat and lands on the right
140	person wherever they are sitting, and 一炮多響 lights up every seat that
141	called. A 流局 has no winner to point at, so it turns the hands over instead:
142	who was 聽牌 and the tiles they were waiting on, the same reveal as at a real
143	table.
144	- The gear — beside the `?` on every nameplate, and it opens that player's
145	own copy of the table's controls: undo, sound, full screen, 設定. Anchored in
146	their strip and turned to face their edge, like the rules panel, so what you
147	open reads the right way up to you and to nobody else. These used to be a bar
148	in the middle of the table, which is the one place that belongs to everybody
149	— the pile lands there and it is upside down to two of the four.
150	- Undo — 復原 in that panel takes back the last action, naming what it will
151	undo (`復原玩家 2 打五萬`). It is in all four panels rather than only the
152	seat that made the mistake, because whoever spots the mis-tap should be able
153	to reach it. Twenty actions deep, cleared when the next hand is dealt.
154	Snapshots live outside the saved state, so an undo does not survive a
155	refresh: what you can take back is what happened while everyone was still
156	watching it happen.
157	- Sound — on by default, muted from the 🔊 button behind any seat's gear, or
158	from settings. A dry clack as a tile goes down, and a distinct
159	two-note chime when a claim window opens, which is how a slow player notices
160	their 碰 is available before the next player draws it shut. Everything is
161	synthesised with a few oscillators (`src/game/sound.ts`) rather than sampled,
162	so there is nothing to load and the cue lands on the same frame as the tile.
163	Browsers refuse to start audio before the page has been clicked, so the first
164	sound anyone hears is the deal — triggered by the button that starts it.
165	- 報牌 (voice) — a second switch under sound calls the game out loud: 碰,
166	吃, 槓, 胡了, 自摸, and the name of every tile as it is discarded — 三條,
167	五萬, 東風. A flower says 補花 and then which one. A new call cuts off one
168	still being spoken; at table pace the newest is the only one that matters.
169	See [the voice pack](#the-voice-pack) for where the audio comes from.
170	- 方位音 (sound by seat) — a third switch, on by default. Every noise comes
171	out of the edge its seat is sitting at: 上家 to your left, 下家 to your right,
172	and 對家 across the table, where it is quieter and has the top taken off it —
173	a metre of air and three people's arms do not carry 12 kHz. So you can tell
174	whose 碰 that was without looking up, which is the whole point of hearing it.
175	Tiles out in the middle are placed properly rather than by edge: the physics
176	knows to the pixel where a tile landed, and that is where the knock comes
177	from. Online the table is turned so your own seat is at the bottom, and the
178	sound turns with it. See [audio, by seat](#audio-by-seat).
179	- Settings — 設定 from the lobby, or from the game-over panel: player names,
180	底 / 台 / starting chips, the house-rule switches below, and sound. Kept in
181	`localStorage` separately from the save, so they carry over to the next game.
182	Stakes are locked once a game is under way — they'd otherwise rewrite chips
183	already won.
184
185	## One table
186
187	四人同桌 and 手機派對 were two buttons on the lobby, and they were never two
188	games: one was the other with the phones left in people's pockets. Every party
189	table played its unclaimed seats hotseat-style at the screen already, and every
190	hotseat table would have taken a phone if it had had a room to put it in. So
191	there is one button now, and picking up your phone is not a mode — it is
192	something one player does, mid-hand, without asking the other three.
193
194	What that costs is a decision about when to open the room, and the answer is:
195	not while anybody is waiting. The tiles are dealt at once, on this screen,
196	before a websocket has been opened — a laptop with no server behind it is still
197	four people at a table, and nobody should watch a spinner to start playing. The
198	room is opened behind the game, and when it lands it inherits the hand in
199	progress (`startParty(names, rules, from)` restores rather than deals) instead
200	of dealing over the top of it. The only thing that changes on screen is that
201	the QRs start working. If it never lands, nothing does.
202
203	Each seat's QR is its own, and lives in that seat's gear beside the sound
204	and the undo, carrying `?room=…&seat=N`. Scanning it lands on that chair
205	without anybody having to say which one they are in: the hand leaves the shared
206	screen for good — face down there, not under a card that lifts — and the phone
207	gets it face up with the claim buttons and the throw. There is a QR for the
208	whole table in the middle of the felt as well, but only while the table is
209	still being sat down at; the moment the first tile is thrown it steps aside,
210	because from then on the middle is where the tiles go.
211
212	The save follows the screen. A table that has opened a room keeps writing
213	`localStorage` (`engine.persist` on the screen's engine, off on every phone —
214	they mirror, and have no business writing it), so 繼續對局 still works and
215	resumes the same way the mode starts: restore here, open the room behind it,
216	publish the hand as it stood.
217
218	## Playing online
219
220	Both networked shapes — a shared screen with phones on it, and four devices in
221	four places — are one room relay of our own: `server/rooms.ts`,
222	a couple hundred lines of Node on `ws`. The relay knows nothing about mahjong:
223	rooms with codes, host election by join order, one bag of shared state only the
224	host may write, and events fanned out to everyone else. One client — the
225	host — runs the engine, publishes the whole `GameState` as room state after
226	every move, and plays intents the other devices send as events. The engine was
227	already a pure JSON state machine, so nothing in `src/game/` knows the network
228	exists — the same trick `autoplay.ts` plays, stretched over a wire. The client
229	end of the wire is `src/net/room.ts`; the rest of `src/net/` is the game
230	riding it.
231
232	- 線上對戰 Online game — everyone on their own device. Whoever opens the
233	room picks 線上對戰 and gets a seat lobby; friends who open the same link
234	land in it, sit down, and the host deals. Empty seats go to the computer,
235	which runs on the host client — that is what stands in for a server on the
236	classic (free) tier. Each screen draws the same full table, turned so your
237	own seat is the bottom edge; other people's tiles are face down. Joining
238	mid-game takes over a vacant or computer seat, so a dropped friend can
239	reload and carry on.
240	- 四人同桌 at one screen, with phones — the mode above, and on the wire
241	still `mode: 'party'`: the laptop is the table and a phone holds one hand.
242	Scanning a seat's QR loads a controller: just that hand, face up, with the
243	claim buttons — and the throw. Flick a tile up off the top of the phone and
244	it sails in from your edge of the common screen, at the speed and angle you
245	let go of it (`NetThrow`, mapped into table coordinates by
246	`TablePool.throwFromNet`). The seat's tiles go face down on the shared screen
247	and stay there; hold the 📱 tag on its nameplate to show the table's QR again
248	for a player who lost theirs. A phone that leaves hands the seat back to the
249	laptop, where it is covered-with-a-tap like the rest. Seats never lock: a
250	second phone scanning the same QR joins the same hand — two people playing
251	one hand, whoever acts first acts. And with sound on, the phone in your hand
252	is what says your calls — see [audio, by seat](#audio-by-seat).
253
254	Design notes, in the order they bit:
255
256	- Seats are claims on a shared map, `seats: {ids, name}[]` in room state,
257	arbitrated by the host. Your own hand's arrangement never goes over the wire
258	— the state carries a multiset and each device keeps its own order
259	(`src/net/handOrder.ts`), because a round-trip inside a drag gesture is lag
260	you can feel.
261	- The host can change. The relay re-elects — the earliest joiner still
262	connected — when the host leaves; every other client already mirrors the
263	full state, so the new host starts its engine from what it was just watching
264	and the game carries on.
265	- A hidden host must keep hosting. Browsers suspend requestAnimationFrame
266	and throttle timers in background tabs, so nothing in `src/net/` runs on a
267	loop: state writes flush on a microtask, everything inbound arrives over the
268	WebSocket (whose delivery is not throttled), and dead connections are the
269	server's ping loop's problem. A party screen somebody tabbed away from
270	keeps answering.
271	- Identity is a UUID in sessionStorage, chosen by the device and taken at
272	its word by the relay. The seat map is keyed on it, so a reload or a wifi
273	blip walks back into its own seat. No auth — this is a home server for one
274	table of friends.
275	- Fairness is social, not cryptographic. Room state carries the whole
276	game, wall and hands included — a friend with devtools open can cheat.
277	Moving the engine into the relay would fix that; the server is ours now, so
278	only the work stands in the way (TODO).
279
280	### Running it
281
282	```
283	npm run dev # vite, with the relay on /ws of the same origin
284	npm run build && npm run serve # production: dist/ + relay, one process
285	```
286
287	The relay always lives at `/ws` on the page's own origin. In development
288	`vite.config.ts` attaches it to vite's server, so `npm run dev` is the whole
289	stack; in production `server/index.ts` serves the built `dist/` and the relay
290	from one port (`PORT`, default 8080), listening on the LAN by default so
291	phones on the same wifi can scan straight in. Anything further away wants TLS
292	in front — a reverse proxy with a certificate — since phones only get camera
293	and fullscreen on https.
294
295	Rooms live in memory. A restart drops them; the next visitor on an old link
296	recreates the room empty, and a host mid-game republishes its state on the
297	next move. Joining a room writes `?room=` back into the address bar, so the
298	page URL — the host's included — is the invite link.
299
300	A QR pointing at `localhost` is a QR only the host's machine can scan, so the
301	server always gives the invite links a public face: `PUBLIC_URL` if set, else
302	it runs its own rsgrok tunnel (the house ngrok replacement) — spawned
303	the moment the server knows its port, the https URL read off the tunnel-up
304	line, no `:4040` inspection API (another agent may own that port). Every QR
305	and invite link wears that origin instead of the page's. If the tunnel dies,
306	or `rsgrok` is not on the PATH (`RSGROK_BIN` points elsewhere), links fall
307	back to the page's own address and the tunnel is retried on later joins.
308
309	The tunnel always asks for the same subdomain — `mahjong-table`, or whatever
310	`TUNNEL_NAME` says — so restarts land back on the URL people already have
311	instead of burning a fresh name each run. A name someone else already holds
312	kills that first attempt before it prints a URL; the retry then goes out
313	nameless and takes whatever it is given.
314
315	## On a phone
316
317	The table assumes four people sitting around a screen lying flat, and about
318	770px in both directions before the middle is worth looking at. A phone has
319	neither, so under `(max-height: 620px), (max-width: 820px)` it switches to the
320	compact layout: nothing is rotated, everything reads upright for the one person
321	holding it, the other three seats shrink to cards showing what is public about
322	them, and the depth that frees up goes to your hand, which is allowed to wrap.
323
324	There is no centre square there — the middle collapses to a one-line bar showing
325	what the wall square was telling you anyway — so there is nowhere to throw a tile
326	to. The compact layout therefore keeps a discard row per seat, and discarding
327	is tap-twice or 打出, exactly as it was. The pool and the throw are a full-size
328	feature.
329
330	The breakpoint is written down once, in `COMPACT_QUERY` in `src/ui/compact.ts`,
331	which sets a `compact` class on `<html>` for the CSS to key off.
332
333	## Computer players
334
335	Single player seats you at the bottom and gives seats 1-3 to the computer.
336	Their tiles go face down and their 聽 / 過水 badges come off, since both would
337	give the hand away; everything public — the pool, melds, flowers, chips — stays
338	exactly as it is, and everyone turns their hand over when the hand ends. They
339	throw their tiles in like anyone else, and under the same rule: a computer seat
340	whose wall is open slides them across, and one still walled in lobs them over.
341
342	The engine does not know the bots exist. `AutoPlay` (`src/game/autoplay.ts`)
343	watches the same state the screen does, and when the seat being waited on
344	belongs to the computer it calls the identical method the button would have
345	called — `discard`, `respond`, `declareConcealedKong`. So scoring, sound,
346	saving, 過水 and 包牌 all work without a special case, and a bot cannot make a
347	move a person could not. It never acts for you and never closes your claim
348	window: if the table is waiting on you, it waits.
349
350	How they play (`src/game/bot.ts`) is one idea applied everywhere. A hand is
351	judged at its resting size — the (5 − melds) × 3 + 1 tiles you hold between a
352	discard and your next draw — by its 向聽 first and by its 進張 count second.
353
354	- Discard — try every distinct tile, keep the one that leaves the best
355	resting hand. Ties go to whatever is hardest to build on: a lone honour with
356	most of its copies already gone, before a lone 五萬 that still has neighbours
357	to meet.
358	- 碰 / 吃 — only when the hand that comes out the other side is strictly
359	closer to home. Melding costs concealment and flexibility, so a claim that
360	merely holds the 向聽 steady is declined — which is why the bots pass on
361	pungs that would narrow a two-sided wait to a single tile.
362	- 槓 — judged more kindly: it pays 台 and fetches a replacement, so standing
363	still is good enough.
364	- 胡 — always taken.
365
366	What they watch you do (`src/game/danger.ts`) is the other half. Efficiency
367	alone throws whatever is fastest and pays for it; these bots read the table
368	first, off the face-up table only — discard rows, exposed melds, the 過水 locks
369	the nameplates already show. Two separate questions:
370
371	- How close does each seat look? Turns taken (a hand is usually settled
372	inside ten goes each, long before the wall looks finished, so counting the
373	wall is the wrong clock), melds exposed, and what they have been throwing
374	lately. Nobody discards 五條 out of a hand that still needs shaping — it comes
375	out once the shape is done, so late middle tiles are the tell. A 過水 lock is
376	a confession: to be locked out of a tile you had to have been able to win on
377	it.
378	- How likely is this tile the one they want? An honour can only be caught by
379	a pair or a triplet; a 五萬 sits in the middle of every run through it. A tile
380	they discarded themselves was not their tile when it went down — not proof
381	now, but the best evidence there is. A tile with no copies left unseen cannot
382	be a pair or triplet wait at all. Two melds in one suit means stay out of that
383	suit. And two dragon pungs down means the third dragon is not going anywhere
384	near the table, because 包牌 bills the feeder for the entire hand.
385
386	Whether any of that changes the discard depends on the bot's own hand. At 聽牌
387	it pushes — nothing short of 包牌 is worth breaking a ready hand for. Two or
388	three away with somebody live across the table and it will give up a whole 向聽
389	step to throw something safe, which is what folding is.
390
391	The estimate is checked against ground truth in the tests rather than assumed:
392	over the tiles bots actually considered, the ones the model rated below 0.2 deal
393	in 0% of the time and the ones above 0.8 deal in 10.5%, cleanly monotonic in
394	between. Switching the read on cuts deal-ins by about 13% over a few hundred
395	hands, takes hands from ~30 discards to ~38, and moves the draw rate from
396	almost nothing to about one hand in ten — which is what a table where people
397	stop feeding each other actually looks like.
398
399	What they know is still only what they can see. `unseenFor` counts the four
400	copies of each tile and subtracts the bot's own hand plus every discard and
401	exposed meld on the table. Neither module ever reads an opponent's concealed
402	tiles or looks at the wall.
403
404	There is no difficulty setting, and the reading stops at the discard: claims are
405	still judged purely on speed, and a bot will take a 碰 that walks it into
406	trouble.
407
408	向聽 lives in `src/game/shanten.ts`, apart from `hu.ts`, because the two want
409	different things: the win check has to be exact, and this one has to be fast —
410	it runs a few hundred times for every discard a bot considers. The tests hold
411	them against each other over random hands, since they work in completely
412	different ways and any disagreement is a bug in the fast one.
413
414	Undo behaves differently against the computer: rewinding into the middle of its
415	turn would only hand the move straight back to it, so one press goes back to
416	the last point you had a decision to make, computer replies and all.
417
418	## Saving
419
420	The game state is plain data, so a save is just its JSON in `localStorage`,
421	rewritten after every move. Close the lid, refresh, or run the battery flat and
422	nothing is lost — the lobby offers 繼續對局 Resume above the ways to start a
423	fresh one, showing whether it was a solo game or a table, the round, hand
424	number, chip counts and when it was saved. Which seats the computer holds is
425	part of the state, so a save resumes as the kind of game it was — a solo game
426	here, a table with its room opened again behind it, so the phones that were on
427	it can come back. A
428	save is validated before it is offered (four players, 144 tiles accounted for),
429	so a truncated or hand-edited one is ignored rather than loaded into a broken
430	table. `VERSION` in `save.ts` retires old saves if the state shape changes.
431
432	## Rules implemented
433
434	- 144 tiles (four of each suit/honour, eight flowers), 16-tile hands, dealer
435	draws the 17th.
436	- 補花 at the deal and on every drawn flower, replacements from the back of the
437	wall.
438	- 吃 only from 上家; 碰/槓/胡 from anyone. 明槓, 暗槓, 加槓, 搶槓, 槓上開花.
439	- 流局 when 16 tiles remain (`Rules.wallReserve`); the dealer keeps the deal on a
440	draw or on a dealer win (連莊), otherwise the deal passes and the round wind
441	advances every four passes. A full 四圈 game is 16 dealer passes.
442
443	### House rules (switches in `Rules`, all on the settings screen)
444
445	- 過水 `sacredDiscard` (on) — pass on a tile you could have won with and it
446	is dead to you until your own next draw; the seat shows a 過水 badge listing
447	what it is locked out of, so the missing 胡 button is never a mystery. A draw
448	from either end of the wall lifts it. `sacredClearedByClaim` (off) decides
449	whether taking a 吃 / 碰 / 槓 lifts it too — tables genuinely differ.
450	- 一炮多響 `multipleWinners` (off) — one discard pays out to every seat that
451	calls on it, each settled separately against the discarder. With it off the
452	tile goes to the caller nearest the discarder. Either way the table now waits
453	for other seats that can win before settling, so the nearest seat wins the
454	tile rather than the quickest hand — and the 摸牌 button still closes the
455	window on anyone dithering.
456	- 包牌 `liability` (on) — feeding the pung that completes a visible 大三元
457	or 大四喜 makes the feeder answer for the whole hand, in place of all three
458	payers. Only the seat that fed the last of those sets is on the hook, and
459	only if it came off a discard: a hand that assembled them itself, or closed
460	the set with a 暗槓, has nobody to blame.
461
462	### 台 scoring (`src/game/tai.ts`)
463
464	自摸 1 · 門清 1 · 門清自摸 +1 · 全求人 2 · 平胡 2 · 五門齊 2 · 正花 1 each ·
465	花槓 2 · 八仙過海 8 · 圈風 / 門風 1 each · 三元牌 1 each · 小三元 4 · 大三元 8 ·
466	小四喜 8 · 大四喜 16 · 碰碰胡 4 · 混一色 4 · 清一色 8 · 字一色 16 ·
467	三暗刻 2 / 四暗刻 5 / 五暗刻 8 · 獨聽 · 單釣 1 · 搶槓 1 · 槓上開花 1 ·
468	海底撈月 1 · 河底撈魚 1 · 天胡 16 · 地胡 16 · 人胡 8 · 莊家 1 (連N拉N → 2N+1)
469
470	Ambiguous hands are decomposed every legal way and scored at the best reading.
471
472	Payment (`Game.settle`): one unit is `底 + 台 × 台值`
473	(`DEFAULT_RULES` = 底 3, 台 1, 100 chips each).
474	放槍一家付 — the discarder alone pays one unit; on 自摸 all three pay one unit
475	each. 拉莊 is billed to the dealer alone when the dealer is a payer, and added
476	to the whole hand when the dealer wins.
477
478	House rules vary a lot; the tai table and payments are plain data/functions in
479	`tai.ts` and `types.ts` if yours differ.
480
481	## Audio, by seat
482
483	A sound at a mahjong table comes from somewhere. You know whose 碰 that was
484	because it came from your left, and you know a tile has been thrown hard at the
485	far corner without watching it go. Both of those are cheap to keep, and both
486	are gone the moment everything comes out of the middle of one screen.
487
488	Every cue is a seat's. `SoundCue` carries a `seat` alongside the kind and
489	the tile — the seat that threw, called, or won — and leaves it off the things
490	that belong to the table rather than to anybody: the deal, a 流局, an undo. The
491	engine says whose only because a sound has to come from somewhere; what that
492	means in the room is entirely the UI's business, as it always was.
493
494	A seat becomes a place. `App.tsx` turns a seat into a *position round this
495	screen* — 0 the near edge, 1 the right, 2 across, 3 the left — because that is
496	what the ear wants and the seat number is not: online the table is turned so
497	you are always at the bottom, and the sound has to turn with it.
498	`game/sound.ts` gives each position a bus of its own: a pan, a gain, and a
499	lowpass that opens all the way for the near edge and closes to 5 kHz for the
500	far one. Distance is two things at once — quieter, and with the top taken off
501	— because between you and 對家 there is a metre of air, a wall of tiles, and
502	three people's arms, none of which carry treble. Tiles out in the middle skip
503	the edges entirely and are placed continuously, panned by where on the felt
504	they actually landed; the physics knows that to the pixel. Buses are built once
505	per spot and quantised, so a pool full of skidding tiles reuses a handful
506	rather than building one per contact. Old Safari has no `StereoPannerNode`; it
507	plays where it always did.
508
509	At a shared table, the words come out of the player. Five devices in one
510	room, and the split the sound should take is the one the room already has: the
511	table makes the noise, because the tiles are on the table, and the phone in
512	somebody's hand says their calls, because the calls are theirs. So the table's
513	screen drops the voice for a seat while keeping the clack, and the phone
514	holding that seat says 碰 and names its own discards and makes no table noise
515	at all.
516
517	That only works if the phone really is going to say it, so it is asked rather
518	than assumed. `sound.voiceLive()` is the honest answer — sound on, 報牌 on, the
519	audio hardware awake, the pack decoded — and every device reports it to the
520	host whenever it changes (`EV_VOICE`). The host works out, seat by seat, which
521	hands have a device that will speak for them and publishes that as `voices` in
522	room state; a nameplate wearing 🔊 next to its 📱 is a seat the table has gone
523	quiet for on purpose. Mute the phone, put it to sleep, hand the seat back —
524	the flag drops and the table takes the calls back mid-hand. The host's own
525	device never counts, even when it holds seats: it is the table, and a table
526	that fell silent on the grounds that it was about to speak would say nothing at
527	all.
528
529	A browser will not start audio before the page has been touched, and a phone
530	that arrived by QR may never touch anything that asks for it by name — so the
531	first touch anywhere unlocks it, which is also the moment it can start
532	claiming the job.
533
534	## The voice pack
535
536	A mahjong table only ever says about fifty things — 42 tile names and a handful
537	of calls — so the whole vocabulary is rendered ahead of time into
538	`public/voice/` (~330 kB of mp3) rather than left to whatever speech synthesis
539	the browser happens to have. On Linux that is usually espeak-ng, which is
540	intelligible but sounds like a modem; and on a machine with no Chinese voice at
541	all the feature would silently do nothing. Shipping the audio makes playback
542	instant, identical everywhere, and lets a call be cut off mid-word when the
543	next one lands, all through the same Web Audio graph as the chimes.
544
545	`scripts/voice.mjs` is the authoring step, not part of `npm run build`. It needs
546	[piper](https://github.com/OHF-Voice/piper1-gpl) and ffmpeg on PATH:
547
548	```
549	node scripts/voice.mjs # → public/voice/*.mp3 + manifest.json
550	PIPER_MODEL=/path/to/voice.onnx node scripts/voice.mjs # a different voice
551	```
552
553	The wording lives in that script, and some of it is deliberately not the bare
554	tile character: 東 alone is a direction where 東風 is the tile, and the dragons
555	are 紅中 / 發財 / 白板 the way they are actually called — which also gives the
556	phonemiser enough context to get the tone right, since 中 on its own is as
557	likely to come out zhòng.
558
559	The clips here were rendered with piper's `zh_CN-huayan-medium`. If you
560	redistribute this app, check that voice's model card in
561	[piper-voices](https://huggingface.co/rhasspy/piper-voices) for the terms
562	attached to it, the same way you would the tile art below — or re-render the
563	pack with a voice whose terms suit you, which is a single command.
564
565	## Tile art
566
567	`public/tiles/tiles.svg` is the postmodern tileset from
568	[gnome-mahjongg](https://gitlab.gnome.org/GNOME/gnome-mahjongg), extracted from
569	the installed binary's GResource — a 43×2 sprite sheet (second row is the
570	highlighted variant, used for a lifted tile). `public/tiles/back.png` is the
571	blank tile from its smooth theme, tinted jade, since a solitaire game has no
572	face-down art of its own.
573
574	How a tile is drawn on the canvas — the outline round it and the shadow under
575	it — lives in `src/ui/tileArt.ts`, and `npm run dev` serves `/tiles.html`, a
576	page of every face at every angle over the felt with a slider on each of those
577	numbers and the finished block ready to paste back. None of it can be judged
578	from the values: it is 246 white against a dark green at 35 pixels across, and
579	the only way to know is to look at it and move something. (`tiles.html` is not
580	one of the build's entry points, so it does not ship.)
581
582	The sheet is not a picture of a tile's face. It is a picture of a whole tile,
583	drawn in an oblique projection, with its own sides painted down the left and
584	along the bottom and its own light coming from the top right — a 16px bevel on a
585	128px cell. That is fine while every tile stands the same way up, and wrong the
586	moment they are scattered: rotating the sprite rotates a pre-rendered solid, so
587	a pool of discards ends up with a different sun on each tile.
588
589	So the art is cropped back to the flat face, and the solid is worked out
590	instead. A tile is a box lying on cloth: take the four corners of the rotated
591	rectangle, offset them by the projection (`depthAngle`, down and to the left,
592	the same direction the art used), and fill the two or three quads whose edges
593	the base falls away from — each shaded from the direction that edge faces *on
594	screen*. Turn the tile and the same physical side comes round to face a
595	different way and its shading changes with it, which is the whole point. No 3D
596	engine, no z-buffer: one projection vector and a dot product per edge.
597
598	Each cell of the sheet is cut out into its own canvas the first time it is
599	wanted. `drawImage` with a source rectangle is allowed to sample past that
600	rectangle when it resamples, and the row under every face is the highlighted
601	variant, whose border is bright blue — so a tile at any angle other than a right
602	one wore a blue fringe along one edge. Square on it never showed, which is why
603	it looked like a rotation bug rather than a spritesheet one.
604
605	A tile used to be drawn as two passes — a slab of ivory offset down the screen
606	with the face on top, so a sliver of the tile's own side showed along the bottom
607	edge. At the size a discard is actually drawn that never read as thickness; it
608	read as a second, paler shape stuck to the bottom of every tile. Shading it
609	better did not help, because the problem was that it was there. What gives a
610	tile its weight now is the shadow and the outline, both of which are true at
611	any size.
612
613	That art is GPL-2.0-or-later. Fine for playing at home; if you ever
614	distribute this app, either honour the GPL or swap the two files for art of your
615	own — `SPRITE_COL` in `tiles.ts` is the only mapping that would need updating.
616
617	Known gaps and house rules that aren't implemented yet are listed in
618	[TODO.md](TODO.md).
619
620	## Layout
621
622	```
623	public/tiles/ sprite sheet + tile back
624	src/game/tiles.ts tile codes, wall, shuffle, sprite mapping
625	src/game/hu.ts hand decomposition, 聽 detection, wait shapes
626	src/game/shanten.ts 向聽 / 進張 counting, for the computer players
627	src/game/bot.ts what a computer player discards and claims (pure)
628	src/game/danger.ts reading the table: who looks ready, which tiles are hot
629	src/game/autoplay.ts when it does it, and how long it appears to think
630	src/game/tai.ts 台 scoring
631	src/game/engine.ts state machine: deal, turns, claim resolution, settlement
632	src/game/ctl.ts TableCtl — the surface the UI drives, local or networked
633	src/game/wall.ts what is left of the square, and what still blocks a throw
634	src/net/room.ts the wire itself: join, reconnect, state, events
635	src/net/session.ts the room: host duties, seats, intents, migration
636	src/net/table.ts TableCtl over the wire: mirror + intents + hand overlay
637	src/net/protocol.ts what crosses the wire, in one place
638	src/net/handOrder.ts your own arrangement, kept on your own device
639	src/ui/Controller.tsx the phone at the shared table: your tiles and the throw
640	src/ui/OnlineLobby.tsx seats and the deal button, before an online game
641	server/rooms.ts the relay: rooms, host election, state fan-out
642	server/index.ts production: dist/ and the relay from one port
643	src/table/physics.ts the discard pool: rectangles with weight, pure and testable
644	src/table/geometry.ts the table measured — colliders, launch points, throw gate
645	src/table/pool.ts game state ⇄ tiles in the middle, by diffing the discards
646	src/ui/ TileView, Hand (drag and throw), Seat, Center, Pool, Help
647	```
648
649	## The tiles in the middle
650
651	The pool is a small rigid-body solver (`src/table/physics.ts`) that knows nothing
652	about mahjong, the DOM, or the clock: fixed 1/120s steps, no randomness of its
653	own, and everything in table pixels. Given the same throws it produces the same
654	pile every time, which is what lets a refresh mid-hand come back to the pile you
655	had rather than a freshly scattered one — positions are derived from the hand
656	number and each tile's place in its thrower's discards, never saved.
657
658	The pile is handled directly. Press on a discard and it comes up out of the
659	pile, carried over the top of the others rather than ploughing through them;
660	let go slowly and it is set down there, flick and it goes off across the felt at
661	the speed it left your fingers — the same throw a tile gets out of a hand, made
662	from the middle of the table instead. Pressing on bare felt does nothing, and
663	the press passes through to whatever was really under it: the tiles are drawn on
664	a canvas with no elements to hit, so the hit test is against the physics and the
665	listener is a capturing one on the table itself.
666
667	A flick is the whole of a throw: the direction and the speed it leaves at are
668	the hand's, and nothing between the fingers and the felt changes either. The one
669	thing the table decides is height — with a standing wall in front of the
670	throw a flat tile would only skid into it, so it is lofted over instead, exactly
671	as far as it was thrown and simply in the air for the first part of the way. A
672	tile that carries past the square and out into the open stays there. (It used to
673	be re-aimed at the middle of the square when the flick's line missed it, which
674	put the tile on a line nobody had thrown and read, fairly, as a bounce off
675	nothing.)
676
677	What stops a tile is other tiles. There is no fence: the standing stacks of the
678	wall, the sets people have laid down and the sixteen each of them is holding are
679	all measured as colliders, so the pile is held in by the ring of tiles round it
680	exactly as it is on a real table, and spills through whatever gaps the wall has
681	been eaten into. The table's own edge is a backstop at the screen edge, there
682	only so a tile that got past all of that isn't lost.
683
684	It is drawn on a canvas that spans the whole table, not just the centre.
685	That is deliberate: `.slot` and `.seat` both clip their own contents, which is
686	why a tile can't be animated out of a strip as an element. On the canvas there is
687	nothing to clip it, so a tile lifted out of a hand crosses the table in one
688	piece.
689
690	The square is the whole wall: eighteen stacks of two a side, four sides, 144
691	tiles, the way it is built on a table. It used to be rebuilt to what was left
692	after a hand had been dealt — barely half of it — because eighteen full-size
693	stacks a side wants about 560px and no ordinary window has that between the top
694	and bottom strips. That bought a square at the price of it not being the wall:
695	a side ran out of stacks before it reached its corner, so the four of them never
696	met.
697
698	Nothing gives now, and in particular the tile does not. Every tile on the table
699	is one size — `--tile-w` in styles.css, in a hand, in the wall, and lying in the
700	middle — because they are the same tiles, and a tile that changed size between
701	the wall and your hand read as a different, smaller set sitting in the middle.
702	The square is built from that tile and is however big that comes to:
703	`wallSquare()` in `game/wall.ts` takes the tile and hands back the lengths, and
704	`WallRing` measures one rendered cell to find out what CSS made it. The wall
705	being bigger than the room between the strips is a fact about a 144-tile wall,
706	not a thing to solve by shrinking it.
707
708	The four walls are placed by CSS alone: each is pinned to its own edge of the
709	opening with `left`/`top`, runs its whole length from the corner it is built
710	from, and so carries one wall-depth past the far corner and over the end of the
711	next wall along. Every corner of the square is covered by exactly one wall and
712	no two overlap — that is the pinwheel. Nothing is rotated; a square wants no
713	rotation to describe it.
714
715	The overhang is exactly one wall-depth, which is what it takes to close a right
716	angle: two bands of thickness `t` meeting at an interior angle ψ overlap by
717	`t / tan(ψ/2)`, and at ninety degrees that is `t`. So the whole square measures a
718	wall's length plus one depth across, and leaves that length less one depth in
719	the middle — which is the opening, and which is what `.wall-ring` itself is.
720
721	The CSS only places what it is told: `.wall-side` is a row of stacks, laid across
722	on the two flat walls and down on the two upright ones, and `--wall-len` from
723	`WallRing` is the only length it is given. Every place in the wall is rendered
724	whether or not there is still a stack standing on it, because with the break
725	anywhere but a corner a wall is eaten from its middle — a row that closed the
726	gap up would drag the whole tail of the wall along the table behind it.
727
728	Where the four walls stand is found at the table itself rather than on a page
729	of sliders: take hold of a wall in a real game and push it. It goes where the
730	finger goes, and lets go saying where it landed — `[wall] top pushed to 0.5,-4.9
731	— top 0.5,-4.9 · right 0,0 · …` in the console, in tiles, which is the form
732	`WALL_PLACED` in `game/wall.ts` is written in, so what a push finds pastes
733	straight back in. Nothing about the hand moves: the wall is the same wall in the
734	same order and the next draw is still the next draw. There used to be a
735	`/wall.html` for this; the table is the honest place to do it, so that page is
736	gone.
737
738	## 擲骰 — where the wall is broken
739
740	The dealer throws three dice to open a hand, and the total does two jobs. It
741	counts round the seats — the dealer being one, and the count going the way the
742	turn goes — to pick whose wall is opened. Then the same number counts stacks in
743	from the right-hand end of that wall, and the break is behind them: the first
744	tile drawn is the next one along, and the drawing runs away to the left from
745	there, on round the square.
746
747	The square makes that cheap to say. Every wall is laid down from the corner its
748	own player's right hand falls on — that is what the pinwheel is — so the run of
749	72 places already starts at each seat's right, and the break is simply so many
750	places into the side the dice picked. `breakAt()` is those two lines.
751
752	Nothing about the tiles turns on it: the wall was shuffled before it was built,
753	so which stack is drawn first is decided either way. What it moves is where in
754	the middle of the table the gap opens and who has to reach furthest for the next
755	draw — which is the whole of what it does at a table too. The throw is made from
756	the same seeded rng that shuffled, so a seed replays a hand's gap as well as its
757	tiles.
758
759	In a dev build a panel in the corner of the table steps the total through every
760	one three dice can make, 3 to 18, and redraws the square on each; 整牆 144
761	puts every tile back, which is what the square is built to and what it only ever
762	is for the moment before the deal. `game.reroll(6, 6, 6)` does the same from the
763	console.
764	Nothing about the square is calculated twice. Its size lives entirely in CSS
765	(`--ws`, `--wd`), so `geometry.ts` measures it instead of restating that
766	arithmetic: `WallRing` already renders every stack as a real element tagged with
767	its index, and the colliders are those elements' bounding rects. That one
768	mapping is what makes the wall a physical object — the thing a thrown tile
769	bounces off, and the thing the throw gate casts its ray at.
770
771	### Seeing the colliders
772
773	Because every boundary is measured off the DOM rather than written down, the
774	only honest way to check a bounce is to draw the boxes in the coordinate space
775	the tiles are drawn in. Add `?colliders` to the address, or call `colliders()`
776	from the console while a hand is running:
777
778	\| drawn \| is \|
779	\| --- \| --- \|
780	\| solid rectangle at the screen edge \| the table itself. Nothing meets this in play — it is only there so a tile that got past everybody's tiles is still on the table afterwards \|
781	\| solid box on every tile \| a collider. Every tile on the table is one: the stacks still standing, the sets people have laid down, and the sixteen each of them is holding. Half stacks aren't drawn because they aren't colliders — a tile goes over them \|
782	\| dashed rectangle \| the wall square's opening — where a throw is aimed. It stops nothing, which is why the pile spills out of it \|
783	\| dotted rectangle, inset \| where the moving tile's own centre may be against the table's edge, which is its half width in from it \|
784	\| box hugging each pool tile \| the rotated rectangle it really collides with \|
785	\| dotted box round the moving tile \| the upright box the straight edges use instead. It comes apart from the rotated one as the tile turns \|
786
787	\| blue rays from a throw \| faint: the flick, as the tile was let go of. Bright: the line it was actually sent along, labelled `slide` or `lob`. These should lie on top of each other — the flick is the throw, and a tile leaving on a line nobody threw reads exactly like a bounce off something invisible \|
788	\| yellow cross \| where contact was actually made, fading over a second or so. One of these sitting in open felt with no box under it is a bounce off something that isn't a collider at all — a different bug from a box in the wrong place \|
789
790	Colliders mode is also a throwing sandbox: a flick throws for real but is not a
791	discard, so the tile stays in your hand, the turn never passes and the computer
792	players hold still. Throw the same tile at the same corner as many times as you
793	like. Sixty stay on the table before the oldest is swept off; `pool.clearLoose()`
794	sweeps them all. Tapping a tile to discard does nothing in this mode — throwing
795	is the thing being tested.
796
797	Add `pause=1` (`?colliders&pause=1`, or `pause()` from the console) to **stop
798	dead on contact**. The physics halts on the fixed step that resolved it and
799	drops the rest of the frame, so what's on screen is where the tile touched
800	rather than where it had got to by the end of the frame. Space carries on, →
801	takes one step, ↑ takes ten; the console says what it stopped on.
802
803	`colliders(false)` turns it off again. It repaints on toggle, so a settled table
804	doesn't have to be poked first. In a dev build `pool` is the live pool: the
805	overlay draws `pool.world.walls`, the physics' own copy rather than a fresh
806	measurement, so if what's drawn ever disagrees with the DOM it is the world that
807	went stale — which `pool.measuredAt` will show, since the stamp carries every
808	hand's shape.
809
810	## What is left of the wall
811
812	Four walls of eighteen full-size stacks want about 560px a side. No ordinary
813	window has that between the top and bottom strips, and the tile is not allowed
814	to shrink to make it fit — a tile in the wall is the same tile you play with, so
815	drawing it smaller was a visible lie.
816
817	What saves it is that nobody ever sees a whole wall: four hands come off the
818	front before the table is on screen, so barely half of it is left by then. So
819	only the stacks still standing are drawn, and they are laid out around a ring
820	cut to the middle rather than to eighteen — `ringLayout` in `game/wall.ts`
821	measures how many stacks a side can take (`WallRing` renders one hidden cell and
822	asks CSS how big it came out) and shares what is left over the four sides in
823	proportion. Every seat keeps a wall in front of it instead of the remainder
824	piling into one corner, and the order runs all the way round, so the break point
825	is still at the head of it and the 底牌 tail still at the end.
826
827	Shuffling the wall along as it is eaten costs nothing to look at, because every
828	stack shows the same green back — and it is what people do to a half-eaten wall
829	anyway.
830
831	`pool.ts` never listens for events. It diffs the discards against what it is
832	already drawing, keyed by `seat:index` — and those keys never shift, because
833	discards are only ever pushed and a claim only ever pops the one on top. So a
834	key that appeared is a tile to throw in and a key that went is a tile to take
835	off, which makes undo, 下一局, a claim and resuming a saved game all the same
836	code path. The engine has no idea any of it exists, and the save format did not
837	change.