games.mafia.state_manager¶

State management for the Mafia game.

This module provides the core state management functionality for the Mafia game, handling game state transitions, move validation, and game progression logic.

The state manager is responsible for:

  • Game initialization and setup

  • Phase transitions (day/night cycles)

  • Move validation and application

  • Game state filtering for information hiding

  • Win condition checking

Classes¶

MafiaStateManager

Manager for the Mafia game state.

Module Contents¶

class games.mafia.state_manager.MafiaStateManager¶

Bases: haive.games.framework.multi_player.state_manager.MultiPlayerGameStateManager[haive.games.mafia.state.MafiaGameState]

Manager for the Mafia game state.

This class extends MultiPlayerGameStateManager to provide Mafia-specific state management functionality. It handles game progression, move validation, and state transitions.

The manager maintains game state including:

  • Player roles and alive/dead status

  • Day/night cycle progression

  • Vote tracking and resolution

  • Night action resolution (kills, saves, investigations)

  • Win condition checking

Note

This class is designed to be used statically, with all methods being class methods that take and return game states.

classmethod advance_phase(state)¶

Advance the game to the next phase.

This method handles the transition between game phases, including:

  • Setup → Night (first night)

  • Night → Day Discussion (with night action resolution)

  • Day Discussion → Day Voting

  • Day Voting → Night (with vote resolution)

  • Game Over checks at appropriate points

Parameters:

state (haive.games.mafia.state.MafiaGameState) – Current game state

Returns:

Updated game state with new phase and relevant changes

Return type:

haive.games.mafia.state.MafiaGameState

classmethod apply_move(state, player_id, move)¶

Apply a move to the game state.

This method validates and applies a player’s move or narrator’s action to the game state, updating all relevant state fields.

Parameters:
Returns:

Updated game state after applying the move

Return type:

haive.games.mafia.state.MafiaGameState

classmethod check_game_status(state)¶

Check if the game has ended and determine the winner.

This method checks win conditions:

  • Village wins if all mafia are dead

  • Mafia wins if they equal/outnumber villagers

Parameters:

state (haive.games.mafia.state.MafiaGameState) – Current game state

Returns:

Updated state with game status and winner if game is over

Return type:

haive.games.mafia.state.MafiaGameState

classmethod filter_state_for_player(state, player_id)¶

Filter the state to include only information visible to a specific player.

This method implements information hiding, ensuring players only see information they should have access to based on their role and the game phase.

Parameters:
Returns:

Filtered state containing only visible information

Return type:

dict[str, Any]

Get legal moves for a specific player.

This method determines what moves are legal for a player based on:

  • Current game phase

  • Player’s role

  • Player’s alive/dead status

  • Previous actions in the current phase

Parameters:
Returns:

List of legal moves (MafiaAction or NarratorAction)

Return type:

list[haive.games.mafia.models.MafiaAction | haive.games.mafia.models.NarratorAction]

classmethod handle_phase_transition(state)¶

Handle phase transition with error handling.

This method safely transitions the game phase, handling any errors that might occur during the transition.

Parameters:

state (haive.games.mafia.state.MafiaGameState) – Current game state

Returns:

Updated state after phase transition

Raises:

ValueError – If critical game state fields are missing

Return type:

haive.games.mafia.state.MafiaGameState

classmethod initialize(player_names, **kwargs)¶

Initialize a new Mafia game with the given players.

This method sets up a new game state with:

  • Random role assignment

  • Initial player states

  • Game phase setup

  • Role knowledge distribution

Parameters:

  • player_names (list[str]) – List of player names/IDs

  • **kwargs – Additional configuration options include_all_roles: Force inclusion of all special roles

Returns:

Initial game state

Raises:

ValueError – If there aren’t enough players (minimum 4)

Return type:

haive.games.mafia.state.MafiaGameState

classmethod resolve_night_actions(state)¶

Resolve night actions and determine outcomes.

This method processes all night actions in the correct order:

  1. Mafia kill attempt

  2. Doctor save attempt

  3. Detective investigation results

Parameters:

state (haive.games.mafia.state.MafiaGameState) – Current game state with night actions recorded

Returns:

Updated state with night actions resolved

Return type:

haive.games.mafia.state.MafiaGameState