Class Position

Instantiate a new Position configured for the usual chess rules, and initialized with the usual starting position.

Instantiate a new Position configured for the usual chess rules, and initialized with an empty board.

Instantiate a new Position configured for the given chess game variant, and initialized with the usual starting position of this variant.

Warning: only chess game variants with a canonical start position can be used here (see variantWithCanonicalStartPosition).

Instantiate a new Position configured for the given chess game variant, and initialized with an empty board.

Instantiate a new Position configured for the Chess960 game variant, and initialized with the starting position corresponding to the given Scharnagl code.

Instantiate a new Position and initialize it by parsing the given FEN string.

If the given FEN string is prefixed by the name of the chess game variant + :, the position is configured for the corresponding chess game variant. Otherwise, the usual chess rules are used.

If the chess game variant is Chess960, X-FEN can be used instead of regular FEN.

Throws

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

Instantiate a new Position configured for the given chess game variant, and initialize it by parsing the given FEN string.

If the chess game variant is Chess960, X-FEN can be used instead of regular FEN.

Throws

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

Instantiate a copy of the given 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 -
Copy

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 Position.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 Position.enPassant returns '-', this method returns '-'. Otherwise, it returns:

• either the same file that is returned by Position.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 Position.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

exception.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

exception.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 Position.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 Position.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 Position.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 Position.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 Position.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 Position.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;
  }
}
Copy

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 Position.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 Position.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 Position.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

exception.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.

Play the given move.

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

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

exception.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).