BaseEnvironment¶
Abstract definition of a game environment. Whenever you wish to make a new environment, make sure to subclass this to have all of the correct functions.
-
class
colosseumrl.BaseEnvironment.BaseEnvironment(config: str = '')[source]¶ Base class for all environments that can be used by colosseum.
-
add_player(state: object) → object[source]¶ OPTIONAL Add a new player to an already existing game.
If your game cannot dynamically change, then you can leave these methods alone.
Notes
Currently not used in any environment and support for dynamic games is still pending.
- Parameters
state (object) – The current state of the game
- Returns
new_state – The state of the game after adding a new player.
- Return type
object
-
compute_ranking(state: object, players: [<class 'int'>], winners: [<class 'int'>]) → Dict[int, int][source]¶ OPTIONAL
Compute the final ranking of all of the players in the game. The state object will be a terminal object. By default, this will simply give a list of players that won with a ranking 0 and losers with ranking 1.
- Parameters
state (object) – Terminal state of the game, right after the final move.
players (List[int]) – A list of all players in the game
winners (List[int]) – A list of final winners in the game.
- Returns
A Dictionary mapping player number to of rankings for each player. Lower rankings indicating better placement.
- Return type
Dict[int, int]
-
static
deserialize_state(serialized_state: bytearray) → object[source]¶ Convert a serialized bytearray back into a game state.
- Parameters
serialized_state (bytearray) – Serialized byte-string for the state.
- Returns
The current game state.
- Return type
object
-
abstract
is_valid_action(state: object, player: int, action: str) → bool[source]¶ Whether or not an action is valid for a specific state.
- Parameters
state (object) – The current state of the game.
player (int) – The player who is executing this action.
action (str) – The action the player is executing.
- Returns
Whether or not this is a valid action in the current state.
- Return type
bool
-
abstract property
max_players¶ Property holding the max number of players present for a game.
Currently, this should be the same as min_players. Future additions will allow for dynamic games.
- Returns
Maximum number of players allowed in game.
- Return type
int
-
abstract property
min_players¶ Property holding the number of players present required to play game.
- Returns
Minimum number of players for game to start.
- Return type
int
-
abstract
new_state(num_players: int = None) → Tuple[object, List[int]][source]¶ Create a fresh state. This could return a fixed object or randomly initialized on, depending on the game.
Note that player numbers must be numbers in the set {0, 1, …, n-1} for an n player game.
- Parameters
num_players (int) – Total number of players in this game.
- Returns
new_state (object) – The initial state for the game. This can be any python object you wish.
new_players (List[int]) – List of players who’s turn it is now.
-
abstract
next_state(state: object, players: [<class 'int'>], actions: [<class 'str'>]) → Tuple[object, List[int], List[float], bool, Optional[List[int]]][source]¶ Compute a single step in the game.
Notes
Player numbers must be numbers in the set {0, 1, …, n-1} for an n player game.
- Parameters
state (object) – The current state of the game.
players ([int]) – The players which are taking the given actions.
actions ([str]) – The actions of each player.
- Returns
new_state (object) – The new state of the game.
new_players (List[int]) – List of players who’s turn it is in the new state now.
rewards (List[float]) – The reward for each player that acted.
terminal (bool) – Whether or not the game has ended.
winners (List[int]) – If the game has ended, who are the winners.
-
abstract static
observation_names() → List[str][source]¶ Static method for returning the names of the observation objects.
This needs to be static to setup spacetime dataframes.
- Returns
The keys of the observation dictionary.
- Return type
List[str]
-
abstract property
observation_shape¶ Describe the fixed numpy shapes of each observation.
- Returns
The shape, as a tuple, of each numpy array by their name.
- Return type
Dict[str, Tuple[int]]
-
remove_player(state: object, player: int) → object[source]¶ OPTIONAL Remove a player from the current game if they disconnect somehow.
Notes
Currently not used in any environment and support for dynamic games is still pending.
- Parameters
state (object) – The current state of the game.
player (int) – The player number of remove.
- Returns
new_state – The state of the game after remove the player.
- Return type
object
-
static
serializable() → bool[source]¶ Some environments may allow for the full game state to be serializable and transferable to the agents.
- Returns
Whether or not this class supports serialization of the state.
- Return type
bool
-
static
serialize_state(state: object) → bytearray[source]¶ Serialize a game state and convert it to a bytearray to be saved or sent over a network.
- Parameters
state (object) – The current game state.
- Returns
Serialized byte-string for the state.
- Return type
bytearray
-
abstract
state_to_observation(state: object, player: int) → Dict[str, numpy.ndarray][source]¶ Convert the raw game state to the observation for the agent. Maps each observation name into an observation.
This can return different values for the different players. Default implementation is just the identity.
-