mancala/docs/specs/game-clock/requirements.md

# Game clock: requirements

Status: implemented on branch `feature/game-clock` (based on `feature/game-history`).
Scope: backend, web app and mobile app.

## Goals

Every game has a chess-style clock: each player has 5 minutes for all of their moves. A player whose time runs out
loses. The server keeps the time and ends such games on its own, whether or not anyone is connected.

## Terms

- **Clock**: the time a player has left in a game.
- **Running clock**: the clock of the player whose turn it is. Only one clock runs at a time.
- **Turn**: from the moment a player is to move until the server receives their move.

## Requirements

### R1. Clock
- R1.1 Each player starts a game with 5 minutes. No time is added after a move.
- R1.2 Only the clock of the player whose turn it is runs. It starts when the game starts, for the player who moves
  first. When a move passes the turn, the mover's clock stops and the opponent's starts.
- R1.3 When a move gives the mover an extra turn, the mover's clock keeps running.
- R1.4 The server measures the time: a turn lasts from when it started on the server to when the server receives the
  move. Network delay and the time the client spends animating the opponent's move count as the player's time.
- R1.5 The clock runs whether or not the player is online.

### R2. Running out of time
- R2.1 When a player's clock reaches zero, the game ends: the opponent wins and the end reason is "timeout".
- R2.2 The server ends such games on its own within 1 second of the time running out, even if no client is
  connected or sends anything.
- R2.3 A move that reaches the server after the mover's time has run out is not played; the game ends as in R2.1.
- R2.4 Players see "You won · Opponent ran out of time" or "You lost · You ran out of time"; spectators see who
  won, as for other endings.

### R3. Showing the clocks
- R3.1 Players and spectators of a live game see both clocks next to the players' names as `m:ss`. The running
  clock is highlighted.
- R3.2 When less than 30 seconds are left, the running clock is shown in a warning style.
- R3.3 The running clock counts down smoothly. It differs from the server's time by no more than about one second,
  even if the device's clock is wrong.
- R3.4 After a reload or a reconnect, the clocks show the right times at once.
- R3.5 When the game ends, both clocks stop at the time they had; a player who ran out of time shows `0:00`.
- R3.6 The mobile app shows the clocks in the same way.

### R4. Saved games and replay
- R4.1 A saved game keeps the time each player started with and, for every move, the time the mover had left after
  it.
- R4.2 The replay of a game shows both clocks as they were after the move being shown, and the time each player
  started with before the first move.
- R4.3 Games saved before this feature have no clock data; their replay shows no clocks.

### R5. Restarts and deploys
- R5.1 Clocks survive a backend restart. Time while the backend is down does not count: after a restart, the
  running clock goes on from where it was when the current turn started.
- R5.2 Games that are in progress when this feature is deployed get a new clock (5 minutes each) when the backend
  restores them.

### R6. Rules the clock replaces
- R6.1 The clock replaces two rules from `game-history` (R3.3 and R3.4): losing after 5 minutes offline on your turn,
  and a game without a winner after both players have been offline for 30 minutes. Because the running clock does not
  stop for an offline player, it ends every such game within 5 minutes.
- R6.2 The "opponent is offline" countdown is replaced by the clocks. The online / offline status of the players
  stays.
- R6.3 Saved games that ended by the old rules still show as before ("timeout", "inactive").

## Out of scope (TODO)
- Other time controls, time added per move, or letting players choose.
- Clocks in the home page's live game previews and in the ongoing-game banner.
- Making up for network delay or animation time.
- Pausing a game, or more time by agreement.