A fully playable two-player chess game that runs inside a vanilla Minecraft Java Edition server, powered by a Python backend.

---

Features

• Two-player local chess on a Minecraft server
• Play against Stockfish AI at any ELO rating
• Two piece styles: armor stands with mob heads or frozen mob entities
• Three board themes: Overworld, Nether, End
• Full chess rules via python-chess (castling, en passant, promotion, check/checkmate/stalemate)
• Standard algebraic notation support (e4, Nf3, Bxc4, O-O)
• Sound effects, particle effects, and fireworks on checkmate
• Title text announcements for check and checkmate
• Captured piece display on the sides of the board
• Tournament mode with configurable series length
• Configurable board position, square size, and block types

---

Screenshots

Mid-Game	Checkmate

Piece Styles

Armor Stand Pieces	Mob Pieces

Board Themes

Overworld	Nether	Ender

---

Tech Stack

Tool	Role
Python 3.10+	Backend game logic and server communication
python-chess	Chess engine, move validation, and game state management
Stockfish	AI opponent engine
mcrcon	RCON protocol client for sending commands to the Minecraft server
opensimplex	Noise-based texture generation for board squares
Minecraft Java Edition	The "frontend" — renders the board and pieces in-game

---

Prerequisites

• Python 3.10 or higher
• Minecraft Java Edition server (vanilla)
• Stockfish chess engine binary (for AI games)

---

Installation

1. Clone the repo

git clone https://github.com/chrismarquezz/craftmate.git
cd craftmate/minecraft-chess

2. Create a virtual environment and install dependencies

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Install Stockfish (for AI games)

# macOS
brew install stockfish

# Linux
sudo apt install stockfish

# Windows — download from https://stockfishchess.org/download/

4. Configure the Minecraft server — add these lines to server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=your_password
broadcast-rcon-to-ops=false

5. Configure secrets — copy the example env and fill in your values:

cp .env.example .env

Edit .env:

RCON_HOST=localhost
RCON_PORT=25575
RCON_PASSWORD=your_password
LOG_FILE=/path/to/your/minecraft-server/logs/latest.log
STOCKFISH_PATH=/opt/homebrew/bin/stockfish  # output of 'which stockfish'

6. Start the Minecraft server, then start the backend:

python main.py

---

Commands Reference

Type these commands in Minecraft chat:

Command	Description
!play	Start a solo game (control both sides)
!play ai	Play against Stockfish at default ELO
!play ai <elo>	Play against Stockfish at specified ELO (e.g. !play ai 1500)
!play ai black	Play as black against Stockfish
!play ai <elo> black	Play as black against Stockfish at specified ELO
!e4	Make a move using standard algebraic notation
!Bxc4	Bishop captures on c4
!e2 e4	Make a move using coordinate notation (from-square to-square)
!resign	Resign the current game
!rematch	Start a new game after game over
!theme <theme>	Switch board to
!tournament 3	Start a best-of-3 tournament
!tournament 5	Start a best-of-5 tournament
!tournament 3 ai 1500	Best-of-3 tournament vs Stockfish at 1500 ELO
!score	Show current tournament score
!tournament stop	Cancel the current tournament
!reset	Clear the board and all pieces

---

Configuration

All settings live in minecraft-chess/config.py:

Option	Default	Description
PIECE_STYLE	"armor_stand"	Piece visual style — "armor_stand" or "mob"
BOARD_THEME	"overworld"	Default board theme — "overworld", "nether", or "end"
SQUARE_SIZE	3	Number of blocks per board square
STOCKFISH_DEFAULT_ELO	1500	Default AI difficulty when no ELO is specified
STOCKFISH_THINK_TIME	1.0	Seconds the AI "thinks" per move
BOARD_ORIGIN_X/Y/Z	-200, -60, 15	World coordinates of the board's corner

---

Architecture

Python Backend (chess logic, RCON commands)
    ├── chess_engine.py      — python-chess wrapper
    ├── rcon_client.py       — RCON connection
    ├── log_watcher.py       — reads player chat from server log
    ├── game_controller.py   — orchestrates game flow
    ├── ai_player.py         — Stockfish integration
    └── renderer/
        ├── base.py          — abstract renderer interface
        └── mob_renderer.py  — armor stand / mob entity renderer

Minecraft Server (visual frontend)
    ├── Receives /summon, /tp, /kill, /fill commands
    ├── Renders board and pieces in-game
    └── Player chat → server log → Python backend

Flow:

1. LogWatcher detects a !command in chat and calls GameController.handle_command()
2. GameController validates turn order and delegates to ChessEngine.try_move()
3. On success, GameController instructs the renderer to update the board visually
4. RCON commands execute the changes live in Minecraft

---

License

MIT