haive.games.mafia.state
=======================

.. py:module:: haive.games.mafia.state

.. autoapi-nested-parse::

   Game state models for the Mafia game.

   This module defines the core state model for the Mafia game, extending the
   base MultiPlayerGameState with Mafia-specific functionality.

   The state model tracks:
       - Player roles and statuses
       - Game phase and progression
       - Voting and action history
       - Public announcements
       - Night action outcomes

   .. rubric:: Examples

   >>> from mafia.state import MafiaGameState
   >>> from mafia.models import PlayerRole, GamePhase
   >>>
   >>> # Create a new game state
   >>> state = MafiaGameState(
   ...     players=["Player_1", "Player_2", "Narrator"],
   ...     roles={"Player_1": PlayerRole.VILLAGER,
   ...            "Player_2": PlayerRole.MAFIA,
   ...            "Narrator": PlayerRole.NARRATOR},
   ...     game_phase=GamePhase.SETUP
   ... )



Classes
-------

.. autoapisummary::

   haive.games.mafia.state.MafiaGameState


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

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

   Bases: :py:obj:`haive.games.framework.multi_player.state.MultiPlayerGameState`


   State model for a Mafia game.

   This class extends MultiPlayerGameState to provide Mafia-specific state
   tracking, including roles, votes, and game progression.

   .. attribute:: players

      List of player names/IDs

      :type: List[str]

   .. attribute:: current_player_idx

      Index of current player in players list

      :type: int

   .. attribute:: game_status

      Status of the game (ongoing, ended)

      :type: str

   .. attribute:: move_history

      History of moves

      :type: List[Dict[str, Any]]

   .. attribute:: round_number

      Current round number

      :type: int

   .. attribute:: player_data

      Player-specific data

      :type: Dict[str, Dict[str, Any]]

   .. attribute:: public_state

      Public game state visible to all

      :type: Dict[str, Any]

   .. attribute:: error_message

      Error message if any

      :type: Optional[str]

   .. attribute:: game_phase

      Current phase of the game

      :type: GamePhase

   .. attribute:: roles

      Mapping of player IDs to roles

      :type: Dict[str, PlayerRole]

   .. attribute:: player_states

      Player state information

      :type: Dict[str, PlayerState]

   .. attribute:: votes

      Player votes during voting phase

      :type: Dict[str, str]

   .. attribute:: action_history

      History of all actions

      :type: List[Dict[str, Any]]

   .. attribute:: public_announcements

      Public game announcements

      :type: List[str]

   .. attribute:: alive_mafia_count

      Number of mafia members alive

      :type: int

   .. attribute:: alive_village_count

      Number of villagers alive

      :type: int

   .. attribute:: alive_doctor_count

      Number of doctors alive

      :type: int

   .. attribute:: alive_detective_count

      Number of detectives alive

      :type: int

   .. attribute:: killed_at_night

      Player targeted by mafia

      :type: Optional[str]

   .. attribute:: saved_at_night

      Player saved by doctor

      :type: Optional[str]

   .. attribute:: night_deaths

      Players who died during the night

      :type: List[str]

   .. attribute:: day_number

      Current day number

      :type: int

   .. attribute:: winner

      Winner (village or mafia)

      :type: Optional[str]

   .. rubric:: Examples

   >>> state = MafiaGameState(
   ...     players=["Player_1", "Player_2", "Narrator"],
   ...     roles={"Player_1": PlayerRole.VILLAGER,
   ...            "Player_2": PlayerRole.MAFIA,
   ...            "Narrator": PlayerRole.NARRATOR},
   ...     game_phase=GamePhase.SETUP
   ... )
   >>> print(state.game_phase)  # Shows SETUP

   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:: add_public_announcement(announcement)

      Add an announcement to the public record.

      :param announcement: The announcement to add
      :type announcement: str

      .. rubric:: Examples

      >>> state.add_public_announcement("Night falls on the village.")
      >>> print(state.public_announcements[-1])



   .. py:method:: log_action(action)

      Log an action in the game history.

      This method records player and narrator actions in both the action_history
      and move_history, ensuring proper serialization of complex objects.

      :param action: Action to log
      :type action: Union[MafiaAction, NarratorAction]

      .. rubric:: Examples

      >>> action = MafiaAction(
      ...     player_id="Player_1",
      ...     action_type=ActionType.VOTE,
      ...     target_id="Player_2",
      ...     phase=GamePhase.DAY_VOTING,
      ...     round_number=1
      ... )
      >>> state.log_action(action)



   .. py:method:: model_copy(*, deep = False, **kwargs)

      Create a copy of the model.

      :param deep: Whether to create a deep copy. Defaults to False.
      :type deep: bool, optional
      :param \*\*kwargs: Additional arguments to pass to model_copy

      :returns: A copy of the current state
      :rtype: MafiaGameState

      .. rubric:: Examples

      >>> new_state = state.model_copy(deep=True)



   .. py:method:: update_alive_counts()

      Update the count of alive players in different roles.

      This method recalculates the number of alive players in each role
      category based on the current player states.

      .. note::

         This should be called after any change that might affect player
         life status (e.g., night kills, voting execution).

      .. rubric:: Examples

      >>> state.player_states["Player_1"].is_alive = False
      >>> state.update_alive_counts()
      >>> print(state.alive_village_count)  # Shows updated count