haive.games.mafia.state

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

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

MafiaGameState

State model for a Mafia game.

Module Contents

class haive.games.mafia.state.MafiaGameState(/, **data)

Bases: 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.

Parameters:

data (Any)

players

List of player names/IDs

Type:

List[str]

current_player_idx

Index of current player in players list

Type:

int

game_status

Status of the game (ongoing, ended)

Type:

str

move_history

History of moves

Type:

List[Dict[str, Any]]

round_number

Current round number

Type:

int

player_data

Player-specific data

Type:

Dict[str, Dict[str, Any]]

public_state

Public game state visible to all

Type:

Dict[str, Any]

error_message

Error message if any

Type:

Optional[str]

game_phase

Current phase of the game

Type:

GamePhase

roles

Mapping of player IDs to roles

Type:

Dict[str, PlayerRole]

player_states

Player state information

Type:

Dict[str, PlayerState]

votes

Player votes during voting phase

Type:

Dict[str, str]

action_history

History of all actions

Type:

List[Dict[str, Any]]

public_announcements

Public game announcements

Type:

List[str]

alive_mafia_count

Number of mafia members alive

Type:

int

alive_village_count

Number of villagers alive

Type:

int

alive_doctor_count

Number of doctors alive

Type:

int

alive_detective_count

Number of detectives alive

Type:

int

killed_at_night

Player targeted by mafia

Type:

Optional[str]

saved_at_night

Player saved by doctor

Type:

Optional[str]

night_deaths

Players who died during the night

Type:

List[str]

day_number

Current day number

Type:

int

winner

Winner (village or mafia)

Type:

Optional[str]

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.

add_public_announcement(announcement)

Add an announcement to the public record.

Parameters:

announcement (str) – The announcement to add

Return type:

None

Examples

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

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.

Parameters:

action (Union[MafiaAction, NarratorAction]) – Action to log

Return type:

None

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)

model_copy(*, deep=False, **kwargs)

Create a copy of the model.

Parameters:

• deep (bool, optional) – Whether to create a deep copy. Defaults to False.

• **kwargs – Additional arguments to pass to model_copy

Returns:

A copy of the current state

Return type:

MafiaGameState

Examples

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

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).

Examples

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