Chess AI v2

A desktop chess game built with Lua + LÖVE 11.x featuring a custom chess engine, animated piece movement, and a live AI search-tree visualizer that shows what the engine explored while thinking.

This project is not just a playable chess app. Its main differentiator is the right-hand visualizer panel, which renders the engine's minimax/alpha-beta search as a branching tree while the AI is running.

Features

• Play as White or Black
• Three built-in difficulty presets:
  • Easy: depth 3
  • Medium: depth 4
  • Hard: depth 5
• Full move validation for core chess rules:
  • normal moves
  • captures
  • castling
  • en passant
  • promotion
  • check / checkmate / stalemate
  • insufficient material detection
• Animated move execution for player and AI moves
• Click-to-move and drag-and-drop piece interaction
• Scrollable move history sidebar using algebraic notation
• Undo support that rewinds game state
• AI search runs in a separate LÖVE thread to keep the UI responsive
• Live search tree visualization with:
  • pan + zoom camera
  • node scores
  • pruned branch rendering
  • best-line highlighting
  • hover tooltip + mini-board preview
  • toggle between full tree and best-line view
• Built-in automated test suites for logic, integration, and worker-thread diagnostics

Tech Stack

• Language: Lua
• Framework: LÖVE 11.x
• Architecture: modular Lua files split into board/, ai/, ui/, and visualizer/
• Concurrency: love.thread + channels for AI worker communication

Repository Layout

chessAIv2/
├── main.lua                 # App entry point and top-level state machine
├── conf.lua                 # LÖVE window configuration
├── README.md
├── LICENSE
├── outline.txt              # Original design/feature outline
│
├── board/
│   ├── board.lua            # Board creation, cloning, piece access
│   ├── moves.lua            # Legal move generation + move execution
│   ├── notation.lua         # Algebraic notation generation
│   ├── pieces.lua           # Piece metadata + sprite loading
│   └── rules.lua            # Check/checkmate/stalemate/draw logic
│
├── ai/
│   ├── engine.lua           # Main-thread AI orchestration
│   ├── minimax.lua          # Iterative deepening + alpha-beta search
│   ├── evaluation.lua       # Static evaluation function
│   ├── movegen.lua          # Move ordering heuristics
│   ├── search_tree.lua      # Tree data structure / serialization helpers
│   └── worker.lua           # Background LÖVE thread worker
│
├── ui/
│   ├── renderer.lua         # Main in-game renderer / layout manager
│   ├── board_renderer.lua   # Board, highlights, pieces, animations
│   ├── input.lua            # Mouse input, move flow, undo, promotion
│   ├── menus.lua            # Main menu + game-over UI
│   ├── hud.lua              # Captured pieces, thinking indicator, buttons
│   ├── sidebar.lua          # Scrollable move list
│   └── promotion_dialog.lua # Promotion picker UI
│
├── visualizer/
│   ├── camera.lua           # Pan/zoom camera logic
│   ├── miniboard.lua        # Hover position preview board
│   ├── tree_builder.lua     # Event-driven tree builder helpers
│   ├── tree_layout.lua      # Tree node positioning
│   ├── tree_renderer.lua    # Tree drawing, tooltips, header
│   └── tree_store.lua       # Tree snapshot storage helpers
│
├── assets/
│   ├── board.png            # Reference board asset
│   └── pieces/              # Piece sprites used by the game
│
├── test.lua                 # Core logic suite
├── test_integration.lua     # Integration suite
├── test_gameflow.lua        # Game-flow simulation
└── test_worker.lua          # Worker-thread diagnostic

Running the Game

Prerequisites

Install LÖVE 11.x.

Examples:

• Arch Linux: sudo pacman -S love
• Or download from: https://love2d.org/

Start

From the repo root:

love .

The game opens in a fixed 1920x1080 window titled Chess AI v2.

Controls

Menu

• Click Play as White or Play as Black
• Click a difficulty button to change search depth
• Click Quit to exit

In Game

• Left click a piece to select it
• Left click a target square to move
• Or drag and drop a piece onto a legal square
• Mouse wheel over the left sidebar to scroll move history
• Click Undo below the board to rewind the game state

AI Visualizer

• Drag inside the visualizer to pan
• Mouse wheel inside the visualizer to zoom
• Hover nodes to inspect move/score details
• Hover nodes to show a mini-board preview of that position
• Click the All / Best Line buttons to switch tree views

How It Works

1. Board and Rules Layer

The board/ modules implement the core chess rules:

• board representation on an 8x8 grid
• move generation per piece type
• legality filtering to prevent self-check
• state tracking for:
  • turn
  • castling rights
  • en passant square
  • halfmove clock
  • fullmove number
  • captured pieces
  • last move

2. AI Layer

The engine uses a classic search stack:

• iterative deepening
• minimax
• alpha-beta pruning
• move ordering using:
  • MVV-LVA capture ordering
  • killer moves
  • history heuristic

The evaluation function combines:

• material
• piece-square tables
• pawn structure
• king safety
• mobility
• endgame-aware king tables

3. Background Worker

AI search runs in ai/worker.lua on a separate thread using love.thread.

The main thread sends a serialized board state over a channel. The worker searches the position, streams search events back, and finally emits a search_complete event with the chosen move.

4. Live Tree Visualizer

While the AI is thinking, the worker streams events such as:

• node created
• node evaluated
• node pruned
• depth started/completed
• search complete

The main thread reconstructs these events into a tree and renders them in the right panel. Best-line nodes are highlighted so you can see the engine's current principal variation.

Game Flow

1. Start from the menu
2. Choose side and difficulty
3. Make a move on the board
4. Player move animates
5. AI thread starts thinking
6. Visualizer fills in with live search nodes
7. AI move is applied and animated
8. Move history updates
9. Repeat until checkmate, stalemate, or draw by insufficient material

Testing

This repo includes several LÖVE-based test entrypoints.

Run them from the project root.

Core logic suite

love . --test

Covers:

• board initialization
• move generation
• rule checks
• notation
• evaluation
• move ordering
• search tree serialization
• minimax search sanity

Integration suite

love . --test-integration

Covers:

• module loading
• renderer setup
• basic game-state transitions
• AI response flow
• undo behavior
• visualizer support modules
• draw calls not crashing

Game-flow simulation

love . --test-gameflow

Simulates a representative player move and AI response loop.

Worker-thread diagnostic

love . --test-worker

Useful when debugging AI thread/channel issues.

Current Architecture Notes

Global state

The game uses a shared global GameState table initialized in main.lua. It stores:

• current screen/state
• player + AI colors
• selected difficulty
• current board
• move history
• undo stack
• AI thinking/animation flags
• visualizer history
• promotion and drag state

Rendering layout

The window is split into three main regions:

• Left: move history sidebar
• Center: chess board + HUD
• Right: AI visualizer

Board orientation

The board flips when the player chooses Black, so input mapping and labels follow the player's perspective.

Assets

Included piece sprites live in:

assets/pieces/

Expected filenames follow this pattern:

wp.png wn.png wb.png wr.png wq.png wk.png
bp.png bn.png bb.png br.png bq.png bk.png

Limitations / Notes

These are based on the current codebase, not a future roadmap:

• Window is currently not resizable (conf.lua sets resizable = false)
• The game is desktop-oriented and expects LÖVE's graphics environment
• Tests are run through love, not a standalone Lua test runner
• Some design ideas remain documented in outline.txt beyond what is currently implemented

Why This Project Is Interesting

Most hobby chess projects stop at either:

• a playable board UI, or
• a backend engine

This repo combines both with a real-time visualization layer that makes the engine's search process visible. That makes it useful not only as a game, but also as an educational tool for understanding how chess search explores and prunes move trees.

License

This repository includes a LICENSE file. See that file for the exact license terms.