Position()

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

This constructor can be invoked with different types of arguments:

new kokopu.Position('regular');                 // 1 -> Usual starting position.
new kokopu.Position('regular', 'start');        // 2 -> Same as 1.
new kokopu.Position('regular', 'empty');        // 3 -> Empty board.
new kokopu.Position('chess960', 'empty');       // 4 -> Empty board, configured for Chess 960.
new kokopu.Position('chess960', scharnaglCode); // 5 -> One of the Chess 960 starting position (`scharnaglCode` is a number between 0 and 959 inclusive).
new kokopu.Position('regular', fenString);      // 6 -> Parse the given FEN string.
new kokopu.Position('chess960', fenString);     // 7 -> Parse the given FEN or X-FEN string, and configure for Chess 960.
new kokopu.Position(anotherPosition);           // 8 -> Make a copy of `anotherPosition`.

Please note that the argument 'regular' can be omitted in cases 1, 2, 3 and 6. In particular, the constructor can be invoked with no argument: in this case, a new Position initialized to the usual starting position is instantiated (as in cases 1 and 2).

Throws:

If the input parameter is not a valid FEN string (can be thrown only in cases 6 and 7).

Type
module:exception.InvalidFEN
See:

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

Must be Castle if the Position is configured for the regular chess rules, and Castle960 for chess 960.

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

Must be Castle if the Position is configured for the regular chess rules, and Castle960 for chess 960.

Returns:
boolean

clear(variantopt)

Set the position to the empty state.

Parameters:
Name Type Attributes Default Description
variant GameVariant <optional>
`'regular'`

Chess game variant to use.

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

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

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|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 function that returns a MoveDescriptor otherwise. When there is only one possible move between the given squares from and to (i.e. in most cases), this function must be invoked with no argument. When there is a "move ambiguity" (i.e. squares from and to are not sufficient to fully describe a move), an argument must be passed to the this function in order to discriminate between the possible moves. A field status is added to the function in order to indicate whether there is a move ambiguity or not.

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 {
  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;

    case 'castle960':
      // The move "from -> to" is legal, but it corresponds either to a castling move
      // or to a regular king move (this case can only happen at Chess 960).
      // The corresponding move descriptors are `result('castle')` and `result('king')`.
      break;

    default:
      // This case is not supposed to happen.
      break;
  }
}
Parameters:
Name Type Description
from Square
to Square
Returns:
boolean | 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(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

notation(moveDescriptor) → {string}

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

Parameters:
Name Type Description
moveDescriptor MoveDescriptor
Returns:
string

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.

reset960(scharnaglCode)

Set the position to one of the Chess 960 starting position.

Parameters:
Name Type Description
scharnaglCode number

Must be between 0 and 959 inclusive (see https://chess960.net/start-positions/ or https://chessprogramming.wikispaces.com/Reinhard+Scharnagl for more details).

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

variant() → {GameVariant}

Get the GameVariant in use.

Returns:
GameVariant