rust-chess

📖 Documentation: 📚 Complete Wiki · 🚀 Quick Start · 📋 API Reference · 🏗️ Architecture

rust-chess is a high-performance chess engine and API server written in Rust. It provides a complete chess implementation with magic-bitboard move generation, AI opponent with alpha-beta pruning, and a RESTful API — all compiled to a single static binary under 3 MB.

What makes rust-chess special:

⚡ Blazing Performance: Magic bitboards, zero-copy serialization, sub-microsecond move validation — compiled to a single static binary with no runtime dependencies.

🦀 Rust Safety Guarantees: Memory safety without garbage collection, fearless concurrency with Tokio, type-safe API with comprehensive error handling.

🤖 AI Engine: Negamax with alpha-beta pruning, MVV-LVA move ordering, piece-square tables, 6 difficulty levels from random to depth-8 search.

🐳 Tiny Docker Image: Multi-stage build producing a scratch-based image at ~3 MB with built-in health checks.

Part of the chess platform family alongside go-chess and npm-chess, sharing a unified API design.

✨ Key Features

Core Chess Engine

• Magic Bitboard Representation: 64-bit bitboards with runtime-computed magic numbers for sliding piece attacks
• Complete Rule Implementation: All chess rules including castling, en passant, pawn promotion (all 4 piece types)
• Legal Move Generation: Pseudo-legal generation with legality filtering, pin detection, check evasion
• Zobrist Hashing: Incremental position hashing for threefold repetition detection
• FEN & PGN Support: Full Forsyth-Edwards Notation import/export and Portable Game Notation export
• SAN Notation: Standard Algebraic Notation generation and parsing with full disambiguation
• Draw Detection: 50-move rule, threefold repetition, insufficient material (KvK, KBvK, KNvK, KBvKB same color)
• Game State Management: Undo/redo with full position restoration, move history tracking

🤖 AI Engine

• Negamax Search: With alpha-beta pruning for exponential search reduction
• MVV-LVA Move Ordering: Most Valuable Victim – Least Valuable Attacker for better pruning
• Piece-Square Tables: Positional evaluation beyond material counting
• Bishop Pair Bonus: 30 centipawn bonus for the bishop pair advantage
• Time Budget Control: Check every 4096 nodes to respect time limits
• 6 Difficulty Levels: Harmless (random), Easy (depth 1), Medium (depth 3), Hard (depth 5), Expert (depth 6), Godlike (depth 8)

🚀 REST API

• 14 Endpoints: Complete game lifecycle — create, move, undo, AI, analysis, hints, PGN, FEN
• JSON API: Consistent request/response format with structured error handling
• Board Representation: 8×8 array (rank 8 → rank 1), uppercase = White, lowercase = Black, null = empty
• CORS Support: Pre-configured for cross-origin requests (any origin/method/header)
• Structured Logging: tracing-based request/response logging with configurable levels

� WebSocket Real-Time Events

• Live Game Streaming: GET /ws/games/{id} — connect to receive real-time game events
• 8 Event Types: subscribed, move_made, ai_thinking, ai_move_complete, game_state, game_over, error, pong
• Client Commands: subscribe, unsubscribe, ping — JSON command protocol
• Multi-Client Support: Multiple WebSocket clients per game with isolated broadcasts
• Automatic Cleanup: Stale connections detected and removed on failed sends

🛠️ Technical Excellence

• 341 Tests: 312 unit tests + 17 perft integration + 12 WebSocket integration, ~89% code coverage
• Zero Warnings: Clean cargo clippy -D warnings and cargo fmt --check
• CI/CD Pipeline: GitHub Actions with fmt → clippy → test → perft → coverage → audit → Docker
• 2.93 MB Docker Image: scratch-based with built-in --health-check flag (no curl needed)
• Zero Runtime Dependencies: Static binary with musl libc

Quick Start

Prerequisites

• Rust 1.82+ (stable, edition 2024)

Build & Run

# Clone the repository
git clone https://github.com/RumenDamyanov/rust-chess.git
cd rust-chess

# Build and run
cargo run

# Or using Make
make run

The server starts on http://localhost:8082 by default.

Verify

curl http://localhost:8082/health

{
  "status": "ok",
  "version": "0.1.0",
  "language": "rust",
  "engine": "rust-chess",
  "uptime": 5
}

Play a Quick Game

# Create a game
GAME=$(curl -s -X POST http://localhost:8082/api/games \
  -H "Content-Type: application/json" \
  -d '{"whitePlayer":"Alice","blackPlayer":"Bob"}')
ID=$(echo $GAME | jq -r '.id')

# Make a move (e2 to e4)
curl -s -X POST "http://localhost:8082/api/games/$ID/moves" \
  -H "Content-Type: application/json" \
  -d '{"from":"e2","to":"e4"}' | jq '.lastMove'

# Ask the AI to respond
curl -s -X POST "http://localhost:8082/api/games/$ID/ai-move" \
  -H "Content-Type: application/json" \
  -d '{"difficulty":"medium"}' | jq '{move: .move, thinkingTime: .thinkingTime}'

# Get analysis
curl -s "http://localhost:8082/api/games/$ID/analysis?depth=5" | jq '{eval: .evaluation, bestMove: .bestMove}'

# Export PGN
curl -s "http://localhost:8082/api/games/$ID/pgn"

Configuration

Environment variables:

PORT=9000 CHESS_AI_DEFAULT_DIFFICULTY=hard cargo run

# Enable LLM chat with OpenAI
CHESS_LLM_ENABLED=true OPENAI_API_KEY=sk-... cargo run

API Endpoints

WebSocket Usage

Connect to ws://localhost:8082/ws/games/{id} to receive real-time events for a game. On connect, the server sends a subscribed event with the current game state.

Server → Client events:

// Sent on connect
{"type":"subscribed","gameId":"...","fen":"...","status":"active","currentPlayer":"white","moveCount":0,"check":false}

// After a player move
{"type":"move_made","gameId":"...","san":"e4","from":"e2","to":"e4","player":"white","fen":"...","status":"active","moveCount":1,"check":false}

// When AI starts thinking
{"type":"ai_thinking","gameId":"...","difficulty":"medium"}

// When AI finishes
{"type":"ai_move_complete","gameId":"...","san":"e5","from":"e7","to":"e5","fen":"...","status":"active","thinkingTimeMs":42,"moveCount":2,"check":false}

// On checkmate/stalemate/draw
{"type":"game_over","gameId":"...","result":"checkmate","fen":"..."}

Client → Server commands:

{"type":"ping"}                         // Server replies with {"type":"pong","timestamp":...}
{"type":"subscribe","game_id":"..."}    // Re-subscribe / get current state
{"type":"unsubscribe","game_id":"..."}  // Unsubscribe from a game

Error Response Format

All errors return structured JSON:

{
  "error": {
    "code": "INVALID_MOVE",
    "message": "Move e2e5 is not legal in the current position"
  }
}

Error codes: GAME_NOT_FOUND, INVALID_MOVE, INVALID_FEN, GAME_OVER, NOTHING_TO_UNDO, INVALID_SQUARE, INTERNAL_ERROR.

Development

Common Commands

make build          # Debug build
make release        # Optimized release build
make test           # Run all tests
make test-verbose   # Run tests with output
make lint           # Run clippy linter
make fmt            # Format code
make check          # fmt + lint + test (pre-commit)
make coverage       # Generate coverage report (needs cargo-tarpaulin)
make audit          # Security audit (needs cargo-audit)
make clean          # Clean build artifacts

Docker

make docker         # Build Docker image (~3 MB)
make docker-run     # Run in container
make docker-size    # Check image size

# Or manually
docker build -t rust-chess .
docker run -p 8082:8082 rust-chess

# With custom port
docker run -e PORT=9000 -p 9000:9000 rust-chess

The scratch-based image includes a built-in health check via --health-check flag (no curl/wget needed).

Architecture

src/
├── main.rs              # Entry point: CLI flags, tracing, server startup
├── lib.rs               # Crate root: module declarations
├── config.rs            # Environment variable configuration
├── engine/
│   ├── mod.rs           # Module re-exports
│   ├── types.rs         # Core types: Color, PieceType, Square, Bitboard, Move, etc.
│   ├── zobrist.rs       # Zobrist hashing (deterministic PRNG, OnceLock singleton)
│   ├── board.rs         # Position: bitboard arrays, make/undo move, FEN, attack detection
│   ├── attacks.rs       # Magic bitboard attack tables (runtime-computed magics)
│   ├── movegen.rs       # Legal move generation (pseudo-legal + legality filter)
│   ├── game.rs          # Game controller: history, undo, status detection, draw rules
│   ├── san.rs           # SAN generation & parsing with disambiguation
│   └── pgn.rs           # PGN export with Seven Tag Roster
├── ai/
│   ├── mod.rs           # Module re-exports
│   ├── evaluation.rs    # Material + PST + bishop pair evaluation
│   └── engine.rs        # AiEngine trait, RandomAi, MinimaxAi (negamax + alpha-beta)
└── api/
    ├── mod.rs           # Module declarations
    ├── router.rs        # Axum router with all routes and middleware
    ├── handlers.rs      # 14 request handler functions
    ├── models.rs        # Request/response JSON models + conversion helpers
    ├── errors.rs        # Structured API error handling with HTTP status mapping
    └── state.rs         # Shared application state (Arc<RwLock<HashMap<String, Game>>>)

Design Principles

• Magic Bitboards: Runtime-computed magic numbers for O(1) sliding piece attack lookups
• LERF Mapping: Little-Endian Rank-File (a1=0, h8=63) for cache-friendly bitboard operations
• Incremental Zobrist: Position hash updated via XOR on every make/undo for O(1) repetition detection
• Type-safe moves: Moves validated at the type level with MoveFlags (capture/castle/ep/promo)
• Shared API design: Endpoint paths and JSON schemas align with go-chess and npm-chess
• Error propagation: thiserror derives with automatic HTTP status mapping

Performance Notes

• Move generation: Magic bitboards provide O(1) attack lookups for bishops, rooks, and queens
• AI search: Alpha-beta with MVV-LVA ordering typically prunes ~90% of nodes at depth 5
• Memory: Each Position is ~200 bytes (12 bitboards + metadata), fully stack-allocated
• Binary size: Release build with LTO + strip produces a ~2.5 MB static binary

Project Phases

License

This project is licensed under the MIT License — see the LICENSE.md file for details.

Related Projects

• go-chess — Go chess engine & API (port 8080)
• npm-chess — TypeScript chess library (port 8081)
• js-chess — JavaScript chess frontend
• react-chess — React chess UI