collin/mahjong

c1de3f155bd40675a20193a465ff3683cf1015df / src / table / physics.ts

1	import type { Tile } from '../game/tiles';
2	import type { SeatId } from '../game/types';
3
4	/**
5	* The tiles in the middle of the table, as things with weight.
6	*
7	* Pure and deterministic: no DOM, no clock, no randomness. Where the world's
8	* measurements come from is `geometry.ts`; what gets thrown into it and when is
9	* `pool.ts`; drawing it is `ui/Pool.tsx`. Anything random — the scatter on a
10	* placed tile, where a rebuilt pile's tiles sit — is decided by the caller and
11	* arrives as a spawn impulse, which is what lets the same hand come back to the
12	* same pile after a refresh.
13	*
14	* Tiles are rectangles and they are solved as rectangles: two of them can lean
15	* against each other at any angle but never share the same ground. Everything is
16	* in CSS pixels, table-local, and seconds.
17	*/
18
19	/** One fixed step. Small enough that a hard flick can't tunnel a wall. */
20	export const FIXED_DT = 1 / 120;
21	/**
22	* Most catch-up a single frame will simulate. A tab that was in the background
23	* for a minute comes back to a settled pile, not to a spin through 7200 steps.
24	*/
25	const MAX_SUBSTEPS = 8;
26
27	/** Falls onto the felt in about half a second from a normal throw. */
28	const GRAVITY = 2600;
29	/** Tiles are dense and land flat; they do not bounce much. */
30	const Z_RESTITUTION = 0.34;
31	/** Below this the tile is flat on the felt: sliding, and in the way of others. */
32	const ON_FELT = 8;
33	/**
34	* How high a standing stack of two reaches. A tile still above this sails over
35	* the wall — which is exactly what a placed tile does, and what a thrown one
36	* must not need to do.
37	*/
38	export const WALL_HEIGHT = 30;
39
40	/**
41	* Felt friction: an exponential part that kills speed, and a constant part that
42	* actually brings it to a stop rather than to an asymptote.
43	*
44	* Deliberately light. A tile thrown hard should cross the square, come off the
45	* far side and barge through what is already lying there before it settles —
46	* heavier friction ate the throw in the first few inches and every discard
47	* ended up looking the same however it was let go of.
48	*/
49	const FELT_DAMP = 2.6;
50	const FELT_STOP = 70;
51	const SPIN_DAMP = 3.4;
52	const SPIN_STOP = 0.9;
53
54	/**
55	* Roughly how much longer a tile keeps travelling after it lands, as a time.
56	* Aiming a throw means solving for where it comes to rest, not where it first
57	* touches down, so `pool.ts` adds this to the flight time.
58	*/
59	export const SLIDE_TIME = 1 / FELT_DAMP;
60
61	/** Off the inside of the wall square, and off another tile. Bouncy enough that
62	* a hard throw ricochets instead of sticking where it first lands. */
63	const BOUND_RESTITUTION = 0.55;
64	const BOUND_FRICTION = 0.9;
65	const TILE_RESTITUTION = 0.42;
66	/** How much of a glancing blow becomes spin. Tiles are light and skate. */
67	const SPIN_TRANSFER = 0.06;
68
69	/** Asleep after this many consecutive steps of going nowhere. */
70	const SLEEP_SPEED = 7;
71	const SLEEP_SPIN = 0.2;
72	const SLEEP_STEPS = 10;
73	/**
74	* Overlap small enough to live with. Without this a crowded pool never sleeps:
75	* a tile squeezed between its neighbours and the pool's edge gets pushed out of
76	* contact and shoved back into it on every step, for ever. A fifth of a pixel is
77	* not something you can see, and it is what lets the pile go quiet.
78	*/
79	const CONTACT_SLOP = 0.2;
80	/**
81	* A body moving this slowly for this long is put to sleep whatever it thinks it
82	* is doing. The backstop that guarantees the pile always settles — counted from
83	* when it last woke, not from when it was thrown.
84	*/
85	const AWAKE_LIMIT = 600;
86
87	/** Pulls a tile that landed short of the pool in towards the rest of them. */
88	const ENTRY_PULL = 700;
89	/**
90	* How long a tile gets to find its own way into the pool before it is simply
91	* put there. A discard is game state made visible — it has to be in the middle
92	* where it can be seen and counted — so a tile that has got itself wedged
93	* against a standing stack, or is bouncing between two of them, cannot be left
94	* out there. Two seconds is far longer than any real throw takes to settle.
95	*/
96	const ENTRY_GRACE = 240;
97
98	/**
99	* How hard a tile that merely arrived counts as having arrived: enough for
100	* the seat it came in past to notice, deliberately under the threshold the
101	* renderer plays a clack at. Nothing was hit, so nothing should be heard.
102	*/
103	const ARRIVED = 0.1;
104
105	/** How fast a tile drawn at hand size shrinks to the size it is in the pool. */
106	const SCALE_EASE = 6;
107
108	export const TAU = Math.PI * 2;
109	/**
110	* How quickly whatever is left of a tumble is taken up once the tile is down.
111	* A thrown tile turns over in the air a whole number of times, so it should be
112	* face up as it lands — but a bounce or a shove can leave it part-way round, and
113	* a mahjong tile on a table is never resting on its face. This takes up the
114	* remainder, and `sleep` guarantees the rest.
115	*/
116	const FLIP_SETTLE = 14;
117
118	export interface Rect {
119	x: number;
120	y: number;
121	w: number;
122	h: number;
123	}
124
125	/** Anything the collision routines can treat as a rotated rectangle. */
126	interface Box {
127	x: number;
128	y: number;
129	w: number;
130	h: number;
131	angle: number;
132	}
133
134	export interface Body {
135	tile: Tile;
136	/** Who threw it — for the fly-out when it is claimed, not for any marking. */
137	seat: SeatId;
138	/** Centre on the felt plane. */
139	x: number;
140	y: number;
141	vx: number;
142	vy: number;
143	/** Height above the felt, and its rate. Only ever >= 0. */
144	z: number;
145	vz: number;
146	angle: number;
147	spin: number;
148	/**
149	* Turning over in the air, about an axis lying in the table — what a thrown
150	* tile does, as opposed to `angle`, which is it turning flat on the cloth.
151	* Zero, or any whole number of turns, is face up.
152	*/
153	flip: number;
154	flipSpin: number;
155	/** Which way that axis points: a tile tumbles across its line of travel. */
156	flipAxis: number;
157	w: number;
158	h: number;
159	/**
160	* Render-only: what to multiply the drawn size by, easing to 1. A tile is
161	* drawn big in a hand so it can be read, and small in the pool because that is
162	* the size it is in the wall, so a thrown one has to settle from one to the
163	* other. Eased here rather than in the renderer so it does not run at a
164	* different speed on a different frame rate.
165	*/
166	scale: number;
167	/**
168	* Whether it has ever been inside the pool. Until it has, it is free to fly
169	* over the wall from a seat's edge; once it has, the pool keeps it.
170	*/
171	entered: boolean;
172	/**
173	* Which side of the table it is still on its way in over. Every tile is
174	* thrown from outside, so every tile has one until it lands; it is what the
175	* table reports when the tile finally gets in, since by then there is no
176	* longer an edge to read off its position.
177	*/
178	over?: Edge;
179	/**
180	* Whether it has got clear of the hand it was thrown from. A tile leaves from
181	* inside its own row — `throwFrom` is the middle of the last cell — so on
182	* the frame it is let go it is overlapping its thrower's own tiles, and
183	* without this every throw would ricochet off the hand that made it. Your own
184	* tiles are not solid to you until you are out of them.
185	*/
186	leftSeat: boolean;
187	/**
188	* In somebody's fingers. Its position is set from outside — a finger is not
189	* a force — so the solver leaves it entirely alone: it does not fall, drift,
190	* settle or take a shove, and it is held high enough to pass over everything
191	* else while it is being carried.
192	*/
193	carried: boolean;
194	resting: boolean;
195	/** Consecutive slow steps, counting towards sleep. */
196	still: number;
197	/** Steps lived, for the grace period on getting into the pool. */
198	age: number;
199	/** Steps since it last woke, for the backstop on settling. */
200	awake: number;
201	}
202
203	/**
204	* Which edge of the middle a tile ran into. The middle stops where the four
205	* players' tiles start, so an edge is somebody's hand: a tile that reaches one
206	* hard has been thrown into their tiles, and they have something to say about
207	* it. Seats are the caller's business; this only says which way it went off.
208	*/
209	export type Edge = 'left' \| 'right' \| 'top' \| 'bottom';
210
211	/** A collision loud enough to hear. `strength` is 0..1. */
212	export interface Impact {
213	x: number;
214	y: number;
215	strength: number;
216	/** Set when it was the edge of the table it hit, not a wall or another tile. */
217	edge?: Edge;
218	/** Whose tiles it ran into, where what it hit belonged to somebody. */
219	into?: SeatId;
220	/** Whose discard it was — you cannot be barged by your own tile. */
221	seat?: SeatId;
222	}
223
224	/**
225	* Something solid on the table. Everything that stops a tile is another tile:
226	* the stacks still standing in the wall, the sets people have laid down, and
227	* the sixteen everyone is holding. `seat` is whose it is, where it is somebody's
228	* — a tile thrown into a hand is a thing that hand's owner answers.
229	*/
230	export interface Barrier {
231	rect: Rect;
232	seat?: SeatId;
233	}
234
235	export interface World {
236	/** Where tiles come to rest — inside the wall square. */
237	bounds: Rect;
238	/** Stacks of two still standing. Half and spent stacks are not obstacles. */
239	walls: Barrier[];
240	bodies: Body[];
241	/** Left-over time from the last frame, so steps stay a fixed size. */
242	carry: number;
243	/**
244	* Overlaps pushed apart in the last step. The pile is not settled while this
245	* is non-zero, however still everything looks — two tiles asleep inside each
246	* other would otherwise stay that way for the rest of the hand, because a
247	* pile that has stopped moving stops being stepped.
248	*/
249	contacts: number;
250	/** Steps spent untangling a pile that is otherwise asleep, so it cannot spin. */
251	relaxed: number;
252	}
253
254	export interface Spawn {
255	tile: Tile;
256	seat: SeatId;
257	x: number;
258	y: number;
259	vx: number;
260	vy: number;
261	z: number;
262	vz: number;
263	angle: number;
264	spin: number;
265	/** Whole turns to make in the air. It lands face up whatever this is. */
266	flipTurns?: number;
267	/** Seconds of flight those turns are spread over. */
268	flipOver?: number;
269	flipAxis?: number;
270	w: number;
271	h: number;
272	/** Drawn this much bigger to start with, easing to its pool size. */
273	scale?: number;
274	/** Already settled — a pile being rebuilt after a reload or an undo. */
275	atRest?: boolean;
276	}
277
278	export function createWorld(bounds: Rect, walls: Barrier[] = []): World {
279	return { bounds, walls, bodies: [], carry: 0, contacts: 0, relaxed: 0 };
280	}
281
282	export function addBody(world: World, s: Spawn): Body {
283	const body: Body = {
284	tile: s.tile,
285	seat: s.seat,
286	x: s.x,
287	y: s.y,
288	vx: s.atRest ? 0 : s.vx,
289	vy: s.atRest ? 0 : s.vy,
290	z: s.atRest ? 0 : s.z,
291	vz: s.atRest ? 0 : s.vz,
292	angle: s.angle,
293	spin: s.atRest ? 0 : s.spin,
294	flip: 0,
295	// Spread the turns over the flight, so the tile comes down as it comes back
296	// round to face up rather than being snapped there on landing.
297	flipSpin:
298	s.atRest \|\| !s.flipTurns \|\| !s.flipOver ? 0 : (TAU * s.flipTurns) / s.flipOver,
299	flipAxis: s.flipAxis ?? 0,
300	w: s.w,
301	h: s.h,
302	scale: s.atRest ? 1 : s.scale ?? 1,
303	entered: !!s.atRest,
304	// A rebuilt pile is already lying in the middle, not in anybody's hand.
305	leftSeat: !!s.atRest,
306	carried: false,
307	resting: !!s.atRest,
308	still: s.atRest ? SLEEP_STEPS : 0,
309	age: 0,
310	awake: 0,
311	};
312	world.bodies.push(body);
313	if (s.atRest) {
314	// A tile dropped straight into a settled pile still has to make room. This
315	// is a first shove only — the relaxing below finishes the job, which matters
316	// for a whole pile rebuilt at once when a saved game is picked up.
317	separate(world, body);
318	world.contacts++;
319	}
320	return body;
321	}
322
323	// ---- rotated rectangles ---------------------------------------------------
324
325	/** Distance from a box's centre to its edge, measured along `ax`. */
326	function reach(b: Box, ax: { x: number; y: number }): number {
327	const c = Math.cos(b.angle);
328	const s = Math.sin(b.angle);
329	return (
330	Math.abs(c * ax.x + s * ax.y) * (b.w / 2) + Math.abs(-s * ax.x + c * ax.y) * (b.h / 2)
331	);
332	}
333
334	/** The rotated rectangle's own bounding box, for the pool's straight edges. */
335	function aabbHalf(b: Box) {
336	const c = Math.abs(Math.cos(b.angle));
337	const s = Math.abs(Math.sin(b.angle));
338	return { x: (b.w / 2) * c + (b.h / 2) * s, y: (b.w / 2) * s + (b.h / 2) * c };
339	}
340
341	/** Enough to skip a pair without doing the real work. */
342	const circumradius = (b: Box) => Math.hypot(b.w, b.h) / 2;
343
344	/**
345	* Separating axis test between two rectangles at any angle. Returns the
346	* shallowest way out — the direction to push `b` away from `a`, and by how much
347	* — or null if they are clear of each other.
348	*
349	* Four axes is all a pair of rectangles needs: each box's two edge normals.
350	*/
351	function overlapOf(a: Box, b: Box): { nx: number; ny: number; depth: number } \| null {
352	const ca = Math.cos(a.angle);
353	const sa = Math.sin(a.angle);
354	const cb = Math.cos(b.angle);
355	const sb = Math.sin(b.angle);
356	const axes = [
357	{ x: ca, y: sa },
358	{ x: -sa, y: ca },
359	{ x: cb, y: sb },
360	{ x: -sb, y: cb },
361	];
362
363	const dx = b.x - a.x;
364	const dy = b.y - a.y;
365	let depth = Infinity;
366	let nx = 0;
367	let ny = 0;
368
369	for (const ax of axes) {
370	const gap = reach(a, ax) + reach(b, ax) - Math.abs(dx * ax.x + dy * ax.y);
371	if (gap <= 0) return null;
372	if (gap < depth) {
373	depth = gap;
374	// Always pointing from a towards b, so callers need not guess.
375	const sign = dx * ax.x + dy * ax.y < 0 ? -1 : 1;
376	nx = ax.x * sign;
377	ny = ax.y * sign;
378	}
379	}
380	return { nx, ny, depth };
381	}
382
383	/** A standing stack, as something the tests above can chew on. */
384	const boxOf = (r: Rect): Box => ({
385	x: r.x + r.w / 2,
386	y: r.y + r.h / 2,
387	w: r.w,
388	h: r.h,
389	angle: 0,
390	});
391
392	// ---- stepping -------------------------------------------------------------
393
394	/**
395	* Where a tile's centre may be for the whole of it to be inside `r`.
396	*
397	* One place rather than three, because the three have to agree: the edge holds
398	* a tile at these limits, and the moment it starts holding it is the moment the
399	* tile reaches them. Deciding that on the centre instead would mean the tile is
400	* declared in while it is still half out, and the first thing the edge did
401	* would be to shove it the rest of the way — half a tile, in one frame, at a
402	* line that is nowhere near the one you can see.
403	*
404	* A pool narrower than a tile would otherwise fight itself, so it centres.
405	*/
406	function limitsOf(r: Rect, b: Box) {
407	const half = aabbHalf(b);
408	return {
409	minX: r.w <= half.x * 2 ? r.x + r.w / 2 : r.x + half.x,
410	maxX: r.w <= half.x * 2 ? r.x + r.w / 2 : r.x + r.w - half.x,
411	minY: r.h <= half.y * 2 ? r.y + r.h / 2 : r.y + half.y,
412	maxY: r.h <= half.y * 2 ? r.y + r.h / 2 : r.y + r.h - half.y,
413	};
414	}
415
416	/** Whether the whole tile has made it in — the edge's own test for `entered`. */
417	function wholly(r: Rect, b: Body): boolean {
418	const l = limitsOf(r, b);
419	return b.x >= l.minX && b.x <= l.maxX && b.y >= l.minY && b.y <= l.maxY;
420	}
421
422	/**
423	* Whose side of the table a tile has ended up off, if it is off any of them.
424	* The furthest it is out, so a tile that overshot a corner belongs to whichever
425	* of the two it went past by more.
426	*/
427	function outsideEdge(r: Rect, b: Body): Edge \| undefined {
428	const out: [Edge, number][] = [
429	['left', r.x - b.x],
430	['right', b.x - (r.x + r.w)],
431	['top', r.y - b.y],
432	['bottom', b.y - (r.y + r.h)],
433	];
434	let worst: [Edge, number] = out[0];
435	for (const one of out) if (one[1] > worst[1]) worst = one;
436	return worst[1] > 0 ? worst[0] : undefined;
437	}
438
439	/**
440	* Run the world forward. `elapsed` is real seconds since the last call; it is
441	* consumed in fixed steps so the result does not depend on the frame rate.
442	* Returns the impacts worth a sound.
443	*/
444	export function advance(world: World, elapsed: number, stopOnImpact = false): Impact[] {
445	world.carry += Math.max(0, elapsed);
446	let steps = Math.floor(world.carry / FIXED_DT);
447	if (steps > MAX_SUBSTEPS) {
448	// Drop the backlog rather than working through it.
449	world.carry = 0;
450	steps = MAX_SUBSTEPS;
451	} else {
452	world.carry -= steps * FIXED_DT;
453	}
454
455	const impacts: Impact[] = [];
456	for (let i = 0; i < steps; i++) {
457	step(world, impacts);
458	// Freeze on the step that resolved the contact, and drop what is left of
459	// the frame — the debugger wants the tile where it touched, not where it
460	// would have been fifteen milliseconds later. See ui/colliders.ts.
461	if (stopOnImpact && impacts.length) {
462	world.carry = 0;
463	break;
464	}
465	}
466	return impacts;
467	}
468
469	/** One fixed step. Exported for the tests, which drive it directly. */
470	export function step(world: World, impacts: Impact[] = []): Impact[] {
471	const dt = FIXED_DT;
472	world.contacts = 0;
473
474	for (const b of world.bodies) {
475	if (b.scale !== 1) {
476	b.scale += (1 - b.scale) * Math.min(1, SCALE_EASE * dt);
477	if (Math.abs(b.scale - 1) < 0.002) b.scale = 1;
478	}
479	// A tile in the fingers is driven, not simulated. Nothing below applies
480	// to it, and it stays awake so it is drawn where the finger put it.
481	if (b.carried) {
482	b.still = 0;
483	b.awake = 0;
484	continue;
485	}
486	if (b.resting) continue;
487	b.age++;
488	b.awake++;
489
490	// --- through the air ---
491	if (b.z > 0 \|\| b.vz !== 0) {
492	b.vz -= GRAVITY * dt;
493	b.z += b.vz * dt;
494	if (b.z <= 0) {
495	const landing = Math.abs(b.vz);
496	b.z = 0;
497	// Below a knock it stops dead rather than shivering out a bounce.
498	b.vz = landing > 40 ? landing * Z_RESTITUTION : 0;
499	const strength = Math.min(1, landing / 900);
500	if (strength > 0.12) impacts.push({ x: b.x, y: b.y, strength });
501	}
502	}
503
504	b.x += b.vx * dt;
505	b.y += b.vy * dt;
506	b.angle += b.spin * dt;
507
508	// Turning over. In the air it tumbles; once it is down, whatever is left of
509	// the turn is taken up so it ends flat on its back with its face showing.
510	if (b.flipSpin !== 0) {
511	if (b.z > 0) {
512	b.flip += b.flipSpin * dt;
513	} else {
514	const target = Math.round(b.flip / TAU) * TAU;
515	b.flip += (target - b.flip) * Math.min(1, FLIP_SETTLE * dt);
516	if (Math.abs(target - b.flip) < 0.01) {
517	b.flip = target;
518	b.flipSpin = 0;
519	}
520	}
521	}
522
523	if (!b.entered) {
524	// Kept from step to step: on the step it finally gets in it is inside
525	// already, and there would be nothing left to read.
526	b.over = outsideEdge(world.bounds, b) ?? b.over;
527	// In means all of it in. Anything less and keepInBounds below would
528	// finish the job in a single frame, which is a collision with nothing.
529	if (wholly(world.bounds, b)) {
530	b.entered = true;
531	// It came in over somebody's side of the table. Said quietly — nothing
532	// was struck, so there is nothing to hear — but said, because a tile
533	// arriving past a seat is that seat's to complain about. Its own
534	// thrower's edge is every tile's way in, and the caller drops that one.
535	if (b.over) {
536	impacts.push({ x: b.x, y: b.y, strength: ARRIVED, edge: b.over, seat: b.seat });
537	}
538	b.over = undefined;
539	} else if (b.age > ENTRY_GRACE) {
540	// Out of time going the long way round. Put it in, gently — but this is
541	// still a tile that ended up off the table on somebody's side.
542	if (b.over) {
543	impacts.push({ x: b.x, y: b.y, strength: ARRIVED, edge: b.over, seat: b.seat });
544	}
545	b.entered = true;
546	b.over = undefined;
547	b.z = 0;
548	b.vz = 0;
549	clampInto(world.bounds, b);
550	}
551	}
552
553	// --- on the felt ---
554	// Strictly z <= 0, not ON_FELT: friction is between the tile and the cloth,
555	// so a tile still in the air keeps the speed it was thrown with. ON_FELT is
556	// only about being low enough to be in another tile's way.
557	if (b.z <= 0) {
558	damp(b, dt);
559	// A tile that fell short skids in rather than sitting outside the pool.
560	if (!b.entered) pullIn(world, b, dt);
561	}
562
563	// A tile still above the wall is clear of it.
564	if (b.z < WALL_HEIGHT) {
565	let inOwnHand = false;
566	for (const wall of world.walls) {
567	if (wall.seat === b.seat && !b.leftSeat) {
568	// Still inside the row it was thrown from: note it, but pass through.
569	const over = overlapOf(boxOf(wall.rect), b);
570	if (over && over.depth > CONTACT_SLOP) inOwnHand = true;
571	continue;
572	}
573	hitWall(b, wall, impacts);
574	}
575	if (!inOwnHand) b.leftSeat = true;
576	}
577
578	// The pool's edge is the inside face of the wall, and it is only as tall as
579	// the wall — a tile lobbed high is over the top of it, not stopped by it.
580	if (b.entered && b.z < WALL_HEIGHT) keepInBounds(world, b, impacts);
581	}
582
583	collideTiles(world, impacts);
584	// Being shoved by a neighbour can put a tile back over the edge, and a tile
585	// that then fell asleep out there would stay out there. Only awake ones need
586	// it: resolvePair never moves a tile that has settled.
587	// Resting tiles included: they get pushed about by the untangling above, and
588	// a tile shoved over the edge must not be left there just because it is asleep.
589	for (const b of world.bodies) {
590	if (b.entered && b.z < WALL_HEIGHT) clampInto(world.bounds, b);
591	}
592	// Deciding to sleep comes last, so it judges where the step actually left
593	// things — before, a contact resolved after the decision would undo it and a
594	// crowded pool would stay awake for ever.
595	for (const b of world.bodies) if (!b.resting) trySleep(b);
596
597	// A pile that has stopped moving but is still untangling itself keeps being
598	// stepped, up to a point. Without the limit a configuration that cannot quite
599	// be resolved would keep the loop running for the rest of the hand.
600	world.relaxed = world.contacts > 0 && world.bodies.every((b) => b.resting) ? world.relaxed + 1 : 0;
601	return impacts;
602	}
603
604	/**
605	* The table has been re-measured — the window resized, or the wall was eaten
606	* further back. The tiles keep where they are, but a pool that shrank must not
607	* leave any of them stranded outside it, and the ones it moves have to wake up
608	* so they can settle again.
609	*/
610	export function reshape(world: World, bounds: Rect, walls: Barrier[]) {
611	world.bounds = bounds;
612	world.walls = walls;
613	for (const b of world.bodies) {
614	if (!b.entered) continue;
615	const x = b.x;
616	const y = b.y;
617	clampInto(bounds, b);
618	if (b.x !== x \|\| b.y !== y) wake(b);
619	}
620	}
621
622	function damp(b: Body, dt: number) {
623	const k = Math.exp(-FELT_DAMP * dt);
624	b.vx *= k;
625	b.vy *= k;
626	b.spin = Math.exp(-SPIN_DAMP dt);
627
628	const speed = Math.hypot(b.vx, b.vy);
629	if (speed > 0) {
630	const next = Math.max(0, speed - FELT_STOP * dt);
631	b.vx = (b.vx / speed) * next;
632	b.vy = (b.vy / speed) * next;
633	}
634	const spin = Math.abs(b.spin);
635	if (spin > 0) b.spin = Math.sign(b.spin) * Math.max(0, spin - SPIN_STOP * dt);
636	}
637
638	/** Nudges a tile that landed outside the pool towards the rest of them. */
639	function pullIn(world: World, b: Body, dt: number) {
640	const cx = world.bounds.x + world.bounds.w / 2;
641	const cy = world.bounds.y + world.bounds.h / 2;
642	const dx = cx - b.x;
643	const dy = cy - b.y;
644	const d = Math.hypot(dx, dy) \|\| 1;
645	b.vx += (dx / d) * ENTRY_PULL * dt;
646	b.vy += (dy / d) * ENTRY_PULL * dt;
647	}
648
649	/** Bounce off whatever is standing there, corner to corner if that is how it
650	* hits — a stack of the wall, a laid-down set, somebody's hand. */
651	function hitWall(b: Body, wall: Barrier, impacts: Impact[]) {
652	const hit = overlapOf(boxOf(wall.rect), b);
653	if (!hit \|\| hit.depth <= CONTACT_SLOP) return;
654
655	const speed = Math.hypot(b.vx, b.vy);
656	b.x += hit.nx * hit.depth;
657	b.y += hit.ny * hit.depth;
658	// Reflect whatever was heading into the wall; keep what was sliding along it.
659	const into = b.vx * hit.nx + b.vy * hit.ny;
660	if (into < 0) {
661	b.vx -= hit.nx * into * (1 + BOUND_RESTITUTION);
662	b.vy -= hit.ny * into * (1 + BOUND_RESTITUTION);
663	}
664	b.spin *= 0.7;
665	b.resting = false;
666	b.still = 0;
667	const strength = Math.min(1, speed / 1100);
668	if (wall.seat !== undefined) {
669	// Into somebody's tiles. Reported however gently it arrived — their row is
670	// theirs, and a discard rolling into it is an event whatever speed it got
671	// there at. Which of them are loud enough to hear is the caller's business.
672	if (speed > SLEEP_SPEED) {
673	impacts.push({ x: b.x, y: b.y, strength, into: wall.seat, seat: b.seat });
674	}
675	} else if (strength > 0.12) {
676	impacts.push({ x: b.x, y: b.y, strength });
677	}
678	}
679
680	/** The pool's edge. Once a tile is in, it stays in — this is the invariant the
681	* tests pin, since a discard that slid off the table would be lost. */
682	function keepInBounds(world: World, b: Body, impacts: Impact[]) {
683	const { minX, maxX, minY, maxY } = limitsOf(world.bounds, b);
684
685	let hit = 0;
686	let edge: Edge \| undefined;
687	if (b.x < minX) {
688	b.x = minX;
689	hit = Math.max(hit, Math.abs(b.vx));
690	edge = 'left';
691	b.vx = Math.abs(b.vx) * BOUND_RESTITUTION;
692	b.vy *= BOUND_FRICTION;
693	} else if (b.x > maxX) {
694	b.x = maxX;
695	hit = Math.max(hit, Math.abs(b.vx));
696	edge = 'right';
697	b.vx = -Math.abs(b.vx) * BOUND_RESTITUTION;
698	b.vy *= BOUND_FRICTION;
699	}
700	if (b.y < minY) {
701	b.y = minY;
702	if (Math.abs(b.vy) > hit) edge = 'top';
703	hit = Math.max(hit, Math.abs(b.vy));
704	b.vy = Math.abs(b.vy) * BOUND_RESTITUTION;
705	b.vx *= BOUND_FRICTION;
706	} else if (b.y > maxY) {
707	b.y = maxY;
708	if (Math.abs(b.vy) > hit) edge = 'bottom';
709	hit = Math.max(hit, Math.abs(b.vy));
710	b.vy = -Math.abs(b.vy) * BOUND_RESTITUTION;
711	b.vx *= BOUND_FRICTION;
712	}
713	// Only a real knock counts as being disturbed. A tile held against the edge
714	// by its neighbours is clamped every single step, and treating that as a knock
715	// would keep the whole pool awake for ever.
716	//
717	// Anything that does arrive under its own steam is reported, however gently:
718	// the edge is where somebody's tiles are, so a discard rolling into them is
719	// an event whatever speed it got there at. Which of them are loud enough to
720	// be worth a sound is the caller's business.
721	if (hit > SLEEP_SPEED) {
722	b.still = 0;
723	impacts.push({ x: b.x, y: b.y, strength: Math.min(1, hit / 1100), edge, seat: b.seat });
724	}
725	}
726
727	/**
728	* Tile against tile.
729	*
730	* Only tiles flat on the felt take part, so a thrown tile passes over the pile
731	* instead of shouldering through it, and a cheap circle test throws out the pairs
732	* that are nowhere near before the real rectangle test runs. Pairs where both
733	* tiles have settled are left alone entirely, which is nearly all of them.
734	*/
735	function collideTiles(world: World, impacts: Impact[]) {
736	const bodies = world.bodies;
737	for (let i = 0; i < bodies.length; i++) {
738	const a = bodies[i];
739	if (a.z > ON_FELT) continue;
740	for (let j = i + 1; j < bodies.length; j++) {
741	const b = bodies[j];
742	if (b.z > ON_FELT) continue;
743	if (Math.hypot(b.x - a.x, b.y - a.y) > circumradius(a) + circumradius(b)) continue;
744	// Two tiles that have both settled are still pushed apart if they are
745	// inside each other — they are just not woken up for it. Skipping the pair
746	// outright was how a pile could end up with tiles sharing ground and stay
747	// that way, since nothing steps a pile that has stopped moving.
748	resolvePair(a, b, impacts, world);
749	}
750	}
751	}
752
753	function resolvePair(a: Body, b: Body, impacts: Impact[], world: World) {
754	const hit = overlapOf(a, b);
755	if (!hit) return;
756	// Resting in contact is not a collision. See CONTACT_SLOP.
757	const depth = hit.depth - CONTACT_SLOP;
758	if (depth <= 0) return;
759	const { nx, ny } = hit;
760
761	world.contacts++;
762	// Push apart. A tile that has settled is the heavy one: a tile thrown into a
763	// pool shoulders in, rather than the pool scattering out of its way.
764	const aShare = a.resting === b.resting ? 0.5 : a.resting ? 0 : 1;
765	const bShare = 1 - aShare;
766	a.x -= nx * depth * aShare;
767	a.y -= ny * depth * aShare;
768	b.x += nx * depth * bShare;
769	b.y += ny * depth * bShare;
770
771	// Impulse along the way out, plus a spin kick off what is left over.
772	//
773	// Only a genuine approach speed counts, and only that wakes anything. Nudging
774	// two touching tiles apart is not a collision: a jammed corner of the pool is
775	// corrected by a fraction of a pixel every step for as long as it is jammed,
776	// and treating each of those as a shove would keep the pile awake for ever.
777	const rvx = b.vx - a.vx;
778	const rvy = b.vy - a.vy;
779	const along = rvx * nx + rvy * ny;
780	if (along >= -SLEEP_SPEED) return;
781
782	const jolt = -along * (1 + TILE_RESTITUTION) * 0.5;
783	a.vx -= nx * jolt;
784	a.vy -= ny * jolt;
785	b.vx += nx * jolt;
786	b.vy += ny * jolt;
787
788	const tangent = rvx * -ny + rvy * nx;
789	a.spin -= tangent * SPIN_TRANSFER * 0.06;
790	b.spin += tangent * SPIN_TRANSFER * 0.06;
791
792	const strength = Math.min(1, Math.abs(along) / 900);
793	if (strength > 0.12) impacts.push({ x: b.x, y: b.y, strength });
794
795	// Whatever was asleep has been shoved, so it is awake now.
796	wake(a);
797	wake(b);
798	}
799
800	function wake(b: Body) {
801	if (b.resting) b.awake = 0;
802	b.resting = false;
803	b.still = 0;
804	}
805
806	function sleep(b: Body) {
807	b.vx = 0;
808	b.vy = 0;
809	b.spin = 0;
810	b.z = 0;
811	b.vz = 0;
812	// Face up, always. A tile lying face down in the discards would be a tile
813	// nobody can read, so this is a guarantee and not an easing.
814	b.flip = Math.round(b.flip / TAU) * TAU;
815	b.flipSpin = 0;
816	b.resting = true;
817	b.awake = 0;
818	}
819
820	function trySleep(b: Body) {
821	const speed = Math.hypot(b.vx, b.vy);
822	const slow =
823	b.entered &&
824	b.z <= 0 &&
825	b.vz === 0 &&
826	b.flipSpin === 0 &&
827	speed < SLEEP_SPEED &&
828	Math.abs(b.spin) < SLEEP_SPIN;
829	if (slow && ++b.still >= SLEEP_STEPS) return sleep(b);
830	if (!slow) b.still = 0;
831	// Backstop: shuffling about in a crowded pool for this long is settled enough.
832	if (b.entered && b.awake > AWAKE_LIMIT && speed < SLEEP_SPEED * 4) sleep(b);
833	}
834
835	/**
836	* Make room for a tile placed straight into a settled pile, without running
837	* time. Used when a pile is rebuilt — a reload, an undo — where the tiles have
838	* to be somewhere sensible immediately and nothing should appear to move.
839	*/
840	function separate(world: World, body: Body, passes = 16) {
841	// Which way to go when two tiles are exactly on top of each other. Stepping
842	// by the golden angle fans successive tiles out in every direction, where a
843	// fixed axis would march them all one way and pack them against a pool edge.
844	const escape = world.bodies.indexOf(body) * 2.39996;
845
846	for (let p = 0; p < passes; p++) {
847	let moved = false;
848	for (const other of world.bodies) {
849	if (other === body) continue;
850	const hit = overlapOf(other, body);
851	if (!hit \|\| hit.depth <= CONTACT_SLOP) continue;
852	if (Math.hypot(body.x - other.x, body.y - other.y) < 0.0001) {
853	body.x += Math.cos(escape + p) * hit.depth;
854	body.y += Math.sin(escape + p) * hit.depth;
855	} else {
856	body.x += hit.nx * hit.depth;
857	body.y += hit.ny * hit.depth;
858	}
859	moved = true;
860	}
861	clampInto(world.bounds, body);
862	if (!moved) break;
863	}
864	}
865
866	function clampInto(r: Rect, b: Body) {
867	const { minX, maxX, minY, maxY } = limitsOf(r, b);
868	b.x = Math.min(maxX, Math.max(minX, b.x));
869	b.y = Math.min(maxY, Math.max(minY, b.y));
870	}
871
872	/**
873	* How long a motionless pile is allowed to keep untangling itself before the
874	* result is accepted as good enough. Anything still overlapping after this is
875	* doing so by a fraction of a pixel, and the loop has better things to do than
876	* keep running over it.
877	*/
878	const RELAX_LIMIT = 90;
879
880	/** Whether everything has settled — what the render loop idles on. */
881	export const settled = (world: World) =>
882	world.bodies.every((b) => b.resting && b.scale === 1) &&
883	(world.contacts === 0 \|\| world.relaxed > RELAX_LIMIT);
884
885	/** How square-on the face is: 1 flat on its back, 0 edge-on, negative face down.
886	* The renderer squashes the tile by this along its tumbling axis. */
887	export const faceOn = (b: Body) => Math.cos(b.flip);
888
889	/**
890	* A tile's own bounding box, upright. Not what it collides with — that is the
891	* rotated rectangle — but what the felt's straight edges are worked out from,
892	* so the overlay draws both and the difference is visible.
893	*/
894	export function aabbOf(b: Body): Rect {
895	const half = aabbHalf(b);
896	return { x: b.x - half.x, y: b.y - half.y, w: half.x * 2, h: half.y * 2 };
897	}
898
899	/**
900	* Where this tile's centre is allowed to be, which is the edge less its own
901	* half. This is the line a bounce actually happens at, and it sits half a tile
902	* inside the one you can see — which is why a tile looks like it turned around
903	* early. For the overlay; the real work is `limitsOf`.
904	*/
905	export function centreLimits(r: Rect, b: Body): Rect {
906	const l = limitsOf(r, b);
907	return { x: l.minX, y: l.minY, w: l.maxX - l.minX, h: l.maxY - l.minY };
908	}
909
910	/** How far outside the pool a tile is sitting. The tests' invariant. */
911	export function outside(b: Body, pool: Rect): number {
912	const half = aabbHalf(b);
913	return Math.max(
914	0,
915	pool.x + half.x - b.x,
916	b.x - (pool.x + pool.w - half.x),
917	pool.y + half.y - b.y,
918	b.y - (pool.y + pool.h - half.y),
919	);
920	}
921
922	/**
923	* How high a tile is held while it is being dragged. Above `WALL_HEIGHT` so it
924	* clears the wall, and above `ON_FELT` so it is out of the way of every tile it
925	* is carried over — the pile does not part in front of a finger, the tile goes
926	* over the top of it, which is what picking one up is.
927	*/
928	export const CARRY_Z = 46;
929
930	/** The topmost tile under a point, or null. What a finger has taken hold of.
931	* Last first: later tiles were thrown later and lie on top. */
932	export function tileAt(world: World, x: number, y: number): Body \| null {
933	for (let i = world.bodies.length - 1; i >= 0; i--) {
934	const b = world.bodies[i];
935	const c = Math.cos(-b.angle);
936	const s = Math.sin(-b.angle);
937	const dx = x - b.x;
938	const dy = y - b.y;
939	// Into the tile's own frame, where the test is a rectangle again.
940	if (Math.abs(dx * c - dy * s) <= b.w / 2 && Math.abs(dx * s + dy * c) <= b.h / 2) return b;
941	}
942	return null;
943	}
944
945	/** Taken out of the pile and held above it. */
946	export function lift(b: Body) {
947	b.carried = true;
948	b.resting = false;
949	b.z = CARRY_Z;
950	b.vx = 0;
951	b.vy = 0;
952	b.vz = 0;
953	b.spin = 0;
954	b.flipSpin = 0;
955	// Whatever it comes down on, it comes down face up, as a tile does.
956	b.flip = Math.round(b.flip / TAU) * TAU;
957	}
958
959	/** Let go of it: dropped where it is, or sent off at whatever it was flicked. */
960	export function drop(b: Body, vx: number, vy: number, spin: number) {
961	b.carried = false;
962	b.vx = vx;
963	b.vy = vy;
964	b.spin = spin;
965	// It was being held up; from here it simply falls.
966	b.vz = 0;
967	b.still = 0;
968	b.awake = 0;
969	b.resting = false;
970	// Thrown from inside the pile rather than from a hand, so it is already past
971	// every seat's tiles and they are solid to it straight away.
972	b.leftSeat = true;
973	b.entered = true;
974	}
975
976	/** Whether two tiles are sharing ground, which they must never do at rest. */
977	export function overlapping(a: Body, b: Body): number {
978	const hit = overlapOf(a, b);
979	return hit ? hit.depth : 0;
980	}
981
982	/** Scale a tile is drawn at, given how high it is. Sells the arc on a flat
983	* canvas; the renderer offsets the shadow by the same height. */
984	export const zScale = (z: number) => 1 + z * 0.0016;
985
986	/**
987	* The upward kick that puts a tile back on the felt after `seconds` in the air.
988	* How a throw is aimed: pick how long it should take, and the horizontal speed
989	* follows from the distance.
990	*/
991	export const liftFor = (seconds: number) => (GRAVITY * seconds) / 2;
992
993	/** How high that kick gets — worth checking against WALL_HEIGHT. */
994	export const peakOf = (vz: number) => (vz * vz) / (2 * GRAVITY);