matrix.matrix_based_game
========================

.. py:module:: matrix.matrix_based_game

.. autoapi-nested-parse::

   Matrix-Based Game Script
   =========================
   This script implements a matrix-based game where players interact with a grid of
   elements. The primary goals are to:
   - Identify connected elements of the same type from a selected position.
   - Remove those elements, adjust the matrix by simulating gravity, and reorganize empty
     columns.
   - Calculate and display the score based on the number of elements removed in each move.

   Functions:
   -----------
   1. `find_repeat`: Finds all connected elements of the same type.
   2. `increment_score`: Calculates the score for a given move.
   3. `move_x`: Simulates gravity in a column.
   4. `move_y`: Reorganizes the matrix by shifting columns leftward when a column becomes
       empty.
   5. `play`: Executes a single move, updating the matrix and returning the score.

   Input Format:
   --------------
   1. Matrix size (`lines`): Integer specifying the size of the matrix (N x N).
   2. Matrix content (`matrix`): Rows of the matrix, each consisting of characters.
   3. Number of moves (`movs`): Integer indicating the number of moves.
   4. List of moves (`movements`): A comma-separated string of coordinates for each move.

   (0,0) position starts from first left column to last right, and below row to up row


   Example Input:
   ---------------
   4
   RRBG
   RBBG
   YYGG
   XYGG
   2
   0 1,1 1

   Example (0,0) = X

   Output:
   --------
   The script outputs the total score after processing all moves.

   Usage:
   -------
   Run the script and provide the required inputs as prompted.



Attributes
----------

.. autoapisummary::

   matrix.matrix_based_game.size


Functions
---------

.. autoapisummary::

   matrix.matrix_based_game.find_repeat
   matrix.matrix_based_game.increment_score
   matrix.matrix_based_game.move_x
   matrix.matrix_based_game.move_y
   matrix.matrix_based_game.parse_moves
   matrix.matrix_based_game.play
   matrix.matrix_based_game.process_game
   matrix.matrix_based_game.validate_matrix_content
   matrix.matrix_based_game.validate_matrix_size
   matrix.matrix_based_game.validate_moves


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

.. py:function:: find_repeat(matrix_g: list[list[str]], row: int, column: int, size: int) -> set[tuple[int, int]]

   Finds all connected elements of the same type from a given position.

   >>> find_repeat([['A', 'B', 'A'], ['A', 'B', 'A'], ['A', 'A', 'A']], 0, 0, 3)
   {(1, 2), (2, 1), (0, 0), (2, 0), (0, 2), (2, 2), (1, 0)}
   >>> find_repeat([['-', '-', '-'], ['-', '-', '-'], ['-', '-', '-']], 1, 1, 3)
   set()


.. py:function:: increment_score(count: int) -> int

   Calculates the score for a move based on the number of elements removed.

   >>> increment_score(3)
   6
   >>> increment_score(0)
   0


.. py:function:: move_x(matrix_g: list[list[str]], column: int, size: int) -> list[list[str]]

   Simulates gravity in a specific column.

   >>> move_x([['-', 'A'], ['-', '-'], ['-', 'C']], 1, 2)
   [['-', '-'], ['-', 'A'], ['-', 'C']]


.. py:function:: move_y(matrix_g: list[list[str]], size: int) -> list[list[str]]

   Shifts all columns leftward when an entire column becomes empty.

   >>> move_y([['-', 'A'], ['-', '-'], ['-', 'C']], 2)
   [['A', '-'], ['-', '-'], ['-', 'C']]


.. py:function:: parse_moves(input_str: str) -> list[tuple[int, int]]

   >>> parse_moves("0 1, 1 1")
   [(0, 1), (1, 1)]
   >>> parse_moves("0 1, 1 1, 2")
   Traceback (most recent call last):
       ...
   ValueError: Each move must have exactly two numbers.
   >>> parse_moves("0 1, 1 1, 2 4 5 6")
   Traceback (most recent call last):
       ...
   ValueError: Each move must have exactly two numbers.


.. py:function:: play(matrix_g: list[list[str]], pos_x: int, pos_y: int, size: int) -> tuple[list[list[str]], int]

   Processes a single move, updating the matrix and calculating the score.

   >>> play([['R', 'G'], ['R', 'G']], 0, 0, 2)
   ([['G', '-'], ['G', '-']], 3)


.. py:function:: process_game(size: int, matrix: list[str], moves: list[tuple[int, int]]) -> int

   Processes the game logic for the given matrix and moves.

   Args:
       size (int): Size of the game board.
       matrix (List[str]): Initial game matrix.
       moves (List[Tuple[int, int]]): List of moves as (x, y) coordinates.

   Returns:
       int: The total score obtained.
   >>> process_game(3, ['aaa', 'bbb', 'ccc'], [(0, 0)])
   6


.. py:function:: validate_matrix_content(matrix: list[str], size: int) -> None

   Validates that the number of elements in the matrix matches the given size.

   >>> validate_matrix_content(['aaaa', 'aaaa', 'aaaa', 'aaaa'], 3)
   Traceback (most recent call last):
       ...
   ValueError: The matrix dont match with size.
   >>> validate_matrix_content(['aa%', 'aaa', 'aaa'], 3)
   Traceback (most recent call last):
       ...
   ValueError: Matrix rows can only contain letters and numbers.
   >>> validate_matrix_content(['aaa', 'aaa', 'aaaa'], 3)
   Traceback (most recent call last):
       ...
   ValueError: Each row in the matrix must have exactly 3 characters.


.. py:function:: validate_matrix_size(size: int) -> None

   >>> validate_matrix_size(-1)
   Traceback (most recent call last):
       ...
   ValueError: Matrix size must be a positive integer.


.. py:function:: validate_moves(moves: list[tuple[int, int]], size: int) -> None

   >>> validate_moves([(1, 2), (-1, 0)], 3)
   Traceback (most recent call last):
       ...
   ValueError: Move is out of bounds for a matrix.


.. py:data:: size