haive.games.single_player.flow_free.state
=========================================

.. py:module:: haive.games.single_player.flow_free.state

.. autoapi-nested-parse::

   State model for Flow Free game.

   This module defines the game state for Flow Free, tracking the board, flows, and game
   progress.



Classes
-------

.. autoapisummary::

   haive.games.single_player.flow_free.state.Cell
   haive.games.single_player.flow_free.state.Flow
   haive.games.single_player.flow_free.state.FlowEndpoint
   haive.games.single_player.flow_free.state.FlowFreeState


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

.. py:class:: Cell(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   A cell on the Flow Free board.

   .. attribute:: position

      Position of the cell.

   .. attribute:: flow_id

      ID of the flow occupying this cell, if any.

   .. attribute:: is_endpoint

      Whether this cell contains an endpoint.

   .. attribute:: pipe_direction

      Direction of the pipe in this cell, if any.

   Create a new model by parsing and validating input data from keyword arguments.

   Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
   validated to form a valid model.

   `self` is explicitly positional-only to allow `self` as a field name.


.. py:class:: Flow(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   A flow in Flow Free, consisting of two endpoints and a path of pipes.

   .. attribute:: id

      Unique identifier for the flow.

   .. attribute:: color

      Color of the flow.

   .. attribute:: start

      Starting endpoint.

   .. attribute:: end

      Ending endpoint.

   .. attribute:: path

      List of positions forming the path between endpoints.

   .. attribute:: completed

      Whether the flow is complete (endpoints connected).

   Create a new model by parsing and validating input data from keyword arguments.

   Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
   validated to form a valid model.

   `self` is explicitly positional-only to allow `self` as a field name.


.. py:class:: FlowEndpoint(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   An endpoint (colored dot) in Flow Free.

   .. attribute:: position

      Position of the endpoint on the board.

   .. attribute:: is_start

      Whether this is the start endpoint (otherwise it's the end).

   Create a new model by parsing and validating input data from keyword arguments.

   Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
   validated to form a valid model.

   `self` is explicitly positional-only to allow `self` as a field name.


.. py:class:: FlowFreeState(/, **data)

   Bases: :py:obj:`haive.games.single_player.base.SinglePlayerGameState`


   State for the Flow Free game.

   .. attribute:: rows

      Number of rows in the grid.

   .. attribute:: cols

      Number of columns in the grid.

   .. attribute:: grid

      2D grid of cells.

   .. attribute:: flows

      Dictionary of flows by ID.

   .. attribute:: current_flow_id

      ID of the currently selected flow.

   .. attribute:: puzzle_id

      Identifier for the current puzzle.

   .. attribute:: hints_used

      Number of hints used.

   Create a new model by parsing and validating input data from keyword arguments.

   Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
   validated to form a valid model.

   `self` is explicitly positional-only to allow `self` as a field name.


   .. py:method:: get_adjacent_positions(position)

      Get all valid adjacent positions.

      :param position: Position to get adjacent positions for.

      :returns: List of adjacent positions.



   .. py:method:: get_cell(position)

      Get the cell at the specified position.

      :param position: Position to get the cell for.

      :returns: The cell at the position, or None if out of bounds.



   .. py:method:: is_cell_empty(position)

      Check if a cell is empty.

      :param position: Position to check.

      :returns: True if the cell is empty, False otherwise.



   .. py:method:: is_cell_endpoint(position)

      Check if a cell contains an endpoint.

      :param position: Position to check.

      :returns: True if the cell contains an endpoint, False otherwise.



   .. py:method:: to_display_string()

      Generate a string representation of the board for display.

      :returns: A formatted string representation of the board.



   .. py:property:: board_fill_percentage
      :type: float


      Calculate the percentage of the board that is filled.


   .. py:property:: completion_percentage
      :type: float


      Calculate the percentage of flows completed.


   .. py:property:: filled_cells
      :type: int


      Calculate the number of filled cells on the board.


   .. py:property:: is_solved
      :type: bool


      Check if the puzzle is solved.

      The puzzle is solved when all flows are completed and all cells are filled.


   .. py:property:: total_cells
      :type: int


      Calculate the total number of cells on the board.