uci

README

uci

A golang API to interact with UCI chess engines. (should be considered experimental for the time being) A description of how UCI works is available here.

Many chess engines support UCI (Universal Chess Interface). This library is designed for use with Stockfish, but should work with other UCI engines.

Godoc for UCI

minimum viable snippet

package main

import (
	"fmt"
	"log"
	"gopkg.in/freeeve/uci.v1"
)

func main() {
	eng, err := uci.NewEngine("/path/to/stockfish")
	if err != nil {
		log.Fatal(err)
	}
	
	// set some engine options
	eng.SetOptions(uci.Options{
		Hash:128,
		Ponder:false,
		OwnBook:true,
		MultiPV:4,
	})

	// set the starting position
	eng.SetFEN("rnb4r/ppp1k1pp/3bp3/1N3p2/1P2n3/P3BN2/2P1PPPP/R3KB1R b KQ - 4 11")
	
	// set some result filter options
	resultOpts := uci.HighestDepthOnly | uci.IncludeUpperbounds | uci.IncludeLowerbounds
	results, _ := eng.GoDepth(10, resultOpts)

	// print it (String() goes to pretty JSON for now)
	fmt.Println(results)
}

produces this output:

{
  "BestMove": "c8d7",
  "Results": [
    {
      "Time": 136,
      "Depth": 10,
      "SelDepth": 16,
      "Nodes": 183853,
      "NodesPerSecond": 1351860,
      "MultiPV": 1,
      "Lowerbound": false,
      "Upperbound": false,
      "Score": 20,
      "Mate": false,
      "BestMoves": [
        "c8d7",
        "b5d6",
        "c7d6",
        "f3g5",
        "b8c6",
        "g5e4",
        "f5e4",
        "a1d1",
        "h7h6",
        "f2f4",
        "a8f8"
      ]
    },
    {
      "Time": 136,
      "Depth": 10,
      "SelDepth": 16,
      "Nodes": 183853,
      "NodesPerSecond": 1351860,
      "MultiPV": 2,
      "Lowerbound": false,
      "Upperbound": false,
      "Score": 2,
      "Mate": false,
      "BestMoves": [
        "a7a5",
        "b5d6",
        "c7d6",
        "b4b5",
        "b8d7",
        "f3d2",
        "e4d2",
        "e3d2",
        "b7b6",
        "a3a4"
      ]
    },
    {
      "Time": 136,
      "Depth": 10,
      "SelDepth": 16,
      "Nodes": 183853,
      "NodesPerSecond": 1351860,
      "MultiPV": 3,
      "Lowerbound": false,
      "Upperbound": false,
      "Score": -4,
      "Mate": false,
      "BestMoves": [
        "b8c6",
        "c2c4",
        "a7a6",
        "b5d6",
        "c7d6",
        "f3g5",
        "c8d7",
        "c4c5",
        "d6d5",
        "g5e4",
        "f5e4"
      ]
    },
    {
      "Time": 136,
      "Depth": 10,
      "SelDepth": 16,
      "Nodes": 183853,
      "NodesPerSecond": 1351860,
      "MultiPV": 4,
      "Lowerbound": false,
      "Upperbound": false,
      "Score": -18,
      "Mate": false,
      "BestMoves": [
        "e7f7",
        "h2h4",
        "a7a5",
        "b5d6",
        "c7d6",
        "b4a5",
        "b8d7",
        "f3g5",
        "e4g5",
        "h4g5",
        "a8a5",
        "e3d2"
      ]
    }
  ]
}

Documentation

Index

• Constants
• type Engine
  • func NewEngine(path string, arg ...string) (*Engine, error)
  • func (eng *Engine) Close()
  • func (eng *Engine) Go(depth int, searchmoves string, movetime int64, resultOpts ...uint) (*Results, error)
  • func (eng *Engine) GoDepth(depth int, resultOpts ...uint) (*Results, error)
  • func (eng *Engine) SendOption(name string, value interface{}) error
  • func (eng *Engine) SetFEN(fen string) error
  • func (eng *Engine) SetMoves(moves string) error
  • func (eng *Engine) SetOptions(opt Options) error
• type Options
• type Results
  • func (r Results) String() string
• type ScoreResult

Constants

const (
	HighestDepthOnly   uint = 1 << iota // only return the highest depth results
	IncludeUpperbounds uint = 1 << iota // include upperbound results
	IncludeLowerbounds uint = 1 << iota // include lowerbound results
)

constants for result filtering

Types

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine holds the information needed to communicate with a chess engine executable. Engines should be created with a call to NewEngine(/path/to/executable)

func NewEngine

func NewEngine(path string, arg ...string) (*Engine, error)

NewEngine returns an Engine it has spun up and connected communication to

func (*Engine) Close

func (eng *Engine) Close()

func (*Engine) Go

func (eng *Engine) Go(depth int, searchmoves string, movetime int64, resultOpts ...uint) (*Results, error)

Go can use search moves, depth and time to move as filter for the results being returned. see http://wbec-ridderkerk.nl/html/UCIProtocol.html

func (*Engine) GoDepth

func (eng *Engine) GoDepth(depth int, resultOpts ...uint) (*Results, error)

GoDepth takes a depth and an optional uint flag that configures filters for the results being returned.

func (*Engine) SendOption

func (eng *Engine) SendOption(name string, value interface{}) error

SendOption sends setoption command to the Engine

func (*Engine) SetFEN

func (eng *Engine) SetFEN(fen string) error

SetFEN takes a FEN string and tells the engine to set the position

func (*Engine) SetMoves

func (eng *Engine) SetMoves(moves string) error

func (*Engine) SetOptions

func (eng *Engine) SetOptions(opt Options) error

SetOptions sends setoption commands to the Engine for the values set in the Options record passed in

type Options

type Options struct {
	MultiPV int  // number of principal variations (ranks top X moves)
	Hash    int  // hash size in MB
	Ponder  bool // whether the engine should ponder
	OwnBook bool // whether the engine should use its opening book
	Threads int  // max number of threads the engine should use
}

Options, for initializing the chess engine

type Results

type Results struct {
	BestMove string

	Results []ScoreResult
	// contains filtered or unexported fields
}

Results holds a slice of ScoreResult records as well as some overall result data

func (Results) String

func (r Results) String() string

type ScoreResult

type ScoreResult struct {
	Time           int      // time spent to get this result (ms)
	Depth          int      // depth (number of plies) of result record
	SelDepth       int      // selective depth -- some engines don't report this
	Nodes          int      // total nodes searched to get this result
	NodesPerSecond int      // current nodes per second rate
	MultiPV        int      // 0 if MultiPV not set
	Lowerbound     bool     // true if reported as lowerbound
	Upperbound     bool     // true if reported as upperbound
	Score          int      // score centipawns or mate in X if Mate is true
	Mate           bool     // whether this move results in forced mate
	BestMoves      []string // best line for this result
}

ScoreResult holds the score result records returned by the engine