Chess Game

A fully functional chess game built with Python and Pygame, featuring legal move validation, special moves (castling, en passant), and check/checkmate detection. Created as part of an AI-directed self-study project.

Use of AI during this project

AI (ChatGPT, Claude) was used to provide the initial project brief. The project brief included primary goals, secondary (stretch) goals, and a list of skills I would learn or reinforce during this project.

During the writing of the code itself, AI was put in "learning"/"study and learn" mode. AI was used to explain new concepts, answer questions about specific functions or syntax, and provide advise on how to improve written code. Requests to write specific sections of code was kept at a minimum.

Assets were made with the use of illustrator or Photopea. Chess pieces were derived from the Chess Unicode icons, by linetracing the icons in illustrator and converting to PNGs. No AI generated image assets were used.

This README was partially written and formatted by AI.

Features

Primary goals

All primary goals were implemented: Core game model

• Represent the chessboard, squares, pieces, colors, and turns.
• Maintain full game state: piece locations, side to move, castling rights, en passant availability, half-move/full-move counters.
• Clear separation between immutable concepts (piece type, color) and mutable state (position, has-moved flags).

Move generation and validation

• Generate pseudo-legal moves per piece type.
• Filter pseudo-legal moves into legal moves by enforcing check rules.
• Implement all standard chess rules:
  • Normal movement and captures
  • Check and check resolution
  • Checkmate and stalemate detection
  • Castling (with all constraints)
  • Enpassant
  • Pawn promotion to Queen
• Provide an API to query “legal moves for this piece on this square”.

Game controller / rules engine

• Apply moves to the board state safely.
• Reject illegal moves.
• Detect game-ending conditions.

Graphical user interface

• Render an 8×8 board with pieces.
• Handle mouse input:
  • Select a piece
  • Highlight its legal moves
  • Move the piece on click
• Keep UI logic separate from game logic.
• Ensure the board view stays synchronized with the underlying game state.

Architecture and boundaries

• Explicit separation between:
  • Model (board, pieces, moves)
  • Rules/logic (move generation, validation)
  • Presentation (GUI)
• Minimal coupling so the GUI could be replaced without rewriting chess logic.
• Code written to PEP 8, with clear naming and docstrings where helpful.

Secondary goals

Four secondary goals was implemented. Other secondary goals might be implemented in the future (though this is unlikely).

• Board orientation that can flip automatically after each turn or manually by the player.
• Visual indication of check, checkmate, and stalemate.
• Clear separation so a computer opponent can be added without modifying core rules.
• Performance that remains responsive even when recalculating legal moves each click.
• Track move history in a structured form.
• Allow Pawn under-promotion
• Promotion choice UI (piece selection dialog).
• Persistent move log with standard algebraic notation.
• Ability to step backward and forward through move history.
• Full undo/redo support without corrupting game state.
• Chess clock with configurable time controls.
• Highlighting of last move played.
• Game reset and new-game initialization.
• Save and load game state (at least one format, e.g. internal or PGN-like).
• Basic settings menu (board theme, piece set, orientation preference).
• Deterministic move application so future AI/search can rely on it.

Requirements

• Python 3.12+
• Pygame 2.6+

Installation

git clone https://github.com/IndexLibrorumProhibitorum/chess.git
cd chess
python -m venv .venv
.venv\Scripts\activate  # Windows
pip install -r requirements.txt

Usage

python -m chess.GUI

Project Structure

chess/
├── chess/
│   ├── Board.py       # Board state and rendering
│   ├── GameState.py   # Game logic and move validation
│   ├── Pieces.py      # Piece classes and movement patterns
│   ├── Geometry.py    # Tile positioning
│   ├── GuiState.py    # GUI state management
│   └── Config.py      # Game configuration
├── tests/             # Unit tests
└── assets/            # Images and resources

Testing

pytest

What I Learned

• Applied python fundamentals
  • Classes with clear responsibilities, dataclasses vs regular classes, PEP8 compliance
  • Data modeling: representing a state space, choosing coordinate systems and representations
  • Software design basics: layered architecture, dependency directions, avoiding 'god objects', refactoring as complexity grows
• Basic algorithms
  • Move generation as a constrained search problem
  • Attack maps and king safety evaluation
  • Incremental state updates
  • Detecting terminal states (checkmate, stalemate) efficiently
• Object-oriented design for game logic
• Test-driven development with pytest
• Event-driven GUI programming with Pygame
• Debugging logic with PyCharm