Data Structures

BoardCoord

BoardCoord is the fundamental coordinate type used throughout the module. It represents a single square on the physical board.

struct BoardCoord {
    int row;
    int col;

    BoardCoord();
    BoardCoord(int r, int c);

    bool operator==(const BoardCoord& other) const;
    bool operator!=(const BoardCoord& other) const;
    bool operator<(const BoardCoord& other) const;

    int toSquareIndex() const;
    static BoardCoord fromSquareIndex(int square);
    static BoardCoord fromFEN(const char* str);
    void toFEN(char* out) const;
};

Member Functions

toSquareIndex() const — Method

Parameters: None

Returns: int – square index in range [0, 63]

Converts the (row, col) coordinate to a linear square index using the formula row * 8 + col. This index is compatible with the bitboard representation used by the Kirin engine.

fromSquareIndex(int square) — Static Method

Parameters: square – linear index [0, 63]

Returns: BoardCoord

Constructs a BoardCoord from a square index. Inverse of toSquareIndex.

fromFEN(const char* str) — Static Method

Parameters: str – two-character FEN string, e.g. "e4"

Returns: BoardCoord

Parses a FEN algebraic square name into physical (row, col) coordinates. The file character (a–h) maps to column 0–7 and the rank digit (1–8) is flipped to row 7–0 respectively. Returns BoardCoord(0,0) on invalid input.

toFEN(char* out) const — Method

Parameters: out – output buffer of at least 3 bytes

Returns: void

Serialises the coordinate back to a two-character FEN algebraic string followed by a null terminator. Inverse of fromFEN.

Ordering

The operator< overload allows BoardCoord values to be stored in std::set and std::map containers. Ordering is row-major: coordinates are compared first by row, then by column.

Path

A Path is an ordered sequence of squares that the gantry head must visit while carrying a piece. The first element is the first square entered after the starting position, and the last element is the destination square.

struct Path {
    std::vector<BoardCoord> squares;

    void append(const BoardCoord& coord);
    void clear();
    int length() const;
    bool empty() const;
    BoardCoord destination() const;
};

Note

Paths do not include the source square. They contain every intermediate square the gantry crosses plus the final destination, making the length equal to the number of squares traversed (not the chess-move distance).

PieceType

An enum identifying the type of piece involved in a move. The board interpreter uses this to select the appropriate path generation algorithm.

enum PieceType {
    PAWN, KNIGHT, BISHOP, ROOK, QUEEN, KING, UNKNOWN
};

When PieceType is UNKNOWN, the path generator falls back to inferring the movement style from the geometric relationship between source and destination squares.

PhysicalMove

Encapsulates a single physical piece movement: where a piece starts, where it ends, what type it is, and whether the move is a capture.

struct PhysicalMove {
    BoardCoord from;
    BoardCoord to;
    PieceType  pieceType;
    bool       isCapture;
};

RelocationPlan

Represents the plan to temporarily move a single blocking piece out of the way of a primary piece move. It records both the source and destination parking square, and the A*-computed path the gantry will follow.

struct RelocationPlan {
    BoardCoord from;
    BoardCoord to;
    Path       path;
};

MovePlan

The top-level output of the board interpreter. A MovePlan is a fully ordered execution plan for one chess move on the physical board.

struct MovePlan {
    std::vector<RelocationPlan> relocations;   // blocker moves (pre-primary)
    PhysicalMove                primaryMove;    // the chess move itself
    Path                        primaryPath;    // gantry path for primary piece
    std::vector<RelocationPlan> restorations;  // return parked pieces
    bool                        isValid;
    const char*                 errorMessage;
};

The gantry controller executes these fields in order:

1. All relocations in sequence

2. The primaryMove along primaryPath

3. All restorations in sequence

PhysicalBoard

PhysicalBoard maintains a temporary occupancy model of the board that the planner mutates during simulation without affecting the engine’s actual position state.

class PhysicalBoard {
public:
    static const int BOARD_SIZE = 8;

    PhysicalBoard();

    void     setOccupancy(Bitboard occ);
    Bitboard getOccupancy() const;

    bool isOccupied(const BoardCoord& coord) const;
    bool isOccupied(int row, int col) const;
    bool isEmpty(const BoardCoord& coord) const;
    bool isEmpty(int row, int col) const;

    static bool isValidSquare(const BoardCoord& coord);
    static bool isValidSquare(int row, int col);

    // Temporary state modification for planning
    void setOccupied(const BoardCoord& coord);
    void clearSquare(const BoardCoord& coord);
    void movePiece(const BoardCoord& from, const BoardCoord& to);

    void print() const;

private:
    Bitboard occupied;   // Bit N set => square N is occupied
};

Occupancy is stored as a single 64-bit integer (Bitboard) matching the engine’s bit layout (bit 0 = a8, bit 63 = h1). The state-mutation methods (setOccupied, clearSquare, movePiece) are used exclusively during move planning on a local copy of the board; they are never called on the authoritative engine state.