Class UCIEngine

Interface to a chess engine supporting UCI protocol

The class allows to implement the GUI part of the UCI protocol manually by using method SendToEngineAsync(String) to send commands to the engine process and event OnEngineOutput to receive messages

Nevertheless the recommended way is to use the more comfortable methods, which this class offers like AnalyzeAsync(String, TimeSpan, Dictionary<String, String>, List<Move>) or StartThinkingAsync(Nullable<TimeSpan>, Nullable<TimeSpan>, Nullable<TimeSpan>, Nullable<TimeSpan>, Int32, Int32, Int64, Boolean, List<Move>)

Game game = PGN.Parse(pathToPGN)[0];
using (UCIEngine engine = new UCIEngine(enginePath))
{
     ExtendedMove move = engine.AnalyseAsync(game, TimeSpan.FromMilliseconds(100), 25, Side.BLACK).Result;
     Console.WriteLine($"Evaluation: {move.Evaluation}");   
}

Inheritance

System.Object

UCIEngine

Implements

System.IDisposable

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: PonzianiComponents.Chesslib

Assembly: PonzianiComponents.dll

Syntax

public sealed class UCIEngine : IDisposable

Constructors

| Improve this Doc View Source

UCIEngine(String, Dictionary<String, String>, String)

Creates a new UCI engine

Declaration

public UCIEngine(string executable, Dictionary<string, string> parameters = null, string arguments = null)

Parameters

Type	Name	Description
System.String	executable	Path to the engine executable
System.Collections.Generic.Dictionary<System.String, System.String>	parameters	Parameters, which will be passed to the engine later on by calling SetOptionsAsync()
System.String	arguments	Command line arguments passed to the engine process on startup

Properties

| Improve this Doc View Source

AnalysisInfo

Get's the current Analysis result from the engine

Declaration

public UCIEngine.Info AnalysisInfo { get; }

Property Value

Type	Description
UCIEngine.Info

| Improve this Doc View Source

Arguments

Arguments passed on start of the engine executable

Declaration

public string Arguments { get; set; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

Author

Engine Author (as given by engine process). Only available once engine process is started.

Declaration

public string Author { get; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

BestMove

Declaration

public ExtendedMove BestMove { get; }

Property Value

Type	Description
ExtendedMove

| Improve this Doc View Source

Executable

Path to the engine executable

Declaration

public string Executable { get; set; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

Name

Engine Name (as given by engine process). Only available once engine process is started.

Declaration

public string Name { get; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

Options

Options as provided by the engine's option commands

Declaration

public Dictionary<string, UCIEngine.Option> Options { get; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, UCIEngine.Option>

| Improve this Doc View Source

Parameters

UCI options, passed via setoption command

Declaration

public Dictionary<string, string> Parameters { get; set; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.String>

| Improve this Doc View Source

PonderMove

Declaration

public Move PonderMove { get; }

Property Value

Type	Description
Move

| Improve this Doc View Source

ProcessId

Id of engine process (0 if process isn't started or stopped)

Declaration

public int ProcessId { get; }

Property Value

Type	Description
System.Int32

| Improve this Doc View Source

Score

Score from white's point of view in centipawns. Mate scores are converted to very high scores

Declaration

public int Score { get; }

Property Value

Type	Description
System.Int32

| Improve this Doc View Source

WorkingDirectory

Working directory of the engine process. If not set directory of Executable is used

Declaration

public string WorkingDirectory { get; set; }

Property Value

Type	Description
System.String

Methods

| Improve this Doc View Source

AnalyzeAsync(Game, Int32, Side, Nullable<TimeSpan>, Nullable<TimeSpan>, Nullable<TimeSpan>, Nullable<TimeSpan>, Int32, Int32, Int64, Boolean, Dictionary<String, String>, List<Move>)

Prepares the engine and executes an analysis undermatch conditions

Declaration

public async Task<ExtendedMove> AnalyzeAsync(Game game, int moveNumber = 1, Side side = Side.WHITE, TimeSpan? whiteTime = null, TimeSpan? whiteIncrement = null, TimeSpan? blackTime = null, TimeSpan? blackIncrement = null, int movesToGo = 0, int depth = 2147483647, long nodes = 0L, bool ponder = false, Dictionary<string, string> parameter = null, List<Move> MovesToBeAnalyzed = null)

Parameters

Type	Name	Description
Game	game	The current game
System.Int32	moveNumber	Movenumber of position
Side	side	Side to move of position
System.Nullable<System.TimeSpan>	whiteTime	White's time on the clock
System.Nullable<System.TimeSpan>	whiteIncrement	White's increment allocated after the move
System.Nullable<System.TimeSpan>	blackTime	Black's time on the clock
System.Nullable<System.TimeSpan>	blackIncrement	Black's increment allocated after the move
System.Int32	movesToGo	Moves until next time control
System.Int32	depth	Maximum search depth
System.Int64	nodes	Maximum nodes to be searched
System.Boolean	ponder	Search shall be executed in ponder mode
System.Collections.Generic.Dictionary<System.String, System.String>	parameter	Engine options, which will be sent to the engine using the "setoption" command
System.Collections.Generic.List<Move>	MovesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<ExtendedMove>	The engine's best move (including evaluation) info

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

AnalyzeAsync(Game, TimeSpan, Int32, Side, Dictionary<String, String>, List<Move>)

Prepares the engine and executes an analysis for a specified time

Declaration

public async Task<ExtendedMove> AnalyzeAsync(Game game, TimeSpan time, int moveNumber = 1, Side side = Side.WHITE, Dictionary<string, string> parameter = null, List<Move> movesToBeAnalyzed = null)

Parameters

Type	Name	Description
Game	game	Game, from which position is taken
System.TimeSpan	time	Time, the analysis shall take
System.Int32	moveNumber	Movenumber of position
Side	side	Side to move of position
System.Collections.Generic.Dictionary<System.String, System.String>	parameter	Engine options, which will be sent to the engine using the "setoption" command
System.Collections.Generic.List<Move>	movesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<ExtendedMove>	The best move determined by the engine (includes Evaluation Info)

| Improve this Doc View Source

AnalyzeAsync(String, String, TimeSpan, Dictionary<String, String>, List<Move>)

Prepares the engine and executes an analysis for a specified time

Declaration

public async Task<ExtendedMove> AnalyzeAsync(string fen, string movelist, TimeSpan time, Dictionary<string, string> parameter = null, List<Move> movesToBeAnalyzed = null)

Parameters

Type	Name	Description
System.String	fen	Startposition as FEN
System.String	movelist
System.TimeSpan	time	Time, the analysis shall take
System.Collections.Generic.Dictionary<System.String, System.String>	parameter	Engine options, which will be sent to the engine using the "setoption" command
System.Collections.Generic.List<Move>	movesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<ExtendedMove>	The best move determined by the engine (includes Evaluation Info)

| Improve this Doc View Source

AnalyzeAsync(String, TimeSpan, Dictionary<String, String>, List<Move>)

Prepares the engine and executes an analysis for a specified time

Declaration

public async Task<ExtendedMove> AnalyzeAsync(string fen, TimeSpan time, Dictionary<string, string> parameter = null, List<Move> movesToBeAnalyzed = null)

Parameters

Type	Name	Description
System.String	fen	Position to be analyzed as FEN
System.TimeSpan	time	Time, the analysis shall take
System.Collections.Generic.Dictionary<System.String, System.String>	parameter	Engine options, which will be sent to the engine using the "setoption" command
System.Collections.Generic.List<Move>	movesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<ExtendedMove>	The best move determined by the engine (includes Evaluation Info)

| Improve this Doc View Source

Dispose()

Declaration

public void Dispose()

| Improve this Doc View Source

GetAnalysisInfo(Int32)

Get's the current Analysis result from the engine for a specified line (inMultiPV mode)

Declaration

public UCIEngine.Info GetAnalysisInfo(int line = 0)

Parameters

Type	Name	Description
System.Int32	line	Line index (zero-based, so line = 0 will return the infor for the main line)

Returns

Type	Description
UCIEngine.Info	Engine's info for this line

| Improve this Doc View Source

NewGameAsync()

Sends the "ucinewgame" command to the engine

this shall besent to the engine when the next search (started with "position" and "go") will be from a different game.This can be a new game the engine should play or a new game it should analyse but also the next position from a testsuite with positions only.

true, if everything went right

Declaration

public async Task<bool> NewGameAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

Ponderhit()

Sends the "ponderhit" command to the engine.

This shall be done to inform the engine, that the opponent has played the expected move. The engine will continue searching but switch from pondering to normal search.

Declaration

public void Ponderhit()

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is not thinking

| Improve this Doc View Source

PrepareEngineForAnalysisAsync(Dictionary<String, String>)

Prepares the engine with one method call. It combines calls to StartEngineAsync(), SetOptionsAsync() and NewGameAsync().

 using (UCIEngine engine = new UCIEngine(enginePath))
 {
      // Start engine
      engine.PrepareEngineForAnalysisAsync().Wait();
      // Set position
      engine.SetPositionAsync(Fen.INITIAL_POSITION).Wait();
      // Analyze for one second
      engine.StartAnalysisAsync(TimeSpan.FromSeconds(1)).Wait();
      // Get best move
      Console.WriteLine(engine.BestMove.ToUCIString());
 }

Declaration

public async Task<bool> PrepareEngineForAnalysisAsync(Dictionary<string, string> parameter = null)

Parameters

Type	Name	Description
System.Collections.Generic.Dictionary<System.String, System.String>	parameter	Engine options, which will be sent to the engine using the "setoption" command

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

| Improve this Doc View Source

SendToEngineAsync(String)

Sends a message (UIC command) to engine.

Handle with care: There is only partial input validation performed. Messages which don't fulfill the UCI protocol might break the engine process!

Declaration

public async Task<bool> SendToEngineAsync(string message)

Parameters

Type	Name	Description
System.String	message	The message to be sent to the engine

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown, if engine state doesn't allow to send the message

| Improve this Doc View Source

SetOptionsAsync()

Calls the setoption commands used to configure the engine. The settings have to be provided before via the Parameters property

Declaration

public async Task<bool> SetOptionsAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

| Improve this Doc View Source

SetPositionAsync(Game, Int32, Side)

Sets the engine's position from a Game

Declaration

public async Task<bool> SetPositionAsync(Game game, int moveNumber, Side side)

Parameters

Type	Name	Description
Game	game	Game, from which position is taken
System.Int32	moveNumber	Movenumber of position
Side	side	Side to move of position

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

SetPositionAsync(Position)

Sets the engine's position

Declaration

public async Task<bool> SetPositionAsync(Position position)

Parameters

Type	Name	Description
Position	position	Position to be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

SetPositionAsync(String, String)

Set's the engine's position

Declaration

public async Task<bool> SetPositionAsync(string fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", string movelist = null)

Parameters

Type	Name	Description
System.String	fen	Start position in FEN representation
System.String	movelist	Moves leading from start position to position to be analysed, in UCI notation separated by spaces. Example: `e2e4 e7e5 g1f3 b8c6 f1b5 a7a6`

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

StartAnalysisAsync(List<Move>)

Starts an infinite analysis of the current position

Declaration

public async Task<bool> StartAnalysisAsync(List<Move> MovesToBeAnalyzed = null)

Parameters

Type	Name	Description
System.Collections.Generic.List<Move>	MovesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

StartAnalysisAsync(Int32, List<Move>)

Starts an analysis of the current position up to a specified search depth

Declaration

public async Task<bool> StartAnalysisAsync(int depth, List<Move> MovesToBeAnalyzed = null)

Parameters

Type	Name	Description
System.Int32	depth	search depth (in plies)
System.Collections.Generic.List<Move>	MovesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

StartAnalysisAsync(TimeSpan, List<Move>)

Starts an analysis of the current position for a specified time

Declaration

public async Task<bool> StartAnalysisAsync(TimeSpan thinkTime, List<Move> MovesToBeAnalyzed = null)

Parameters

Type	Name	Description
System.TimeSpan	thinkTime	the time the engine shall spend
System.Collections.Generic.List<Move>	MovesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

StartEngineAsync()

Starts the engine process

Declaration

public async Task<bool> StartEngineAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if engine process could be started

| Improve this Doc View Source

StartThinkingAsync(Nullable<TimeSpan>, Nullable<TimeSpan>, Nullable<TimeSpan>, Nullable<TimeSpan>, Int32, Int32, Int64, Boolean, List<Move>)

Starts an analysis of the current position in a match situation

Declaration

public async Task<bool> StartThinkingAsync(TimeSpan? whiteTime = null, TimeSpan? whiteIncrement = null, TimeSpan? blackTime = null, TimeSpan? blackIncrement = null, int movesToGo = 0, int depth = 2147483647, long nodes = 0L, bool ponder = false, List<Move> MovesToBeAnalyzed = null)

Parameters

Type	Name	Description
System.Nullable<System.TimeSpan>	whiteTime	White's time on the clock
System.Nullable<System.TimeSpan>	whiteIncrement	White's increment allocated after the move
System.Nullable<System.TimeSpan>	blackTime	Black's time on the clock
System.Nullable<System.TimeSpan>	blackIncrement	Black's increment allocated after the move
System.Int32	movesToGo	Moves until next time control
System.Int32	depth	Maximum search depth
System.Int64	nodes	Maximum nodes to be searched
System.Boolean	ponder	Search shall be executed in ponder mode
System.Collections.Generic.List<Move>	MovesToBeAnalyzed	List of moves, which shall be analyzed - if null, all moves will be analyzed

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine state doesn't allow to set position. Method must not be called while engine is off, initializing or thinking

| Improve this Doc View Source

StopThinkingAsync()

Stops engine analysis (sends UCI "stop" command)

Declaration

public async Task<bool> StopThinkingAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	true, if everything went right

Exceptions

Type	Condition
UCIEngine.EngineException	thrown if engine isn't analysing

Events

| Improve this Doc View Source

OnEngineInfoChanged

Raised whenever the engine issues a "info" message (except "info string" messages), by which the engine sends information about the current state of analysis

Declaration

public event EventHandler<UCIEngine.EngineInfoEventArgs> OnEngineInfoChanged

Event Type

Type	Description
System.EventHandler<UCIEngine.EngineInfoEventArgs>

| Improve this Doc View Source

OnEngineOutput

Raised whenever the engine outputs anything

Declaration

public event EventHandler<UCIEngine.EngineOutputEventArgs> OnEngineOutput

Event Type

Type	Description
System.EventHandler<UCIEngine.EngineOutputEventArgs>

Implements

System.IDisposable