Instantiate a new Position configured for the usual chess rules, and initialized with the usual starting position.
Optional
state: "start"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).
Optional
state: "start"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.
Must be between 0 and 959 inclusive (see https://chess960.net/start-positions/ or https://www.chessprogramming.org/Reinhard_Scharnagl for more details).
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.
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.
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 -
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:
'-'
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).
Optional
options: { Optional
fiftyValue of the fifty move clock counter (5th field) in the generated FEN string. 0
by default.
Optional
fullValue of the full move number counter (6th field) in the generated FEN string. 1
by default.
Optional
regularFENIfFor Chess960 only: if true
, the castling flags are rendered using the regular-FEN style (i.e. KQkq
)
if no ambiguity is possible; if false
or if there is an ambiguity, X-FEN style (i.e. AHah
) is used instead.
For non-Chess960 variants, this flag has no effect (regular FEN-style is always used in these cases).
false
by default.
Optional
withIf true
, a prefix containing the name of the chess game variant + :
is prepend to the generated FEN string.
false
by default.
Parse the given FEN string and set the position accordingly.
Optional
strict: booleanIf true
, only perfectly formatted FEN strings are accepted. false
by default.
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).
Optional
strict: booleanIf true
, only perfectly formatted FAN moves are accepted. If false
, "small errors" in the input
such as a missing capture character, an unnecessary disambiguation symbol... do not interrupt the parsing.
false
by default.
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).
true
to use the USCF rules (forced checkmate), false
to use the FIDE rules (possible checkmate).
Check whether the current position is legal or not.
A position is considered to be legal if all the following conditions are met:
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:
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;
}
}
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:
false
is always returned,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.
Optional
strict: booleanIf true
, only perfectly formatted SAN moves are accepted. If false
, "small errors" in the input
such as a missing capture character, an unnecessary disambiguation symbol... do not interrupt the parsing.
false
by default.
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.
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.
WARNING: this MoveDescriptor MUST have been generated by one of the methods of the current Position. Trying to invoke Position.play with a MoveDescriptor generated by another Position instance would result in an undefined behavior.
Set the position to Chess960 starting position corresponding to the given Scharnagl code.
Must be between 0 and 959 inclusive (see https://chess960.net/start-positions/ or https://www.chessprogramming.org/Reinhard_Scharnagl for more details).
Get the content of a square.
Set the content of a square.
Return the UCI notation corresponding to the given move descriptor.
Examples of UCI notation: 'e2e4'
, 'b8c6'
, 'e7e8q'
(promotion)... For more details, please refer to:
Optional
forceKxR: booleanIf true
, castling moves are encoded as "king-take-rook", i.e. for instance white king-side castling will be 'e1h1'
(instead of 'e1g1'
in UCI standard). If false
, castling move encoding follows the UCI standard for normal chess games
(e.g. 'e1g1'
). For Chess960 games, the "king-take-rook" style is always used, whatever the value of this flag.
false
by default.
Parse the given string as UCI notation and return the corresponding move descriptor.
Optional
strict: booleanIf true
, "king-take-rook"-encoded castling moves (i.e. for instance 'e1h1'
for white king-side castling)
are rejected in case of normal chess games. If false
, both "king-take-rook"-encoded and UCI-standard-encoded castling moves
(e.g. 'e1g1'
) are accepted. For Chess960 games, only the "king-take-rook" style is accepted, whatever the value of this flag.
false
by default.
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.
Static
is
Represent a chess position, i.e.: