What counts as a move ?#

A chess engine move is more than source and destination squares. To make and unmake correctly you need:

• from square, to square
• moving piece type and color
• capture piece type (if any) and capture square (which may differ from to for en passant)
• promotion piece type (if any)
• flags for double push, en passant capture, castling (kingside/queenside)
• incremental state: castling rights after the move, en passant file after the move, halfmove clock, Zobrist key delta

The move encoding is not incidental. If you omit the capture square for en passant, your unmake will restore the wrong pawn. If you omit the previous en passant file, you cannot correctly restore the position for repetition detection. Design the move struct before optimizing the generator. The debugging you will do is almost entirely make/unmake symmetry checks.

Castling: four preconditions, often checked as two#

FIDE castling preconditions are, king and the chosen rook have not moved (castling rights), the king is not currently in check, no square the king passes through is under attack, and no piece occupies the squares between king and rook. The third condition is the one most often implemented incompletely.

The Chess Programming Wiki states it precisely. No square between king’s start and final square may be controlled by the enemy. For kingside, that is e1 and f1 and g1 not under attack (white). For queenside, e1, d1, c1 not under attack. And the intermediate squares must be empty. Overlooking that c1 must not be attacked on queenside is a common error that perft on Kiwipete will catch. Kiwipete has castling rights still present and pieces arranged to attack those squares.

Castling rights bookkeeping is the deeper trap. Rights are not “has the king moved” alone. They are per-wing and they are lost if:

• the king moves at all,
• the specific rook moves,
• the specific rook is captured, even if the rook has not moved.

That last case is missed often. If white captures black’s h8 rook, black’s kingside rights evaporate even though black’s king never moved. Represent rights as four bits (KQkq as in FEN) and update them on every move by masking with precomputed castling_mask[from] and castling_mask[to] tables. Do not recompute rights from piece positions. A rook that returns to its home square does not regain rights.

A compact, correct legality check (Python, mailbox or bitboard agnostic):

1
def can_castle_kingside(board, color):
2
    rights = board.castling_rights
3
    if color == WHITE and not (rights & WHITE_KING_SIDE):
4
        return False
5
    if color == BLACK and not (rights & BLACK_KING_SIDE):
6
        return False
7

8
    king_sq = board.king_square(color)
9
    # King must not be in check now
10
    if board.is_attacked(king_sq, opposite(color)):
11
        return False
12

13
    # Squares between must be empty, destination squares not attacked
14
    # White kingside: f1, g1 must be empty; e1, f1, g1 not attacked
15
    # (e1 already tested above; f1,g1 remain)
16
    path_empty, path_safe = castling_path(color, KINGSIDE)
17
    if any(board.piece_at(sq) is not None for sq in path_empty):
18
        return False
19
    if any(board.is_attacked(sq, opposite(color)) for sq in path_safe):
20
        return False
21

22
    return True

castling_path returns two sets: the squares that must be empty (which includes the rook’s transit) and the king’s transit squares that must not be attacked. Keep them separate. Queenside has more empty squares than safe squares, b1 must be empty but the king never steps there.

En passant: the only capture that breaks the destination model#

Every other capture removes the piece on the destination square. En passant removes a pawn that is not there. The capturing pawn moves diagonally onto an empty square. The captured pawn sits adjacent on the same rank the capturing pawn left. Two pawns leave one rank. If you model captures as “piece on to square,” en passant will corrupt the board.

There are three intertwined details:

1. Representation. FEN stores the en passant target square. The square behind the double pushed pawn, on rank 3 or 6. Your board should store the en passant file (or target square) only when a pawn actually double pushed around an enemy pawn that could capture. Some engines set the ep square unconditionally on any double push. Perft implementations historically do this and compare correctly only because both sides agree, but for hashing correctness you should set it only when an enemy pawn is adjacent. The CPW recommends doing the legality test at double-push time and folding the Zobrist key update there to avoid hashing distinct positions as identical.

2. Generation. An en passant capture is pseudo legal if an enemy pawn is adjacent and the ep target square matches. That is trivial.

3. Legality filtering. This is where engines fail. An en passant capture can be illegal due to a horizontal pin that no other move exhibits. Consider:

1
8/6bb/8/8/R1pP2k1/4P3/P7/K7  b - d3  (after d2-d4)

If black plays c4xd3 en passant, both the c4 pawn and the d4 pawn disappear from rank 4, opening a rook line against the king. Neither pawn was pinned vertically. The illegality is only visible after both pawns are removed. A generator that checks “is the moving pawn pinned?” but not “does removing two pawns from the same rank expose the king?” will accept this illegal capture. The correct pseudo legal filter catches it automatically: make the double disappearance, then test isAttacked(king). A direct legal generator that filters pinned pieces without considering the captured pawn’s square will get it wrong.

Implementation shape for make/unmake:

1
def make_en_passant(board, move):
2
    # move.from is the capturing pawn, move.to is the ep target (empty)
3
    board.remove_piece(move.from)
4
    board.place_piece(move.to, move.piece)
5
    # Captured pawn is on the same file as move.to, same rank as move.from
6
    captured_sq = square(move.to.file, move.from.rank)
7
    captured = board.remove_piece(captured_sq)
8
    board.ep_capture_square = captured_sq  # for unmake
9
    return captured
10

11
def unmake_en_passant(board, move, captured):
12
    board.remove_piece(move.to)
13
    board.place_piece(move.from, move.piece)
14
    captured_sq = square(move.to.file, move.from.rank)
15
    board.place_piece(captured_sq, captured)

If you forget to save the captured pawn type (it is always a pawn, but save it anyway for symmetry), or you compute captured_sq as move.to plus/minus one rank, you will swap colors under promotion en-passant adjacent tests and perft will diverge only on the one position that has pawns on the fifth rank with ep rights. Which is exactly Position 3 in the CPW test suite.

Promotion: four moves where you thought there was one#

When a pawn reaches the last rank, the move is not complete until you choose a piece. Perft counts each promotion choice as a distinct leaf. From the start position, promotions first appear at depth 7+ (or earlier in tactical test positions like Position 4, where underpromotions appear at depth 2). If you only generate queen promotions, perft will match at low depth and drift at mid depth, which is the most confusing failure mode because you will blame en passant or castling first.

Generate promotions as an expansion of pawn pushes and pawn captures that land on the promotion rank:

1
PROMOTION_PIECES = [QUEEN, ROOK, BISHOP, KNIGHT]
2

3
def generate_pawn_moves(board, sq, color):
4
    moves = []
5
    forward = 1 if color == WHITE else -1
6
    start_rank = 1 if color == WHITE else 6
7
    promo_rank = 7 if color == WHITE else 0
8

9
    # Single push
10
    to = sq + forward * 8  # assuming 0x88 or linear mailbox; adapt for bitboards
11
    if board.is_empty(to):
12
        if to.rank == promo_rank:
13
            for promo in PROMOTION_PIECES:
14
                moves.append(Move(sq, to, promotion=promo))
15
        else:
16
            moves.append(Move(sq, to))
17
            # Double push, only from start rank, and only if intermediate empty
18
            if sq.rank == start_rank:
19
                to2 = to + forward * 8
20
                if board.is_empty(to2):
21
                    moves.append(Move(sq, two, flag=DOUBLE_PUSH))
22

23
    # Captures
24
    for df in (-1, 1):
25
        cap = square(sq.file + df, sq.rank + forward)
26
        if not on_board(cap):
27
            continue
28
        is_capture = board.piece_at(cap) is not None and board.color_at(cap) != color
29
        is_ep = cap == board.en_passant_target
30
        if is_capture or is_ep:
31
            if cap.rank == promo_rank:
32
                for promo in PROMOTION_PIECES:
33
                    # Capture-promotion: both a capture and a promotion
34
                    moves.append(Move(sq, cap, promotion=promo, capture=is_capture))
35
            elif is_capture or is_ep:
36
                moves.append(Move(sq, cap, capture=is_capture, en_passant=is_ep))
37

38
    return moves

Three notes on this snippet. First, the double push checks the intermediate square to - the is_empty(to) guard above, and then to2. Collapsing that into a single “is to2 empty?” test is wrong. Second, promotion captures where the target is occupied and ep is possible on the same diagonal are distinct; generate both if both conditions hold (rare, but legal). Third, the queen was not always the answer: underpromotion to knight can give check where queen promotion does not, or avoid stalemate. The engine does not get to choose. It must generate all four.

Double pawn push: the smallest bug with the widest blast radius#

The double push rule is one sentence and one bug: the pawn moves two squares forward from its starting rank if both the target square and the square between are empty. The fix is equally small: check both. The blast radius is large because a missed intermediate check creates phantom moves that enable en passant possibilities that never should have existed, and perft divergence compounds exponentially. If perft at depth 1 matches but depth 3 diverges and the delta is a multiple of en passant counts, check double pushes first. It is the cheapest fix with the highest leverage.

The expensive-but-correct filter#

1
generate all pseudo legal moves
2
for each move:
3
    make(move)
4
    if not isAttacked(ownKingSquare, opponent):
5
        keep move
6
    unmake(move)

That is the whole pin and check implementation. A bishop pinned on the a2-g8 diagonal that tries to move off diagonal will leave the king in check after the make. It is discarded. A move that does not resolve a check also leaves the king in check and is discarded. Double check where the king is attacked by two pieces simultaneously, falls out naturally: the only pseudo legal moves that pass the filter are king moves to safe squares, because any block or capture can at most address one attacker.

This is expensive in the sense that you make illegal moves you will discard. It is not expensive in practice once perft passes. Perft enumerates every node. Search does not. Alpha beta plus move ordering means most illegal moves in check positions are never generated because the search terminates early or the check-evasion path prunes. And even in perft, the illegal fraction is modest: in the initial position at depth 5, zero moves are illegal due to pins because no pins exist yet. In Kiwipete, where the position is deliberately dense with pins and checks, the illegal rate is still well under half.

When to generate directly#

There are two legitimate reasons to generate legal moves directly:

1. Check evasion at search time. When in check, only a tiny subset of pseudo legal moves are legal. Generating only king moves, captures of the attacker, and blocks of the ray (if the attacker is a slider) avoids making dozens of doomed moves. The CPW notes that special generators for getting out of check can be more efficient than generating and testing each possible move. This is true and worth doing once the engine is correct.

2. Evasions plus attack-map reuse. With bitboards, you already compute attacks to the king to detect check. Reusing the pinner bitboard and the check-ray bitboard to mask move generation is elegant. The CPW’s Checks and Pinned Pieces (Bitboards) page shows the pattern:

1
U64 attacksToKing(Square kingSq, Color kingColor) {
2
    U64 opPawns   = pieceBB[nBlackPawn   - kingColor];
3
    U64 opKnights = pieceBB[nBlackKnight - kingColor];
4
    U64 opRQ = pieceBB[nBlackQueen - kingColor] | pieceBB[nBlackRook - kingColor];
5
    U64 opBQ = pieceBB[nBlackQueen - kingColor] | pieceBB[nBlackBishop - kingColor];
6
    return (pawnAttacks[kingColor][kingSq] & opPawns)
7
         | (knightAttacks[kingSq]           & opKnights)
8
         | (bishopAttacks(occupied, kingSq) & opBQ)
9
         | (rookAttacks(occupied, kingSq)   & opRQ);
10
}

Pinned pieces then fall out of x-ray attacks:

1
pinned = 0;
2
pinner = xrayRookAttacks(occupied, ownPieces, kingSq) & opRQ;
3
while (pinner) {
4
    Square sq = popLSB(&pinner);
5
    pinned |= obstructed(sq, kingSq) & ownPieces;
6
}
7
pinner = xrayBishopAttacks(occupied, ownPieces, kingSq) & opBQ;
8
while (pinner) {
9
    Square sq = popLSB(&pinner);
10
    pinned |= obstructed(sq, kingSq) & ownPieces;
11
}

The direction disjoint variant (DirGolem) does the same with ray intersections. Both are correct. Both are optimizations of the same invariant: a move is legal if the king is not attacked after it. If you implement either, keep the pseudo legal filter as an assertion in debug builds:

1
assert set(generate_legal_direct(board)) == set(filter_pseudo_legal(board))

Run that assertion under perft. It is the cheapest way to catch a divergence between two implementations of the same geometry.

Check types and their consequences#

• Single check. Three responses: move the king to a non attacked square, capture the attacker (with a piece that is not absolutely pinned off the capture line), or interpose on the ray between attacker and king if the attacker is a sliding piece. A direct generator must handle all three. The pseudo legal filter handles them implicitly.

• Double check. Only king moves. This is not an optimization; it is a rule. No block or capture can address two attackers at once. A common bug is generating interpositions during double check because the “block the ray” code does not check the attacker count. Perft Position 5 is designed to expose this.

• Discovered check. The checker is not the piece that moved but the slider behind it. Detection by last move, testing whether the origin square was on a ray from the king is the cheapest scalar approach. With bitboards, recomputing attacksToKing is branchless and reuses the slider attack tables, so the per-node cost is negligible.

Reference tables you can trust#

The single most useful debugging asset is a set of published perft numbers for positions deliberately chosen to exercise different rule interactions. The CPW’s Perft Results page is the canonical source. Do not invent numbers. Do not approximate. Compare exactly.

Initial position : rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

Higher depths verified by Steven Edwards (Symbolic) through depth 13 and Ankan Banerjee through depth 15 exist but are not needed for move-gen debugging. Depth 5 or 6 from the start position is sufficient to catch most bugs; the breakdown columns (captures, ep, checks) pinpoint which category is wrong.

Kiwipete : r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1 by Peter McKenzie. Dense with promotions, castling, and pins.

If your engine passes the initial position but fails Kiwipete, the bug is almost certainly castling through check, promotion undercount, or a pin that only manifests when the board is crowded.

Position 3 : 8/2p5/3p4/KP5r/1R3p1k/8/4P1P1/8 w - - 0 1 the en passant torture test. Almost every en passant bug, including the double-disappearance discovered check, is exposed here.

Position 4 : r3k2r/Pppp1ppp/1b3nbN/nP6/BBP1P3/q4N2/Pp1P2PP/R2Q1RK1 w kq - 0 1 promotions and underpromotions with checks.

Position 5 : rnbq1k1r/pp1Pbppp/2p5/8/2B5/8/PPP1NnPP/RNBQK2R w KQ - 1 8 discovered checks and double checks. Caught bugs in engines several years old at depth 3.

Position 6 : r4rk1/1pp1qppp/p1np1n2/2b1p1B1/2B1P1b1/P1NP1N2/1PP1QPPP/R4RK1 w - - 0 10 a symmetrical stress test with many captures.

A seventh, often overlooked, is the ep-discovered-check position from the CPW’s en passant discussion, the one with two pawns on the fifth rank and rooks aligned. Keep it in your test suite as a dedicated regression, not just as one node inside a larger perft.

Divide: how to isolate the first bad move#

Perft tells you that you are wrong. Divide tells you where.

Divide enumerates the legal moves at the root and prints the perft of each subtree. Stockfish’s go perft 5 on the start position prints 20 lines, one per first move, with node counts like a2a3: 181046 and e2e4: 405385. When your perft diverges, compare your divide output to a reference (Stockfish, qperft by Harm Geert Muller, or vaulet/perft.txt). Find the first move where the counts differ. That move’s subtree contains the bug.

Iterate: make that move on the board, run perft at depth - 1 from the resulting position, divide again, and follow the divergent branch. Within a handful of steps you converge on a leaf position where perft(1) is wrong, that is, where your move list and the reference move list differ by a single move. At that point the bug is visible: a missing en passant capture, an extra illegal castling, a promotion you did not generate, or a pinned piece that moved off the line.

The workflow is mechanical:

1. Run perft(n) on a reference position. If it matches, go deeper or switch positions.
2. On mismatch, run divide(n) and diff against a trusted divide.
3. Recurse into the first divergent move’s position with perft(n-1).
4. When n == 1, compare move lists directly. The symmetric difference is the bug.

Do not try to debug by staring at generation code. Follow the divide. It turns a tree of billions of nodes into a binary search over depth.

A perft harness you can ship#

Perft is not a one-off script. It is a permanent regression. Wire it as a test, not a manual command.

1
import chess  # for FEN parsing only; generation is yours
2

3
REFERENCE = {
4
    # (fen, depth): expected_nodes
5
    ("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", 5): 4865609,
6
    ("r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1", 4): 4085603,
7
    ("8/2p5/3p4/KP5r/1R3p1k/8/4P1P1/8 w - - 0 1", 5): 674624,
8
    ("r3k2r/Pppp1ppp/1b3nbN/nP6/BBP1P3/q4N2/Pp1P2PP/R2Q1RK1 w kq - 0 1", 4): 422333,
9
    ("rnbq1k1r/pp1Pbppp/2p5/8/2B5/8/PPP1NnPP/RNBQK2R w KQ - 1 8", 4): 2103487,
10
}
11

12
def test_perft():
13
    for (fen, depth), expected in REFERENCE.items():
14
        board = Board.from_fen(fen)
15
        result = board.perft(depth)  # your implementation
16
        assert result == expected, f"perft({depth}) on {fen}: got {result}, expected {expected}"
17

18
def divide(board, depth):
19
    """Print per-move subtree counts for diffing against Stockfish/qperft."""
20
    for move in board.generate_legal_moves():
21
        board.make(move)
22
        nodes = board.perft(depth - 1)
23
        board.unmake(move)
24
        print(f"{move.uci()}: {nodes}")

Run this in CI. Add the ep-discovered-check regression position explicitly. When a future refactor breaks castling rights, you want the failure in a pull request, not in a tournament game where the engine castles through check.

Verification with trusted tooling is also worth doing once: Stockfish’s perft and Muller’s qperft should agree on every reference position. The CPW’s perft results page includes the exact node counts and breakdowns; vajolet/perft.txt on GitHub and perft-random.epd by Marcel van Kervinck provide additional random positions for fuzzing.

Attack maps and incremental update#

isAttacked(square, color) is the most called function in the engine. In perft it is called once per pseudo legal move. In search it is called at every node to test legality and to decide extensions. Its implementation dominates move-gen cost.

Three approaches, in increasing sophistication:

1. Recompute on the fly. For each query, generate attacks from the target square outward and intersect with enemy pieces. With bitboards and magic bitboards (see [[Magic Bitboards]]), bishop and rook attacks are a table lookup plus a few bitwise ops. Knight and pawn attacks are array lookups. King attacks are an array lookup. The total is a handful of 64-bit operations and no persistent state. For most engines this is fast enough and trivially correct. No incremental update to maintain, no attack map to invalidate on make/unmake.

2. Incrementally updated attack maps. Maintain a board-wide attackedBy[color] bitboard updated on every make/unmake. Query becomes attackedBy[them] & (1 << square). Make/unmake cost increases. Every move updates the map, but query cost drops to one AND. This wins only if queries vastly outnumber updates, which they do not in perft (one query per move, one update per make). In search the ratio is more favorable because evaluation queries the same map many times. If you go incremental, the perft-speed comparison must be done with bulk counting disabled, or you are measuring the wrong thing.

3. Last-move check detection. Instead of recomputing attacks to the king, test whether the last move gave check by checking direct attack from move.to and discovered attack from move.from. This avoids a full isAttacked at the cost of branching logic for en passant and promotion. With bitboards the savings are negligible and the branchless isAttacked is simpler. The CPW recommends the on-the-fly approach for bitboard engines for exactly this reason: you already compute rook and bishop attacks for move generation, so reusing them for check detection costs almost nothing.

Bulk counting and hashing#

Two perft-specific speedups dominate reported nodes-per-second numbers. Neither affects search.

• Bulk counting : at depth == 1, return len(generateLegalMoves()) without making the moves. This skips the leaf make/unmake entirely. It is valid only with a legal generator (or with a pseudo legal generator that filters before counting). It roughly doubles speed and is the standard when comparing generator throughput.

• Transposition hashing : memoize perft results by position key (Zobrist). Hashing can speed perft by 1.5x to 4x but introduces a small chance of collision-based miscount. It is also a useful sanity check for Zobrist key correctness: hash perft results and compare with and without hashing, if they differ, the key has a bug, often around en passant or castling rights. The CPW notes this use explicitly.

Both are measurement confounders. When someone reports “1.5 giganodes per second per core” (Gigantua, 2021) or “4 billion nodes per second” (2025 optimization threads), the setup, bulk counting on or off, hashing on or off, language, CPU changes the number by multiples. Compare perft speed only against identical configurations.

Magic bitboards and slider generation#

1
rook_attacks = rook_table[square][(occupied * rook_magic[square]) >> rook_shift[square]]
2
bishop_attacks = bishop_table[square][(occupied * bishop_magic[square]) >> bishop_shift[square]]

Reuse the same tables for move generation and for isAttacked. Do not write a second ray-marcher for one and a magic lookup for the other. The fastest way to introduce a perft bug is to have two implementations of the same geometry that disagree on edge cases. Blockers on the edge of the board, occupied squares at the attack origin.

For move enumeration, sliders contribute a bounded number of moves (at most 14 for a queen on an open board, fewer in practice). The generator loops over attack bitboards by popping least-significant bits:

1
attacks = rook_attacks(square, occupied) & ~own_pieces
2
while attacks:
3
    to = pop_lsb(attacks)
4
    if board.piece_at(to):
5
        moves.append(Move(square, to, capture=True))
6
    else:
7
        moves.append(Move(square, to))

Pawns, again, are the exception: their move set depends on occupancy of specific neighboring squares, not on a precomputed attack table alone. Write pawn generation as explicit square tests, not as a table lookup intersected with occupancy, so the double-push intermediate check and the promotion expansion remain visible.

Order-of-magnitude expectations#

You do not need to hit a target nps to ship. But for calibration:

• A Python pseudo legal generator with mailbox or simple bitboard should do perft(5) from the start position (4.8M nodes) in seconds, not minutes. If it takes minutes, the bottleneck is usually Python loops over 64 squares per piece rather than the attack computation.

• A Python generator with python-chess as a reference comparison will be slower than a C++ engine by 100-1000x on raw perft. That is fine. Perft in Python is for correctness, not for benchmarking search speed.

• Depth scales exponentially. Perft(6) from the start position is 119M nodes, roughly 24x perft(5). Perft(7) is 3.1B. Do not run perft(7) from Python without bulk counting as a smoke test. Use perft(5) plus Kiwipete 4 and Position 3 depth 5 as the standard regression. They cover the rule interactions without requiring hours.