Game Interface

A generic interface for two-players, zero-sum games.

Stochastic games and intermediate rewards are supported. By convention, rewards are expressed from the point of view of the player called white.

AbstractGame

Abstract base type for a game environment.

Constructors

Any subtype Game must implement the following constructors:

Game()

Return an initialized game environment. Note that this constructor does not have to be deterministic.

Game(state)

Return a fresh game environment starting at a given state.

State(Game::Type{<:AbstractGame})

Return the state type corresponding to Game.

State objects must be persistent or appear as such as they are stored into the MCTS tree without copying. They also have to be comparable and hashable.

Action(Game::Type{<:AbstractGame})

Return the action type corresponding to Game.

two_players(::Type{<:AbstractGame}) :: Bool

Return whether or not a game is a two-players game.

game_terminated(::AbstractGame)

Return a boolean indicating whether or not the game is in a terminal state.

white_playing(::Type{<:AbstractGame}, state) :: Bool
white_playing(env::AbstractGame)
  = white_playing(typeof(env), current_state(env))

Return true if white is to play and false otherwise. For a one-player game, it must always return true.

white_reward(env::AbstractGame)

Return the intermediate reward obtained by the white player after the last transition step. The result is undetermined when called at an initial state.

current_state(env::AbstractGame)

Return the game state (which is persistent).

actions(::Type{<:AbstractGame})

Return the vector of all game actions.

actions_mask(env::AbstractGame)

Return a boolean mask indicating what actions are available from env.

The following identities must hold:

• game_terminated(env) || any(actions_mask(env))
• length(actions_mask(env)) == length(actions(typeof(env)))

play!(env::AbstractGame, action)

Update the game environment by making the current player perform action. Note that this function does not have to be deterministic.

heuristic_value(env::AbstractGame)

Return a heuristic estimate of the state value for the current player.

The given state must be nonfinal and returned values must belong to the $(-∞, ∞)$ interval.

This function is not needed by AlphaZero but it is useful for building baselines such as minmax players.

vectorize_state(::Type{<:AbstractGame}, state) :: Array{Float32}

Return a vectorized representation of a state.

symmetries(::Type{G}, state) where {G <: AbstractGame}

Return the vector of all pairs (s, σ) where:

• s is the image of state by a nonidentical symmetry
• σ is the associated actions permutation, as an integer vector of size num_actions(Game).

A default implementation is provided that returns an empty vector.

Example

In the game of tic-tac-toe, there are eight symmetries that can be obtained by composing reflexions and rotations of the board (including the identity symmetry).

action_string(::Type{<:AbstractGame}, action) :: String

Return a human-readable string representing the provided action.

parse_action(::Type{<:AbstractGame}, str::String)

Return the action described by string str or nothing if str does not denote a valid action.

read_state(::Type{G}) where G <: AbstractGame :: Union{State(G), Nothing}

Read a state from the standard input. Return the corresponding state or nothing in case of an invalid input.

render(env::AbstractGame)

Print the game state on the standard output.

num_actions(::Type{G})

Return the total number of actions associated with a game.

available_actions(env::AbstractGame)

Return the vector of all available actions.

state_dim(::Type{G})

Return a tuple that indicates the shape of a vectorized state representation.

apply_random_symmetry(::AbstractGame)

Return a fresh new state that is the image of the given state by a random symmetry (see symmetries).