haive.games.checkers.state_manager
==================================

.. py:module:: haive.games.checkers.state_manager

.. autoapi-nested-parse::

   Checkers game state management module.

   This module provides comprehensive state management functionality for the classic
   Checkers game, including board management, move validation, jump detection, and
   king promotion handling.

   Checkers is a classic strategy game played on an 8×8 board with 64 squares, using
   only the dark squares. Each player starts with 12 pieces on their side of the board.
   Regular pieces move diagonally forward, but kings can move diagonally in any direction.
   Players capture opponent pieces by jumping over them, and multiple jumps are possible.

   Classes:
       CheckersStateManager: Main state management class for checkers operations.

   .. rubric:: Example

   Basic checkers game setup and play:

       >>> from haive.games.checkers.state_manager import CheckersStateManager
       >>> from haive.games.checkers.models import CheckersMove
       >>>
       >>> # Initialize standard checkers game
       >>> state = CheckersStateManager.initialize()
       >>> print(f"Current player: {state.current_player}")  # "red"
       >>> print(f"Board size: 8x8 with {len(state.pieces)} total pieces")
       >>>
       >>> # Get legal moves (including mandatory jumps)
       >>> legal_moves = CheckersStateManager.get_legal_moves(state)
       >>> print(f"Available moves: {len(legal_moves)}")
       >>>
       >>> # Make a move
       >>> if legal_moves:
       ...     move = legal_moves[0]
       ...     new_state = CheckersStateManager.apply_move(state, move)
       ...     print(f"Move applied: {move.from_square} to {move.to_square}")

   .. note::

      - Uses standard 8×8 checkers board with 64 squares (only dark squares used)
      - Players are "red" and "black" with red moving first
      - Mandatory jump rule: if a jump is available, it must be taken
      - Kings are promoted when pieces reach the opposite end of the board
      - Multiple jumps in sequence are supported when available



Classes
-------

.. autoapisummary::

   haive.games.checkers.state_manager.CheckersStateManager


Module Contents
---------------

.. py:class:: CheckersStateManager

   Manager for checkers game state.

   This class provides static methods for managing checkers game states:
       - Game initialization with default settings
       - Legal move generation (including mandatory jumps)
       - Move application with validation
       - Analysis updates
       - Game status checks
       - King promotion handling

   The manager implements a functional approach where methods take the current
   state and return a new state, rather than modifying the state in place.

   .. attribute:: BOARD_SIZE

      Size of the checkers board (8x8)

      :type: int


   .. py:method:: apply_move(state, move)
      :classmethod:


      Apply a move to the current game state.

      Takes a move and applies it to the current state, returning a new state.
      Handles piece movement, captures, king promotion, and game status updates.

      :param state: Current game state
      :type state: CheckersState
      :param move: Move to apply
      :type move: CheckersMove

      :returns: New game state after the move
      :rtype: CheckersState

      .. rubric:: Examples

      >>> state = CheckersStateManager.initialize()
      >>> moves = CheckersStateManager.get_legal_moves(state)
      >>> new_state = CheckersStateManager.apply_move(state, moves[0])
      >>> new_state.turn
      'black'
      >>> len(new_state.move_history)
      1



   .. py:method:: check_game_status(state)
      :classmethod:


      Check and update the game status.

      Evaluates the current game state to determine if the game is over
      and who the winner is, if any.

      Game-ending conditions include:
      - A player has no pieces left
      - A player has no legal moves

      :param state: Current game state
      :type state: CheckersState

      :returns: Updated game state with correct status
      :rtype: CheckersState



   .. py:method:: get_legal_moves(state)
      :classmethod:


      Get all legal moves for the current player.

      Checks for all legal moves in the current position, following checkers rules:
      - If jump moves are available, only jump moves are returned (mandatory jumps)
      - Otherwise, regular moves are returned
      - Kings can move in all diagonal directions
      - Regular pieces can only move forward (down for black, up for red)

      :param state: Current game state
      :type state: CheckersState

      :returns: List of legal moves for the current player
      :rtype: list[CheckersMove]

      .. rubric:: Examples

      >>> state = CheckersStateManager.initialize()
      >>> moves = CheckersStateManager.get_legal_moves(state)
      >>> len(moves) > 0
      True
      >>> all(move.player == "red" for move in moves)
      True



   .. py:method:: initialize()
      :classmethod:


      Initialize a new checkers game.

      Creates a fresh checkers game state with the standard starting board
      configuration, red to move first, and initial values for all tracking fields.

      :returns: A new game state with the initial board setup.
      :rtype: CheckersState

      .. rubric:: Examples

      >>> state = CheckersStateManager.initialize()
      >>> state.turn
      'red'
      >>> state.game_status
      'ongoing'
      >>> len(state.move_history)
      0



   .. py:method:: update_analysis(state, analysis, player)
      :classmethod:


      Update the state with new analysis.

      Adds new position analysis data to the state for the specified player,
      keeping only the most recent analyses.

      :param state: Current game state
      :type state: CheckersState
      :param analysis: Analysis data to add
      :type analysis: dict[str, Any]
      :param player: Player the analysis is for ("red" or "black")
      :type player: str

      :returns: Updated game state with new analysis
      :rtype: CheckersState