stockfish 0.2.8

Light, easy-to-use wrapper for the Stockfish engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

# stockfish


[![crates-io](https://img.shields.io/crates/v/stockfish.svg)](https://crates.io/crates/stockfish)
[![api-docs](https://docs.rs/stockfish/badge.svg)](https://docs.rs/stockfish)
[![License](https://img.shields.io/crates/l/bitflags.svg)](https://img.shields.io/badge/license-MIT%20or%20Apache2.0-Green)
[![Crates.io (recent)](https://img.shields.io/crates/dr/stockfish)](https://crates.io/crates/stockfish)

A wrapper library that makes integrating Stockfish with Rust a breeze.

An [installation](https://stockfishchess.org/download/) of the Stockfish engine is needed. (Or any [UCI](https://official-stockfish.github.io/docs/stockfish-wiki/UCI-&-Commands.html)-compatible engine, although this library was mainly written with Stockfish in mind.)

## Usage


Add this to your `Cargo.toml`:

```toml
[dependencies]
stockfish = "0.2.8"
```

And this to your source code:

```rust
use stockfish::Stockfish;
```

## Example usage


Using the path to the Stockfish executable, construct an instance. (Mind the `?`; it's possible that any of these operations may fail, as they involve IO operations.)

```rust
let mut stockfish = Stockfish::new("path/to/stockfish")?;
```

Once created, setup the engine:

```rust
stockfish.setup_for_new_game()?;
```

Direct the engine to the desired position on the board; this may be done through a sequence of moves from the regular starting position:

```rust
stockfish.play_moves(&["e2e4", "c7c5"])?;
```

Or through setting its position via Forsyth-Edwards notation ([FEN](https://www.chessprogramming.org/Forsyth-Edwards_Notation)):

```rust
let fen = "r1bqkb1r/pppp1ppp/2n2n2/4p3/4P3/2N2N2/PPPP1PPP/\
R1BQKB1R w KQkq - 0 1";
stockfish.set_fen_position(fen)?;
```

Then, calculation may be initiated through various methods, the simplest of which
is `go`, which makes Stockfish calculate until it reaches a certain [depth](https://www.chessprogramming.org/Depth):

```rust
stockfish.set_depth(20); // Optional; default depth is 15
let engine_output = stockfish.go()?;
```

The returned `EngineOutput` may be worked with like so:

```rust
let best_move = engine_output.best_move();
println!("Best move according to Stockfish: {best_move}");

let eval = engine_output.eval();
match eval.eval_type() {
    EvalType::Centipawn => {
        println!("Eval: {} centipawns", eval.value());
    }
    EvalType::Mate => {
        println!("Eval: Mate in {}", eval.value());
    }
};
```

## A longer example


```rust
use stockfish::Stockfish;

fn main() -> Result<(), std::io::Error> {
    let path = if cfg!(target_os = "windows") {
        "./stockfish.exe"
    } else {
        "stockfish"
    };

    let mut stockfish = Stockfish::new(&path)?;
    stockfish.setup_for_new_game()?;
    stockfish.print_board()?;

    println!("Stockfish version: {:?}", stockfish.get_version());

    stockfish.set_depth(20); // Optional; default depth is 15

    let engine_output = stockfish.go()?;
    println!("engine_output: {engine_output:?}");

    // Play some moves!
    let moves = ["e2e4", "e7e5", "g1f3"];
    for move_str in moves {
        stockfish.play_move(move_str)?;
        stockfish.print_board()?;

        let engine_output = stockfish.go()?;
        println!("engine_output: {engine_output:?}");
    }

    stockfish.quit()?;

    Ok(())
}
```

## Other details


Some different ways of invoking calculation from Stockfish:

```rust
// Have stockfish calculate for five seconds, then get its output
let engine_output = stockfish.go_for(
    Duration::from_millis(5000)
)?;

// Have stockfish calculate for a variable amount of time based on
// the players' move times in the chess game
// (expressed in milliseconds)
let engine_output = stockfish.go_based_on_times(
    Some(60_000), Some(60_000)
);
```

Some configuration options (of which the most likely to be changed
would be [hash table size](https://www.chessprogramming.org/Hash_Table)
and [thread count](https://official-stockfish.github.io/docs/stockfish-wiki/UCI-&-Commands.html#threads)):

```rust
stockfish.set_threads(6)?;
stockfish.set_hash(64)?;

// Set any UCI option for stockfish
stockfish.set_option("Move Overhead", "5")?;
```