haive.games.among_us.state_manager ================================== .. py:module:: haive.games.among_us.state_manager .. autoapi-nested-parse:: Comprehensive state management mixin for Among Us social deduction gameplay. This module provides the core state management functionality for Among Us games, handling complex game mechanics including role assignments, task management, sabotage systems, meeting coordination, and win condition evaluation. The state manager coordinates all gameplay elements for authentic Among Us experiences. The state manager handles: - Game initialization with role assignments and task generation - Move validation and application for all player actions - Complex sabotage mechanics with resolution systems - Meeting and voting coordination - Win condition evaluation and game progression - Player state filtering for information hiding - Legal move generation for AI decision-making .. rubric:: Examples Initializing a game:: state = AmongUsStateManagerMixin.initialize( player_names=["Alice", "Bob", "Charlie", "David", "Eve"], map_name="skeld", num_impostors=1 ) Applying player moves:: move = {"action": "move", "location": "electrical"} new_state = AmongUsStateManagerMixin.apply_move(state, "Alice", move) Checking game status:: updated_state = AmongUsStateManagerMixin.check_game_status(state) if updated_state.game_status == "ended": print(f"Game over! Winner: {updated_state.winner}") .. note:: This is a mixin class designed to be inherited by game agents, providing state management capabilities without agent-specific behavior. Classes ------- .. autoapisummary:: haive.games.among_us.state_manager.AmongUsStateManagerMixin Module Contents --------------- .. py:class:: AmongUsStateManagerMixin Bases: :py:obj:`haive.games.framework.multi_player.state_manager.MultiPlayerGameStateManager`\ [\ :py:obj:`haive.games.among_us.state.AmongUsState`\ ] Comprehensive state management mixin for Among Us social deduction gameplay. This mixin class provides complete state management functionality for Among Us games, handling complex mechanics including role-based gameplay, task systems, sabotage mechanics, meeting coordination, and win condition evaluation. The class separates state management from agent behavior, allowing any inheriting class to gain full Among Us state management capabilities. The state manager handles: - Game initialization with intelligent role assignment - Task generation and completion tracking - Complex sabotage systems with resolution mechanics - Meeting and voting coordination - Move validation and application - Win condition evaluation - Player state filtering for information hiding - Legal move generation for AI systems .. rubric:: Examples Initializing a new game:: state = AmongUsStateManagerMixin.initialize( player_names=["Alice", "Bob", "Charlie", "David", "Eve"], map_name="skeld", num_impostors=1, tasks_per_player=5 ) Applying player actions:: # Player movement move = {"action": "move", "location": "electrical"} new_state = AmongUsStateManagerMixin.apply_move(state, "Alice", move) # Task completion task_move = {"action": "complete_task", "task_id": "Alice_task_1"} new_state = AmongUsStateManagerMixin.apply_move(state, "Alice", task_move) # Impostor actions kill_move = {"action": "kill", "target_id": "Bob"} new_state = AmongUsStateManagerMixin.apply_move(state, "Eve", kill_move) Checking game progression:: updated_state = AmongUsStateManagerMixin.check_game_status(state) if updated_state.game_status == "ended": print(f"Game over! {updated_state.winner} wins!") .. note:: This mixin is designed to be inherited by game agents, providing state management capabilities without imposing specific agent behaviors. .. py:method:: advance_phase(state) :classmethod: Advance the game to the next phase in the game cycle. Progresses the game through its phases: TASKS -> MEETING -> VOTING -> TASKS. Updates related state variables and resets phase-specific data. :param state: Current game state to advance. :returns: Updated state in the next phase. :rtype: AmongUsState .. rubric:: Examples Task to meeting transition:: new_state = cls.advance_phase(state) # game_phase changes from TASKS to MEETING Meeting to voting transition:: new_state = cls.advance_phase(state) # game_phase changes from MEETING to VOTING Voting to tasks transition:: new_state = cls.advance_phase(state) # game_phase changes from VOTING to TASKS # round_number increments, votes cleared .. py:method:: apply_move(state, player_id, move) :classmethod: Apply a player's move to the game state with comprehensive validation. Processes and validates player moves, updating the game state accordingly. Handles all move types across different game phases with proper error handling and state consistency maintenance. :param state: Current game state to modify. :param player_id: ID of the player making the move. :param move: Move dictionary containing action and parameters. :returns: Updated game state after applying the move. :rtype: AmongUsState .. rubric:: Examples Movement action:: move = {"action": "move", "location": "electrical"} new_state = cls.apply_move(state, "Alice", move) Task completion:: move = {"action": "complete_task", "task_id": "Alice_task_1"} new_state = cls.apply_move(state, "Alice", move) Impostor kill:: move = {"action": "kill", "target_id": "Bob"} new_state = cls.apply_move(state, "Eve", move) Voting action:: move = {"action": "vote", "vote_for": "Charlie"} new_state = cls.apply_move(state, "Alice", move) .. note:: The method creates a deep copy of the state to avoid modifying the original, ensuring state immutability. .. py:method:: check_game_status(state) :classmethod: Check and update game status with win condition evaluation. Evaluates the current game state to determine if any win conditions have been met and updates the game status accordingly. :param state: Current game state to check. :returns: Updated state with current game status. :rtype: AmongUsState .. rubric:: Examples Ongoing game:: updated_state = cls.check_game_status(state) # Returns state with game_status="ongoing" Crewmate victory:: updated_state = cls.check_game_status(state) # Returns state with game_status="ended", winner="crewmates" Impostor victory:: updated_state = cls.check_game_status(state) # Returns state with game_status="ended", winner="impostors" .. py:method:: filter_state_for_player(state, player_id) :classmethod: Filter game state to include only information visible to a specific player. Creates a filtered view of the game state that includes only information the specified player should have access to, implementing proper information hiding for authentic social deduction gameplay. :param state: Complete game state to filter. :param player_id: ID of the player to create filtered state for. :returns: Filtered state dictionary with player-visible information. :rtype: Dict[str, Any] .. rubric:: Examples Crewmate filtered state:: filtered = cls.filter_state_for_player(state, "Alice") # Includes: own location, tasks, observations, connected rooms # Excludes: other players' roles, impostor identities Impostor filtered state:: filtered = cls.filter_state_for_player(state, "Eve") # Includes: fellow impostors, vent locations, kill cooldown # Excludes: crewmate task progress details Dead player filtered state:: filtered = cls.filter_state_for_player(state, "Bob") # Includes: basic game information, spectator view # Excludes: ability to influence game .. py:method:: get_legal_moves(state, player_id) :classmethod: Generate comprehensive legal moves for a player based on game state. Analyzes the current game state and player situation to generate all valid moves available to the player, considering their role, location, game phase, and current constraints. :param state: Current game state. :param player_id: ID of the player to generate moves for. :returns: List of legal move dictionaries. :rtype: List[Dict[str, Any]] .. rubric:: Examples Crewmate in task phase:: moves = cls.get_legal_moves(state, "Alice") # Returns moves like: # [{"action": "move", "location": "electrical"}, # {"action": "complete_task", "task_id": "Alice_task_1"}, # {"action": "report_body"}] (if body present) Impostor in task phase:: moves = cls.get_legal_moves(state, "Eve") # Returns moves like: # [{"action": "move", "location": "medbay"}, # {"action": "kill", "target_id": "Bob"}, # {"action": "vent", "vent_id": "electrical_vent"}, # {"action": "sabotage", "sabotage_type": "lights"}] Player in voting phase:: moves = cls.get_legal_moves(state, "Alice") # Returns moves like: # [{"action": "vote", "vote_for": "Charlie"}, # {"action": "vote", "vote_for": "skip"}] .. py:method:: initialize(player_names, **kwargs) :classmethod: Initialize a new Among Us game state with intelligent defaults. Creates a complete game state with role assignments, task generation, map initialization, and all necessary game components. The initialization process follows standard Among Us rules for balanced gameplay. :param player_names: List of player identifiers (4-15 players). :param \*\*kwargs: Additional configuration options. map_name (str): Map to use (default: "skeld"). num_impostors (int): Number of impostors (auto-calculated if None). tasks_per_player (int): Tasks per crewmate (default: 5). kill_cooldown (int): Impostor kill cooldown in seconds (default: 45). seed: Random seed for reproducible games. :returns: Fully initialized game state ready for gameplay. :rtype: AmongUsState .. rubric:: Examples Standard initialization:: state = AmongUsStateManagerMixin.initialize( player_names=["Alice", "Bob", "Charlie", "David", "Eve"], map_name="skeld" ) # Auto-assigns 1 impostor for 5 players Custom configuration:: state = AmongUsStateManagerMixin.initialize( player_names=["Player_" + str(i) for i in range(10)], map_name="polus", num_impostors=2, tasks_per_player=6, kill_cooldown=30, seed=12345 ) .. note:: The initialization automatically balances impostor count based on player count following standard Among Us ratios.