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