gtmanfred/mastermind repository overview

⁠mastermind-server

A Mastermind game server

⁠Overview and Game Rules

Mastermind is a game where one player (the code master) will create a sequence of 4 colors. Each of these colors can be one of six values, "red", "blue", "green", "yellow", "white", or "black". Repeating colors are allowed.

The other player (the code breaker) gets 10 turns to attempt to guess the sequence of colors. After each guess, the code master will respond by telling them how many colors were guessed exactly correct, and also how many colors guessed are in the solution, but in a different location.

⁠Examples

The code master creates a solution, lets say ("red", "blue", "white", "red"). Now the code breaker will try to guess the solution:

Guess #1: ("blue", "green", "red", "yellow")
Response #1: 0 correct, and 2 close (red and blue are in the solution, but not in the guessed locations).

Guess #2: ("red", "red", "black", "yellow")
Response #2: 1 correct (for the first red), and 1 close (for the other red).

Guess #3: ("black", "red", "white", "blue")
Response #3: 1 correct (for the white), and 2 close (for the red and the blue).

Guess #4: ("red", "red", "blue", "white")
Response #4: 1 correct (for the red), and 3 close (for the rest). The player now knows all of the colors in the solution and just needs to put them in the correct order.

Guess #5: ("red", "blue", "white", "red")
Response #5: 4 correct. The player has won.

⁠Quickstart

This mastermind service can be run locally (on port 5000) using the following:

docker run -d -p 5000:5000 docker.io/gtmanfred/mastermind:latest
curl -X POST http://localhost:5000/create

⁠Usage Guide

The API has two endpoints:

⁠POST /create

This endpoint will create a new game on the server and return the game ID in JSON format like this:

{
  "game_id": "eb24434f-be4c-4c9a-978f-993ed255691d"
}

You can also choose to set the game's solution rather than have it create a random solution by providing the solution in the request body in JSON format like this:

{
  "solution": ["red", "black", "blue", "red"]
}

⁠POST /game/<game_id>/guess

This endpoint requires a game ID (obtained from the create endpoint) in the path. The guess is sent in the request body in JSON format like this:

{
  "guess": ["red", "black", "blue", "red"]
}

The response will say how many colors were guessed exactly correct, how many were just in the wrong location (close), and how many turns the player has left in JSON format like this:

{
  "close": 1,
  "correct": 2,
  "turns_left": 5
}

The game ends when either the player wins, which will be indicated by "correct": 4 in the response, or when the player runs out of turns, which will be indicated by "turns_left": 0 in the response. Any subsequent calls to this endpoint after the game has ended will respond with an HTTP code 404.