♞ CeruleanJS

JavaScript Chess Engine by Joey Robert


CeruleanJS by Joey Robert

JavaScript Chess Engine

                            /\_ \
  ___     __   _ __   __  __\//\ \      __     __      ___
 /'___\ /'__`\/\`'__\/\ \/\ \ \ \ \   /'__`\ /'__`\  /' _ `\
/\ \__//\  __/\ \ \/ \ \ \_\ \ \_\ \_/\  __//\ \L\.\_/\ \/\ \
\ \____\ \____\\ \_\  \ \____/ /\____\ \____\ \__/.\_\ \_\ \_\
 \/____/\/____/ \/_/   \/___/  \/____/\/____/\/__/\/_/\/_/\/_/

Official Website: http://ceruleanjs.joeyrobert.org/


CeruleanJS is an XBoard chess engine for NodeJS, written by Joey Robert.

The goals of CeruleanJS are threefold:

CeruleanJS aims to be ranked on the CCRL.



To install the binary into your $PATH, install the ceruleanjs package globally:

npm install -g ceruleanjs

Run the engine with the command:


If you’re installing from sources, check out this git repository and run:

npm install

To run:

npm start

To run mocha tests:

npm test

To generate a Windows binary executable using nexe, run:

npm run build-windows

This requires Microsoft Visual Studio 2015/2019/2022 to be installed. It will generate ceruleanjs.exe and book.bin in dist.

To generate a web build, run:

npm run build-web

This will generate a babelify’d ES5 version of CeruleanJS that is compatible with most modern day web browsers that support Web Workers. This build is used in the CeruleanJS Player.


CeruleanJS supports the XBoard/winboard/CECP format for communicating with interfaces or other chess engines. It’s also usable directly through STDIN/OUT. Here’s the list of commands:

CeruleanJS 0.2.0, Javascript Chess Engine by Joey Robert
More info at https://ceruleanjs.joeyrobert.org/

Command                     Description

display                     Draws the board
perft [INT]                 Perfts the current board to specified depth
perfthash [INT]             Sets perft hashtable exponent (size 2^exponent)
memory [INT]                Sets the memory used by the engine in megabytes
divide [INT]                Divides the current board to specified depth
moves                       Lists valid moves for this position
e2e4                        Moves from the current position and thinks
go                          Forces the engine to think
undo                        Subtracts the previous move
new                         Sets up the default board position
setboard [FEN]              Sets the board using Forsyth-Edwards Notation
evaluate                    Performs a static evaluation of the board
result                      Displays game result (checkmate or stalemate)
book [on|off]               Toggles whether engine uses opening book
white                       Sets the active colour to WHITE
black                       Sets the active colour to BLACK
time [INT]                  Sets engine's time (in centiseconds)
otim [INT]                  Sets opponent's time (in centiseconds)
sd [INT]                    Sets maximum depth
st [INT]                    Sets maximum time
level [MPT] [BASE] [INC]    Sets Winboard level timing
sts                         Run Strategic Test Suite (1s per move)
version                     Outputs the version number
exit                        Exits the menu
quit                        See exit
help                        Gets you this magical menu

Interface GIF

CeruleanJS Usage GIF


For a more technical breakdown of how CeruleanJS is implemented, see docs/TECHNICAL.md


CeruleanJS is licensed under the GNU GPL v3.