Move Planning

planMove

planMove(PhysicalBoard& board, const PhysicalMove& move) — Function

Parameters: board – current physical board state (will be read but not permanently modified); move – the physical chess move to plan

Returns: MovePlan – complete execution plan

This is the primary entry point for the board interpreter. It orchestrates all sub-systems to produce the complete MovePlan. The board parameter is passed by reference to allow temporary mutation during planning via a local copy; the original is not modified.

Planning Algorithm

1. Generate candidate paths for the primary piece by calling generatePath(move).

2. Select the best path using selectBestPath, which minimises the number of blockers.

3. Identify all blockers on the chosen path using findBlockers. Intermediate squares only; the destination is excluded.

4. Build the exclusion set containing every square on the primary path and the primary piece’s source square.

5. Copy the board into tempBoard. All subsequent mutations happen on this copy.

6. Plan blocker relocations: for each blocker call planBlockerRelocation, which recursively handles secondary blockers and appends RelocationPlan entries to plan.relocations.

7. Apply the primary move to tempBoard so the restored post-move board state is available for restoration path planning.

8. Plan restorations: iterate over relocations in reverse order (LIFO). For each relocation, call findClearPath from the parking spot back to the piece’s original square. During execution, the gantry follows this restoration path when it exists; if no clear path exists, the path is left empty and the gantry controller falls back to a direct move.

9. Mark the plan valid and return.

Error Handling

MovePlan.isValid is set to false and MovePlan.errorMessage is populated in the following failure cases:

Condition	Error Message
No paths generated for piece type	"No paths generated for move"
selectBestPath returns empty	"No valid path found"
Blocker cannot be relocated	"Cannot relocate blocker (position too constrained)"

MovePlan failure modes

Warning

If planMove returns an invalid plan, the gantry controller must not attempt to execute it. The game controller layer is responsible for checking MovePlan.isValid before dispatching commands.