Mastermind Game (Java)

A console-based Mastermind-style number game written in Java. The game generates a secret four-digit number and asks the player to identify it using feedback after each guess.

Requirements

• Java Development Kit (JDK) 25
• Apache Maven

The project is configured with Java 25 as both its Maven compiler source and target version.

Rules

1. At the start of each round, the game generates a four-digit secret number.
2. The secret number is between 1000 and 9999, so its first digit is not zero.
3. All four digits in the secret number are different.
4. You have up to 10 attempts per round.
5. A guess must contain exactly four characters, digits only, and four different digits.
6. A bull (+) is a digit that is correct and in the correct position.
7. A cow (-) is a digit that exists in the secret number but is in the wrong position.
8. The round is won with four bulls. If all 10 attempts are used, the secret number is revealed.

For example, if the secret number is 1234 and the guess is 1524, the result is +2 -1: two digits are in the correct position and one additional digit is present but misplaced.

Getting started

Clone the repository and enter the project directory:

git clone https://github.com/suleymanibis/mastermind-game-java.git
cd mastermind-game-java

Compile the project with Maven:

mvn compile

Playing the game

After compilation, start the application with:

Windows

java -cp "target\classes" Mastermind

macOS/Linux

java -cp "target/classes" Mastermind

The game prints the number of remaining attempts, prompts for a guess, and displays feedback in the +bulls -cows format. After a round, enter a response beginning with y to play again; any other response exits the game.

When a round is won, the score is the number of attempts remaining. The best score is retained while the application is running.

Running the tests

Run the complete JUnit test suite with:

mvn test

The tests cover validation of length, numeric content, and duplicate digits; evaluation of bulls and cows; and generation of four-digit numbers with unique digits and a non-zero first digit.

Project structure

src/
├── main/java/
│   ├── Mastermind.java        # Application entry point
│   ├── MastermindGame.java   # Console game loop
│   ├── NumberGenerator.java   # Secret-number generation
│   ├── InputValidator.java    # Guess validation
│   ├── GuessEvaluator.java    # Bulls-and-cows evaluation
│   └── ...                    # Result types
└── test/java/                 # JUnit 5 tests

License

No license file is currently included in the repository.