Overview
This module provides types and classes for representing chess position setups, material counts, and castling rights.
import { defaultSetup, Material, Castles } from 'chessops';
const setup = defaultSetup();
const material = Material.fromBoard(setup.board);
console.log('Total pieces:', material.size());
Setup
Represents a complete (not necessarily legal) chess or chess variant position.
Interface
interface Setup {
board: Board;
pockets: Material | undefined;
turn: Color;
castlingRights: SquareSet;
epSquare: Square | undefined;
remainingChecks: RemainingChecks | undefined;
halfmoves: number;
fullmoves: number;
}
The board with piece positions
Pieces in hand (for variants like Crazyhouse). Undefined for standard chess.
The side to move (‘white’ or ‘black’)
Squares of rooks that still have castling rights
The en passant target square, if any
remainingChecks
RemainingChecks | undefined
Remaining checks for Three-Check variant. Undefined for standard chess.
Halfmove clock for the fifty-move rule
Fullmove number, starting at 1 and incremented after Black’s move
Factory Functions
defaultSetup
Creates a setup with the standard chess starting position.
import { defaultSetup } from 'chessops';
const setup = defaultSetup();
console.log(setup.turn); // 'white'
console.log(setup.fullmoves); // 1
emptySetup
Creates a setup with an empty board.
import { emptySetup } from 'chessops';
const setup = emptySetup();
console.log(setup.board.occupied.isEmpty()); // true
Utility Functions
setupClone
setupClone(setup: Setup): Setup
import { setupClone } from 'chessops';
const original = defaultSetup();
const copy = setupClone(original);
// Modifications to copy don't affect original
copy.turn = 'black';
console.log(original.turn); // 'white'
setupEquals
setupEquals(left: Setup, right: Setup): boolean
import { setupEquals, defaultSetup } from 'chessops';
const setup1 = defaultSetup();
const setup2 = defaultSetup();
if (setupEquals(setup1, setup2)) {
console.log('Setups are identical');
}
MaterialSide
Represents material count for one side.
Properties
Static Methods
empty
static empty(): MaterialSide
import { MaterialSide } from 'chessops';
const material = MaterialSide.empty();
console.log(material.pawn); // 0
fromBoard
static fromBoard(board: Board, color: Color): MaterialSide
The board to count pieces from
The color to count pieces for
import { MaterialSide, Board } from 'chessops';
const board = Board.default();
const whiteMaterial = MaterialSide.fromBoard(board, 'white');
console.log(whiteMaterial.pawn); // 8
Instance Methods
clone
Creates a copy of the material side.
const copy = material.clone();
equals
equals(other: MaterialSide): boolean
The other material side to compare
if (material1.equals(material2)) {
console.log('Same material');
}
add
add(other: MaterialSide): MaterialSide
const total = material1.add(material2);
subtract
subtract(other: MaterialSide): MaterialSide
const difference = material1.subtract(material2);
size
Returns the total number of pieces.
const totalPieces = material.size();
isEmpty
Checks if there are no pieces.
if (material.isEmpty()) {
console.log('No pieces');
}
nonEmpty
Checks if there is at least one piece.
if (material.nonEmpty()) {
console.log('Has pieces');
}
hasPawns
Checks if there are any pawns.
if (material.hasPawns()) {
console.log('Has pawns');
}
hasNonPawns
Checks if there are any pieces other than pawns.
if (material.hasNonPawns()) {
console.log('Has pieces other than pawns');
}
Material
Represents material count for both sides.
Constructor
constructor(white: MaterialSide, black: MaterialSide)
Properties
Static Methods
empty
Creates empty material for both sides.
import { Material } from 'chessops';
const material = Material.empty();
fromBoard
static fromBoard(board: Board): Material
The board to count pieces from
import { Material, Board } from 'chessops';
const board = Board.default();
const material = Material.fromBoard(board);
console.log('White pawns:', material.white.pawn);
console.log('Black pawns:', material.black.pawn);
Instance Methods
clone
Creates a copy of the material.
const copy = material.clone();
equals
equals(other: Material): boolean
The other material to compare
if (material1.equals(material2)) {
console.log('Same material');
}
add
add(other: Material): Material
const total = material1.add(material2);
subtract
subtract(other: Material): Material
const difference = material1.subtract(material2);
count
count(role: Role): number
const totalQueens = material.count('queen');
size
Returns the total number of pieces for both sides.
const totalPieces = material.size();
isEmpty
Checks if both sides have no pieces.
if (material.isEmpty()) {
console.log('No pieces on board');
}
nonEmpty
Checks if at least one side has pieces.
if (material.nonEmpty()) {
console.log('Has pieces');
}
hasPawns
Checks if either side has pawns.
if (material.hasPawns()) {
console.log('Pawns are present');
}
hasNonPawns
Checks if either side has pieces other than pawns.
if (material.hasNonPawns()) {
console.log('Has pieces other than pawns');
}
RemainingChecks
Tracks remaining checks for the Three-Check variant.
Constructor
constructor(white: number, black: number)
Remaining checks for white
Remaining checks for black
Properties
Number of remaining checks white can give
Number of remaining checks black can give
Static Methods
default
static default(): RemainingChecks
import { RemainingChecks } from 'chessops';
const checks = RemainingChecks.default();
console.log(checks.white); // 3
console.log(checks.black); // 3
Instance Methods
clone
Creates a copy of the remaining checks.
const copy = checks.clone();
equals
equals(other: RemainingChecks): boolean
The other remaining checks to compare
if (checks1.equals(checks2)) {
console.log('Same check counts');
}
Castles
Tracks castling rights and paths.
Properties
Squares of rooks that still have castling rights
rook
ByColor<ByCastlingSide<Square | undefined>>
Rook positions for castling, organized by color and side
path
ByColor<ByCastlingSide<SquareSet>>
Squares that must be empty for castling, organized by color and side
Static Methods
default
static default(): Castles
import { Castles } from 'chessops/chess';
const castles = Castles.default();
console.log(castles.castlingRights.size()); // 4 (rooks on a1, h1, a8, h8)
empty
Creates castles with no castling rights.
const castles = Castles.empty();
console.log(castles.castlingRights.isEmpty()); // true
fromSetup
static fromSetup(setup: Setup): Castles
The setup to create castles from
import { Castles } from 'chessops/chess';
import { defaultSetup } from 'chessops';
const setup = defaultSetup();
const castles = Castles.fromSetup(setup);
Instance Methods
clone
Creates a copy of the castles.
const copy = castles.clone();
discardRook
discardRook(square: Square): void
The square of the rook to discard
castles.discardRook(0); // Remove castling rights for a1
discardColor
discardColor(color: Color): void
The color to remove castling rights for
castles.discardColor('white'); // Remove all white castling rights
Examples
Working with Setups
import { defaultSetup, setupClone } from 'chessops';
import { makeFen } from 'chessops/fen';
const setup = defaultSetup();
// Modify the setup
setup.turn = 'black';
setup.halfmoves = 5;
setup.fullmoves = 3;
// Convert to FEN
const fen = makeFen(setup);
console.log(fen);
// Clone before modifying
const copy = setupClone(setup);
copy.turn = 'white';
Material Analysis
import { Material, Board } from 'chessops';
const board = Board.default();
const material = Material.fromBoard(board);
console.log('White pieces:');
console.log(' Pawns:', material.white.pawn);
console.log(' Knights:', material.white.knight);
console.log(' Bishops:', material.white.bishop);
console.log(' Rooks:', material.white.rook);
console.log(' Queens:', material.white.queen);
console.log(' Kings:', material.white.king);
console.log('Total pieces:', material.size());
console.log('Total queens:', material.count('queen'));
Material Difference
import { Material, Board } from 'chessops';
const board = Board.default();
// Remove some pieces
board.take(8); // Remove a white pawn
board.take(12); // Remove another white pawn
const current = Material.fromBoard(board);
const starting = Material.fromBoard(Board.default());
const difference = starting.subtract(current);
console.log('Captured white pawns:', difference.white.pawn);
Castling Rights Management
import { Castles } from 'chessops/chess';
import { defaultSetup } from 'chessops';
const castles = Castles.fromSetup(defaultSetup());
console.log('White can castle queenside:', castles.rook.white.a !== undefined);
console.log('White can castle kingside:', castles.rook.white.h !== undefined);
// Remove castling right when king moves
castles.discardColor('white');
console.log('White castling rights:', castles.rook.white.a); // undefined
Three-Check Variant
import { RemainingChecks } from 'chessops';
const checks = RemainingChecks.default();
// After white gives a check
checks.white = Math.max(checks.white - 1, 0);
console.log('White remaining checks:', checks.white);
if (checks.white === 0) {
console.log('White wins by three checks!');
}