Arcade 2.0 / P3: Race mode — 1–N players, first-to-goal, on Snake + merge-drop

[Anuraj-dev]

Parent

Spec 27: #162

What to build

Race mode: 1–N players play the same game simultaneously with the identical layout and item sequence; the first to reach the finish line wins the moment they cross it (Snake: eat N apples; merge-drop: build the target tier). If every run ends before anyone finishes, most progress wins. Interacting with a cabinet offers Solo or Race; race entrants ready-up, a countdown starts once ≥2 are ready, and during the race each player sees opponents' live progress bars beside their own game. The loser was still playing when it ended — no dead waiting — and a one-click rematch restarts the lobby. Solo mode is the same system against the clock, recording best times.

Server-side: a race manager modeled on the existing board-manager pattern — per-space serialized dispatch, Redis-mirrored snapshots with TTL, space-scoped broadcasts, disconnect forfeits after a grace window. The server is lobby + relay + arbiter only: it hands out the shared seed, relays throttled progress events (~1/sec per racer), and declares the result — it never simulates gameplay. All wire shapes (join/leave/ready/start/progress/finish) are strict zod schemas in the shared contract package; clients run their own deterministic sims from the shared seed.

Acceptance criteria

• Pure race lifecycle machine (lobby → countdown → running → finished) with exhaustive transition tests including joins/leaves/disconnects at every phase, modeled on the meeting/board-match machines
• Race manager shell: per-space serialization, Redis snapshot + TTL, grace-window forfeit, space-scoped broadcasts; wire payloads all defined in the shared package and safeParsed server-side
• Snake and merge-drop expose data-defined finish lines consumed by both solo (race-the-clock, best time recorded) and multiplayer races
• In-race HUD: opponents' live progress bars, immediate end on first finish (or most-progress on all-dead), result screen with one-click rematch
• Progress events throttled to ~1/sec per racer; determinism of shared-seed runs proven by reducer tests
• One Playwright E2E at most (solo race happy path via bus hook + DOM, no sleeps); CI fully green

Blocked by

• Arcade 2.0 / P1: Juice overhaul + Snake rework (speed, levels, art) + board-table animations & sounds #163 (final Snake reducer: speeds/levels define the race course)
• Arcade 2.0 / P2: Merge-drop flagship cabinet (space theme, deterministic physics) #164 (merge-drop must exist to receive its finish line)