OpenSpiel Core API Reference

OpenSpiel consists of several core functions and classes. This page acts as a helpful reminder of how to use the main functionality of OpenSpiel.

Most of the functions are described and illustrated via Python syntax and examples, and there are pointers to the corresponding C++ functions.

Disclaimer: This is meant as a guide to facilitate OpenSpiel development in Python. However, spiel.h remains the single source of truth for documentation on the core API.

Core Functions

Method Python C++ Description
deserialize_game_and_state(serialized_data: string) Python C++ Returns a tuple of (game, state) reconstructed from the serialized object data.
load_game(game_string: str) Python C++ Returns a game object for the specified game string.
load_game(game_string: str, parameters: Dict[str, Any]) Python C++ Returns a game object for the specified game string and parameter values.
registered_names() Python C++ Returns a list of all short names of games in the library.
serialize_game_and_state(game: pyspiel.Game, state: pyspiel.State) Python C++ Returns a string representation of the state and game that created it.

State methods

Method Python C++ Description
action_to_string(player: int, action: int) Python C++ Returns a string representation of the specified player's action.
apply_action(action: int) Python C++ Applies the specified action to the state.
apply_actions(actions: List[int]) Python C++ Applies the specified joint action (action for each player) to the state.
chance_outcomes() Python C++ Returns the a list of (action, prob) tuples representing the chance outcome distribution.
current_player() Python C++ Returns the player ID of the acting player.
history() Python C++ Returns the sequence of actions taken by all players since the start of the game.
information_state_string() Python C++ Returns a string representing the information state for the current player.
information_state_string(player: int) Python C++ Returns a string representing the information state for the specified player.
information_state_tensor() Python C++ Returns a list of floats representing the information state for the current player.
information_state_tensor(player: int) Python C++ Returns a list of floats representing the information state for the specified player.
is_chance_node() Python C++ Returns True if the state represents a chance node, False otherwise.
is_simultaneous_node() Python C++ Returns True if the state represents a simultaneous player node, False otherwise.
is_terminal() Python C++ Returns True if the state is terminal (game has finished), False otherwise.
legal_actions() Python C++ Returns the list of legal actions for the current player.
legal_actions(player: int) Python C++ Returns the list of legal actions for the specified player.
observation_string() Python C++ Returns a string representing the observation for the current player.
observation_string(player: int) Python C++ Returns a string representing the observation for the specified player.
observation_tensor() Python C++ Returns a list of floats representing the observation for the current player.
observation_tensor(player: int) Python C++ Returns a list of floats representing the observation for the specified player.
returns() Python C++ Returns the list of returns (cumulated reward from the start of the game): one value per player.
rewards() Python C++ Returns the list of intermediate rewards (rewards obtained since the last time the player acted): one value per player.
serialize() Python C++ Returns a string representation of the state which can be used to reconstruct the state from the game.

Game methods

Method Python C++ Description
action_to_string(player: int, action: int) Python C++ Returns a (state-independent) string representation of the specified player's action.
deserialize_state(serialized_data: str) Python C++ Reconstructs the state from the serialized state string.
information_state_tensor_shape() Python C++ Shape that the information state tensor should be perceived as.
information_state_tensor_size() Python C++ Size of the list (number of values) returned by the state's information state tensor function.
max_chance_outcomes() Python C++ The maximum number of distinct chance outcomes for chance nodes in the game.
max_game_length() Python C++ The maximum length of any one game (in terms of number of decision nodes visited in the game tree).
max_utility() Python C++ The maximum achievable utility (return) in over any playing (episode) of the game.
min_utility() Python C++ The minimum achievable utility (return) in over any playing (episode) of the game.
new_initial_state() Python C++ Returns a new initial state of the game (note: which might be a chance node).
num_distinct_actions() Python C++ Returns the number of (state-independent) distinct actions in the game.
observation_tensor_shape() Python C++ Shape that the observation tensor should be perceived as.
observation_tensor_size() Python C++ Size of the list (number of values) returned by the state's observation tensor function.