CQLi fully supports several popular chess variants including those supported by lichess.org and FICS. Within PGN files, variants are identified by the Variant tag. The supported variants and corresponding tag values recognized are provided in the table below.
| Variant Name | Brief Description | Recognized Aliases |
|---|---|---|
| Atomic | Captures cause explosions that destroy surrounding pieces. | Atom, Atomic, Atomic Chess |
| Chess960 | Random setup of backrank pieces. | Chess960, Fischerandom |
| Crazyhouse | Captured pieces change color and may be dropped on later moves. | Crazyhouse, Crazy House, House, ZH |
| Giveaway | Lose all pieces or get stalemated to win. Captures are compulsory. | Antichess, Giveaway, Give away, Giveaway Chess, Give away chess |
| Horde | White has 36 pawns and wins `Hor by checkmating Black before all white pawns are captured. | de,Horde Chess` |
| King of the Hill | Like standard chess but a king that makes it to a center square immediately wins the game. | King of the Hill, kingOfTheHill, KOTH |
| Losers | Lose all pieces except the king, get checkmated, or get stalemated to win. Captures are compulsory. | Losers |
| Racing Kings | There are no pawns. White and black pieces start on the first two ranks. Win by getting your king to the last rank first. Moves that would result in check are forbidden. | Race, Racing, RacingKings, Racing Kings |
| Standard | Standard chess. | Chess, Classical, Normal, Standard |
| Suicide | Lose all pieces to win. Captures are compulsory. | Suicide, Suicide Chess |
| Three-Check | Like standard chess but giving three checks to the opponent also wins the game. | Three-Check, Three Check, ThreeCheck, Three Check Chess, 3-Check, 3 Check |
Games that contain a Variant tag with a value corresponding to a recognized alias above are automatically handled as a game of that variant. Aliases are case-insensitive, e.g. zh and crazyhouse are both acceptable values to denote a Crazyhouse chess game. New aliases can be defined using the –variantalias option. Games containing a Variant tag that CQLi does not recognize may be skipped using the –skipunknownvariants option.
Chess960 Support
Chess960 semantics are implicitly supported for all variants, including Standard. In particular, the FEN tag may be used to specify a starting position using X-FEN notation to express castling rights regardless of variant.
Filters Supporting Variants
Many of the supported variants change the winning, losing, and/or drawing conditions. For example, King of the Hill introduces an alternate winning condition (getting a king to the center of the board) and stalemate is a win for the stalemated side in the Giveaway variant. In addition to the variant filter used to identify variants, CQLi includes several filters that can be used to query these variant-specific conditions.
The variant Filter
The variant filter yields a Boolean value indicating whether the current game is a non-standard variant. A game is considered to be a variant if the Variant PGN tag is provided and contains a value other than the values shown in the previous table that correspond to Standard.
When used as an argument to the str, comment, or message filters, the result is a string containing the canonical name of the variant which is either one of the names in the Variant Name column in the previous table or unknown if a Variant PGN tag was provided with an unrecognized value. The canonical name of a non-variant game is Standard. To obtain a string with the Boolean value of the variant filter when used as an argument to str, comment, or message, surround the variant filter with parentheses or braces.
The variantwin Filter
This filter yields a Boolean value indicating whether a variant-specific winning condition has been met for the current side to move. This filter always yields false for Standard chess and the Chess960, Crazyhouse, and Horde variants as these variants do not define new winning conditions (Horde defines a new losing condition where White loses if all of their pieces are captured). The table below lists the conditions under which variantwin will yield true in other variants.
| Variant | Winning Condition |
|---|---|
| Atomic | The side to move has a king on the board but the opposite side does not (presumably having been destroyed in the explosion accompanying an atomic capture). |
| Giveaway | No moves are available for the current side to move (either because of stalemate or because the player has no pieces or pawns remaining on the board). |
| King of the Hill | The current side-to-move’s king resides on d4, d5, e4, or e5. |
| Losers | The current side to move only has a king or is checkmated. |
| Racing Kings | The current side-to-move’s king resides on rank 8 and the opponent’s king does not. |
| Suicide | The current side to move has no pieces or pawns or is stalemated with fewer pieces or pawns than the opponent. |
| Three-Check | The current side to move has delivered check to the opposing king the prescribed number of times (default is 3). |
Note that the conditions under which variantwin is true for Atomic, King of the Hill, and Three-Check do not occur under normal circumstances as the game ends after the winning condition has been met so the terminal position will be the opposite side to move. For the Racing Kings variant, if the white king makes it to rank 8 first, Black gets one chance to draw by getting their king to the back rank, otherwise White wins after Black’s move in which case variantwin will then be true.
The variantloss Filter
This filter yields a Boolean value indicating whether a variant-specific winning condition has been met for the opposite side to move. This filter always yields true if the current side to move has no pieces or pawns, otherwise this filter always yields false for Standard chess and the Chess960 and Crazyhouse variants. The table below lists the conditions under which variantloss will yield true in other variants.
| Variant | Losing Condition |
|---|---|
| Atomic | The side to move has no king on the board but the opposite side does. |
| Giveaway | The opposite side to move has no pieces. |
| King of the Hill | The opposite side-to-move’s king resides on d4, d5, e4, or e5. |
| Losers | The opposite side to move only has a king. |
| Racing Kings | The black king resides on rank 8 and the current side to move is White. |
| Suicide | The opposite side to move has no pieces or pawns or the current side to move stalemated with more pieces or pawns than the opponent. |
| Three-Check | The opposite side to move has delivered check to the opposing king the prescribed number of times (default is 3). |
The situation for which variantloss will return true for the Giveaway or Losers does not occur under normal circumstances as the opposite side will have already won on the previous move ending the game.
The variantdraw Filter
This filter yields a Boolean value indicating whether a variant-specific drawing condition has been met. This filter yields false except in the following situations:
Both kings reside on rank 8 in the Racing Kings variant. This can occur when the black king reaches rank 8 immediately following the white king reaching rank 8.
Both kings have been exposed to check the prescribed number of times to warrant a win. This never happens under normal circumstances.
The current side to move is stalemated with the same number of pieces/pawns as the opponent in a Suicide game.
The variantend Filter
This filter yields true if the game is over due to a variant-specific condition. Note that checkmate and stalemate are not considered to be variant-specific ending conditions even though e.g. stalemate may be considered a variant win for the stalemated side in certain variants. In other words, variantend is not equivalent to variantwin or variantloss or variantdraw. The variantend filter always yields true if the current side to move has no pieces or pawns on the board. Other situations for which this filter will yield true are provided in the below table.
| Variant | End Condition |
|---|---|
| Atomic | One or both sides has no king. |
| Giveaway | At least one side has no pieces/pawns. |
| King of the Hill | There is a king on one of the center squares (d4, d5, e4, or e5). |
| Losers | At least one side has only a king. |
| Racing Kings | The black king resides on rank 8 or it is White to move and the white king resides on rank 8. |
| Suicide | At least one side has no pieces/pawns. |
| Three-Check | At least one side has delivered check to the opposing king the prescribed number of times. |
Behavior of check, mate, and stalemate with Variants
The check filter will only yield true when there is exactly one royal king of the color of the current side to move on the board and it is under attack from an enemy piece, except when the king is adjacent to a non-promoted enemy king in the Atomic variant. A royal king is one that may be subjected to checks. Kings in all supported variants are royal except the kings in the Suicide and Giveaway variants. In the Atomic variant opposing kings may be adjacent to each other in which case neither is subjectable to check.
The mate filter yields a true value when check is true and there are no legal moves for the current side in the current position.
The stalemate filter will yield false if variantend would be true, such as when there are no pieces of the current color on the board.
Behavior of move with Variants
The move filter can be used to generate legal or pseudolegal moves when using the legal or pseudolegal parameters. The Giveaway, Losers, and Suicide variants have a compulsory capture rule requiring that a capture move be made if one is legal. In such cases only capture moves will be generated when using either the legal or pseudolegal parameters. In the Racing Kings variant moves that place either king in check are illegal and such moves will not be generated even when pseudolegal is used.
To support the Crazyhouse variant, the move filter accepts a drop parameter followed by a piece type designator indicating the type of piece being dropped. For example, move to . legal drop R will yield the set of squares for which a previously captured rook may legally be dropped in the current position.
Using pin with Variants
The behavior of the pin filter does not change with variants. While kings in the Suicide variant have no special powers and are not subject to check, the pin filter will still report pieces as being pinned to the king. In the Atomic variant, pieces are not subject to absolute pins when the two kings are adjacent. To accommodate this situation when using the pin filter, the additional check for king adjacency can be made using K attacks k, K attackedby k, or anydirection 1 K & k.
FEN Extensions for Variants
The Crazyhouse and Three-Check variants introduce state information needed to represent a given position that is not articulated by the standard FEN notation. CQLi supports commonly-used extensions to FEN to represent this information as described in the following sections.
Crazyhouse FEN Extensions
There are several different methods used by popular chess software to encode the pocket piece and promoted piece information in a FEN tag. The methods supported by CQLi are described below.
Rank Zero
The piece-placement field is suffixed with an extra slash (/) followed by a list of pocket pieces. Promoted pieces in the piece-placement field are suffixed with a tilde (~). An example of the Rank Zero format is:
rnbq2nQ~/ppppk2p/5p1B/8/8/1P6/P1P1PPPP/q~N1QKBNR/PBRr w K - 1 8
Bracketed
The piece-placement field is suffixed by a square-bracket enclosed list of pocket pieces and promoted pieces in the piece-placement field are suffixed with a tilde (~). An example of the Bracketed format is:
rnbq2nQ~/ppppk2p/5p1B/8/8/1P6/P1P1PPPP/q~N1QKBNR[PBRr] w K - 1 8
Appended
Two new fields are added to the end of the FEN string. The first field is the list of pocket pieces. The second field is a list of squares upon which promoted pieces reside. An example of the Appended format is:
rnbq2nQ/ppppk2p/5p1B/8/8/1P6/P1P1PPPP/qN1QKBNR w K - 1 8 PBRr a1h8
Three-Check FEN Extensions
There are two common methods used to track the number of checks needed to win in the Three-Check variant, both of which are supported by CQLi.
Checks Given
The number of checks given by each side is provided in +W+B format in a new field following the full move number. W and B correspond to the number of checks that have been delivered by White and Black, respectively. CQLi assumes that a total of three checks is required to meet the variant-specific winning condition when this format is used. An example of the Checks Given format is:
5k2/p7/1p6/3B2P1/3P1rp1/b1P2P2/P5K1/7R w - - 4 34 +2+0
Checks Remaining
The number of checks remaining for each side to reach the variant-specific winning condition is provided in W+B format in a new field between the en passant square indicator and the halfmove counter. W and B are each single digits between 0 and 9 that represent the number of checks remaining to be delivered before meeting the variant-specific winning condition by White and Black, respectively. The advantage of this format is that it can support variants where an alternate number of checks are needed to win. An example of the Checks Remaining format is:
5k2/p7/1p6/3B2P1/3P1rp1/b1P2P2/P5K1/7R w - - 1+3 4 34