♔ Chess Master AI 🚀

A beautiful, feature-rich chess game with AI opponent powered by Stockfish

Train against 7 difficulty levels • Real-time move analysis • Professional move ratings

🚀 Quick Start • 📋 Features • 🎮 Controls • ⚙️ Setup

---

🌟 Features

🧠 AI Opponent

• 7 Difficulty Levels: From complete beginner to grandmaster strength
• Powered by Stockfish: World's strongest chess engine
• Adaptive Thinking Time: 0.1s to 5s based on difficulty
• Dynamic Level Switching: Change difficulty mid-game

📊 Move Analysis & Rating

• Real-time Evaluation: Every move is analyzed and rated
• Professional Ratings:
  • ⭐⭐⭐ Brilliant - Outstanding moves
  • ⭐⭐ Great - Excellent moves
  • ⭐ Good - Solid moves
  • ❓❗ Inaccuracy - Minor mistakes
  • ❓ Mistake - Significant errors
  • ❓❓ Blunder - Major mistakes
• Score Evaluation: See how each move affects your position

🎨 Beautiful Interface

• Modern Design: Clean, professional chess board
• Move History Panel: Complete game notation with ratings
• Visual Highlights: Last move, selected piece, legal moves
• Coordinate Labels: File and rank indicators
• Responsive UI: Smooth animations and feedback

🎮 Game Features

• Complete Chess Rules: All standard chess rules implemented
• Automatic Promotion: Pawns promote to queen (customizable)
• Check Detection: Visual and textual check indicators
• Game Over Detection: Checkmate, stalemate, and draw conditions
• Move Validation: Only legal moves allowed

---

🚀 Quick Start

1. Install Dependencies

   pip install pygame python-chess

2. Install Stockfish

   • Windows: Download from stockfishchess.org and add to PATH
   • Mac: brew install stockfish
   • Linux: sudo apt install stockfish or sudo pacman -S stockfish

3. Run the Game

   python main.py

4. Choose Your Challenge

   • Select AI difficulty level
   • Start playing as White
   • Watch your moves get rated in real-time!

---

🎮 Controls

Key	Action
Mouse Click	Select piece / Make move
R	Restart game
L	Change AI difficulty level
ESC	Quit game

🖱️ Gameplay

1. Select a Piece: Click on your piece (White)
2. See Legal Moves: Available moves highlighted in yellow
3. Make Your Move: Click destination square
4. Watch AI Respond: AI thinks and makes its move
5. Analyze: See move ratings and evaluations in real-time

---

⚙️ Installation

📋 Requirements

• Python 3.8 or higher
• Pygame 2.0+
• python-chess library
• Stockfish engine

🔧 Detailed Setup

Step 1: Clone or Download

git clone https://github.com/KaTOxDev/PlayChessWithAI.git
cd PlayChessWithAI

Step 2: Install Python Dependencies

pip install pygame python-chess

Step 3: Install Stockfish Engine

Windows:

1. Download Stockfish from stockfishchess.org
2. Extract to a folder (e.g., C:\stockfish\)
3. Add to PATH or place executable in project folder

macOS:

brew install stockfish

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install stockfish

Linux (Arch):

sudo pacman -S stockfish

Step 4: Optional - Add Piece Images

For premium visuals, create a chess/ folder and add PNG files:

chess/
├── white_pawn.png
├── white_rook.png
├── white_knight.png
├── white_bishop.png
├── white_queen.png
├── white_king.png
├── black_pawn.png
├── black_rook.png
├── black_knight.png
├── black_bishop.png
├── black_queen.png
└── black_king.png

Note: Game works perfectly with built-in text pieces if images aren't provided

---

🎯 AI Difficulty Levels

Level	Name	Think Time	Depth	Strength
1	Beginner	0.1s	5	~800 ELO
2	Easy	0.2s	8	~1200 ELO
3	Medium	0.5s	10	~1600 ELO
4	Hard	1.0s	12	~2000 ELO
5	Expert	2.0s	15	~2400 ELO
6	Master	3.0s	18	~2800 ELO
7	Grandmaster	5.0s	20	~3200+ ELO

---

🏆 Game Features in Detail

🎨 Visual Elements

• Board Colors: Professional tournament colors
• Piece Highlighting: Selected pieces shown in green
• Legal Move Indicators: Yellow highlights for valid moves
• Last Move Display: Orange highlights for previous move
• Check Warnings: Visual and text indicators

📈 Move Analysis System

The game uses Stockfish's evaluation to rate every move:

• Evaluation Depth: 12 moves ahead for accurate analysis
• Score Tracking: Position evaluation in centipawns
• Rating Algorithm: Compares move quality to best possible moves
• Real-time Feedback: Instant move ratings as you play

🎲 Game Modes

• Human vs AI: Play against Stockfish
• Analysis Mode: Review and learn from your games
• Difficulty Progression: Start easy and work your way up

---

🐛 Troubleshooting

Common Issues

❌ "Stockfish engine not found"

• Ensure Stockfish is installed and in your system PATH
• Try placing stockfish executable in the same folder as the game

❌ "No module named 'pygame'"

pip install pygame python-chess

❌ Game runs but pieces look like text

• This is normal! Add PNG images to chess/ folder for better graphics
• Game is fully functional with text pieces

❌ AI takes too long to move

• Lower the difficulty level
• Ensure you're not running other CPU-intensive programs

Performance Tips

• Slow Computer? Use levels 1-3 for faster gameplay
• Want Challenge? Levels 5-7 provide tournament-strength opposition
• Learning? Level 3-4 is perfect for intermediate players

---

🎓 Learning Features

Improve Your Chess

• Move Ratings Help: Learn what makes moves good or bad
• Pattern Recognition: See how the AI responds to different positions
• Mistake Analysis: Understand your blunders and inaccuracies
• Progress Tracking: Challenge higher difficulties as you improve

Educational Value

• Opening Principles: AI demonstrates sound opening play
• Tactical Awareness: Spot tactical motifs through AI play
• Endgame Technique: Learn proper endgame technique
• Positional Understanding: See how small advantages accumulate

---

📊 Technical Specifications

• Engine: Stockfish 15+ compatible
• GUI Framework: Pygame
• Chess Logic: python-chess library
• Move Generation: Full legal move validation
• Position Evaluation: Stockfish UCI protocol
• Threading: Non-blocking AI calculations
• Performance: 60 FPS smooth gameplay

---

🎉 Future Enhancements

Planned Features

• Opening Book: Common opening variations
• Time Controls: Blitz, rapid, and classical time formats
• Game Database: Save and replay games
• Multiple Themes: Different board and piece sets
• Sound Effects: Audio feedback for moves
• Online Play: Challenge friends remotely
• Tournament Mode: Multi-game matches
• Puzzle Mode: Tactical training exercises

---

🤝 Contributing

We welcome contributions! Whether it's:

• 🐛 Bug fixes
• ✨ New features
• 🎨 UI improvements
• 📚 Documentation
• 🧪 Testing

Feel free to open issues and pull requests!

---

📜 License

This project is open source and available under the MIT License.

---

Made with ❤️ for chess enthusiasts

Train • Play • Improve • Master

⭐ Star this repo if you enjoyed playing! ⭐