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

# Game bot: requirements

Status: implemented on branch `feature/game-bot` (based on `develop`).
Scope: backend, `packages/core`, web app and mobile app.

## Goals

Players can always get a game: when no other player is looking for one, they can play against a bot. They choose
how strong the bot is, but within a level the bot is not always equally strong, so games against it differ from
each other. A game against the bot is a normal game: it has the clock, can be watched and is saved like any other.

## Terms

- **Bot**: a player run by the server.
- **Level**: what the player chooses: Easy, Medium, Hard or Master (Turkish: Kolay, Orta, Zor, Usta).
- **Strength**: a number from 0 to 100 that sets how well the bot plays. Each level is a range of strengths; the bot
  takes a strength from it at the start of each game.
- **Bot game**: a game between a player and the bot.

## Requirements

### R1. Starting a bot game
- R1.1 When a player has been looking for an opponent for 10 seconds without one being found, the lobby offers a
  game against the bot with the four levels to choose from. The search goes on while the offer is shown; if an
  opponent is found first, the game with them starts as usual.
- R1.2 Choosing a level ends the search and starts a bot game at that level at once.
- R1.3 The home page also has a "Play with bot" button that opens the same choice of levels, without searching for
  an opponent first.
- R1.4 The level chosen last is preselected the next time (kept on the device).
- R1.5 A player who has a game in progress cannot start a bot game; they are offered to continue that game, as when
  they look for an opponent.
- R1.6 Who moves first is chosen at random, as in other games.

### R2. Levels and strength
- R2.1 There are four levels, from weakest to strongest: Easy, Medium, Hard, Master.
- R2.2 At the start of each game the bot takes a random strength within the level's range. Within a game, it plays
  each move with a strength that varies a little around that value.
- R2.3 Easy makes obvious mistakes and can be beaten by a beginner. Master plays close to perfectly and is rarely
  beaten.
- R2.4 Each level is clearly stronger than the one below: played against each other by the server, the stronger
  of two neighbouring levels wins at least 65% of the games, and Master wins at least 95% against Easy.
- R2.5 Two games at the same level from the same starting position do not play out the same way: in 20 such games
  against the same sequence of the opponent's moves, the bot's first five moves are not all the same.

### R3. How the bot plays
- R3.1 The bot plays by the same rules as players; its moves go through the same game logic.
- R3.2 The bot does not move instantly: it waits until the previous move's animation has finished, then about 1 to
  3 seconds more, a little longer at the higher levels. An extra turn is played the same way.
- R3.3 The bot has a clock like any player and its waiting counts on it. It never runs out of time.
- R3.4 The bot never leaves a game and is always shown as online.
- R3.5 Working out the bot's moves never delays other games: other players' moves are handled as fast as without
  bots, even while many bot games are being played.

### R4. During and after the game
- R4.1 The bot is shown as "Bot" with its level, e.g. "Bot · Medium" / "Bot · Orta", wherever players are shown:
  the game page, live game previews, recent and popular games, and replays.
- R4.2 Everything that ends a game works as in other games: a player who leaves loses, a player whose time runs out
  loses, a completed game is won by the player with more stones.
- R4.3 Bot games are saved like other games and appear in the player's recent games and can be replayed.
- R4.4 At the end of a bot game, the game over card offers "Play again", which starts a new bot game at the same
  level.
- R4.5 Bot games can be watched by others and appear in live game previews like other games.
- R4.6 A bot game survives a backend restart: the bot goes on at the same strength, and if it was its turn, it moves.

### R5. Mobile app
- R5.1 The mobile app has the offer in the lobby (R1.1, R1.2), the button on the home screen (R1.3) and shows the
  bot's name with its level (R4.1).

## Out of scope (TODO)
- Playing against the bot without a connection (a bot in the TypeScript engine on the device).
- Ratings or statistics; when they come, bot games should be kept apart from games against people.
- Hints or move analysis for players.
- Choosing an exact strength or who moves first.
- Rebuilding the game engine (`MancalaGame`, `Board`, the rules) on the compact board this feature adds.