{"id":31756552,"url":"https://github.com/ginesthoii/checkmate","last_synced_at":"2026-05-18T19:03:01.343Z","repository":{"id":317251079,"uuid":"1065063384","full_name":"ginesthoii/CheckMate","owner":"ginesthoii","description":"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.","archived":false,"fork":false,"pushed_at":"2025-09-29T19:16:21.000Z","size":154,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T20:42:45.859Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ginesthoii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T02:05:50.000Z","updated_at":"2025-09-29T19:16:24.000Z","dependencies_parsed_at":"2025-09-29T20:42:48.511Z","dependency_job_id":null,"html_url":"https://github.com/ginesthoii/CheckMate","commit_stats":null,"previous_names":["ginesthoii/checkmate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ginesthoii/CheckMate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginesthoii%2FCheckMate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginesthoii%2FCheckMate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginesthoii%2FCheckMate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginesthoii%2FCheckMate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ginesthoii","download_url":"https://codeload.github.com/ginesthoii/CheckMate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ginesthoii%2FCheckMate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001981,"owners_count":26083243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2025-10-09T19:19:15.336Z","updated_at":"2025-10-09T19:19:16.415Z","avatar_url":"https://github.com/ginesthoii.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/905ead19-3392-4fe8-bbb6-8904cef3ae3b\" alt=\"CheckMate animation\" width=\"560\" style=\"border-radius:14px;\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCheckMate — PyBot Chess AI Coach\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003ePlay. Watch. Learn. An interactive chess coach built with Python + Pygame, powered by Stockfish.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## What it is\nCheckMate 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 \u0026 development, and warns when you’ve left pieces hanging.\n\n### Highlights\n- Stockfish-backed evaluations + principal variation (multi-move plan)\n- Toggleable coaching overlays:\n  - **Hints (H):** Best-move arrows, blunder vs. better alternative\n  - **Openings (O):** Center control \u0026 early development tips\n  - **Tactics (T):** Undefended (“hanging”) piece warnings\n- Human vs Bot, **Self-play**, or **Bot vs Bot Duel**\n- Click-to-move with reselect support\n- Sidebar with eval bar, commentary, scoreboard\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/8c8ef489-b939-445f-ada1-c6d9079e2a15\" alt=\"Banner\" height=\"500\" width=\"500\" style=\"border-radius:12px;\"/\u003e\n\u003c/p\u003e\n\n---\n\n# Features\n- Full chessboard with PNG sprites (pieces-png/ folder included)\n- Stockfish-backed evaluations + principal variation (next-move plan)\n- Beginner overlays (Hints, Openings, Tactics) toggleable in-game\n- Click-to-move with reselect support (change piece before committing)\n- Scoreboard for wins, draws, losses\n- Human vs Bot, Self-play, or Bot vs Bot Duel\n- Sidebar shows evaluation, plan, and teaching commentary\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/52d17797-c503-499c-b7a7-42f1c98ad0ec\" alt=\"Banner\" height=\"500\" width=\"500\" style=\"border-radius:12px;\"/\u003e\n\u003c/p\u003e\n\n### Installation\n\ngit clone \u003cthis-repo-url\u003e\ncd CheckMate\n\n# Install dependencies\npip install pygame python-chess\n\nInstall Stockfish (recommended)\n\nOn macOS with Homebrew:\n\nbrew install stockfish\n\nOn Ubuntu/Debian:\n\nsudo apt install stockfish\n\nCheck path:\n\nwhich stockfish\n# e.g. /opt/homebrew/bin/stockfish\n\n\n\n## Usage\n\nRun with defaults (human as White):\n\npython3 play_pygame_pro.py --mode human --side white\n\n# Human as White\npython3 src/play_pygame_pro.py --mode human --side white\n\n# Watch AI self-play\npython3 src/play_pygame_pro.py --mode self\n\n# Bot vs Bot duel\npython3 src/play_pygame_pro.py --mode duel\n\n\n## Options\n\t•\t--side white|black — color (human mode)\n\t•\t--ms N — delay per bot move in ms (default 300)\n\t•\t--engine PATH — Stockfish path (overrides auto-detect)\n\t•\t--w N / --h N — optional window clamp if your monitor is small\n\n\n### Modes\n\t•\t--mode human → Play against the bot\n\t•\t--mode self → Watch AI self-play\n\t•\t--mode duel → Bot vs Bot duel (slightly different styles)\n\n### Options\n\t•\t--side white|black → Choose your color (if human mode)\n\t•\t--ms N → Milliseconds delay per bot move (default 300)\n\t•\t--engine PATH → Explicit path to Stockfish (auto-detected if omitted)\n\n\n## Assets\n\nAll chess piece sprites are loaded from /pieces-png/.\nThe loader automatically handles aliases like rook.png, rook4.png, bpawn.png, etc.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/2ecf05c6-d4bf-4071-b10b-7013a9d79e3b\" alt=\"Banner\" height=\"500\" width=\"500\" style=\"border-radius:12px;\"/\u003e\n\u003c/p\u003e\n\n## How It Teaches\n- Explains your moves vs. engine best: “That was a blunder. Knight f3 was stronger because it develops a piece and controls the center.”\n- Highlights tactical oversights: undefended pieces flash red.\n- Suggests opening principles: “Try playing e4/d4 to control the center. Develop knights and bishops first.”\n- Shows a multi-move “Plan” (principal variation) for strategy context.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/fe20bd7a-0be7-4c57-9ed5-49d5b2e6ac8e\" alt=\"Banner\" height=\"500\" width=\"500\" style=\"border-radius:12px;\"/\u003e\n\u003c/p\u003e\n\n\n\n\n\n### MIT License.\nStockfish engine is GPL and installed separately; this project does not redistribute it.\n\n\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/8f9893cb-67cb-4d58-8bee-5701a3e82038\" alt=\"Banner\" height=\"400\" width=\"400\" style=\"border-radius:12px;\"/\u003e\n\u003c/p\u003e\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fginesthoii%2Fcheckmate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fginesthoii%2Fcheckmate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fginesthoii%2Fcheckmate/lists"}