haive.games.connect4.state_manager

Connect Four game state management module.

This module provides comprehensive state management functionality for the Connect Four game, including board management, move validation, win detection, and game status tracking.

Connect Four is a strategy game played on a 7×6 grid where players take turns dropping colored pieces into columns. The pieces fall to the lowest available position in the chosen column. The first player to get four pieces in a row (horizontally, vertically, or diagonally) wins the game.

Classes:

Connect4StateManager: Main state management class for Connect Four operations.

Example

Basic Connect Four game setup and play:

>>> from haive.games.connect4.state_manager import Connect4StateManager
>>> from haive.games.connect4.models import Connect4Move
>>>
>>> # Initialize game (red player starts)
>>> state = Connect4StateManager.initialize()
>>> print(f"Current player: {state.current_player}")  # "red"
>>> print(f"Board size: {len(state.board)}x{len(state.board[0])}")  # "6x7"
>>>
>>> # Drop piece in center column
>>> move = Connect4Move(column=3, explanation="Center play")
>>> new_state = Connect4StateManager.apply_move(state, move)
>>>
>>> # Check if column is full
>>> legal_moves = Connect4StateManager.get_legal_moves(new_state)
>>> print(f"Available columns: {[m.column for m in legal_moves]}")

Note

  • Columns are 0-indexed (0-6 for a standard 7-column board)

  • Players alternate between “red” and “yellow”

  • Pieces are placed at the bottom-most available position in each column

  • The game ends when a player gets 4 in a row or the board is full (draw)

Classes

Connect4StateManager

Manager for Connect4 game state.

Module Contents

class haive.games.connect4.state_manager.Connect4StateManager[source]

Bases: haive.games.framework.base.state_manager.GameStateManager[haive.games.connect4.state.Connect4State]

Manager for Connect4 game state.

This class provides methods for managing Connect4 game state, including:

  • Game initialization

  • Move application and validation

  • Win condition checking

  • Game state conversion

The state manager follows the immutable state pattern, creating new state instances rather than modifying existing ones.

classmethod apply_move(state, move)[source]

Apply a move to the Connect4 state.

Applies the given move to the game state, updating the board, checking win conditions, and switching turns as appropriate.

Parameters:
Returns:

Updated game state after applying the move

Return type:

Connect4State

Raises:

ValueError – If the move is invalid (column full or out of range)

Example

>>> state = Connect4StateManager.initialize()
>>> move = Connect4Move(column=3)
>>> new_state = Connect4StateManager.apply_move(state, move)
>>> new_state.turn
'yellow'
classmethod check_game_over(state)[source]

Check if the game is over (win or draw).

Parameters:

state (haive.games.connect4.state.Connect4State) – Current game state

Returns:

True if the game is over, False otherwise

Return type:

bool

Example

>>> state = Connect4StateManager.initialize()
>>> Connect4StateManager.check_game_over(state)
False
classmethod ensure_state(state)[source]

Ensure the input is a proper Connect4State object.

Parameters:

state (dict[str, Any] | haive.games.connect4.state.Connect4State) – State object or dictionary

Returns:

Properly typed state object

Return type:

Connect4State

Example

>>> state_dict = {"board": [[None for _ in range(7)] for _ in range(6)],
...               "turn": "red", "game_status": "ongoing"}
>>> state = Connect4StateManager.ensure_state(state_dict)
>>> isinstance(state, Connect4State)
True

Get all legal moves for the current game state.

Returns a list of all valid moves (non-full columns) for the current player.

Parameters:

state (haive.games.connect4.state.Connect4State) – Current game state

Returns:

List of legal moves

Return type:

list[Connect4Move]

Example

>>> state = Connect4StateManager.initialize()
>>> legal_moves = Connect4StateManager.get_legal_moves(state)
>>> len(legal_moves)
7  # All columns are empty in a new game
classmethod initialize()[source]

Initialize a new Connect4 game.

Creates a fresh Connect4 game state with an empty board, red player starting, and game status set to ongoing.

Returns:

A new game state with default settings

Return type:

Connect4State

Example

>>> state = Connect4StateManager.initialize()
>>> state.turn
'red'
>>> state.game_status
'ongoing'