Class Position

Represent a chess position, i.e.:

  • the state of a 64-square chessboard,
  • who is about to play,
  • the castling rights,
  • and the file on which en-passant is possible, if any.

Constructors

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

    Parameters

    • Optionalstate: "start"

    Returns Position

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

    Parameters

    • state: "empty"

    Returns Position

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

    Parameters

    • variant: "regular" | "antichess" | "horde"
    • Optionalstate: "start"

    Returns Position

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

    Parameters

    Returns Position

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

    Parameters

    Returns Position

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

    Parameters

    • fen: string

    Returns Position

    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.

    Parameters

    Returns Position

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

  • Instantiate a copy of the given Position.

    Parameters

    Returns Position

Methods

  • 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 -

    Returns string

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

    Parameters

    • castle:
          | "bb"
          | "wb"
          | Castle
          | "bd"
          | "ba"
          | "bg"
          | "bc"
          | "be"
          | "bf"
          | "bh"
          | "wd"
          | "wa"
          | "wg"
          | "wc"
          | "we"
          | "wf"
          | "wh"

      Must be Castle960 if the Position is configured for Chess960, or Castle otherwise.

    Returns boolean

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

    Parameters

    • castle:
          | "bb"
          | "wb"
          | Castle
          | "bd"
          | "ba"
          | "bg"
          | "bc"
          | "be"
          | "bf"
          | "bh"
          | "wd"
          | "wa"
          | "wg"
          | "wc"
          | "we"
          | "wf"
          | "wh"

      Must be Castle960 if the Position is configured for Chess960, or Castle otherwise.

    • value: boolean

    Returns void

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

    Parameters

    Returns void

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

    Parameters

    • castle:
          | "bb"
          | "wb"
          | Castle
          | "bd"
          | "ba"
          | "bg"
          | "bc"
          | "be"
          | "bf"
          | "bh"
          | "wd"
          | "wa"
          | "wg"
          | "wc"
          | "we"
          | "wf"
          | "wh"

      Must be Castle960 if the Position is configured for Chess960, or Castle otherwise.

    Returns boolean

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

    Returns File | "-"

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

    Returns File | "-"

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

    Parameters

    Returns void

  • Get the FEN representation of the current Position.

    Parameters

    • Optionaloptions: {
          fiftyMoveClock?: number;
          fullMoveNumber?: number;
          regularFENIfPossible?: boolean;
          withVariant?: boolean;
      }
      • OptionalfiftyMoveClock?: number

        Value of the fifty move clock counter (5th field) in the generated FEN string. 0 by default.

      • OptionalfullMoveNumber?: number

        Value of the full move number counter (6th field) in the generated FEN string. 1 by default.

      • OptionalregularFENIfPossible?: boolean

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

      • OptionalwithVariant?: boolean

        If true, a prefix containing the name of the chess game variant + : is prepend to the generated FEN string. false by default.

    Returns string

  • Parse the given FEN string and set the position accordingly.

    Parameters

    • fen: string
    • Optionalstrict: boolean

      If true, only perfectly formatted FEN strings are accepted. false by default.

    Returns {
        fiftyMoveClock: number;
        fullMoveNumber: number;
    }

    • fiftyMoveClock: number
    • fullMoveNumber: number

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

    Parameters

    Returns string

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

    Parameters

    • move: string
    • Optionalstrict: boolean

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

    Returns MoveDescriptor

    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.

    Parameters

    • square:
          | "h1"
          | "h2"
          | "h3"
          | "h4"
          | "h5"
          | "h6"
          | "d1"
          | "d2"
          | "d3"
          | "d4"
          | "d5"
          | "d6"
          | "d7"
          | "d8"
          | "a1"
          | "a2"
          | "a3"
          | "a4"
          | "a5"
          | "a6"
          | "a7"
          | "a8"
          | "b1"
          | "b2"
          | "b3"
          | "b4"
          | "b5"
          | "b6"
          | "b7"
          | "b8"
          | "g1"
          | "g2"
          | "g3"
          | "g4"
          | "g5"
          | "g6"
          | "g7"
          | "g8"
          | "c1"
          | "c2"
          | "c3"
          | "c4"
          | "c5"
          | "c6"
          | "c7"
          | "c8"
          | "e1"
          | "e2"
          | "e3"
          | "e4"
          | "e5"
          | "e6"
          | "e7"
          | "e8"
          | "f1"
          | "f2"
          | "f3"
          | "f4"
          | "f5"
          | "f6"
          | "f7"
          | "f8"
          | "h7"
          | "h8"
    • byWho: Color

    Returns (
        | "h1"
        | "h2"
        | "h3"
        | "h4"
        | "h5"
        | "h6"
        | "d1"
        | "d2"
        | "d3"
        | "d4"
        | "d5"
        | "d6"
        | "d7"
        | "d8"
        | "a1"
        | "a2"
        | "a3"
        | "a4"
        | "a5"
        | "a6"
        | "a7"
        | "a8"
        | "b1"
        | "b2"
        | "b3"
        | "b4"
        | "b5"
        | "b6"
        | "b7"
        | "b8"
        | "g1"
        | "g2"
        | "g3"
        | "g4"
        | "g5"
        | "g6"
        | "g7"
        | "g8"
        | "c1"
        | "c2"
        | "c3"
        | "c4"
        | "c5"
        | "c6"
        | "c7"
        | "c8"
        | "e1"
        | "e2"
        | "e3"
        | "e4"
        | "e5"
        | "e6"
        | "e7"
        | "e8"
        | "f1"
        | "f2"
        | "f3"
        | "f4"
        | "f5"
        | "f6"
        | "f7"
        | "f8"
        | "h7"
        | "h8")[]

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

    Returns boolean

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

    Parameters

    • square:
          | "h1"
          | "h2"
          | "h3"
          | "h4"
          | "h5"
          | "h6"
          | "d1"
          | "d2"
          | "d3"
          | "d4"
          | "d5"
          | "d6"
          | "d7"
          | "d8"
          | "a1"
          | "a2"
          | "a3"
          | "a4"
          | "a5"
          | "a6"
          | "a7"
          | "a8"
          | "b1"
          | "b2"
          | "b3"
          | "b4"
          | "b5"
          | "b6"
          | "b7"
          | "b8"
          | "g1"
          | "g2"
          | "g3"
          | "g4"
          | "g5"
          | "g6"
          | "g7"
          | "g8"
          | "c1"
          | "c2"
          | "c3"
          | "c4"
          | "c5"
          | "c6"
          | "c7"
          | "c8"
          | "e1"
          | "e2"
          | "e3"
          | "e4"
          | "e5"
          | "e6"
          | "e7"
          | "e8"
          | "f1"
          | "f2"
          | "f3"
          | "f4"
          | "f5"
          | "f6"
          | "f7"
          | "f8"
          | "h7"
          | "h8"
    • byWho: Color

    Returns boolean

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

    Returns boolean

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

    Returns boolean

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

    Parameters

    • uscfRules: boolean = false

      true to use the USCF rules (forced checkmate), false to use the FIDE rules (possible checkmate).

    Returns boolean

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

    Returns boolean

  • 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;
    }
    }

    Parameters

    • from:
          | "h1"
          | "h2"
          | "h3"
          | "h4"
          | "h5"
          | "h6"
          | "d1"
          | "d2"
          | "d3"
          | "d4"
          | "d5"
          | "d6"
          | "d7"
          | "d8"
          | "a1"
          | "a2"
          | "a3"
          | "a4"
          | "a5"
          | "a6"
          | "a7"
          | "a8"
          | "b1"
          | "b2"
          | "b3"
          | "b4"
          | "b5"
          | "b6"
          | "b7"
          | "b8"
          | "g1"
          | "g2"
          | "g3"
          | "g4"
          | "g5"
          | "g6"
          | "g7"
          | "g8"
          | "c1"
          | "c2"
          | "c3"
          | "c4"
          | "c5"
          | "c6"
          | "c7"
          | "c8"
          | "e1"
          | "e2"
          | "e3"
          | "e4"
          | "e5"
          | "e6"
          | "e7"
          | "e8"
          | "f1"
          | "f2"
          | "f3"
          | "f4"
          | "f5"
          | "f6"
          | "f7"
          | "f8"
          | "h7"
          | "h8"
    • to:
          | "h1"
          | "h2"
          | "h3"
          | "h4"
          | "h5"
          | "h6"
          | "d1"
          | "d2"
          | "d3"
          | "d4"
          | "d5"
          | "d6"
          | "d7"
          | "d8"
          | "a1"
          | "a2"
          | "a3"
          | "a4"
          | "a5"
          | "a6"
          | "a7"
          | "a8"
          | "b1"
          | "b2"
          | "b3"
          | "b4"
          | "b5"
          | "b6"
          | "b7"
          | "b8"
          | "g1"
          | "g2"
          | "g3"
          | "g4"
          | "g5"
          | "g6"
          | "g7"
          | "g8"
          | "c1"
          | "c2"
          | "c3"
          | "c4"
          | "c5"
          | "c6"
          | "c7"
          | "c8"
          | "e1"
          | "e2"
          | "e3"
          | "e4"
          | "e5"
          | "e6"
          | "e7"
          | "e8"
          | "f1"
          | "f2"
          | "f3"
          | "f4"
          | "f5"
          | "f6"
          | "f7"
          | "f8"
          | "h7"
          | "h8"

    Returns false | RegularMoveFactory | PromotionMoveFactory

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

    Returns boolean

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

    Returns boolean

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

    Parameters

    Returns
        | false
        | "h1"
        | "h2"
        | "h3"
        | "h4"
        | "h5"
        | "h6"
        | "d1"
        | "d2"
        | "d3"
        | "d4"
        | "d5"
        | "d6"
        | "d7"
        | "d8"
        | "a1"
        | "a2"
        | "a3"
        | "a4"
        | "a5"
        | "a6"
        | "a7"
        | "a8"
        | "b1"
        | "b2"
        | "b3"
        | "b4"
        | "b5"
        | "b6"
        | "b7"
        | "b8"
        | "g1"
        | "g2"
        | "g3"
        | "g4"
        | "g5"
        | "g6"
        | "g7"
        | "g8"
        | "c1"
        | "c2"
        | "c3"
        | "c4"
        | "c5"
        | "c6"
        | "c7"
        | "c8"
        | "e1"
        | "e2"
        | "e3"
        | "e4"
        | "e5"
        | "e6"
        | "e7"
        | "e8"
        | "f1"
        | "f2"
        | "f3"
        | "f4"
        | "f5"
        | "f6"
        | "f7"
        | "f8"
        | "h7"
        | "h8"

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

    Parameters

    Returns string

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

    Parameters

    • move: string
    • Optionalstrict: boolean

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

    Returns MoveDescriptor

    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.

    Parameters

    • move: string

    Returns boolean

    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.

    Parameters

    Returns true

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

    Returns boolean

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

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

    Returns void

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

    Returns void

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

    Returns void

  • Get the content of a square.

    Parameters

    • square:
          | "h1"
          | "h2"
          | "h3"
          | "h4"
          | "h5"
          | "h6"
          | "d1"
          | "d2"
          | "d3"
          | "d4"
          | "d5"
          | "d6"
          | "d7"
          | "d8"
          | "a1"
          | "a2"
          | "a3"
          | "a4"
          | "a5"
          | "a6"
          | "a7"
          | "a8"
          | "b1"
          | "b2"
          | "b3"
          | "b4"
          | "b5"
          | "b6"
          | "b7"
          | "b8"
          | "g1"
          | "g2"
          | "g3"
          | "g4"
          | "g5"
          | "g6"
          | "g7"
          | "g8"
          | "c1"
          | "c2"
          | "c3"
          | "c4"
          | "c5"
          | "c6"
          | "c7"
          | "c8"
          | "e1"
          | "e2"
          | "e3"
          | "e4"
          | "e5"
          | "e6"
          | "e7"
          | "e8"
          | "f1"
          | "f2"
          | "f3"
          | "f4"
          | "f5"
          | "f6"
          | "f7"
          | "f8"
          | "h7"
          | "h8"

    Returns
        | "br"
        | "bb"
        | "bp"
        | "bq"
        | "bk"
        | "bn"
        | "wr"
        | "wb"
        | "wp"
        | "wq"
        | "wk"
        | "wn"
        | "-"

  • Set the content of a square.

    Parameters

    • square:
          | "h1"
          | "h2"
          | "h3"
          | "h4"
          | "h5"
          | "h6"
          | "d1"
          | "d2"
          | "d3"
          | "d4"
          | "d5"
          | "d6"
          | "d7"
          | "d8"
          | "a1"
          | "a2"
          | "a3"
          | "a4"
          | "a5"
          | "a6"
          | "a7"
          | "a8"
          | "b1"
          | "b2"
          | "b3"
          | "b4"
          | "b5"
          | "b6"
          | "b7"
          | "b8"
          | "g1"
          | "g2"
          | "g3"
          | "g4"
          | "g5"
          | "g6"
          | "g7"
          | "g8"
          | "c1"
          | "c2"
          | "c3"
          | "c4"
          | "c5"
          | "c6"
          | "c7"
          | "c8"
          | "e1"
          | "e2"
          | "e3"
          | "e4"
          | "e5"
          | "e6"
          | "e7"
          | "e8"
          | "f1"
          | "f2"
          | "f3"
          | "f4"
          | "f5"
          | "f6"
          | "f7"
          | "f8"
          | "h7"
          | "h8"
    • value:
          | "br"
          | "bb"
          | "bp"
          | "bq"
          | "bk"
          | "bn"
          | "wr"
          | "wb"
          | "wp"
          | "wq"
          | "wk"
          | "wn"
          | "-"

    Returns void

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

    Returns Color

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

    Parameters

    Returns void

  • Return the UCI notation corresponding to the given move descriptor.

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

    Parameters

    • moveDescriptor: MoveDescriptor
    • OptionalforceKxR: boolean

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

    Returns string

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

    Parameters

    • move: string
    • Optionalstrict: boolean

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

    Returns MoveDescriptor

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

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

    Parameters

    • pos1: unknown
    • pos2: unknown

    Returns boolean

""