naddu

Naddu

Naddu is a Javascript UCI chess engine.

It can be easily included in your web pages.

All you need is naddu.js from the repo root.

The code is written in a straightforward style and deliberately easy to tweak.

Strength is around 2400 Elo.

The hash table defaults to 16 MB and can be set with setoption name Hash value <mb>.

Hello world

const naddu = new Worker('naddu.js');
const ucioutput = document.getElementById('ucioutput');

naddu.onmessage = function(e) {
  ucioutput.textContent += e.data + '\n'; // naddu reponds with text as per UCI 
};

naddu.postMessage('uci');
naddu.postMessage('ucinewgame');
naddu.postMessage('position startpos');
naddu.postMessage('board');
naddu.postMessage('eval');
naddu.postMessage('go depth 8');
naddu.postMessage('go movetime 1000')

Try this example here: https://op12no2.github.io/naddu/examples/hello_world.html

More examples

• mates - finds mates and checks the reported mate distance.
• console - a console, type UCI commands and see the replies, ? lists them.
• play - play against Naddu at five strength levels, or watch Naddu play itself.
• endgames - plays out random K+Q v K and K+R v K positions and checks white mates.
• analysis - set up a position by dragging pieces, presets or FEN, then analyse it.
• openings - twenty workers search each first move deeper and deeper, then rank them.
• perft - move generator node counts against the known values, plus your own.
• bk - the Bratko-Kopec test at a search time of your choice.
• sts - the 1500 position Strategic Test Suite, one worker per theme, to a fixed depth or time, scored overall and per theme.
• pst - the piece square tables as heat maps on one shared colour scale.
• taper - one board per piece with a phase slider, showing the blended values the eval really uses.
• parallel - workers share out the root moves of one position and search them together.
• arena - a round robin between the five strength levels, twenty workers, live crosstable.
• landscape - a worker per piece tries it on every empty square, heat maps of where the eval would like each piece.
• game - the engine plays itself on a clock with a live score graph, time bars and a deeper second opinion from a worker pool.
• scaling - root moves shared out between 1 to 16 workers, speedup plotted against the ideal.
• deepening - nodes per iteration and the branching factor charted live for five positions side by side.
• symmetry - eight workers play random games and check every position evals the same when colour flipped.

UCI commands

UCI is richer than this, these are the commands Naddu implements:-

• uci - engine name and author, then uciok.
• isready - replies readyok.
• ucinewgame - clears the hash and history, do this before a new game.
• setoption name Hash value <mb> - hash table size, default 16.
• position startpos [moves ...] and position fen <fen> [moves ...].
• go depth <n>, go nodes <n>, go movetime <ms>, go infinite and go wtime <ms> btime <ms> winc <ms> binc <ms> [movestogo <n>].
• stop - accepted but does nothing, see below.
• quit - exits, in a worker it closes the worker.

A search runs to completion inside the worker and replies with info lines and then bestmove. Commands sent while it is searching queue up until it finishes. So stop cannot interrupt a search and go infinite runs until the worker is killed. To stop a search, kill the worker and make a new one:-

naddu.terminate();
naddu = new Worker('naddu.js');

UCI options

Reported by uci and set with setoption name <name> value <value>, the name is not case sensitive:-

• Hash - hash table size in MB, spin, default 16, min 1, max 1024. Setting it clears the table. The size is rounded down to a power of two entries of 16 bytes, so 24 gives the same table as 16.

UCI extensions

Extra commands handy for web pages and testing, with any shortform in parenthsis:-

• board (b) - show the current position.
• moves (l) - list the legal moves, or checkmate or stalemate if there are none.
• eval (e) - static eval of the current position from the side to move’s point of view.
• pst - print, set or reset the piece square tables, see below.
• perft <depth> (f) - leaf node count.
• bench (h) - search 50 positions, report nodes and nps.
• evaltests (et) - evals of the bench positions.
• perfttests (pt) - the perft test suite, takes a while.
• ? or help - list the commands.

Some standard UCI commands and sub-commands have shortforms too:-

• ucinewgame (u)
• position (p)
• startpos (s)
• fen (f)
• go (g)
• depth (d)
• movetime (m)
• nodes (n)
• quit (q)

Allowing useful quick sequences like:-

u
p s
b
g d 10
q

go on its own searches for 100 ms.

Piece square tables

The pst command prints, sets and resets the piece square tables, so a page or a script can restyle the engine without editing it. Pieces are p n b r q k, which means both colours with black mirrored, or wn, bq etc for one colour. Squares are absolute, e4 is e4 for either colour. Values are in centipawns a1 to h8, mg is middlegame and eg endgame. Not case sensitive. Any change clears the hash.

• pst - print all 24 tables, one line each, e.g. pst wn mg <64 values>.
• pst n or pst wn mg - print some of them.
• pst n mg e4 25 - set one square, white e4 and black e5.
• pst bn mg e4 25 - set one square for black only.
• pst n mg <64 values> - set a table, a printed line can be pasted back.
• pst n mg def, pst n def, pst def - reset a table, a piece or everything to the PeSTO values.

Command line

Naddu can also be started from a command line using Node or Bun:-

node naddu.js

Or give it commands:-

bun naddu.js uci ucinewgame "position startpos" "go depth 8"

Creating binaries

You can create executables using Bun:-

bun build naddu.js --compile --minify --target=bun-windows-x64   --outfile=naddu-win-x64
bun build naddu.js --compile --minify --target=bun-windows-arm64 --outfile=naddu-win-arm64
bun build naddu.js --compile --minify --target=bun-linux-x64     --outfile=naddu-linux-x64
bun build naddu.js --compile --minify --target=bun-linux-arm64   --outfile=naddu-linux-arm64
bun build naddu.js --compile --minify --target=bun-darwin-x64    --outfile=naddu-mac-x64
bun build naddu.js --compile --minify --target=bun-darwin-arm64  --outfile=naddu-mac-arm64

The Linux arm64 binary runs on a Raspberry Pi 3 or later with a 64-bit OS. Add -musl to the Linux targets for Alpine.

This site is open source. Improve this page.