# Game Interface

`AlphaZero.GameInterface`

— ModuleA 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*.

## Mandatory Interface

### Types

`AlphaZero.GameInterface.AbstractGame`

— Type`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.

`AlphaZero.GameInterface.State`

— Function`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.

`AlphaZero.GameInterface.Action`

— Function`Action(Game::Type{<:AbstractGame})`

Return the action type corresponding to `Game`

.

`AlphaZero.GameInterface.two_players`

— Function`two_players(::Type{<:AbstractGame}) :: Bool`

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

### Game Functions

`AlphaZero.GameInterface.game_terminated`

— Function`game_terminated(::AbstractGame)`

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

`AlphaZero.GameInterface.white_playing`

— Function```
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`

.

`AlphaZero.GameInterface.white_reward`

— Function`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.

`AlphaZero.GameInterface.current_state`

— Function`current_state(env::AbstractGame)`

Return the game state (which is persistent).

`AlphaZero.GameInterface.actions`

— Function`actions(::Type{<:AbstractGame})`

Return the vector of all game actions.

`AlphaZero.GameInterface.actions_mask`

— Function`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)))`

`AlphaZero.GameInterface.play!`

— Function`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.

`AlphaZero.GameInterface.heuristic_value`

— Function`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.

`AlphaZero.GameInterface.vectorize_state`

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

Return a vectorized representation of a state.

`AlphaZero.GameInterface.symmetries`

— Function`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).

### Interface for Interactive Tools

`AlphaZero.GameInterface.action_string`

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

Return a human-readable string representing the provided action.

`AlphaZero.GameInterface.parse_action`

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

Return the action described by string `str`

or `nothing`

if `str`

does not denote a valid action.

`AlphaZero.GameInterface.read_state`

— Function`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.

`AlphaZero.GameInterface.render`

— Function`render(env::AbstractGame)`

Print the game state on the standard output.

## Derived Functions

`AlphaZero.GameInterface.num_actions`

— Function`num_actions(::Type{G})`

Return the total number of actions associated with a game.

`AlphaZero.GameInterface.available_actions`

— Function`available_actions(env::AbstractGame)`

Return the vector of all available actions.

`AlphaZero.GameInterface.state_dim`

— Function`state_dim(::Type{G})`

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

`AlphaZero.GameInterface.apply_random_symmetry`

— Function`apply_random_symmetry(::AbstractGame)`

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

).