Position(fenopt)

Represent a chess position, i.e. the state of a 64-square chessboard with a few additional information (who is about to play, castling rights, en-passant rights).

new Position(fenopt)

Parameters:
Name Type Attributes Default Description
fen string | Position <optional>
'start'

Either 'start', 'empty', a FEN string representing a chess position, an existing Position object.

Throws:

If the input parameter is neither a correctly formatted FEN string nor 'start' or 'empty'.

Type
module:exception.InvalidFEN

Methods

ascii() → {string}

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

Returns:
string -

Human-readable representation of the position.

castling(castle, value)

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

Parameters:
Name Type Description
castle Castle
value boolean

castling(castle) → {boolean}

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

Parameters:
Name Type Description
castle Castle
Returns:
boolean

clear()

Set the position to the empty state.

enPassant() → {EnPassantFlag}

Get the en-passant flag (i.e. the file on which en-passant is allowed, if any).

Returns:
EnPassantFlag

enPassant(value)

Set the en-passant flag (i.e. the file on which en-passant is allowed, if any).

Parameters:
Name Type Description
value EnPassantFlag

fen(fen, strictopt) → {Object}

Parse the given FEN string and set the position accordingly.

Parameters:
Name Type Attributes Default Description
fen string
strict boolean <optional>
false

If true, only perfectly formatted FEN strings are accepted.

Throws:

If the given string cannot be parsed as a valid FEN string.

Type
module:exception.InvalidFEN
Returns:
Object

fen(optionsopt)

Get the FEN representation of the current Position).

Parameters:
Name Type Attributes Description
options Object <optional>

If not provided the fiftyMoveClock and the fullMoveNumber fields of the returned FEN string are set respectively to 0 and 1.

getAttacks(square, byWho) → {Array.<Square>}

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

Parameters:
Name Type Description
square Square
byWho Color
Returns:
Array.<Square>

hasMove() → {boolean}

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

isAttacked(square, byWho) → {boolean}

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

Parameters:
Name Type Description
square Square
byWho Color
Returns:
boolean

isCheck() → {boolean}

Return true if the player that is about to play is in check. If the position is not legal (see Position#isLegal), the returned value is always false.

Returns:
boolean

isCheckmate() → {boolean}

Return true if the player that is about to play is checkmated. If the position is not legal (see Position#isLegal), the returned value is always false.

Returns:
boolean

isLegal() → {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.
  2. The player that is not about to play is not in check.
  3. There are no pawn on ranks 1 and 8.
  4. For each colored castle flag set, there is a rook and a king on the corresponding initial squares.
  5. The pawn situation is consistent with the en-passant flag if it is set. For instance, if it is set to the "e" file and black is about to play, the squares e2 and e3 must be empty, and there must be a white pawn on e4.
Returns:
boolean

isMoveLegal(from, to) → {boolean|MoveDescriptor|function}

Check whether a move is legal or not, and return the corresponding MoveDescriptor if it is legal.

Depending on the situation, the method returns:

  • false if it is not possible to move from from to to (either because the move itself is not legal, or because the underlying position is not legal).
  • a MoveDescriptor object if the move is legal, and if it does not correspond to a promotion.
  • a function that takes in input a Piece (among 'q', 'r', 'b' and 'n') and returns a MoveDescriptor if the move is legal and corresponds to a promotion. In this case, the Piece passed to this function corresponds to the promoted piece. Furthermore, the attribute needPromotion is set to true on the returned function.

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

var result = position.isMoveLegal(from, to);
if(!result) {
  // The move "from -> to" is not legal.
}
else if(result.needPromotion) {
  // 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')`.
}
else {
  // The move "from -> to" is legal, and the corresponding move descriptor is `result`.
}
Parameters:
Name Type Description
from Square
to Square
Returns:
boolean | MoveDescriptor | function

isNullMoveLegal() → {boolean}

Determine whether a null-move (i.e. switching the player about to play) can be play in the current position.

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

Returns:
boolean

isStalemate() → {boolean}

Return true if the player that is about to play is stalemated. If the position is not legal (see Position#isLegal), the returned value is always false.

Returns:
boolean

kingSquare(color) → {Square|boolean}

Return the square on which is located the king of the given color.

Parameters:
Name Type Description
color Color
Returns:
Square | boolean -

Square where is located the searched king. false is returned if there is no king of the given color, or if the are 2 such kings or more.

moves() → {Array.<MoveDescriptor>}

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

Returns:
Array.<MoveDescriptor>

notation(moveDescriptor) → {string}

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

Parameters:
Name Type Description
moveDescriptor MoveDescriptor
Returns:
string

notation(move, strictopt) → {MoveDescriptor}

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

Parameters:
Name Type Attributes Default Description
move string
strict boolean <optional>
false

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.

Throws:

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

Type
module:exception.InvalidNotation
Returns:
MoveDescriptor

play(move) → {boolean}

Play the given move if it is legal.

WARNING: when a MoveDescriptor is passed to this method, this MoveDescriptor must have been issued by one of the Position#moves / Position#isMoveLegal / Position#notation methods of the current Position. Trying to invoke Position#play with a MoveDescriptor generated by another Position object would result in an undefined behavior.

Parameters:
Name Type Description
move string | MoveDescriptor
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 (see Position#notation).

playNullMove() → {boolean}

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

Returns:
boolean -

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

reset()

Set the position to the starting state.

square(square) → {ColoredPiece|Empty}

Get the content of a square.

Parameters:
Name Type Description
square Square
Returns:
ColoredPiece | Empty

square(square, value)

Set the content of a square.

Parameters:
Name Type Description
square Square
value ColoredPiece | Empty

turn(value)

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

Parameters:
Name Type Description
value Color

turn() → {Color}

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

Returns:
Color