Getting Started: Playing Interactively

This guide covers using OrbisChessEngine as a Julia package: creating positions, making moves, and calling the engine directly from Julia code. To use it as a UCI engine from a GUI or a tool like cutechess-cli instead, see the UCI guide.

Playing Chess

First we load the package:

using OrbisChessEngine

We can create a starting position using:

board = Board()

r n b q k b n r 
p p p p p p p p 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
P P P P P P P P 
R N B Q K B N R 

or load a game from a FEN string:

board = Board(fen="rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")

r n b q k b n r 
p p p p p p p p 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
P P P P P P P P 
R N B Q K B N R 

This is a struct of type Board which contains the relevant information about the chess position needed for playing and searching. It provides a simple ASCII show method, but you can use plot instead, as shown below.

Graphical rendering

To view the board we can use plot():

plot(board)

 8  ♖  ♘  ♗  ♕  ♔  ♗  ♘  ♖ 
 7  ♙  ♙  ♙  ♙  ♙  ♙  ♙  ♙ 
 6                         
 5                         
 4                         
 3                         
 2  ♟  ♟  ♟  ♟  ♟  ♟  ♟  ♟ 
 1  ♜  ♞  ♝  ♛  ♚  ♝  ♞  ♜ 
    a  b  c  d  e  f  g  h

plot prints a colored board to the terminal by default, using a dark theme. If your editor/terminal uses a light theme, switch the board to match by setting the "theme" preference (via Preferences.jl) to "light":

using Preferences
set_preferences!(OrbisChessEngine, "theme" => "light")

If a Makie backend (e.g. CairoMakie) plus FileIO and Images are loaded, plot returns a graphical Figure instead.

import CairoMakie, FileIO, Images
plot(board)

Making Moves

We can use Move to create a move. Several formats are supported, but the simplest is to use the long algebraic notation:

mv = Move(board, "e2e4")

e2e4

The advantage of the move format used above, is that you don't have to specify captures, promotions or castling, as these are inferred from the board position (hence it needs the board as an argument).

We can make a move using by make_move() or the in-place version make_move!():

make_move!(board, mv)

We can undo a move using undo_move() or the in-place version undo_move!():

undo_move!(board, mv)

Note that make_move() (and the in-place version make_move!()) does not check legality, so it is possible to make illegal moves. To ensure moves are legal, you can use apply_moves() (or the in-place version apply_moves!()), which will throw an error if any move is illegal.

apply_moves!(board, "e2e4", "e7e5", "g1f3", "b8c6", "f1b5")

r . b q k b n r 
p p p p . p p p 
. . n . . . . . 
. B . . p . . . 
. . . . P . . . 
. . . . . N . . 
P P P P . P P P 
R N B Q K . . R 

You can check the game status using game_status():

game_status(board)

:ongoing

Using the Engine

To generate a move using the engine we can use search():

result = search(board; depth = 3, opening_book = nothing)

SearchResult(2, d7d6, false, true)

search() returns a SearchResult object containing the evaluation score, the move and if it is a book move. This package ships with a small opening book, which is default when calling search(). To disable the opening book, set opening_book = nothing. To use a custom opening book use load_polyglot_book() to load another polyglot book in .bin format.

To make a 3+2 game we can use Game():

game = Game(; minutes = 3, increment = 2)

r n b q k b n r 
p p p p p p p p 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
P P P P P P P P 
R N B Q K B N R 

or the short-hand notation:

game = Game("3+2")

r n b q k b n r 
p p p p p p p p 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
. . . . . . . . 
P P P P P P P P 
R N B Q K B N R 

This is a struct of type Game which contains the board, white and black time left, and the increment.

The engine will then automatically allocate how much time to use for each move. To let the engine make a move in a timed game we can use engine_move!():

engine_move!(game)

Combining everything we can let the engine play against itself in a 1+1 game against itself:

game = Game("1+1")
boards = [deepcopy(game.board)]
while game_status(game.board) == :ongoing
    engine_move!(game)
    push!(boards, deepcopy(game.board))
end

And view the game:

for i in eachindex(boards)
    sleep(0.5)
    plot(boards[i])
end