games.nim.state_manager

Nim game state management module.

This module provides comprehensive state management functionality for the Nim game, including game initialization, move validation, and game status tracking.

The Nim game is a mathematical strategy game where players take turns removing stones from piles. The goal varies by game mode: - Standard mode: The player who takes the last stone wins - Misère mode: The player who takes the last stone loses

Classes:

NimStateManager: Main state management class for Nim game operations.

Example

Basic Nim game setup and play:

>>> from haive.games.nim.state_manager import NimStateManager
>>> from haive.games.nim.models import NimMove
>>>
>>> # Initialize game with custom pile sizes
>>> state = NimStateManager.initialize(pile_sizes=[3, 5, 7])
>>> print(f"Starting piles: {state.piles}")
>>>
>>> # Get legal moves for current player
>>> legal_moves = NimStateManager.get_legal_moves(state)
>>> print(f"Available moves: {len(legal_moves)}")
>>>
>>> # Make a move
>>> move = NimMove(pile_index=1, stones_taken=3, player="player1")
>>> new_state = NimStateManager.apply_move(state, move)
>>> print(f"New piles: {new_state.piles}")

Note

This implementation follows the Game State Manager pattern used throughout the haive-games package, providing consistent interfaces across all games.

Classes

NimStateManager

Manager for Nim game state.

Module Contents

class games.nim.state_manager.NimStateManager

Bases: haive.games.framework.base.state_manager.GameStateManager[haive.games.nim.state.NimState]

Manager for Nim game state.

This class provides methods for initializing a new Nim game, retrieving legal moves, applying moves, adding analyses, and checking game status.

classmethod add_analysis(state, player, analysis)

Add an analysis to the state.

Parameters:

• state (haive.games.nim.state.NimState) – The current game state.

• player (str) – The player who performed the analysis.

• analysis (haive.games.nim.models.NimAnalysis) – The analysis to add.

Returns:

Updated state with the analysis added.

Return type:

NimState

classmethod apply_move(state, move)

Apply a move to the current state and return the new state.

Parameters:

• state (haive.games.nim.state.NimState) – The current game state.

• move (haive.games.nim.models.NimMove) – The move to apply.

Returns:

A new game state after applying the move.

Return type:

NimState

Raises:

ValueError – If the move is invalid.

classmethod check_game_status(state)

Check and update the game status.

Parameters:

state (haive.games.nim.state.NimState) – The current game state.

Returns:

The game state with updated status.

Return type:

NimState

classmethod get_legal_moves(state, player=None)

Get all legal moves for the current state.

Parameters:

• state (haive.games.nim.state.NimState) – The current game state.

• player (str) – The player making the moves. If None, uses current player from state.

Returns:

A list of all legal moves.

Return type:

List[NimMove]

classmethod get_winner(state)

Get the winner of the game, if any.

Parameters:

state (haive.games.nim.state.NimState) – The current game state.

Returns:

The winner, or None if the game is ongoing.

Return type:

Optional[str]

classmethod initialize(**kwargs)

Initialize a new Nim game with the given pile sizes.

Parameters:

**kwargs – Keyword arguments for game initialization. pile_sizes: Optional list of pile sizes. Defaults to [3, 5, 7].

Returns:

A new Nim game state.

Return type:

NimState

classmethod make_move(state, player, move)

Make a move and return a Command with the updated state.

Parameters:

• state (haive.games.nim.state.NimState | dict[str, Any]) – The current game state.

• player (str) – The player making the move.

• move (haive.games.nim.models.NimMove) – The move to make.

Returns:

Command with the updated state.

Return type:

Command

Raises:

ValueError – If it’s not the player’s turn.