haive.games.battleship.state_manager

Battleship game state management module.

This module provides state transition logic for the Battleship game, including:

• Game initialization

• Ship placement validation

• Move execution and validation

• Strategic analysis tracking

• Game state updates

Classes

BattleshipStateManager

Manager for Battleship game state transitions.

Module Contents

class haive.games.battleship.state_manager.BattleshipStateManager

Manager for Battleship game state transitions.

This class provides methods for:

• Initializing a new game

• Placing ships

• Making moves

• Checking game status

• Tracking strategic analysis

The state manager ensures immutability by returning new state objects rather than modifying existing ones, making state transitions predictable and traceable.

Examples

>>> manager = BattleshipStateManager()
>>> state = manager.initialize()
>>> state.game_phase
GamePhase.SETUP

static add_analysis(state, player, analysis)

Add strategic analysis for a player.

Records a strategic analysis provided by the LLM for the specified player, maintaining a limited history of the most recent analyses.

Parameters:

• state (haive.games.battleship.state.BattleshipState) – Current game state

• player (str) – Player for whom to add analysis

• analysis (str) – Analysis text from LLM

Returns:

Updated game state with added analysis

Return type:

BattleshipState

Examples

>>> manager = BattleshipStateManager()
>>> state = manager.initialize()
>>> analysis = "Focus attacks on the center of the board."
>>> new_state = manager.add_analysis(state, "player1", analysis)
>>> new_state.player1_state.strategic_analysis[-1]
'Focus attacks on the center of the board.'

static initialize()

Initialize a new Battleship game state.

Creates a fresh game state with default settings, setting up empty player states, initial game phase, and empty move history.

Returns:

Fresh game state with default settings

Return type:

BattleshipState

Examples

>>> manager = BattleshipStateManager()
>>> state = manager.initialize()
>>> state.current_player
'player1'
>>> state.game_phase
GamePhase.SETUP

static make_move(state, player, move)

Make a move for a player.

Processes an attack command from the specified player, updates the game state with the move outcome (hit, miss, or sunk), and checks for game-ending conditions.

Parameters:

• state (haive.games.battleship.state.BattleshipState) – Current game state

• player (str) – Player making the move (“player1” or “player2”)

• move (haive.games.battleship.models.MoveCommand) – Attack command with target coordinates

Returns:

Updated game state with move outcome

Return type:

BattleshipState

Examples

>>> manager = BattleshipStateManager()
>>> state = BattleshipState(game_phase=GamePhase.PLAYING)
>>> move = MoveCommand(row=3, col=4)
>>> new_state = manager.make_move(state, "player1", move)
>>> # Check if move was recorded in history
>>> len(new_state.move_history) > 0
True

static place_ships(state, player, placements)

Place ships for a player.

Processes a list of ship placements for the specified player, validating each placement against game rules (e.g., no overlapping ships, valid ship types, correct placement) and updating the game state accordingly.

Parameters:

• state (haive.games.battleship.state.BattleshipState) – Current game state

• player (str) – Player making the placements (“player1” or “player2”)

• placements (list[haive.games.battleship.models.ShipPlacement]) – List of ship placements

Returns:

Updated game state with placed ships or error message

Return type:

BattleshipState

Examples

>>> manager = BattleshipStateManager()
>>> state = manager.initialize()
>>> placements = [
...     ShipPlacement(ship_type=ShipType.CARRIER, coordinates=[
...         Coordinates(row=0, col=0), Coordinates(row=0, col=1),
...         Coordinates(row=0, col=2), Coordinates(row=0, col=3),
...         Coordinates(row=0, col=4)
...     ]),
...     # Additional placements for other ships...
... ]
>>> new_state = manager.place_ships(state, "player1", placements)
>>> new_state.player1_state.has_placed_ships
True