@hiron-tez/chess v1.0.2
Chess engine
This is a fully functional game core that implements all the functionality and logic and provides an easy way to interact with the pieces.
Install
npm
npm i @hiron-tez/chess
pnpm
pnpm add @hiron-tez/chess
yarn
yarn add @hiron-tez/chess
bun
bun add @hiron-tez/chess
Usage
Basic
import { Board } from "@hiron-tez/chess";
const board = new Board();
await board.move("a2", "a4");
Advanced
import { Board, King, Pawn } from "@hiron-tez/chess";
const board = new CustomBoard([
new King("B2", Color.White),
new King("B8", Color.Black),
new Pawn("A2", Color.White),
new Pawn("B4", Color.Black),
]);
const pawnDoubleMoved = await board.move("A2", "A4");
// true
const enPassantSuccess = await board.move("B4", "A3");
// true
const capturedPiece = board.getPieceAt("A4");
// undefined
const blackPawn = board.getPieceAt("A3");
// [instance of Piece]
const checkColor = board.check;
// Color.White
const checkmateColor = board.checkmate;
// undefined
const whiteKingPossibleMoves = board.getPossibleMoves("B2");
// [array of Position instances]
const isBlackPawnAtA3 = blackPawn?.isAt("A3");
// true
Documentation
PositionNotationT
String that represents a position on a chess board. Allowed characters: a-h, A-H, 1-8.
- example:
"A1"
- example:
PointT
An object with x and y coordinates. Allowed values: 0-7
example:
{ x: 0, y: 0 }
PositionInputT
PositionNotationT, PointT or Position
Type
Enum that represents the type of a chess piece.
- members:
King
Queen
Rook
Bishop
Knight
Pawn
- members:
Color
Enum that represents the color of a chess piece.
- members:
White
Black
- members:
Position
A class with coordinates and useful methods and properties to work with positions
- params:
position
PositionInputT | string
- properties:
x
number - coordinatey
number - coordinatenotation
string | undefined - a string representation of the positionisValid
boolean - indicates whether the position is valid
- methods:
distanceTo
- get distance to a specified position- params:
position
PositionInputT
- returns number
- example:
position.distanceTo("A1");
- params:
- params:
Piece
A class representing a chess piece.
- properties:
type
Type (readonly) - the type of the piececolor
Color (readonly) - the color of the pieceoppositeColor
Color (readonly) - the color of the opposite teamposition
Position - the position of the pieceisMoved
boolean - whether the piece was already moved or not yet
- methods:
isAt
- check if the piece is at specified position- params:
position
PositionInputT | string
- returns boolean
- params:
- properties:
King, Queen, Rook, Bishop, Knight, Pawn (extend Piece)
Classes that represent chess pieces with their unique behaviors
- parameters:
position
PositionInputT - the position of the piececolor
Color - the color of the piece
- parameters:
CustomBoard
Chess game controller
- parameters:
pieces
Array<King | Queen | Rook | Bishop | Knight | Pawn> - the set of piecesoptions.getPromotionVariant
(optional) - get the promotion variant for a pawn- parameters:
position
Position - the position of the pawn
- returns Type | Promise
- parameters:
options.onCheck
(optional) - check event handler- parameters:
color
Color - the color of the team that's in check
- parameters:
options.onCheckmate
(optional) - checkmate event handler- parameters:
color
Color - the color of the team that's in checkmate
- parameters:
options.onCheckResolve
(optional) - check resolve event handleroptions.onStalemate
(optional) - stalemate event handler- parameters:
color
Color - the color of the team that's in stalemate
- parameters:
options.onBoardChange
(optional) - board change event handler- parameters:
pieces
Array - the current piece set
- parameters:
options.onMove
(optional) - piece movement event handler- parameters:
startPosition
Position - piece start positionendPosition
Position - piece end position
- parameters:
options.onCapture
(optional) - piece capture event handler- parameters:
startPosition
Position - piece start positionendPosition
Position - piece end positioncapturedPosition
Position - captured target position. It's different fromendPosition
only on en passant because the piece doesn't move to the target's position
- parameters:
options.onCastling
(optional) - castling event handler- parameters:
kingStartPosition
Position - king start positionkingEndPosition
Position - king end positionrookStartPosition
Position - rook start positionrookEndPosition
Position - rook end position
- parameters:
options.onPromotion
(optional) - pawn promotion event handler- parameters:
position
Position - position of the pawn
- parameters:
- properties:
check
Color | undefined - color team in checkcheckmate
Color | undefined - color team in checkmatestalemate
Color | undefined - color team in stalematepieces
Array - the current set of piecescurrentTurn
Color - color of the team to make next move
- methods:
getPieceAt
- get a piece at the specified position- params:
position
PositionInputT
- returns Piece | undefined
- params:
getPiecesByColor
- get all the pieces of a specified team- params:
color
Color
- returns Array
- params:
getPossibleMoves
- get all possible moves of a specified piece- params:
position
PositionInput
- returns Array - positions for valid moves
- params:
move
- move a piece from and to a specified position- params:
startPosition
PositionInputendPosition
PositionInput
- returns Promise - move success status
- params:
- parameters:
Board (extends CustomBoard)
Chess game controller with the prepared set of pieces
- parameters:
options
- same as in CustomBoard
- parameters: