Public API Reference

Board

A chess board representation using bitboards.

• bitboards: A fixed-size vector where each element corresponds to a piece type's bitboard.
• side_to_move: The side to move.
• castling_rights: A 4-bit integer representing castling rights (KQkq).
• en_passant: The square index (0-63) for en passant target, or -1 if none.
• halfmove_clock: The number of halfmoves since the last capture or pawn move (for the 50-move rule).
• position_history: A vector of position Zobrist hashes for detecting threefold repetition.
• undo_stack: A stack of UndoInfo structs for unmaking moves.
• undo_index: The current index in the undo stack.
• eval_score: Cached evaluation score from White's point of view.
• game_phase_value: Cached phase numerator (sum of weights) for evaluation scaling.

Game

A struct representing a chess game with time control.

• board: The current state of the chess board.
• white_time: Time remaining for White in milliseconds.
• black_time: Time remaining for Black in milliseconds.
• increment: Time increment per move in milliseconds.

Move

A chess move.

• from is a square index (0-63)
• to is a square index (0-63)
• promotion is the piece type promoted to (0 if none)
• capture is captured piece type (0 if none)
• castling: 0 = normal, 1 = kingside, 2 = queenside
• en_passant: true if en passant capture

Move(board::Board, str::AbstractString)

Construct a Move from a long algebraic string like "e2e4" or "e7e8=Q", using the board to infer capture, en passant, and castling.

• board: current Board state
• str: move string in long algebraic notation

Captures are inferred based on the board state (so "e4d5" captures if d5 is occupied by opponent). Castling can be specified with "O-O" (kingside) or "O-O-O" (queenside). Also accepts "o-o", "0-0", "o-o-o", "0-0-0".

Note, that this function does not validate the legality of the move; it only constructs the Move object.

SearchResult

Result of a search operation.

• score: The evaluation score of the position.
• move: The best move found.
• from_book: Boolean indicating if the move was from the opening book.

UndoInfo

Information needed to undo a move

• captured_piece: The piece type that was captured, or 0 if none.
• en_passant: The previous en passant square.
• castling_rights: The previous castling rights.
• halfmove_clock: The previous halfmove clock.
• moved_piece: The piece type that was moved.
• promotion: The piece type if the move was a promotion, or 0 otherwise.
• is_en_passant: A boolean indicating if the move was an en passant capture.
• prev_eval_score: The evaluation score before the move.
• prev_game_phase_value: The game phase value before the move.

evaluate(board::Board) -> Int

Evaluate a position from White’s perspective using piece-square tables.

• board: Board struct

game_status(board::Board) -> Symbol

Return the current game status (checkmate, stalemate, draw, or ongoing)

• board: Board struct

Returns: Symbol - one of

• :checkmate_white
• :checkmate_black
• :stalemate
• :draw_threefold
• :draw_fiftymove
• :draw_insufficient_material
• :ongoing

game_status(game::Game)

Return the current game status (checkmate, stalemate, draw, timeout, or ongoing).

• game: Game struct

Returns: Symbol — one of

• :checkmate_white
• :checkmate_black
• :stalemate
• :draw_threefold
• :draw_fiftymove
• :draw_insufficient_material
• :timeout_white
• :timeout_black
• :ongoing

in_check(board::Board, side::Side) -> Bool

Check if the king of the given side is in check

• board: Board struct
• side: Side (WHITE or BLACK)

Returns: Bool

make_move!(board, m)

Apply move m to board, modifying it in place.

• board: Board struct
• m: Move

make_move(board, m) -> Board

Return a new board with move m applied, leaving the original board unchanged.

• board: Board struct
• m: Move

make_timed_move!(game::Game; opening_book::Union{Nothing, PolyglotBook}=KOMODO_OPENING_BOOK, verbose=false)

Searches for and makes a move for the current player, updating the Game struct with the updated board and time remaining.

• game: Game struct
• opening_book: Optional PolyglotBook for opening moves
• verbose: If true, print move details and time used

The time allocated for the search is done automatically based on remaining time and increment. See search for details on how the search is performed.

make_timed_move(game::Game; opening_book::Union{Nothing, PolyglotBook}=KOMODO_OPENING_BOOK, verbose=false) -> Game

Searches for and makes a move for the current player, returning a new Game struct with the updated board and time remaining.

• game: Game struct
• opening_book: Optional PolyglotBook for opening moves
• verbose: If true, print move details and time used

The time allocated for the search is done automatically based on remaining time and increment. See search for details on how the search is performed.

perft(board::Board, depth::Int) -> Int

Compute the number of leaf nodes reachable from the given board position at the given depth. It uses the Board struct to immitate search behavior. In particular, this means it still computes zobrist hashes and updates evaluation scores slowing it down compared to a minimal perft implementation.

perft_fast(board::Board, depth::Int) -> Int

Compute the number of leaf nodes reachable from the given board position at the given depth using multiple threads at the root. It uses the Board struct to immitate search behavior. In particular, this means it still computes zobrist hashes and updates evaluation scores slowing it down compared to a minimal perft implementation.

search(
    board::Board;
    depth::Int,
    opening_book::Union{Nothing, PolyglotBook} = KOMODO_OPENING_BOOK,
    verbose::Bool = false,
    time_budget::Int = typemax(Int)
)::SearchResult

Search for the best move using minimax with iterative deepening, alpha-beta pruning, quiescence search, null move pruning, and transposition tables.

Arguments:

• board: current board position
• depth: search depth
• opening_book: if provided, uses a opening book. Default is KOMODO_OPENING_BOOK

taken from free-opening-books. Set to nothing to disable.

• verbose: if true, prints search information and principal variation (PV) at each depth
• time_budget: time in milliseconds to stop the search (if depth not reached)

Returns:

• SearchResult containing the best move and its evaluation score (or nothing if no move found)

undo_move!(board::Board, m::Move)

Undo move m on board in place, restoring previous state.

• board: Board struct
• m: Move struct

undo_move(board::Board, m::Move) -> Board

Return a new board with move m undone, leaving the original board unchanged.

• board: Board struct
• m: Move struct