https://github.com/ginesthoii/checkmate

An interactive chess coach powered by Stockfish and Pygame. Play against a self-learning bot, watch AI duels, or train with toggleable beginner overlays (Hints, Openings, Tactics) that explain moves, highlight principles, and make learning chess fun.
https://github.com/ginesthoii/checkmate

ai-bot beginner-friendly boardgames chess-ai chess-ai-bot chess-engine chess-trainer game-development machine-learning pygame python3 reinforcement-learning stockfish-api stockfish-chess teaching-tool

Last synced: 2 months ago
JSON representation

An interactive chess coach powered by Stockfish and Pygame. Play against a self-learning bot, watch AI duels, or train with toggleable beginner overlays (Hints, Openings, Tactics) that explain moves, highlight principles, and make learning chess fun.

• Host: GitHub
• URL: https://github.com/ginesthoii/checkmate
• Owner: ginesthoii
• License: mit
• Created: 2025-09-27T02:05:50.000Z (10 months ago)
• Default Branch: main
• Last Pushed: 2025-09-29T19:16:21.000Z (10 months ago)
• Last Synced: 2025-09-29T20:42:45.859Z (10 months ago)
• Topics: ai-bot, beginner-friendly, boardgames, chess-ai, chess-ai-bot, chess-engine, chess-trainer, game-development, machine-learning, pygame, python3, reinforcement-learning, stockfish-api, stockfish-chess, teaching-tool
• Language: Python
• Homepage:
• Size: 150 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  



CheckMate — PyBot Chess AI Coach




  Play. Watch. Learn. An interactive chess coach built with Python + Pygame, powered by Stockfish.



---

## What it is

CheckMate is a teaching-first chess app: you can play the bot, watch self-play, or train with beginner-friendly overlays. It explains blunders plainly, shows best-move arrows, highlights center control & development, and warns when you’ve left pieces hanging.

### Highlights

- Stockfish-backed evaluations + principal variation (multi-move plan)

- Toggleable coaching overlays:

  - **Hints (H):** Best-move arrows, blunder vs. better alternative

  - **Openings (O):** Center control & early development tips

  - **Tactics (T):** Undefended (“hanging”) piece warnings

- Human vs Bot, **Self-play**, or **Bot vs Bot Duel**

- Click-to-move with reselect support

- Sidebar with eval bar, commentary, scoreboard



  



---

# Features

- Full chessboard with PNG sprites (pieces-png/ folder included)

- Stockfish-backed evaluations + principal variation (next-move plan)

- Beginner overlays (Hints, Openings, Tactics) toggleable in-game

- Click-to-move with reselect support (change piece before committing)

- Scoreboard for wins, draws, losses

- Human vs Bot, Self-play, or Bot vs Bot Duel

- Sidebar shows evaluation, plan, and teaching commentary



  



### Installation

git clone 

cd CheckMate

# Install dependencies

pip install pygame python-chess

Install Stockfish (recommended)

On macOS with Homebrew:

brew install stockfish

On Ubuntu/Debian:

sudo apt install stockfish

Check path:

which stockfish

# e.g. /opt/homebrew/bin/stockfish

## Usage

Run with defaults (human as White):

python3 play_pygame_pro.py --mode human --side white

# Human as White

python3 src/play_pygame_pro.py --mode human --side white

# Watch AI self-play

python3 src/play_pygame_pro.py --mode self

# Bot vs Bot duel

python3 src/play_pygame_pro.py --mode duel

## Options

	•	--side white|black — color (human mode)

	•	--ms N — delay per bot move in ms (default 300)

	•	--engine PATH — Stockfish path (overrides auto-detect)

	•	--w N / --h N — optional window clamp if your monitor is small

### Modes

	•	--mode human → Play against the bot

	•	--mode self → Watch AI self-play

	•	--mode duel → Bot vs Bot duel (slightly different styles)

### Options

	•	--side white|black → Choose your color (if human mode)

	•	--ms N → Milliseconds delay per bot move (default 300)

	•	--engine PATH → Explicit path to Stockfish (auto-detected if omitted)

## Assets

All chess piece sprites are loaded from /pieces-png/.

The loader automatically handles aliases like rook.png, rook4.png, bpawn.png, etc.



  



## How It Teaches

- Explains your moves vs. engine best: “That was a blunder. Knight f3 was stronger because it develops a piece and controls the center.”

- Highlights tactical oversights: undefended pieces flash red.

- Suggests opening principles: “Try playing e4/d4 to control the center. Develop knights and bishops first.”

- Shows a multi-move “Plan” (principal variation) for strategy context.



  



### MIT License.

Stockfish engine is GPL and installed separately; this project does not redistribute it.