boardgame2
=======================

`boardgame2` is an extension of OpenAI Gym that implements multiple two-player zero-sum 2-dimension board games, such as TicTacToe, Gomuko, and Reversi.

## Environments
- `Reversi-v0`
- `KInARow-v0`, as well as `Gomuku-v0` and `TicTacToe-v0`
- `Go-v0` (Experimental)

## Install

    pip install --upgrade boardgame2


## Usage

Create a Game

```
import gym
import boardgame2

env = gym.make('TicTacToe-v0')
env = gym.make('Gomuku-v0')
env = gym.make('KInARow-v0', board_shape=5, target_length=4)
env = gym.make('KInARow-v0', board_shape=(3, 5), target_length=4)
env = gym.make('Reversi-v0')
env = gym.make('Reversi-v0', board_shape=6)
env = gym.make('Go-v0')
```

Play a Game

```
import gym
import boardgame2

env = gym.make('TicTacToe-v0')
print('observation space = {}'.format(env.observation_space))
print('action space = {}'.format(env.action_space))

observation = env.reset()
while True:
    action = env.action_space.sample()
    observation, reward, done, info = env.step(action)
    if done:
        break
env.close()
```

# API

### Constants

**boardgame2.BLACK**

The 1st player.

**boardgame2.WHITE**

The 2nd player.

**boardgame2.EMPTY**

Neither of the two players.

### Functions

**boardgame2.strfboard**
```
strfboard(board:np.array, render_characters:str='+ox', end:str='\n') -> str
```
Format a board as a string

**boardgame2.is_index**
```
is_index(board:np.array, location:np.array) -> bool
```
Check whether a location is a valid index for the board

**boardgame2.extend_board**
```
extend_board(board:np.array)
```
Get the rotations of the board. Only valid for square board.

### Classes

**boardgame2.BoardGameEnv**

The base class of all board game environment.

```
__init__(board_shape, illegal_action_mode:str='resign', render_characters:str='+ox', allow_pass:bool=True) -> boardgame2.BoardGameEnv
```
Constructor.
board_shape can be either an `int` or `(int, int)`.

```
seed(seed=None) -> NoneType
```
See `gym.Env.seed()`.

```
reset() -> tuple
```
See `gym.Env.reset()`.
observation is in the form of `(np.array, int)`.

```
step(action:np.array) -> tuple, float, bool, dict
```
See `gym.Env.step()`.

```
render(mode:str='human')
```
See `gym.Env.render()`.

```
is_valid(state:tuple, action:np.array) -> bool
```
Check whether the action is valid for current state.

```
get_valid(state:tuple) -> np.array
```
Get all valid locations for the current state.

```
has_valid(state:tuple) -> bool
```
Check whether there are valid locations for current state.

```
get_winner(state:tuple)
```
Check whether the game has ended. If so, who is the winner.

```
get_next_state(state:tuple, action:np.array) -> tuple
```
Get the next state.

```
next_step(state:tuple, action:np.array) -> tuple, float, bool, dict
```
Get the next observation, reward, done, and info. Similar to `gym.Env.step()`.

```
PASS
```
Intend to skip, as a predefined constant action.

```
RESIGN
```
Intend to resign, as a predefined constant action.


**boardgame2.KInARowEnv** (registered as `KInARow-v0`, as well as `Gomuku-v0` and `TicTacToe-v0`)
```
__init__(board_shape, target_length:int=3, illegal_action_mode:str='pass', render_characters:str='+ox') -> boardgame2.KInARowEnv
```


**boardgame2.ReversiEnv** (registered as `Reversi-v0`)
```
__init__(board_shape, render_characters:str='+ox') -> boardgame2.ReversiEnv
```


**boardgame2.GoEnv** (registered as `Go-v0`, Not fully implemented)
```
__init__(board_shape, komi:float=0., allow_suicide:bool=False, illegal_action_mode:str='pass', render_characters:str='+ox') -> boardgame2.GoEnv
```

