Integration Guide

Typical Usage Pattern

The following code illustrates the typical call sequence for executing an engine move:

#include "board_interpreter.h"

// 1. Receive occupancy from the engine
Bitboard occupancy = engine.getOccupancyBitboard();

// 2. Set up the physical board
PhysicalBoard board;
board.setOccupancy(occupancy);

// 3. Build the physical move descriptor
PhysicalMove move;
move.from      = BoardCoord::fromFEN("e2");
move.to        = BoardCoord::fromFEN("e4");
move.pieceType = PAWN;
move.isCapture = false;

// 4. Plan the move
MovePlan plan = planMove(board, move);

// 5. Check validity and dispatch
if (!plan.isValid) {
    fprintf(stderr, "Board interpreter error: %s\n", plan.errorMessage);
    return;
}

// 6. Hand off to gantry controller
gantryController.executePlan(plan);

Capture Moves

For capture moves, set PhysicalMove::isCapture = true. The board interpreter itself does not remove the captured piece from the occupancy bitboard — it treats the destination square as empty for path-planning purposes (by excluding it from blocker detection). The gantry controller is responsible for lifting the captured piece off the board before the primary move begins, using the off-board staging area defined in the gantry configuration.

Special Chess Moves

Castling

Castling must be decomposed into two PhysicalMove operations by the game controller before being passed to the board interpreter:

1. King move: e.g. e1 -> g1

2. Rook move: e.g. h1 -> f1

Each is planned independently and the resulting MovePlan values are executed in sequence. The game controller layer in game_controller.cpp is responsible for this decomposition.

En Passant

En passant is handled similarly: the pawn’s physical move is planned normally, and the capture of the opponent’s pawn (which sits on a different square from the destination) is an additional operation the game controller schedules separately.

Promotion

Promotion is transparent to the board interpreter. The pawn moves to the back rank and the piece identity change is an engine-level concern; the physical gantry simply moves the pawn and the game controller then coordinates any physical piece swap with the captured-piece area.