# TGL Pool

> A free, no-install, browser-based 8-ball pool game with realistic spin
> physics, a Yahoo-Pool-style aim helper, deterministic replays, live 1v1
> multiplayer, public spectators, Glicko-2 rating ladder, single-elimination
> tournaments, daily seeded challenges, and a Practice mode with contextual
> tips. Plays on phones, tablets, fold-phones, and desktops.

Site: https://tglgames.com/
Game: https://tglgames.com/pool/
About: https://tglgames.com/pool/about/

## Tagline
Smart Shots. Clean Game.

## What's distinctive
- 240 Hz fixed-step physics with side spin (English), top spin (follow),
  bottom spin (draw), cushion bounces, and pocket-mouth gaps.
- Yahoo-Pool-style aim helper: white cue forward path, ghost cue ball at
  contact, up to 3 cushion reflections, yellow target-trajectory line
  scaled by power × cos²(cut_angle) × restitution. Available in every
  mode; toggleable in the drawer; in friend matches the host can disable
  it for both players.
- Drag-back-with-accuracy-bar input. Sweep speed scales with pull
  distance. Green zone shrinks for longer / bounce-heavy shots.
- Deterministic replay: every shot is logged forever (cue position, aim,
  power, spin, accuracy phase, end-state hash). Server re-simulates each
  shot in PHP and compares the hash; mismatches flag for review.
- Replay scrubber UI with 0.5× / 1× / 2× / 4× playback, per-shot deep
  links (`/pool/r.php?id=N&shot=K`), and WebM video export from canvas.
- Full 8-ball rules: open table, group assignment on first legal pot,
  fouls (scratch / no-rail / wrong-group / 8-ball-too-early), win on the
  legal 8.

## Modes
- **Practice** — open table, contextual tips, no opponent.
- **Vs Bot (8-Ball)** — Rookie / Steady / Shark archetypes. Real `_bot`
  user accounts; bot opponent is stamped on the run row.
- **Run-out** — time-trial; pot all 15 + 8 fastest.
- **Daily Seeded** — same rack worldwide each UTC day, 10 shots, board
  resets at midnight.
- **Friend Match** — host/join via 8-character invite code or DM friend
  invite; host can flip aim helper off and visibility public/invite.
- **Quick Match** — rating-matched 1v1: queue widens by ±50 every 10 s,
  60-second timeout, then auto-seats both players in a public match.
- **Race a Ghost** — replay any logged run shot-for-shot between yours;
  lowest shot count wins.
- **Tournaments** — single-elimination, auto-pads to next power of 2 with
  byes, host-driven (or auto-advance via finished pool_matches).

## Multiplayer
- Single WebSocket at /ws/lcs (Workerman, PHP).
- Server authoritative for turn order + shot sequence. Physics
  deterministic on each client.
- Public matches list at /pool/spectate/. Spectators get full move-log
  history on subscribe + live `pool.shot.applied` frames.
- Match chat in `room_type='pool_match'` (shared with site's chat system,
  including emoji reactions).
- Web Push notifications for offline invites (VAPID + AES-128-GCM).

## Ratings + badges + seasons
- Glicko-2 (Glickman 2012) on every decisive multiplayer match.
- /pool/ratings/ — top 50 by rating, RD ≤ 200 (provisional excluded),
  *_bot accounts hidden.
- Badges: pool_champion, pool_finalist, pool_first_century. Visible on
  profile popovers.
- Quarterly seasons (UTC). Decay cron widens RD on idle players. Final
  standings archived in pool_season_archive.

## Controls
- Drag the cue ball back, release to shoot.
- W/S = power ±5% (Shift = ±10%).
- A/D = aim ±0.3° (Shift = ±1°).
- Space = fire.
- Arrow keys mirror WASD.
- English widget in the corner — drag for spin, double-click to reset.

## Architecture
- /pool/ is a self-contained ES-module game (no build step). Mirrors
  Last Card Standing's modular split. See /docs/pool.md.
- Per-game tables: pool_runs, pool_shots, pool_matches,
  pool_match_seats, pool_match_moves, pool_tournaments,
  pool_tournament_entries, pool_tournament_matches, pool_ratings,
  pool_season_archive, pool_user_badges.
- Rack rules verified: 1 on apex, 8 in centre of third row, back-row
  corners always one solid + one stripe.
- All raw IPs, UAs, and request bodies are logged forever per the site's
  "log everything" stance.

## Free + open
- No install, no signup required. Guest accounts on first visit.
- Free forever (no in-app purchases, no ads, no paid tiers).
- HTML5 + ES modules; works in every modern browser.