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

Game bot: requirements

Status: spec, not implemented yet. 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.