diff --git a/.gitignore b/.gitignore
index 13275f1..3a35132 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,9 @@ out/
 !**/src/test/**/out/
 .kotlin
 
+### Java ###
+*.class
+
 ### Eclipse ###
 .apt_generated
 .classpath
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..04adbc9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+# Mastermind v2
+
+A Java implementation of the classic code-breaking game Mastermind.
+
+## About the Game
+
+Mastermind is a code-breaking game where you must guess a secret color code generated by the computer. After each guess, you receive feedback in the form of pins:
+- **BLACK pin**: Correct color in the correct position
+- **WHITE pin**: Correct color but in the wrong position
+
+The goal is to crack the code within the allowed number of attempts!
+
+## Features
+
+- **Three Difficulty Levels:**
+  - **Easy**: 4 positions, 6 colors (red, green, blue, yellow, orange, purple)
+  - **Medium**: 5 positions, 8 colors (red, green, blue, yellow, orange, purple, pink, cyan)
+  - **Hard**: 6 positions, 10 colors (red, green, blue, yellow, orange, purple, pink, cyan, brown, white)
+
+- **Customizable Attempts**: Choose between 5 to 15 attempts to crack the code
+
+- **Input Validation**: Robust error handling for invalid inputs
+
+- **Clear Feedback System**: Visual feedback with black and white pins after each guess
+
+## Requirements
+
+- Java Development Kit (JDK) 8 or higher
+
+## How to Compile
+
+Navigate to the project directory and compile the Java files:
+
+```bash
+javac src/mastermind/*.java
+```
+
+## How to Run
+
+After compiling, run the game with:
+
+```bash
+java -cp src mastermind.Mastermind
+```
+
+## How to Play
+
+1. **Start the game**: Run the program using the command above
+2. **Choose difficulty**: Select from Easy (1), Medium (2), or Hard (3)
+3. **Set attempts**: Choose how many attempts you want (5-15)
+4. **Make your guess**: Enter your color guesses separated by spaces
+   - Example: `red blue green yellow`
+5. **Review feedback**: 
+   - Black pins indicate correct colors in correct positions
+   - White pins indicate correct colors in wrong positions
+6. **Keep guessing**: Use the feedback to refine your next guess
+7. **Win or lose**: Crack the code within your attempts to win!
+
+## Example Gameplay
+
+```
+=================================
+       Welcome to Mastermind
+=================================
+The computer generates a secret code.
+You must guess the correct colors in the correct order.
+
+BLACK pin = correct color, correct position
+WHITE pin = correct color, wrong position
+
+Enter colors separated by spaces.
+Example: red blue green yellow
+=================================
+
+Choose difficulty:
+1. Easy   (4 positions, 6 colors)
+2. Medium (5 positions, 8 colors)
+3. Hard   (6 positions, 10 colors)
+Choice (1-3): 1
+
+Code length: 4
+Available colors: red green blue yellow orange purple 
+
+Choose max attempts (5-15): 10
+You have 10 attempts.
+
+Attempt 1/10
+Enter 4 colors:
+red blue green yellow
+Black pins: 2
+White pins: 1
+```
+
+## Project Structure
+
+```
+Mastermindv2/
+├── src/
+│   └── mastermind/
+│       ├── Mastermind.java          # Main entry point
+│       └── MastermindFuncties.java  # Game logic and functions
+├── .gitignore
+└── README.md
+```
+
+## Technologies Used
+
+- **Java**: Core programming language
+- **Scanner**: For user input handling
+- **Random**: For generating random secret codes
+
+## License
+
+This project is available for educational purposes.