Overview
Board represents piece positions on a chess board. It stores pieces as sets of squares (SquareSet) organized by color and role. The class is iterable and provides methods for querying and modifying the board state.
import { Board } from 'chessops';
const board = Board.default();
console.log(board.occupied.size()); // 32
Properties
All occupied squares on the board
All squares occupied by pieces known to be promoted. This information is relevant in chess variants like Crazyhouse.
All squares occupied by white pieces
All squares occupied by black pieces
All squares occupied by pawns
All squares occupied by knights
All squares occupied by bishops
All squares occupied by rooks
All squares occupied by queens
All squares occupied by kings
Static Factory Methods
default
Creates a board with pieces in the standard chess starting position.
const board = Board.default();
console.log(board.get(0)); // { color: 'white', role: 'rook', promoted: false }
empty
Creates an empty board with no pieces.
const board = Board.empty();
console.log(board.occupied.isEmpty()); // true
Instance Methods
reset
Resets all pieces to the default starting position for standard chess. Mutates the board in place.
const board = Board.empty();
board.reset();
console.log(board.occupied.size()); // 32
clear
Removes all pieces from the board. Mutates the board in place.
const board = Board.default();
board.clear();
console.log(board.occupied.isEmpty()); // true
clone
Creates a deep copy of the board.
const board = Board.default();
const copy = board.clone();
// Modifications to copy don't affect original
copy.clear();
console.log(board.occupied.nonEmpty()); // true
console.log(copy.occupied.isEmpty()); // true
get
get(square: Square): Piece | undefined
The square to query (0-63)
An object with color, role, and promoted properties, or undefined
const piece = board.get(28); // e4
if (piece) {
console.log(`${piece.color} ${piece.role}`);
}
getColor
getColor(square: Square): Color | undefined
The square to query (0-63)
Either ‘white’, ‘black’, or undefined if the square is empty
const color = board.getColor(0);
console.log(color); // 'white' for a1 in starting position
getRole
getRole(square: Square): Role | undefined
The square to query (0-63)
One of ‘pawn’, ‘knight’, ‘bishop’, ‘rook’, ‘queen’, ‘king’, or undefined
const role = board.getRole(0);
console.log(role); // 'rook' for a1 in starting position
set
set(square: Square, piece: Piece): Piece | undefined
The square to place the piece on (0-63)
The piece to place, with color, role, and optionally promoted properties
The piece that was replaced, if any
const oldPiece = board.set(28, {
color: 'white',
role: 'queen',
promoted: false
});
take
take(square: Square): Piece | undefined
The square to remove the piece from (0-63)
The removed piece, if any
const piece = board.take(28);
if (piece) {
console.log('Removed', piece.role);
}
has
has(square: Square): boolean
The square to check (0-63)
if (board.has(28)) {
console.log('e4 is occupied');
}
pieces
pieces(color: Color, role: Role): SquareSet
Either ‘white’ or ‘black’
One of ‘pawn’, ‘knight’, ‘bishop’, ‘rook’, ‘queen’, ‘king’
const whiteKnights = board.pieces('white', 'knight');
console.log('White has', whiteKnights.size(), 'knights');
kingOf
kingOf(color: Color): Square | undefined
Either ‘white’ or ‘black’
The square of the king, or undefined if not found or multiple kings exist
const whiteKing = board.kingOf('white');
if (whiteKing !== undefined) {
console.log('White king on square', whiteKing);
}
rooksAndQueens
rooksAndQueens(): SquareSet
const sliders = board.rooksAndQueens();
bishopsAndQueens
bishopsAndQueens(): SquareSet
const diagonalSliders = board.bishopsAndQueens();
steppers
Returns all squares occupied by knights, pawns, or kings (pieces that move in discrete steps).
const steppers = board.steppers();
sliders
Returns all squares occupied by bishops, rooks, or queens (pieces that slide).
const sliders = board.sliders();
[Symbol.iterator]
[Symbol.iterator](): Iterator<[Square, Piece]>
for (const [square, piece] of board) {
console.log(`${piece.color} ${piece.role} on square ${square}`);
}
// Or destructure in other ways
const pieces = Array.from(board);
Utility Functions
boardEquals
boardEquals(left: Board, right: Board): boolean
import { boardEquals } from 'chessops/board';
const board1 = Board.default();
const board2 = Board.default();
if (boardEquals(board1, board2)) {
console.log('Boards are identical');
}
Examples
Creating a Custom Position
import { Board } from 'chessops';
import { parseSquare } from 'chessops';
const board = Board.empty();
// Place white king on e1
board.set(parseSquare('e1')!, {
color: 'white',
role: 'king',
promoted: false
});
// Place black king on e8
board.set(parseSquare('e8')!, {
color: 'black',
role: 'king',
promoted: false
});
// Place white queen on d1
board.set(parseSquare('d1')!, {
color: 'white',
role: 'queen',
promoted: false
});
Analyzing Material
const board = Board.default();
// Count pieces for each side
const whitePawns = board.pieces('white', 'pawn').size();
const blackPawns = board.pieces('black', 'pawn').size();
const whiteKnights = board.pieces('white', 'knight').size();
console.log(`White has ${whitePawns} pawns and ${whiteKnights} knights`);
// Check for specific pieces
if (board.pieces('white', 'queen').nonEmpty()) {
console.log('White still has queen');
}
Iterating Over Specific Pieces
const board = Board.default();
const whitePieces = board.white;
for (const [square, piece] of board) {
if (piece.color === 'white' && piece.role === 'pawn') {
console.log('White pawn on square', square);
}
}
// Or filter using SquareSet
for (const square of board.pieces('black', 'knight')) {
console.log('Black knight on square', square);
}
Moving Pieces
const board = Board.default();
// Move e2 pawn to e4
const from = 12; // e2
const to = 28; // e4
const piece = board.take(from);
if (piece) {
board.set(to, piece);
}
Checking Board State
const board = Board.default();
// Count total pieces
console.log('Total pieces:', board.occupied.size());
// Check if square is attacked by sliders
const targetSquare = 28; // e4
const sliders = board.sliders();
const enemySliders = sliders.intersect(board.black);
for (const slider of enemySliders) {
// Use attack functions to check if slider attacks target
console.log('Slider on square', slider);
}
const board = Board.empty();
// Place a promoted queen (from pawn promotion)
board.set(56, { // a8
color: 'white',
role: 'queen',
promoted: true
});
// Check for promoted pieces
for (const [square, piece] of board) {
if (piece.promoted) {
console.log(`Promoted ${piece.role} on square ${square}`);
}
}
console.log('Promoted pieces:', board.promoted.size());