Zug, from
first principles.
A chess engine small enough to understand. Every board index, legal move, and pruned branch built by hand.
The point was to understand it.
I didn’t build Zug to challenge Stockfish. I wanted to understand the machinery underneath a chess engine: how a position is represented, what makes a move legal, and how a program chooses between possible futures.
A chess library would have hidden the most interesting parts. So I started with a board, wrote the move generator, and added a search. The design stayed deliberately small: no chess library, no elaborate evaluator, and no custom GUI.
Give each part one job.
The engine separates command handling, board state, move generation, search, and evaluation. A Game object owns the position and exposes operations such as loading FEN, finding legal moves, checking the king, and searching for a best move.
Keeping those responsibilities separate made it easier to reason about a failure. An incorrect move could be traced to the board or generator before blaming the search.
A board with room around it.
The board is a flat std::array<int, 120>. Sixty-four cells are playable squares. The other 56 are sentinels: one column on either side and two rows above and below.
A sliding piece walks through the array using a direction offset. One file is an offset of 1; one rank is an offset of 10. A sentinel ends the walk. There is no need to translate every step back into a row and column to detect the edge.
Board illustration · Knight moves only, independent of engine search.
The extra rows matter for knights. A knight can jump two ranks in one move. The padding keeps those jumps inside the allocated array, landing on a sentinel when they leave the playable board. The representation trades compactness for simple, explicit boundary handling.
Bitboards are a powerful alternative. The mailbox was the better starting point for this project because I could inspect an index and explain what it meant.
Generate first. Check legality second.
A piece can move according to its movement rules and still expose its own king. Zug handles these as two separate questions.
If the king is safe after the move, keep it. Otherwise, discard it. Either way, restore the position before considering the next candidate. This makes the legality rule easy to state and test, even though it performs more work than a highly specialized generator.
The tricky cases are stateful: castling, en passant, and promotion. They change more than a piece’s destination square, so they cannot be treated as ordinary moves with a few visual exceptions.
Undo is part of the algorithm.
Search repeatedly makes and unmakes moves. Copying the entire board for every candidate would add work at every node. Instead, each move records the small amount of information needed to reverse its effects.
The undo record preserves captured material and the previous position state, including castling rights and the en passant square. Castling also requires restoring the rook. A promotion must restore the original pawn.
The important invariant is simple: make a move, then undo it, and the complete state must be identical. Getting this right matters more than making the first search clever. A fast search over a corrupted board is still wrong.
Look ahead. Skip what cannot matter.
Chess is zero-sum, which lets a single negamax function serve both players. A score that is good for one side is equally bad for the other. A recursive call changes the side to move and negates the returned score.
score = -search(next_side, depth - 1, -beta, -alpha);Alpha-beta pruning avoids exploring branches that cannot improve the choice already available. Alpha records the lower bound for the current player. Beta supplies the cutoff imposed by the opposing side. A score at or above beta lets the search stop investigating that branch.
Stopping at a fixed depth introduces another problem: a leaf may fall in the middle of a capture sequence. Scoring the position there can mistake a temporary material gain for a good move.
Zug adds quiescence search at the frontier, extending the search through captures before evaluating a quieter position. It is a targeted response to the horizon effect, rather than simply searching every continuation deeper.
Keep the evaluator boring.
The evaluator counts material from the active player’s point of view. There are no positional bonuses for pawn structure, piece activity, or king safety.
This was a deliberate constraint. It kept the scoring function understandable while I worked on legal moves, deeper search, and reliable state restoration. The value assigned to a king is part of the source’s simple material table; king safety and terminal positions still need their own chess rules.
Use a protocol. Borrow the interface.
Zug communicates through UCI, using text over standard input and output. That allowed existing chess interfaces and tournament tools to drive the engine without a custom board renderer.
It also kept the project focused. I could spend time on move generation and search while tools such as Arena and Cute Chess handled presentation and matches.
Correctness before strength.
The most useful tests targeted transitions that are easy to get almost right:
- Castling: reject blocked or otherwise illegal castles, and correctly update both pieces when castling is allowed.
- King safety: reject any move that leaves the moving side’s king in check.
- En passant: remove the captured pawn from the correct square and restore it on undo.
- FEN parsing: reconstruct the board and the side to move from a position string.
- Search sanity: return a legal move when a move is available.
The original benchmark recorded 100 games against a Stockfish opponent configured at 1400, with a 24% score. The write-up estimated Zug at roughly 1200 Elo under that setup. That is a rough result from one match configuration, rather than a calibrated rating across opponents and time controls.
What I would carry into the next engine.
Make/unmake deserves its own tests. Search improvements are easier to evaluate when the scoring function is simple. Choosing a protocol early saves building tools that are not the point of the project.
Most of all, a chess engine is too stateful to verify by playing a few games and deciding that it looks right. Each special move, restoration step, and search boundary needs an automated check.
Zug’s value to me is that I can follow the whole chain: from a UCI command, through an array index and a legal move, to a search decision. Small enough to hold in my head. Complete enough to teach me something.