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.
Add the JitPack repository and the dependency to your project build file.
<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> repositories { maven { url '[https://jitpack.io](https://jitpack.io)' } } dependencies { implementation 'com.github.bhlangonijr:chesslib:1.3.6' } 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 The Board class is the heart of the library. Here are the most essential commands for manipulating state.
| 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. |
| 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). |
| 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. |
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(); }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); }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;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... });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).
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); 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.
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.