Class Position

Return a human-readable string representing the position. This string is multi-line, and is intended to be displayed in a fixed-width font (similarly to an ASCII-art picture). For instance:

const position = new Position();
console.log(position.ascii());

// +---+---+---+---+---+---+---+---+
// | 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 |
// +---+---+---+---+---+---+---+---+
// w KQkq -

Get a castle flag (i.e. whether or not the corresponding castle is allowed or not).

Set a castle flag (i.e. whether or not the corresponding castle is allowed or not).

Set the position to the empty state, for the given chess game variant.

Get a validated (aka. effective) castle flag (i.e. whether or not the corresponding castle is allowed or not).

Compared to castling, if this method returns true, then it is guaranteed that there are a king and a rook on the squares corresponding to the given castle.

Get the effective en-passant flag (i.e. the column on which a en-passant capture is possible, if any).

If enPassant returns '-', this method returns '-'. Otherwise, it returns:

• either the same file that is returned by enPassant if a en-passant capture is allowed on this file,
• or '-' otherwise.

Get the en-passant flag (i.e. the file on which a 2-square pawn move has just happen, if any).

WARNING: even if this method returns something different from '-', en-passant capture may not be possible on the corresponding file. Use effectiveEnPassant to determine whether en-passant capture is actually possible or not.

Set the en-passant flag (i.e. the file on which a 2-square pawn move has just happen, if any).

Get the FEN representation of the current Position.

Parse the given FEN string and set the position accordingly.

Throws

InvalidFEN if the given string cannot be parsed as a valid FEN string.

Return the figurine algebraic notation corresponding to the given move descriptor (figurine algebraic notation is the same as standard algebraic notation, except that chess pieces are represented with their respective unicode character, instead of the first letter of their English name).

Parse the given string as figurine algebraic notation and return the corresponding move descriptor (figurine algebraic notation is the same as standard algebraic notation, except that chess pieces are represented with their respective unicode character, instead of the first letter of their English name).

Throws

InvalidNotation if the move parsing fails or if the parsed move would correspond to an illegal move.

Return the squares from which a piece of the given color attacks the given square.

Whether at least one legal move exists in the current position or not. If the position is not legal (see isLegal), the returned value is always false.

Check if any piece of the given color attacks the given square.

Whether the player that is about to play is in check or not. If the position is not legal (see isLegal), the returned value is always false.

For antichess, this method always returns false.

Whether the player that is about to play is checkmated or not. If the position is not legal (see isLegal), the returned value is always false.

For antichess, this method returns true if the player about to play has no remaining piece or pawn, or if non of his/her remaining pieces can move (i.e. same behavior as isStalemate for this variant).

For horde chess, this method returns true if black has been checkmated or if white has no remaining piece.

Whether both players have insufficient material so the game cannot end in checkmate (dead position rule). If the position is not legal (see isLegal), the returned value is always false.

By default, the method uses the FIDE rules, i.e. the position is considered as dead if there is no possible checkmate, even if both players cooperate for that. This is different from the USCF rules, for which the position is considered as dead if no player can force the other into a checkmate. For instance, king + two knights vs king is NOT considered as dead according to the FIDE rules, whereas it is according to the USCF rules.

For antichess and horde chess, this method always returns false since it is always possible to end in a checkmate-like situation (by capturing all the pieces of one player).

Check whether the current position is legal or not.

A position is considered to be legal if all the following conditions are met:

1. There is exactly one white king and one black king on the board (or more generally, the number of kings on the board matches what is expected in the game variant of the position).
2. The player that is not about to play is not in check (this condition is omitted for variants in which kings have no royal power).
3. There are no pawn on ranks 1 and 8 (except if the game variant of the position allows it).

Check whether a move is legal or not, and return a factory capable the corresponding MoveDescriptor(-s) if it is legal.

For castling moves, to is supposed to represent:

• for regular chess, the destination square of the king (i.e. c1, g1, c8 or g8),
• for Chess960, the origin square of the rook ("king-take-rook" pattern).

A code interpreting the result returned by isMoveLegal would typically look like this:

const result = position.isMoveLegal(from, to);
if (!result) {
  // The move "from -> to" is not legal.
}
else {
  switch (result.status) {

    case 'regular':
      // The move "from -> to" is legal, and the corresponding move descriptor
      // is `result()`.
      break;

    case 'promotion':
      // The move "from -> to" is legal, but it corresponds to a promotion,
      // so the promoted piece must be specified. The corresponding move descriptors
      // are `result('q')`, `result('r')`, `result('b')` and `result('n')`.
      break;

    default:
      // This case is not supposed to happen.
      break;
  }
}

Whether a null-move (i.e. switching the player about to play) can be played in the current position or not.

A null-move is possible if the position is legal and if the current player about to play is not in check.

Whether the player that is about to play is stalemated or not. If the position is not legal (see isLegal), the returned value is always false.

For antichess, this method returns true if the player about to play has no remaining piece or pawn, or if non of his/her remaining pieces can move (i.e. same behavior as isCheckmate for this variant).

For horde chess, this method returns true if black has been stalemated or if white cannot move but has still at least one piece.

Return the square on which is located the king of the given color. If there is no such king on the board (or on the contrary, if there are two or more such kings on the board), false is returned.

For non-standard variants, the behavior of this method depends on whether king has royal power in the current variant or not (i.e. whether it can be put in check or not). For instance:

• in antichess, the king has no royal power, thus false is always returned,
• in Chess960, the king has royal power (as in the usual chess rules), thus the method returns the square on which the king is located.

Return the list of all legal moves in the current position. An empty list is returned if the position itself is not legal (see isLegal).

Return the standard algebraic notation corresponding to the given move descriptor.

Parse the given string as standard algebraic notation and return the corresponding move descriptor.

Throws

InvalidNotation if the move parsing fails or if the parsed move would correspond to an illegal move.

Try to parse the given string as a SAN notation, and to play the corresponding move on the current position.

Returns

true if the move has been played, false if the move is not legal or if the string passed to the method cannot be interpreted as a valid SAN move notation.

Play the given move.

Play a null-move on the current position if it is legal.

Returns

true if the move has actually been played, false otherwise.

Set the position to the starting state (in the regular chess variant).

Set the position to Chess960 starting position corresponding to the given Scharnagl code.

Set the position to the starting state of the antichess variant.

Set the position to the starting state of the horde chess variant.

Get the content of a square.

Set the content of a square.

Get the turn flag (i.e. who is about to play).

Set the turn flag (i.e. who is about to play).

Return the UCI notation corresponding to the given move descriptor.

Examples of UCI notation: 'e2e4', 'b8c6', 'e7e8q' (promotion)... For more details, please refer to:

• https://en.wikipedia.org/wiki/Universal_Chess_Interface
• https://www.chessprogramming.org/UCI
• https://www.shredderchess.com/download/div/uci.zip

Parse the given string as UCI notation and return the corresponding move descriptor.

Throws

InvalidNotation if the move parsing fails or if the parsed move would correspond to an illegal move.

Get the chess game variant in use.

Check whether both given objects represent the same chess position (i.e. the same chess variant, same board, and same turn/castling/en-passant flags).