feat(web): add visible countdown timer to multiplayer game #10

New issue

Open

opened 2026-04-19 07:11:41 +00:00 by forgejo-lila · 0 comments

forgejo-lila commented

2026-04-19 07:11:41 +00:00

Owner

Background

The server enforces a 15-second answer timer per round in multiplayer games.
When the timer expires, unanswered players are marked as timed out and the
round resolves automatically. Currently the client has no visual indication
of the remaining time — players don't know how long they have to answer.

What needs to happen

Add a countdown timer component to the multiplayer game view that:

Starts at 15 seconds when a new game:question message is received.
Counts down visually in real time (per-second updates).
Shows urgency as time runs low (e.g. color change at 5s, animation at 3s).
Stops and resets when game:answer_result is received (round resolved).
Handles the case where the player has already answered — timer can
continue counting down (showing other players' remaining time) or
stop on answer (simpler).

Options for timer sync

A. Client-side only: start a setTimeout(15000) on game:question.
Simple, but drifts if the client tab is backgrounded or the device is slow.
The server timer and client timer can get out of sync, causing the UI to
show "5 seconds left" when the server has already resolved the round.

B. Server sends remaining time: include timeLimit and startedAt
in game:question so the client can calculate elapsed time and display
accurate remaining time. More robust, handles late joins and reconnections.

My lean: B — include timeLimit: number and startedAt: string (ISO) in
WsGameQuestionSchema. Client computes remaining = timeLimit - (now - startedAt).

Acceptance criteria

Countdown timer visible during each round.
Timer starts on game:question, stops on game:answer_result.
Visual urgency indicator when < 5 seconds remain.
Timer is accurate within ~1 second of server timer.
Timer handles tab backgrounding gracefully (Page Visibility API).

packages/shared/src/schemas/lobby.ts — WsGameQuestionSchema
apps/api/src/ws/handlers/gameHandlers.ts — handleLobbyStart, resolveRound
apps/web/src/routes/multiplayer/game.$code.tsx

## Background The server enforces a 15-second answer timer per round in multiplayer games. When the timer expires, unanswered players are marked as timed out and the round resolves automatically. Currently the client has no visual indication of the remaining time — players don't know how long they have to answer. ## What needs to happen Add a countdown timer component to the multiplayer game view that: - Starts at 15 seconds when a new `game:question` message is received. - Counts down visually in real time (per-second updates). - Shows urgency as time runs low (e.g. color change at 5s, animation at 3s). - Stops and resets when `game:answer_result` is received (round resolved). - Handles the case where the player has already answered — timer can continue counting down (showing other players' remaining time) or stop on answer (simpler). ## Options for timer sync **A. Client-side only:** start a `setTimeout(15000)` on `game:question`. Simple, but drifts if the client tab is backgrounded or the device is slow. The server timer and client timer can get out of sync, causing the UI to show "5 seconds left" when the server has already resolved the round. **B. Server sends remaining time:** include `timeLimit` and `startedAt` in `game:question` so the client can calculate elapsed time and display accurate remaining time. More robust, handles late joins and reconnections. My lean: B — include `timeLimit: number` and `startedAt: string (ISO)` in `WsGameQuestionSchema`. Client computes `remaining = timeLimit - (now - startedAt)`. ## Acceptance criteria - [ ] Countdown timer visible during each round. - [ ] Timer starts on `game:question`, stops on `game:answer_result`. - [ ] Visual urgency indicator when < 5 seconds remain. - [ ] Timer is accurate within ~1 second of server timer. - [ ] Timer handles tab backgrounding gracefully (Page Visibility API). ## Related - `packages/shared/src/schemas/lobby.ts` — `WsGameQuestionSchema` - `apps/api/src/ws/handlers/gameHandlers.ts` — `handleLobbyStart`, `resolveRound` - `apps/web/src/routes/multiplayer/game.$code.tsx`