Chess Engine Features

A powerful and flexible chess engine supporting classic and custom variants, move validation, full history, and Chess960.

Features

- Accepts moves in algebraic notation
- Lists valid moves in algebraic notation
- Fuzzy algebraic notation parsing
- En Passant validation
- 3-fold and 5-fold repetition detection
- 50-move and 75-move rule detection
- Dead position detection
- Stalemate detection
- Check detection
- Checkmate detection
- Supports resignations
- Flag (timeout) detection
- Forfait (technical loss)
- Draw offers and acceptance
- Undo and redo moves
- Full event log of all actions
- Full FEN support
- PGN support
- Custom board sizes
- Custom pieces with unique moves
- Custom castling rules
- Chess960 (Fischer Random Chess) support
- Fairy/variant chess support
- Generates valid moves for any custom piece, supporting leapers, riders, and hoppers
- ASCII visualizations of board, position, moves, and reachability
- Works in both Node.js and browser environments

``js import { Game } from "xchess2"

// Create a new game with the standard board const game = new Game();

// Setup position game.position.setup(); // Play game game.play();

game.on('check', () => console.log('Check!')); game.on('gameover', () => console.log(game.reason));

// Make moves in algebraic notation game.move("e4"); game.move("e5");`

`Work with a custom board and custom pieces`

`js import { Game } from "xchess2"

const game = new Game({board: [10, 8], bestiary: ["chess", "princess"]});

// FEN position game.fen = 'rnbsqksbrn/pppppppppp/10/10/10/10/PPPPPPPPPP/RNBSQKSBNR w KQkq - 0 1';

// Show position game.on('state', () => console.log(game.position.text()))

game.play();

game.move("a3");

// Get the full event log of the game for(const state of game.moveLog()) console.log(state.toSAN());

// Generate FEN and PGN console.log(game.fen); console.log(game.toPGN());`

`Example of a custom piece class — Elephant`

`js import { Game, Piece, moves, hits} from "xchess2"

class Elephant extends Piece { static id = "elephant"; // Unique identifier of the piece static whiteFen = "E"; // Symbol in FEN for the white piece static blackFen = "e"; // Symbol in FEN for the black piece static moveLetter = "E"; // Letter used in algebraic notation static whiteSign = "🐘"; // Unicode symbol for white Elephant static blackSign = "🦏"; // Unicode symbol for black Elephant static code = 6; // Internal code for the engine

// Method to generate legal moves (customizable) moves(state, from){ return moves.A(from, this, state.position); }

// Check attacks (customizable) attacks(position, from, to){ return hits.A(from, to); } }

// Using the custom piece in a game const customGame = new Game({ board: [10, 8], bestiary: ['chess', Elephant] });

game.fen = 'renbqkbner/pppppppppp/10/10/10/10/PPPPPPPPPP/RENBQKBNER w KQkq - 0 1';

// Place Elephant on a1 and make a move game.position.set("a1", "E"); pos.move("a3");

// Check FEN after the move console.log(pos.fen);`

`Table of Contents`

`Game`

Game is the main class representing a chess game. It manages the game state, move history, and gameplay logic.

`$3`

- Setup Mode (game.isSetup = true): - The game is in edit mode immediately after creation. - You can freely modify the position, castling rights, and other parameters. - Move history does not exist, and methods related to gameplay or history navigation are unavailable.

- Game Mode (game.isSetup = false): - Activated by callinggame.play(). - The game cannot return to setup mode once started. - Manual editing of game parameters is not allowed; all state changes are determined by game logic. - You can trigger game events or navigate the move history. - The current game cursor (game.current) points to a specific position in the event chain.

`Game.is(value)`


Checks if the given

value is a Game

 instance.
$3

-

value (any

): The value to check.
$3

-

boolean: true if value is a Game instance, otherwise false

.
Game.from(value)

Creates a

Game instance from the given value.

If value is already a Gameinstance, it is returned as-is. Otherwise, a newGame is created using new Game(value).

`$3`

value (Game | string | object

):  
  The source to create the game from:
  -

Game

: returned directly.
  -

string

: a FEN string representing a board position.
  -

object

: a set of game parameters (e.g., initial position, options).
$3

-

Game: the existing game (if value was a Game

) or a new game created from the value.
new Game(config)
Creating a New Game

A new game is created using the Game constructor with a config parameter.

The config parameter can be:

- A string — a FEN string representing the starting position. - An object — with detailed configuration options. - An instance ofGame— another game object. In this case, the constructor creates a clone of the current state of that game in editing mode. Unlike a full copy, it does not duplicate the move history, but only transfers the current board state and related parameters.

`$3`

- Board instance (Board) - Object{ width, height }- Array[width, height]See:Board.from(value)

`$3`

- Bestiary instance (Bestiary) - Identifier of a built-in piece class or bestiary - Piece subclass (custom piece class) - Iterator of any of the above See:Bestiary.from(value)

`$3`

- Iterator of key-value string pairs - Object of tags

`$3`

- EngineRules subclass instance See:EngineRules

`$3`

- FEN string of the starting position - Position instance (Position) - Iterator of[square, piece]pairs - An object in the form{a1: 'Q', ...}where keys are square names and values are pieces See: new Position(game, position)

`$3`

- String values: 'white', 'black', 'w', 'b'- Numeric codes:0 (white), 1(black) - Color instance:Color.white, Color.blackSee: Color.from(value)

`$3`

- null- String — square name - Number — square ID - Square instance (Square) See: board.get(value)

`$3`


- Positive integer
$3

- Non-negative integer
$3

- Boolean flags for castling rights
- Ignored if

config.castling

 is provided
$3

- String — FEN castling rights
- Castling or SetupCastling instance
- Object

{ wk, wq, bk, bq }


- Iterator of custom castlings, where each castling can be:
  - Array of squares

[kingFrom, kingTo, rookFrom, rookTo]


  - Object of squares

{ kingFrom, kingTo, rookFrom, rookTo }

  
See: SetupCastling.from(game, value)
Notes:

- Immediately after creation, the game is in setup mode (game.isSetup = true). - No move history exists at this point. - You can freely edit the position, castling rights, and other parameters before starting the game. - To start the game, callgame.play(). - Once the game is started, it is impossible to return to setup mode. - In game mode, all state changes are governed by game logic, and manual editing of parameters is disabled.

`game.board`

- Represents the chessboard of the game. - Instance ofBoard. - Provides access to squares, files, ranks, and board dimensions. - Usegame.board.at(x, y) or game.board.get(value)to access individual squares. - See: Board

`game.bestiary`

- Contains the pieces used in the game. - Instance ofBestiary. - Defines piece types, promotions, and custom piece rules. - You can check if a piece type is supported or get a random piece of a given color. - See: Bestiary

`game.rules`

- Holds the rules engine for the game. - Instance ofRuleEngineor subclass. - Determines valid moves, checks, repetitions, dead positions, and game results. - Provides methods likerules.moves(state) or rules.repetitionCount(state). - See: RuleEngine

`game.tags`

- Stores game metadata (e.g., players, event, date). - Can be an object of key-value pairs or an iterator of string pairs. - Example:{ White: "Alice", Black: "Bob", Event: "Friendly Match" }

`game.current`

- Represents the current event in the game. - Points to the event at the current position of the game cursor in the event chain. - Used for navigating, inspecting, or applying moves relative to the current game state. - In game mode, it always points to a specific event, allowing methods likegame.goEvent(offset) or game.gotoEvent(eventID) to navigate the history.

`game.first`

- Represents the first event in the game history. - Useful for rewinding or iterating from the beginning of the game. - In setup mode,game.first is nullbecause no events exist yet. - In game mode, it always points to the very first move or event played.

`game.last`

- Represents the last event in the game history. - Useful for checking the most recent move or appending new events. - In setup mode,game.last is nullsince no moves have been made. - In game mode, it points to the latest event in the event chain.

`game.time`

- Represents the timestamp or sequence number of the current event in the game. - Indicates the chronological order of events. - In setup mode,game.time is typically nullbecause no events have occurred. - In game mode, it updates automatically as new moves or events are applied. - Can be used to compare the relative timing of events or for logging purposes.

`game.prevEvent`

- Represents the previous event relative to the current position (game.current) in the event chain. - Returnsnull if game.currentis the first event or if in setup mode. - Useful for navigating backward in the game's history or undoing moves.

`game.nextEvent`

- Represents the next event relative to the current position (game.current) in the event chain. - Returnsnull if game.currentis the last event or if in setup mode. - Useful for navigating forward in the game's history or redoing moves.

`game.eventID`

- Unique identifier of the current event (game.current) in the event chain. - Can be used to reference, navigate to, or log specific events. - In setup mode, usuallynull because no events exist yet.

`game.status`

- Represents the status of the current event (game.current) as a string. - Indicates the type or phase of the event, e.g.,'move', 'promotion', 'draw-offer', 'gameover'. - Useful for identifying what kind of action or outcome the current event represents. - In setup mode,game.status is usually 'setup'.

`game.state`

- Represents the current state of the game at the event pointed to by game.current. - Includes all relevant parameters: position, active color, castling rights, en passant, move counters, etc. - In setup mode, reflects the manually configured setup. - In game mode, reflects the state determined by game logic and event history.

`game.ply`

- Represents the last completed ply (half-move) or the initial game state corresponding to the current event (game.current). - Provides the reference point for the game state at that moment. - Returnsnullin setup mode, because no moves have been made yet. - Useful for inspecting the state of the board, move history, or for performing navigations relative to completed plies.

`game.result`

- Instance of the Result class representing the outcome of the game for the current event (game.current). - Contains: -reason— the reason the game ended (e.g., checkmate, resignation, draw). -winner — color of the winning side (Color.white or Color.black), if applicable. -loser— color of the losing side, if applicable. -pgn— PGN string representing the game conclusion. - If the game is not finished,game.result contains a placeholder object NoResult. - Updated automatically based on game logic and event outcomes.

`game.prev`

- Represents the previous ply event relative to game.current. - Returnsnullif the current event is the first in the history or if in setup mode. - Useful for navigating backward through the sequence of completed plies in the game.

`game.next`

- Represents the next ply event relative to game.current. - Returnsnullif the current event is the last in the history or if in setup mode. - Useful for navigating forward through the sequence of completed plies in the game.

`game.plyID`

- Unique identifier of the current ply (half-move) in the game. - Starts at0for the initial game position. - Corresponds to the ply associated withgame.current. - Useful for navigating to a specific ply using methods likegame.goto(plyID) or game.go(offset). - In setup mode,game.plyID is null because no moves have been made yet.

`game.drawOffer`

- Instance of the Colorclass representing the player who offered a draw. - Updated when a draw is proposed usinggame.draw(color). - Returnsnullif no draw offer has been made after the last move. - Useful for checking if a draw offer is currently active and which player made it.

`game.fen`

- Represents the FEN string of the current game state. - Automatically updated as moves are applied or the position changes. - Can be extended in the following cases: 1. The board is not 8×8. 2. The bestiary contains additional custom pieces. 3. Custom castlings are added viagame.castling.add(...). - In setup mode, the property is writable, allowing you to set the position manually:`js game.fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";`- In game mode, it reflects the position determined by game logic and move history and is read-only. - Useful for exporting, saving, or analyzing the current board state.

`game.color`

- Instance of the Colorclass representing the active color (the side to move next). - Indicates which player's turn it is in the current game state. - In setup mode, the property is writable: - Can be set using string values:'white', 'black', 'w', 'b'. - Can be set using numeric codes:0 (white) or 1(black). - Can be set using Color instances:Color.white or Color.black. - In game mode, the value is determined automatically by game logic and is read-only. - Useful for configuring the initial turn or inspecting whose move it is.

`game.position`

- Represents the current board position in the game. - Returns different objects depending on the mode: - Setup mode: returns a SetupPosition instance (writable, editable). - Game mode: returns a Position instance (immutable, read-only). - In setup mode, the property is writable and supports all variants of assigning a position: - FEN string - Position object - Object of square-piece pairs, e.g.,{ a1: 'Q', b1: 'N', ... }- Iterator of[square, piece]pairs - AnotherPosition or SetupPositioninstance - In game mode, the position is determined by game logic and the history of events, and cannot be manually changed. - Useful for configuring, inspecting, or exporting the current board state.

`$3`

`js // 1. Using a FEN string game.position = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR";

// 2. Using an object of square-piece pairs game.position = { a1: 'R', b1: 'N', c1: 'B', d1: 'Q', e1: 'K', f1: 'B', g1: 'N', h1: 'R', a2: 'P', b2: 'P', c2: 'P', d2: 'P', e2: 'P', f2: 'P', g2: 'P', h2: 'P' };

// 3. Using an iterator of [square, piece] pairs game.position = [ ['a1', 'R'], ['b1', 'N'], ['c1', 'B'], ['d1', 'Q'], ['e1', 'K'], ['f1', 'B'], ['g1', 'N'], ['h1', 'R'] ];

// 4. Using another Position or SetupPosition instance const game2 = new Game("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"); game.position = game2.position;

// Output the current position to the console console.log(game.position.text());`

`game.castling`

- Represents the current castling rights in the game. - Returns a Castling or SetupCastling instance depending on the mode: - Setup mode: writable, allows adding, modifying, or clearing castling rights. - Game mode: read-only, determined by the position and game history. - Supports multiple ways to assign castling rights in setup mode: 1. FEN string (e.g.,"KQkq"for standard castling rights). 2. Object of flags{ wk, wq, bk, bq }. 3. Castling / SetupCastling instance with custom castling definitions. 4. Iterator of custom castling moves, each defined as an array[kingFrom, kingTo, rookFrom, rookTo]. - Useful for configuring the initial castling rights or inspecting the current castling possibilities.

`$3`

`js // 1. Using a FEN string for castling rights game.castling = "KQkq";

// 2. Using an object of castling flags game.castling = { wk: true, wq: true, bk: true, bq: true };

// 3. Using a Castling game.castling.add('e1', 'g1', 'h1', 'f1'); // custom white kingside game.castling.add('e8', 'c8', 'a8', 'd8'); // custom black queenside

// 4. Using an iterator of custom castlings game.castling = [ ['e1', 'g1', 'h1', 'f1'], // white kingside ['e8', 'c8', 'a8', 'd8'] // black queenside ];

// Output current castling configuration console.log(game.castling.toArray());`

`game.enPassant`

- Represents the en passant target square in the current game state. - Returns aSquare instance, or nullif no en passant target exists. - In setup mode, the property is writable and supports multiple ways to assign a square: -null— no en passant target. - String square name, e.g.,'e6'. - Numeric square ID. - Square instance from the board, e.g.,board.get('e6'). - In game mode, the value is determined automatically by the game logic based on the last move and is read-only. - Useful for determining whether an en passant capture is possible.

`game.fullmoveNumber`

- Represents the fullmove number of the game (counts complete turns, i.e., pairs of White and Black moves). - Starts at1for the initial position. - In setup mode, the property is writable, allowing manual configuration. - In game mode, automatically updated by the game logic after each move. - Useful for PGN export and move tracking.

`game.halfmoveClock`

- Represents the halfmove clock used for the fifty-move rule. - Counts the number of half-moves (plies) since the last pawn advance or capture. - Starts at0for the initial position. - In setup mode, the property is writable for manual configuration. - In game mode, automatically updated by the game logic. - Useful for enforcing the fifty-move draw rule and analyzing game state.

`game.wk`


game.wq

game.bk

game.bq

- Shorthand properties for individual castling rights: -game.wk— White kingside castling -game.wq— White queenside castling -game.bk— Black kingside castling -game.bq— Black queenside castling - In setup mode, all these properties are writable, allowing manual configuration of castling rights. - In game mode, they are read-only and reflect the castling possibilities determined by the game state. - Internally, they map directly togame.castling.wk, game.castling.wq, game.castling.bk, and game.castling.bq. - Useful for quickly reading or modifying individual castling permissions without interacting with the fullgame.castling object.

`game.lastMove`

- Represents the last move played in the game as aMoveinstance. - Returnsnullin the following cases: - Setup mode, because no moves have been made. - At the initial game position, before any moves. - In game mode, updated automatically as moves are applied. - Useful for inspecting the most recent action, including its source and destination squares, captured pieces, promotion, or special move properties (castling, en passant, etc.).

`game.moves`

- Represents the list of legal moves available for the current player. - Returns a MoveList instance. - Always available, even if the list is empty (e.g., checkmate or stalemate). - In setup mode, not applicable; moves are determined only in game mode. - Useful for: - Displaying legal moves to the player. - AI or move selection. - Validating player input before applying a move.

`game.checkSquares`

- Returns an array of squares currently under check for the side to move. - Each element is a Square instance. - Empty array if the king is not under check. - Useful for highlighting threats or detecting checks programmatically.

`game.isCheck`

- Boolean indicating whether the current player is in check. - Returnstrue if game.checkSquares is non-empty, otherwise false. - Useful for enforcing rules that prevent illegal moves or for UI indicators.

`game.repetitionCount`

- Represents the number of times the current position has occurred in the game history. - Returns a positive integer starting from1. - Useful for detecting threefold (or fivefold) repetition draws and other repetition-based rules.

`game.isDeadPisition`

- Boolean indicating whether the current position is a dead position, i.e., a position where checkmate is impossible by any legal sequence of moves. - Useful for detecting automatic draws in scenarios like king vs. king or insufficient material.

`game.hash`

- Represents a BigInt hash of the current game state. - Includes in the hash calculation: - Board position - Castling rights - En passant target square - Active color (side to move) - Used primarily for implementing threefold and fivefold repetition rules. - Useful for efficiently detecting repeated positions without comparing entire board states.

`game.reason`

- Represents the reason for the game ending or the current game state. - Returns a string, one of the following values:

- 'no result'— game is ongoing or in setup mode -'checkmate'— game ended by checkmate -'forfeit'— game ended by forfeit -'resignation'— game ended by resignation -'win on time'— game ended due to time expiration -'stalemate'— game ended by stalemate -'dead position'— game ended because checkmate is impossible -'3-repetition'— draw by threefold repetition -'5-repetition'— draw by fivefold repetition -'50 moves'— draw by fifty-move rule -'75 moves'— draw by seventy-five-move rule -'draw by agreement'— draw agreed by players -'draw by resignation'— draw due to resignation of a player -'draw on time' — draw because both players’ time expired

`game.isSetup`

true if the game is in setup/edit mode; false

 in game mode.
game.isPromotion

-

true

 if the current move involves a promotion.
game.isState

-

true

 if the current event is a game state change rather than a player move.
game.isMeta

-

true

 if the current event is a meta event, like comment, NAG, or draw offer.
game.isPly

-

true

 if the current event represents a ply/move in the game.
game.canMove

- Boolean indicating whether moves can currently be made. - Returnsfalsein the following cases: - Setup mode (editing the game). - The current move is a promotion that has not been completed. - The game is finished (checkmate, draw, resignation, etc.). - Returnstrueonly in game mode when a move is legally allowed for the current player. - Useful for validating whether a player or AI can make a move at the current point in the game.

`game.canMeta`

- Boolean indicating whether meta events can currently be added. - Meta events are events that do not alter the core game state, such as: - Comments - NAG (Numeric Annotation Glyphs) - Draw offers - Returnstruein setup mode or in game mode when the current event allows meta actions. - Returnsfalseif the current event or game state does not allow meta events, e.g., during an incomplete promotion or after game over. - Useful for determining whether you can attach annotations or auxiliary events at the current point in the game history.

`game.isIrreversible`

- Boolean indicating whether the current event irreversibly changes the game state. - Returnstruefor moves that cannot be undone without altering game history, such as: - Pawn advances - Captures - The initial game state is also considered irreversible. - Used internally for enforcing rules such as: - Threefold/fivefold repetition - Fifty-move and seventy-five-move rules - Returnsfalse for meta events or reversible moves that do not affect these rules.

`game.isGameOver`

true

 if the game has finished (checkmate, draw, resignation, etc.).
game.isWin

-

true

 if the game ended with a win for one of the players.
game.isDraw

-

true

 if the game ended in a draw for any reason.
game.isCheckmate

-

true

 if the current player is checkmated.
game.isStalemate

-

true

 if the current position is a stalemate.
game.winner

- Returns the Color of the winning player, or

null

 if the game is not finished or ended in a draw.
game.loser

- Returns the Color of the losing player, or

null

 if the game is not finished or ended in a draw.
game.stats()

- Returns a simple object containing various statistics of the game
game.traceMoves(square, piece)

Returns a map of reachable squares and the minimum number of moves required to reach them.
$3

-

square (Square

):  
  The starting square for the calculation.  
-

piece? (Piece

, optional):  
  If provided, the calculation assumes the given piece is standing on the specified square, regardless of the actual board state.  
  If omitted, the method uses the piece currently occupying the square (if any).  
$3

- The search is performed based on the current board state, including the positions of all pieces.  
- The starting square itself is excluded from the results.  
- The turn order (which side is to move) is ignored.  
$3

Returns a TraceMap, which is like a

Map

 but specialized for board cells.  
- Keys must be

Squares

.
- Has an extra method

text(limit = Infinity)

 that renders the board as ASCII graphics:
  - Each cell is marked with the minimal number of moves required to reach it from

from

.  
  - The optional

limit

 parameter restricts how far (in moves) cells will be shown. For example:  
    -

text(1) shows only the start cell as 0 and all cells reachable in one move as 1

.  
    - By default,

text(Infinity)

 shows all reachable cells.
#### Examples

js
const trace = game.traceMoves('D4', 'N');
console.log(trace.text(1));

// a b c d e f g h // ┌───┬───┬───┬───┬───┬───┬───┬───┐ // 8 │ │ │ │ │ │ │ │ │ 8 // ├───┼───┼───┼───┼───┼───┼───┼───┤ // 7 │ │ │ │ │ │ │ │ │ 7 // ├───┼───┼───┼───┼───┼───┼───┼───┤ // 6 │ │ │ 1 │ │ 1 │ │ │ │ 6 // ├───┼───┼───┼───┼───┼───┼───┼───┤ // 5 │ │ 1 │ │ │ │ 1 │ │ │ 5 // ├───┼───┼───┼───┼───┼───┼───┼───┤ // 4 │ │ │ │ 0 │ │ │ │ │ 4 // ├───┼───┼───┼───┼───┼───┼───┼───┤ // 3 │ │ 1 │ │ │ │ 1 │ │ │ 3 // ├───┼───┼───┼───┼───┼───┼───┼───┤ // 2 │ │ │ 1 │ │ 1 │ │ │ │ 2 // ├───┼───┼───┼───┼───┼───┼───┼───┤ // 1 │ │ │ │ │ │ │ │ │ 1 // └───┴───┴───┴───┴───┴───┴───┴───┘ // a b c d e f g h`

`game.play()`

Starts the game execution. This method is irreversible: once the game is switched from setup mode to play mode, it cannot go back.

`$3`


  - On the first call, the game leaves setup mode and enters play mode.  
  - On repeated calls, the method does nothing and returns

false

.  
  - While entering play mode, the game validates and applies editing state options:

1. Castling flags (wk, wq, bk, bq): - The engine searches for a valid pair of pieces on the same rank: a "king" (isCastlingActor) and a "rook" (isCastlingPartner). - On an 8×8 board, final castling squares are determined according to Chess960 rules. - On non-standard boards, the king jumps two squares, and the rook is placed on the other side. - If no valid pair is found, the flag is ignored.

2. Custom castling rules (config.castling): - For each defined castling, the engine checks whether the required pieces are present on the specified squares. - If not, the castling option is ignored.

3. En passant square (enPassant): - The target square must be empty. - A pawn must exist in front of it in the correct position. - If conditions are not satisfied, the en passant option is ignored.

`$3`

true

 — if this is the first call (setup → play mode).  
  -

false

 — if the game was already in play mode.
game.move(query)
Performs a move in game mode if it is valid.  
Throws an error if the move is not allowed.
$3

- query  
  Can be one of:
  1. A string — the move in SAN format.  
  2. An existing Move object – will be matched against the moves in the list.
  3. A number representing the numeric move code, unique for the combination of start and end squares.
	4. An object — a move search template with possible properties:
     -

piece — piece type (e.g., "N", "Q"

, etc.)
     -

from

 — starting square
     -

 — destination square
     -

fromFile

 — originating file
     -

fromRank

 — originating rank
     -

promoteTo

 — piece type to promote to
     -

 — queenside castling indicator
     -

 — kingside castling indicator  
     > ⚠️ The list of properties may be extended for custom moves.
	5. If omitted, the call is only valid when there is exactly one legal move available.
$3

- If exactly one move matches the query, it is executed and returned.  
- If multiple moves match, an ambiguity error is thrown.  
- If no move matches, a not found error is thrown.  
- If the move requires promotion but no promotion piece is provided,  
  the game enters promotion state (

game.isPromotion = true

),  
  and expects a further call to:

js
  game.promote(piece)


$3

- The found move (instance of class Move) if the move is successfully executed.
$3

`js // Using a SAN string const move1 = game.move("e4");

// Using a search template object const move2 = game.move({ piece: "N", from: "g1", to: "f3" });

// Custom property example for extended moves const move3 = game.move({ piece: "P", from: "e7", to: "e8", promoteTo: "Q" });`

`game.promote(piece)`

Completes a pawn promotion move. This method can only be called while the game is in promotion state (game.isPromotion = true). Calling it outside this state will throw an error.

#### Parameters - piece — the piece to promote to. Can be one of: 1. An instance of Piece. 2. A string identifier of a piece type; the piece color will be determined automatically according togame.color.

> ⚠️ The chosen piece must be among those allowed for promotion (game.lastMove.promotes). > The color must match the current player's color; otherwise, an error is thrown.

`$3`


- Completes the promotion move.  
- Updates the game state accordingly.  
- Exits promotion state (

game.isPromotion = false

).
$3

- The completed Move object representing the promotion.
$3

`js // Assuming the game is in promotion state after moving a pawn to the last rank game.isPromotion; // true

// Promoting by piece instance const queenPiece = game.bestiary.from("Q", game.color); const move = game.promote(queenPiece);

// Promoting by piece identifier string const move2 = game.promote("Q");

// After promotion, promotion state ends game.isPromotion; // false`

`game.forfeit(color)`

Forfeits the game for the specified player. This method can only be called in game mode.

`$3`


- color — the color of the player who wants to forfeit:  
  -

Color.white, Color.black

  
  - or any value accepted by Color.from(value)
$3

- Immediately ends the game.  
- Sets the winner to the opposite color.  
- Updates

game.result with the reason "forfeit"

.  
- Can be called at any point during play.  
$3

- The final

Result object

 representing the game's outcome.
game.resign(color)
Registers a resignation for the specified player.  
This method can only be called in game mode.  
$3

- color — the color of the player who resigns:  
  -

Color.white, Color.black

  
  - or any value accepted by Color.from(value)
$3

- Ends the game immediately.  
- Sets the winner to the opposite color.  
- Updates

game.result with the reason "resignation" or "draw by resignation"

.  
- Can be called at any point during play.
game.flagFall()
Registers a time forfeit (flag fall) for the current player.  
This method can only be called in game mode.  
$3

- Ends the game immediately.  
- Sets the winner to the opposite color of the player whose time ran out.  
- Updates

game.result with the reason "win on time" or "draw on time"

 depending on the rules.  
- Can be called at any point during play.
game.draw(color)
Offers or enforces a draw in the game, depending on the context.  
This method can only be called in game mode.  
$3

- color — the color of the player proposing the draw:  
  -

Color.white, Color.black

  
  - or any value accepted by Color.from(value)
$3

- Immediate draw occurs if any of the following conditions are met:
  1. The opposite player already proposed a draw (

game.drawOffer

 is set to the opposite color) after the last move.  
  2. A draw is allowed according to the 50-move rule.  
  3. A draw is allowed according to the threefold repetition rule.

- Otherwise, a DrawOffer event is added to the game history: -game.drawOfferis set to the color of the player who proposed the draw. - The offer remains active until the next move or until the method is called again by another color.

`game.nag(value)`

Adds a Numeric Annotation Glyph (NAG) to the current move in the game. This method can only be called in game mode.

#### Parameters - value — the NAG to add. Can be: - A number representing the NAG code - A string such as"!", "!!", "?", "!?", "??", etc.

#### Behavior - Attaches the NAG to the current move (game.current). - Can be used to annotate the game with standard chess commentary symbols.

`game.comment(comment)`

Adds a text comment to the current move in the game. This method can only be called in game mode.

`$3`


- comment — a string containing the text of the comment.
$3

- Attaches the comment to the current move (

game.current

).  
- Comments are preserved when exporting the game to PGN.  
game.undo()
Moves the game game.current to the previous completed ply.  
This method is used to navigate backward in game history.  
$3

- Returns to the previous ply state.  
- If the current state is a promotion, it returns to the last completed ply before the promotion (since promotion itself is not a full ply).  
- In edit mode or if the current ply is the first ply, the method does nothing.  
- Updates

game.current

 to reflect the new cursor position.  
$3

-

true

 if the undo successfully moved the cursor.  
-

false

 if no movement was possible (edit mode or first ply).
game.redo()
Moves the game game.current to the next completed ply.  
This method is used to navigate forward in game history.  
$3

- Advances to the next ply state.  
- In edit mode or if the current ply is the last ply, the method does nothing.  
- Updates

game.current

 to reflect the new cursor position. 
$3

-

true

 if the redo successfully moved the cursor.  
-

false

 if no movement was possible (edit mode or last ply).
game.go(offset)
Moves the game game.current by a specified number of completed plies.  
Used to jump forward or backward in game history.  
$3

- offset — a signed integer representing the number of plies to move:  
  - Positive: move forward  
  - Negative: move backward  
  -

: does not move
$3

- Moves the cursor by up to

offset plies

.  
- If the offset exceeds the available history, it stops at the first or last ply.  
- In edit mode or if

offset is 0

, the method does nothing.
- Updates

game.current

 to reflect the new cursor position.  
$3

-

true

 if the cursor moved.  
-

false

 if no movement was possible (edit mode, offset 0, or at the bounds of history).
game.goto(plyID)
Moves the game game.current to a specific ply by its ID.  
$3

- plyID — integer representing the target ply ID:  
  -

 — first ply  
  -

-1

 or any negative value — first ply  
  - Values greater than the last ply ID — moves to the last ply  
$3

- Sets

game.current

 to the specified ply.  
- If

plyID

 is out of bounds, clamps to the first or last ply.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if no movement was possible (edit mode or already at the target ply).
game.rewind()
Moves the game game.current back to the first ply (beginning of the game).  
$3

- Sets

game.current

 to the initial state.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the first ply or in edit mode.
game.end()
Moves the game game.current to the last event (most recent ply).  
$3

- Sets

game.current

 to the last completed move or event.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the last event or in edit mode.
game.undoEvent()
Moves the game game.current back by one event in the history chain.  
$3

- Advances to the previous event, regardless of ply boundaries.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the first event or in edit mode.
game.redoEvent()
Moves the game game.current forward by one event in the history chain.  
$3

- Advances to the next event, regardless of ply boundaries.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the last event or in edit mode.
game.goEvent(offset)
Moves the game game.current by a specified number of events in the history chain.  
$3

- offset — a signed integer representing the number of events to move:  
  - Positive: move forward  
  - Negative: move backward  
  -

: does not move
$3

- Moves the cursor by up to

offset events

.  
- If the offset exceeds the available events, it stops at the first or last event.  
- In edit mode or if

offset is 0

, the method does nothing.  
- Updates

game.current

 to reflect the new cursor position.  
$3

-

true

 if the cursor moved.  
-

false` if no movement was possible (edit mode, offset 0, or at the bounds of history).

game.gotoEvent(eventID)

Move

Chess Engine Features

A powerful and flexible chess engine supporting classic and custom variants, move validation, full history, and Chess960.

Features

``js import { Game } from "xchess2"

// Create a new game with the standard board const game = new Game();

// Setup position game.position.setup(); // Play game game.play();

game.on('check', () => console.log('Check!')); game.on('gameover', () => console.log(game.reason));

// Make moves in algebraic notation game.move("e4"); game.move("e5");`

`Work with a custom board and custom pieces`

`js import { Game } from "xchess2"

const game = new Game({board: [10, 8], bestiary: ["chess", "princess"]});

// FEN position game.fen = 'rnbsqksbrn/pppppppppp/10/10/10/10/PPPPPPPPPP/RNBSQKSBNR w KQkq - 0 1';

// Show position game.on('state', () => console.log(game.position.text()))

game.play();

game.move("a3");

// Get the full event log of the game for(const state of game.moveLog()) console.log(state.toSAN());

// Generate FEN and PGN console.log(game.fen); console.log(game.toPGN());`

`Example of a custom piece class — Elephant`

`js import { Game, Piece, moves, hits} from "xchess2"

// Method to generate legal moves (customizable) moves(state, from){ return moves.A(from, this, state.position); }

// Check attacks (customizable) attacks(position, from, to){ return hits.A(from, to); } }

// Using the custom piece in a game const customGame = new Game({ board: [10, 8], bestiary: ['chess', Elephant] });

game.fen = 'renbqkbner/pppppppppp/10/10/10/10/PPPPPPPPPP/RENBQKBNER w KQkq - 0 1';

// Place Elephant on a1 and make a move game.position.set("a1", "E"); pos.move("a3");

// Check FEN after the move console.log(pos.fen);`

`Table of Contents`

`Game`

Game is the main class representing a chess game. It manages the game state, move history, and gameplay logic.

`$3`

`Game.is(value)`


Checks if the given

value is a Game

 instance.
$3

-

value (any

): The value to check.
$3

-

boolean: true if value is a Game instance, otherwise false

.
Game.from(value)

Creates a

Game instance from the given value.

If value is already a Gameinstance, it is returned as-is. Otherwise, a newGame is created using new Game(value).

`$3`

value (Game | string | object

):  
  The source to create the game from:
  -

Game

: returned directly.
  -

string

: a FEN string representing a board position.
  -

object

: a set of game parameters (e.g., initial position, options).
$3

-

Game: the existing game (if value was a Game

) or a new game created from the value.
new Game(config)
Creating a New Game

A new game is created using the Game constructor with a config parameter.

The config parameter can be:

`$3`

- Board instance (Board) - Object{ width, height }- Array[width, height]See:Board.from(value)

`$3`

- Bestiary instance (Bestiary) - Identifier of a built-in piece class or bestiary - Piece subclass (custom piece class) - Iterator of any of the above See:Bestiary.from(value)

`$3`

- Iterator of key-value string pairs - Object of tags

`$3`

- EngineRules subclass instance See:EngineRules

`$3`

- String values: 'white', 'black', 'w', 'b'- Numeric codes:0 (white), 1(black) - Color instance:Color.white, Color.blackSee: Color.from(value)

`$3`

- null- String — square name - Number — square ID - Square instance (Square) See: board.get(value)

`$3`


- Positive integer
$3

- Non-negative integer
$3

- Boolean flags for castling rights
- Ignored if

config.castling

 is provided
$3

- String — FEN castling rights
- Castling or SetupCastling instance
- Object

{ wk, wq, bk, bq }


- Iterator of custom castlings, where each castling can be:
  - Array of squares

[kingFrom, kingTo, rookFrom, rookTo]


  - Object of squares

{ kingFrom, kingTo, rookFrom, rookTo }

  
See: SetupCastling.from(game, value)
Notes:

`game.board`

`game.bestiary`

`game.rules`

`game.tags`

- Stores game metadata (e.g., players, event, date). - Can be an object of key-value pairs or an iterator of string pairs. - Example:{ White: "Alice", Black: "Bob", Event: "Friendly Match" }

`game.current`

`game.first`

`game.last`

`game.time`

`game.prevEvent`

`game.nextEvent`

`game.eventID`

`game.status`

`game.state`

`game.ply`

`game.result`

`game.prev`

`game.next`

`game.plyID`

`game.drawOffer`

`game.fen`

`game.color`

`game.position`

`$3`

`js // 1. Using a FEN string game.position = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR";

// 3. Using an iterator of [square, piece] pairs game.position = [ ['a1', 'R'], ['b1', 'N'], ['c1', 'B'], ['d1', 'Q'], ['e1', 'K'], ['f1', 'B'], ['g1', 'N'], ['h1', 'R'] ];

// 4. Using another Position or SetupPosition instance const game2 = new Game("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"); game.position = game2.position;

// Output the current position to the console console.log(game.position.text());`

`game.castling`

`$3`

`js // 1. Using a FEN string for castling rights game.castling = "KQkq";

// 2. Using an object of castling flags game.castling = { wk: true, wq: true, bk: true, bq: true };

// 3. Using a Castling game.castling.add('e1', 'g1', 'h1', 'f1'); // custom white kingside game.castling.add('e8', 'c8', 'a8', 'd8'); // custom black queenside

// 4. Using an iterator of custom castlings game.castling = [ ['e1', 'g1', 'h1', 'f1'], // white kingside ['e8', 'c8', 'a8', 'd8'] // black queenside ];

// Output current castling configuration console.log(game.castling.toArray());`

`game.enPassant`

`game.fullmoveNumber`

`game.halfmoveClock`

`game.wk`


game.wq

game.bk

game.bq

`game.lastMove`

`game.moves`

`game.checkSquares`

`game.isCheck`

`game.repetitionCount`

`game.isDeadPisition`

`game.hash`

`game.reason`

- Represents the reason for the game ending or the current game state. - Returns a string, one of the following values:

`game.isSetup`

true if the game is in setup/edit mode; false

 in game mode.
game.isPromotion

-

true

 if the current move involves a promotion.
game.isState

-

true

 if the current event is a game state change rather than a player move.
game.isMeta

-

true

 if the current event is a meta event, like comment, NAG, or draw offer.
game.isPly

-

true

 if the current event represents a ply/move in the game.
game.canMove

`game.canMeta`

`game.isIrreversible`

`game.isGameOver`

true

 if the game has finished (checkmate, draw, resignation, etc.).
game.isWin

-

true

 if the game ended with a win for one of the players.
game.isDraw

-

true

 if the game ended in a draw for any reason.
game.isCheckmate

-

true

 if the current player is checkmated.
game.isStalemate

-

true

 if the current position is a stalemate.
game.winner

- Returns the Color of the winning player, or

null

 if the game is not finished or ended in a draw.
game.loser

- Returns the Color of the losing player, or

null

 if the game is not finished or ended in a draw.
game.stats()

- Returns a simple object containing various statistics of the game
game.traceMoves(square, piece)

Returns a map of reachable squares and the minimum number of moves required to reach them.
$3

-

square (Square

):  
  The starting square for the calculation.  
-

piece? (Piece

, optional):  
  If provided, the calculation assumes the given piece is standing on the specified square, regardless of the actual board state.  
  If omitted, the method uses the piece currently occupying the square (if any).  
$3

- The search is performed based on the current board state, including the positions of all pieces.  
- The starting square itself is excluded from the results.  
- The turn order (which side is to move) is ignored.  
$3

Returns a TraceMap, which is like a

Map

 but specialized for board cells.  
- Keys must be

Squares

.
- Has an extra method

text(limit = Infinity)

 that renders the board as ASCII graphics:
  - Each cell is marked with the minimal number of moves required to reach it from

from

.  
  - The optional

limit

 parameter restricts how far (in moves) cells will be shown. For example:  
    -

text(1) shows only the start cell as 0 and all cells reachable in one move as 1

.  
    - By default,

text(Infinity)

 shows all reachable cells.
#### Examples

js
const trace = game.traceMoves('D4', 'N');
console.log(trace.text(1));

`game.play()`

Starts the game execution. This method is irreversible: once the game is switched from setup mode to play mode, it cannot go back.

`$3`


  - On the first call, the game leaves setup mode and enters play mode.  
  - On repeated calls, the method does nothing and returns

false

.  
  - While entering play mode, the game validates and applies editing state options:

`$3`

true

 — if this is the first call (setup → play mode).  
  -

false

 — if the game was already in play mode.
game.move(query)
Performs a move in game mode if it is valid.  
Throws an error if the move is not allowed.
$3

- query  
  Can be one of:
  1. A string — the move in SAN format.  
  2. An existing Move object – will be matched against the moves in the list.
  3. A number representing the numeric move code, unique for the combination of start and end squares.
	4. An object — a move search template with possible properties:
     -

piece — piece type (e.g., "N", "Q"

, etc.)
     -

from

 — starting square
     -

 — destination square
     -

fromFile

 — originating file
     -

fromRank

 — originating rank
     -

promoteTo

 — piece type to promote to
     -

 — queenside castling indicator
     -

 — kingside castling indicator  
     > ⚠️ The list of properties may be extended for custom moves.
	5. If omitted, the call is only valid when there is exactly one legal move available.
$3

- If exactly one move matches the query, it is executed and returned.  
- If multiple moves match, an ambiguity error is thrown.  
- If no move matches, a not found error is thrown.  
- If the move requires promotion but no promotion piece is provided,  
  the game enters promotion state (

game.isPromotion = true

),  
  and expects a further call to:

js
  game.promote(piece)


$3

- The found move (instance of class Move) if the move is successfully executed.
$3

`js // Using a SAN string const move1 = game.move("e4");

// Using a search template object const move2 = game.move({ piece: "N", from: "g1", to: "f3" });

// Custom property example for extended moves const move3 = game.move({ piece: "P", from: "e7", to: "e8", promoteTo: "Q" });`

`game.promote(piece)`

Completes a pawn promotion move. This method can only be called while the game is in promotion state (game.isPromotion = true). Calling it outside this state will throw an error.

> ⚠️ The chosen piece must be among those allowed for promotion (game.lastMove.promotes). > The color must match the current player's color; otherwise, an error is thrown.

`$3`


- Completes the promotion move.  
- Updates the game state accordingly.  
- Exits promotion state (

game.isPromotion = false

).
$3

- The completed Move object representing the promotion.
$3

`js // Assuming the game is in promotion state after moving a pawn to the last rank game.isPromotion; // true

// Promoting by piece instance const queenPiece = game.bestiary.from("Q", game.color); const move = game.promote(queenPiece);

// Promoting by piece identifier string const move2 = game.promote("Q");

// After promotion, promotion state ends game.isPromotion; // false`

`game.forfeit(color)`

Forfeits the game for the specified player. This method can only be called in game mode.

`$3`


- color — the color of the player who wants to forfeit:  
  -

Color.white, Color.black

  
  - or any value accepted by Color.from(value)
$3

- Immediately ends the game.  
- Sets the winner to the opposite color.  
- Updates

game.result with the reason "forfeit"

.  
- Can be called at any point during play.  
$3

- The final

Result object

 representing the game's outcome.
game.resign(color)
Registers a resignation for the specified player.  
This method can only be called in game mode.  
$3

- color — the color of the player who resigns:  
  -

Color.white, Color.black

  
  - or any value accepted by Color.from(value)
$3

- Ends the game immediately.  
- Sets the winner to the opposite color.  
- Updates

game.result with the reason "resignation" or "draw by resignation"

.  
- Can be called at any point during play.
game.flagFall()
Registers a time forfeit (flag fall) for the current player.  
This method can only be called in game mode.  
$3

- Ends the game immediately.  
- Sets the winner to the opposite color of the player whose time ran out.  
- Updates

game.result with the reason "win on time" or "draw on time"

 depending on the rules.  
- Can be called at any point during play.
game.draw(color)
Offers or enforces a draw in the game, depending on the context.  
This method can only be called in game mode.  
$3

- color — the color of the player proposing the draw:  
  -

Color.white, Color.black

  
  - or any value accepted by Color.from(value)
$3

- Immediate draw occurs if any of the following conditions are met:
  1. The opposite player already proposed a draw (

game.drawOffer

 is set to the opposite color) after the last move.  
  2. A draw is allowed according to the 50-move rule.  
  3. A draw is allowed according to the threefold repetition rule.

`game.nag(value)`

Adds a Numeric Annotation Glyph (NAG) to the current move in the game. This method can only be called in game mode.

#### Parameters - value — the NAG to add. Can be: - A number representing the NAG code - A string such as"!", "!!", "?", "!?", "??", etc.

#### Behavior - Attaches the NAG to the current move (game.current). - Can be used to annotate the game with standard chess commentary symbols.

`game.comment(comment)`

Adds a text comment to the current move in the game. This method can only be called in game mode.

`$3`


- comment — a string containing the text of the comment.
$3

- Attaches the comment to the current move (

game.current

).  
- Comments are preserved when exporting the game to PGN.  
game.undo()
Moves the game game.current to the previous completed ply.  
This method is used to navigate backward in game history.  
$3

- Returns to the previous ply state.  
- If the current state is a promotion, it returns to the last completed ply before the promotion (since promotion itself is not a full ply).  
- In edit mode or if the current ply is the first ply, the method does nothing.  
- Updates

game.current

 to reflect the new cursor position.  
$3

-

true

 if the undo successfully moved the cursor.  
-

false

 if no movement was possible (edit mode or first ply).
game.redo()
Moves the game game.current to the next completed ply.  
This method is used to navigate forward in game history.  
$3

- Advances to the next ply state.  
- In edit mode or if the current ply is the last ply, the method does nothing.  
- Updates

game.current

 to reflect the new cursor position. 
$3

-

true

 if the redo successfully moved the cursor.  
-

false

 if no movement was possible (edit mode or last ply).
game.go(offset)
Moves the game game.current by a specified number of completed plies.  
Used to jump forward or backward in game history.  
$3

- offset — a signed integer representing the number of plies to move:  
  - Positive: move forward  
  - Negative: move backward  
  -

: does not move
$3

- Moves the cursor by up to

offset plies

.  
- If the offset exceeds the available history, it stops at the first or last ply.  
- In edit mode or if

offset is 0

, the method does nothing.
- Updates

game.current

 to reflect the new cursor position.  
$3

-

true

 if the cursor moved.  
-

false

 if no movement was possible (edit mode, offset 0, or at the bounds of history).
game.goto(plyID)
Moves the game game.current to a specific ply by its ID.  
$3

- plyID — integer representing the target ply ID:  
  -

 — first ply  
  -

-1

 or any negative value — first ply  
  - Values greater than the last ply ID — moves to the last ply  
$3

- Sets

game.current

 to the specified ply.  
- If

plyID

 is out of bounds, clamps to the first or last ply.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if no movement was possible (edit mode or already at the target ply).
game.rewind()
Moves the game game.current back to the first ply (beginning of the game).  
$3

- Sets

game.current

 to the initial state.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the first ply or in edit mode.
game.end()
Moves the game game.current to the last event (most recent ply).  
$3

- Sets

game.current

 to the last completed move or event.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the last event or in edit mode.
game.undoEvent()
Moves the game game.current back by one event in the history chain.  
$3

- Advances to the previous event, regardless of ply boundaries.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the first event or in edit mode.
game.redoEvent()
Moves the game game.current forward by one event in the history chain.  
$3

- Advances to the next event, regardless of ply boundaries.  
- In edit mode, the cursor cannot move and the method does nothing.  
$3

-

true

 if the cursor moved.  
-

false

 if already at the last event or in edit mode.
game.goEvent(offset)
Moves the game game.current by a specified number of events in the history chain.  
$3

- offset — a signed integer representing the number of events to move:  
  - Positive: move forward  
  - Negative: move backward  
  -

: does not move
$3

- Moves the cursor by up to

offset events

.  
- If the offset exceeds the available events, it stops at the first or last event.  
- In edit mode or if

offset is 0

, the method does nothing.  
- Updates

game.current

 to reflect the new cursor position.  
$3

-

true

 if the cursor moved.  
-

false` if no movement was possible (edit mode, offset 0, or at the bounds of history).

game.gotoEvent(eventID)

Move