games.framework.multi_player.state¶

Base state management for multi-player games.

This module provides the foundational state model for multi-player games, supporting features like:

  • Player tracking and turn management

  • Game phase transitions

  • Move history recording

  • Public and private state management

  • Error handling

Examples

>>> from haive.agents.agent_games.framework.multi_player.state import MultiPlayerGameState
>>>
>>> # Create a game state
>>> state = MultiPlayerGameState(
...     players=["player1", "player2", "player3"],
...     game_phase=GamePhase.SETUP
... )
>>>
>>> # Advance to next player
>>> next_player = state.advance_player()

Classes¶

MultiPlayerGameState

Base game state for multi-player games.

Module Contents¶

class games.framework.multi_player.state.MultiPlayerGameState(/, **data)¶

Bases: pydantic.BaseModel

Base game state for multi-player games.

This class provides the foundation for managing game state in multi-player games. It handles player turns, game phases, move history, and both public and private state information.

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_phase¶

Current phase of the game (see GamePhase enum).

Type:

str

game_status¶

Status of the game (e.g., “ongoing”, “ended”).

Type:

str

move_history¶

History of all moves made.

Type:

List[Dict[str, Any]]

round_number¶

Current round number.

Type:

int

player_data¶

Private data for each player.

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]

Examples

>>> state = MultiPlayerGameState(
...     players=["player1", "player2"],
...     game_phase=GamePhase.SETUP
... )
>>> state.advance_player()
'player2'
>>> private_data = state.get_player_private_data("player1")

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.

advance_player()¶

Advance to the next player and return their name/ID.

This method updates the current_player_idx to the next player in the rotation and returns the new current player’s name/ID.

Returns:

The next player’s name/ID.

Return type:

str

Examples

>>> state = MultiPlayerGameState(players=["p1", "p2", "p3"])
>>> state.advance_player()
'p2'
>>> state.advance_player()  # Advances to p3
'p3'
>>> state.advance_player()  # Wraps back to p1
'p1'
get_player_private_data(player_id)¶

Get private data for a specific player.

This method safely retrieves the private state data for a given player, returning an empty dict if no data exists.

Parameters:

player_id (str) – The ID of the player whose data to retrieve.

Returns:

The player’s private data, or empty dict if none exists.

Return type:

Dict[str, Any]

Examples

>>> state = MultiPlayerGameState(players=["p1", "p2"])
>>> state.player_data["p1"] = {"secret_info": 42}
>>> state.get_player_private_data("p1")
{'secret_info': 42}
>>> state.get_player_private_data("unknown")
{}
property current_player: str¶

Get the current player’s name/ID.

Returns:

The current player’s name/ID, or empty string if invalid index.

Return type:

str

Examples

>>> state = MultiPlayerGameState(players=["p1", "p2"])
>>> state.current_player
'p1'