Redesign GameState and GameManager

[haidark]

The specs for the new design are below (credit to @c-rit for the great work)

Core Components:

environment:

• the target of the 'hard requirement' move/role (Target Grid, Chess board, etc.)

  context:

• message from the GameManager
• anything that will be used by the player to make a specific decision (history, piece placements, etc.)
• input of intermediate 'soft requirement' moves/roles (annotations, reasoning, etc.)

  roles:

• an object containing the games' roles in order of turn

  GameState Implementation API

GameState is an immutable data class that defines a game fully. It is responsible for fully defining all states and transitions between states, including proper validation and feedback. At minimum, GameState contains three members:

• environment: stores a representation of the current state of the game.

• roles: an ordered list (len(roles) >= 1) of roles that will be played. The first element of this list is the current role.

• context: a dictionary with one required field "message" (and additional optional fields). "message" contains information from the GameManager. Any additional field is allowed (e.g. history containing information about the past) This is the class that is implemented by the game developer and requires the following methods:

  `update_game

  `

• Description: Advances the game given a compatible environment and move.

• Requires:   - An environment and move

• Returns:   - A full game state as defined by the game implementation.   - context["message"] is None if the move successfully completes the turn.   - context["message"] is not None if the move does not advance the turn.

  query_game

• Description: Returns a game state with all information relevant to the game's next role-to-move. Any context["message"] in self will be relevant to the role.

• Requires:   - None

• Returns:   - A GameState that is a subset of self, containing all information needed by the role-to-move as defined by the "rules" (implementation) of the game.

  validate_game

• Description: Forwards non-continue conditions from the last move or returns new non-continue conditions in the environment, specific to the game implementation.

• Requires:   - None

• Returns:   - If the game should not continue based on the self environment returns an object (currently a string) with a condition or error describing the reason.   - Otherwise, returns None signaling that the game should continue

  get_next_roles

• Description: Determines the list of roles given the current state of the game.

• Requires:   - None

• Returns:   - a valid ordered list of roles

  export

• Description: Provides a complete representation of the current game state in a compatible game config format

• Requires:  * None

• Returns:  * A config/transferable representation of GameState

GameManager Class

The GameManager class is responsible for managing the initialization of the game and players, the flow of game rounds, and the evaluation of player moves. Standard configurations for games are used to initialize the game and player roles, and standard fields in the GameState are used for tracking game progress and validation according to the game's rules. All data and data transformations are provided by the game implementation according to the API.

The following are the key methods:

__init__(self, config):

  - Initializes the GameManager with the provided configuration.   - Sets up the game and players.

**`_init_game(self):

`**   - Builds the game instance using the configuration.   - Adds the game to the list of managed games.

_init_players(self):

  - Builds the player instances using the configuration.   - Associates players with their respective roles in the game.   - Raises an error if a player’s role is not defined in the game.

start(self):

  - Begins the game evaluation process.   - Calls the run_game_loop method to run the game.

run_game_loop(self, game_state):

  - Manages the game loop, processing each turn until the maximum number of rounds is reached or a game-ending condition is met.   - Validates game states, queries the current game state, and processes player turns.

process_turn(self, game_state, player):

  - Executes a player’s turn by facilitating the move, updating the game state, and validating the result.   - Handles retries if a player makes an invalid move and logs errors if a player fails to make a valid move after the maximum number of attempts.

[haidark]

thanks @c-rit for the in-person review. merging this