Public API Reference

Board

A chess board representation using bitboards.

• bitboards: A dictionary mapping piece types to their corresponding bitboards.
• 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.
• 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 and to are square indices 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

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

SearchResult

Result of a search operation.

• score: The evaluation score of the position (nothing if from book).
• move: The best move found (nothing if from book).
• 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.

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

game_over(board::Board)

Check if the game is over (checkmate, stalemate, draw)

• board: Board struct

Returns: Symbol (:checkmatewhite, :checkmateblack, :stalemate, :drawthreefold, :drawfiftymove, :drawinsufficientmaterial, :ongoing)

game_over(game::Game)

Check if the game is over (checkmate, stalemate, draw)

• game: Game struct

Returns: Symbol (:checkmatewhite, :checkmateblack, :stalemate, :drawthreefold, :drawfiftymove, :drawinsufficientmaterial, :ongoing)

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)

Make a move for the current player, updating the game state and time control.

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

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

Make a move for the current player, returning a new Game state.

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

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

Performance test function: counts the number of leaf nodes reachable from the given board position up to depth.

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

Fast perft function using a preallocated moves buffer to avoid repeated allocations. Ideal for benchmarking.

search(
    board::Board, 
    depth::Int;
    ply::Int = 0,
    α::Int = (-MATE_VALUE),
    β::Int = MATE_VALUE,
    opening_book::Union{Nothing,PolyglotBook} = KOMODO_OPENING_BOOK,
    verbose::Bool = false,
    time_budget::Int = typemax(Int)
)

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.

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

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

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

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