Chesslib

A Lightweight, High-Performance Java Chess Library

Chesslib is a clean, efficient Java library for legal move generation, position validation, and PGN/FEN parsing. It is designed for developers who need a robust engine backbone with high-speed performance and a low memory footprint.

Whether you are building a chess UI, a server-side validator, or a full-strength engine, Chesslib provides the tools you need.

---

Quick Start

Installation

Add the JitPack repository and the dependency to your project build file.

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>[https://jitpack.io](https://jitpack.io)</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.bhlangonijr</groupId>
    <artifactId>chesslib</artifactId>
    <version>1.3.6</version>
</dependency>

Gradle

repositories { maven { url '[https://jitpack.io](https://jitpack.io)' } }
dependencies { implementation 'com.github.bhlangonijr:chesslib:1.3.6' }

Hello World: Making Moves

import com.github.bhlangonijr.chesslib.*;

public class Main {
    public static void main(String[] args) {
        // Create a new board in the starting position
        Board board = new Board();

        // Make a move using SAN (Standard Algebraic Notation)
        board.doMove("e4"); 
        
        // Make a move using Square constants
        board.doMove(new Move(Square.E7, Square.E5));

        // Print the board to console
        System.out.println(board.toString());
    }
}

Output:

r n b q k b n r
p p p p . p p p
. . . . . . . .
. . . . p . . .
. . . . P . . .
. . . . . . . .
P P P P . P P P
R N B Q K B N R
Side: WHITE

---

API Cheat Sheet

The Board class is the heart of the library. Here are the most essential commands for manipulating state.

♟️ Move Execution & History

Action	Method	Description
Do Move (SAN)	board.doMove("Nf3")	Parses and executes a SAN move string.
Do Move (Object)	board.doMove(new Move(sq1, sq2))	Executes a move object (faster).
Undo Move	board.undoMove()	Reverts the last move and returns it.
Get Legal Moves	board.legalMoves()	Returns a List<Move> of all valid moves.
Check Legality	board.isMoveLegal(move, true)	returns boolean if a specific move is valid.

State Inspection

Action	Method	Description
Current Side	board.getSideToMove()	Returns Side.WHITE or Side.BLACK.
Get Piece	board.getPiece(Square.E4)	Returns the piece at a square (or Piece.NONE).
Find Pieces	board.getPieceLocation(Piece.WHITE_KING)	Returns List<Square> of that piece type.
Game Over?	board.isMated()	Returns true if the side to move is checkmated.
Stalemate?	board.isStaleMate()	Returns true if no moves are possible but not in check.
In Check?	board.isKingAttacked()	Returns true if the current King is under attack.
Draw?	board.isDraw()	Checks all draw rules (repetition, 50-move, insufficient material).

Persistence (FEN)

Action	Method	Description
Get FEN	board.getFen()	Exports current state to FEN string.
Load FEN	board.loadFromFen(fenString)	Resets board to the specific FEN position.

---

⚡ Power Features

1. PGN Parsing (Large Databases)

Chesslib includes a streaming PgnIterator that allows you to parse multi-gigabyte PGN files without memory exhaustion.

// Iterate through a PGN file game by game
PgnIterator games = new PgnIterator("grandmaster_games.pgn");

for (Game game : games) {
    System.out.println("Event: " + game.getEvent());
    System.out.println("White: " + game.getWhitePlayer().getName());
    System.out.println("Black: " + game.getBlackPlayer().getName());
    
    // Load the moves to replay them
    game.loadMoveText();
    MoveList moves = game.getHalfMoves();
}

2. MoveList & SAN Handling

Easily convert between standard chess notation and internal move objects.

// Load a game sequence from a string
MoveList list = new MoveList();
list.loadFromSan("1. e4 e5 2. Nf3 Nc6 3. Bb5 a6");

// Export to SAN array
String[] sanMoves = list.toSanArray();

// Apply all moves to a board
Board board = new Board();
for (Move move : list) {
    board.doMove(move);
}

3. Bitboards (For Engine Devs)

Access the raw 64-bit integer (long) representations of the board for high-performance bitwise operations.

// Get a bitmask of all White Pawns
long whitePawns = board.getBitboard(Piece.WHITE_PAWN);

// Get a bitmask of all occupied squares
long allPieces = board.getBitboard();

// Example: Check if A1 is occupied using bitwise AND
boolean isOccupied = (allPieces & (1L << Square.A1.ordinal())) != 0;

4. Event Listeners

Hooks are available for UI updates or logging when the board state changes.

board.addEventListener(BoardEventType.ON_MOVE, event -> {
    Move move = (Move) event;
    System.out.println("Move played: " + move);
    // Trigger GUI update here...
});

5. Board Comparison & Hashing

• board.getZobristKey(): Returns the Zobrist hash (long) for rapid transposition table lookups.
• board.strictEquals(otherBoard): Compares position AND move history (crucial for 3-fold repetition detection).

---

Performance & Testing

Perft (Performance Test)

Validate the move generator against known node counts. This is standard practice when developing engines to ensure bug-free move generation.

// Calculate nodes at depth 5 (Standard Start Position)
// Should return 4,865,609
long nodes = Perft.perft(board, 5); 

---

Contributing

We welcome pull requests! Please ensure all tests pass before submitting.

• Bug Reports: Please provide a minimal reproduction case (FEN + Move).
• Feature Requests: Open an issue to discuss.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Showcase: Check out kengine, a reference chess engine implementation using Chesslib.