1.3.2Engine is a UCI interface between an engine executable (that understands UCI) and itself. It abstracts away communication to the engine process by providing methods for sending commands and mechanisms for parsing responses.
It also has a chainable api (EngineChain) that allows for terse coding.
Implements everything in the UCI protocol except debug and registration.
(string)
absolute path to engine executable
const enginePath = '/some/place/here'
//async/await
const engine = new Engine(enginePath)
await engine.init()
await engine.setoption('MultiPV', '4')
await engine.isready()
console.log('engine ready', engine.id, engine.options)
const result = await engine.go({depth: 4})
console.log('result', result)
await engine.quit()
//with chain api
const engine = new Engine(enginePath)
engine.chain()
.init()
.setoption('MultiPV', 3)
.position('r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3')
.go({depth: 15})
.then(result => {
console.log('result', result)
})
Retireve the proc buffer until condition is true. You shouldn't need to use this normally.
(function (string))
a function that returns true at some point
promise<Array<string>>:
array of strings containing buffer received from engine
//async/await
const lines = await myEngine.getBufferUntil(line => line === 'uciok')
//promise
myEngine.getBufferUntil(function(line) {
return line === 'uciok'
})
.then(function(lines) {
console.log('engine says', lines)
})
Returns a new EngineChain using this engine.
EngineChain:
new instance of
EngineChain
const chain = myEngine.chain()
//equivalent to
const myEngine = new Engine(myPath)
const chain = new EngineChain(myEngine)
Initializes the engine process and handshakes with the UCI protocol. When this is done, #Engine#id and #Engine#options are populated.
promise<Engine>:
itself (the Engine instance)
//async/await
const engine = new Engine(somePath)
await engine.init()
//engine is initialized, do stuff...
//promise
var myEngine = new Engine(somePath)
myEngine.init()
.then(function (engine) {
//myEngine === engine
//do stuff
})
Sends a command to engine process. Promise resolves after readyok is received.
Some commands in the UCI protocol do not require responses (like setoption).
So, to be sure, Engine#isready is invoked to determine when it's safe to continue.
(string)
command to send to the engine process
promise<Engine>:
itself (the Engine instance)
Sends the setoption command for given option name and its value.
Does not validate parameters. value, if given, is coerced into a string.
promise<Engine>:
itself (the Engine instance)
//async/await
await myEngine.setoption('MultiPV', '3')
await myEngine.setoption('Slow Mover', '400')
console.log(myEngine.options)
// -> output includes newly set options
//promise
myEngine.setoption('MultiPV', '3')
.then(function (engine) {
return engine.setoption('Slow Mover', '400');
})
.then(function (engine) {
console.log(myEngine.options)
// -> output includes newly set options
})
Sends the go command to the engine process. Returns after engine finds the best move.
Does not validate options. Does not work for infinite search. For intinite search, see #Engine#goInfinite.
Options have identical names as the UCI go options. See UCI protocol for information.
On completion, it returns an object containing the bestmove and an array of info objects,
these info objects have properties that correspond to the UCI protocol.
(object)
options
| Name | Description |
|---|---|
options.searchmoves Array<string>
|
moves (in engine notation) to search for |
options.ponder boolean
|
ponder mode |
options.wtime number
|
wtime (integer > 0) |
options.btime number
|
btime (integer > 0) |
options.winc number
|
winc (integer > 0) |
options.binc number
|
binc (integer > 0) |
options.movestogo number
|
movestogo (integer > 0) |
options.depth number
|
depth (integer > 0) |
options.nodes number
|
nodes (integer > 0) |
options.mate number
|
mate (integer > 0) |
options.movetime number
|
movetime (integer > 0) |
promise<{bestmove: string, info: Array<string>}>:
result -
bestmove
string
and array of chronologically-ordered
info
objects
//async/await
const engine = new Engine(somePath)
await engine.init()
const result = await engine.go({depth: 3})
console.log(result)
// -> {bestmove: 'e2e4', info: [{depth: 1, seldepth: 1, nodes: 21,...}, ...]}
//promise
var myEngine = new Engine(somePath)
myEngine.init()
.then(function (engine) {
return engine.go({depth: 3})
})
.then(function (result) {
console.log(result)
// -> {bestmove: 'e2e4', info: [{depth: 1, seldepth: 1, nodes: 21,...}, ...]}
})
Special case of #Engine#go with infinite search enabled.
EventEmitter:
an EventEmitter that will emit
data
events with either
bestmove
string or
info
objects.
#Engine#stop
must be used to stop
the search and receive the bestmove.
//async/await
const engine = new Engine(enginePath)
await engine.init()
await engine.isready()
await engine.setoption('MultiPV', '3')
const emitter = engine.goInfinite()
emitter.on('data', a => {
console.log('data', a)
})
setTimeout(async () => {
const bestmove = await engine.stop()
console.log('bestmove', bestmove)
await engine.quit()
}, 5000)
Sends stop command to the engine, for stopping an ongoing search. Engine will
reply with the bestmove, which is returned, along with any other info lines.
See #Engine#goInfinite for usage example.
promise<{bestmove: string, info: Array<string>}>:
result - See
#Engine#go
EngineChain sets up an api to enable chaining when dealing with Engines.
go is a special case that ends the chain by calling #EngineChain#exec,
and returns the search result.
const engine = new Engine(enginePath)
const chain = new EngineChain(engine)
// OR: const chain = engine.chain()
.init()
.setoption('MultiPV', 3)
.position('r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3')
.go({depth: 15})
.then(result => {
console.log('result', result)
})