gym-tetris 2.2.0

Tetris (NES) for OpenAI Gym

gym-tetris

An OpenAI Gym environment for Tetris on The Nintendo Entertainment System (NES) based on the nes-py emulator.

Installation

The preferred installation of gym-tetris is from pip:

pip install gym-tetris

Usage

Python

You must import gym_tetris before trying to make an environment. This is because gym environments are registered at runtime. By default, gym_tetris environments use the full NES action space of 256 discrete actions. To constrain this, gym_tetris.actions provides an action list called MOVEMENT (20 discrete actions) for the nes_py.wrappers.BinarySpaceToDiscreteSpaceEnv wrapper. There is also SIMPLE_MOVEMENT with a reduced action space (6 actions). For exact details, see gym_tetris/actions.py.

from nes_py.wrappers import BinarySpaceToDiscreteSpaceEnv
import gym_tetris
from gym_tetris.actions import MOVEMENT

env = gym_tetris.make('Tetris-v0')
env = BinarySpaceToDiscreteSpaceEnv(env, MOVEMENT)

done = True
for step in range(5000):
    if done:
        state = env.reset()
    state, reward, done, info = env.step(env.action_space.sample())
    env.render()

env.close()

NOTE: gym_tetris.make is just an alias to gym.make for convenience.

NOTE: remove calls to render in training code for a nontrivial speedup.

Command Line

gym_tetris features a command line interface for playing environments using either the keyboard, or uniform random movement.

gym_tetris -e <`Tetris-v0` or `Tetris-v1`> -m <`human` or `random`>

Environments

Environment	Reward function
Tetris-v0	Instantaneous change in score
Tetris-v1	2^(Number of lines cleared) - 1

Note on v1: The number of lines cleared is managed by the NES and fires until the PPU removes the cleared line from the screen. In other words, the reward is triggered for every frame that cleared lines are visible.

info dictionary

The info dictionary returned by the step method contains the following keys:

Key	Type	Description
current_piece	str	the current piece as a string
number_of_lines	int	the number of cleared lines
score	int	the current score of the game
next_piece	str	the next piece on deck
statistics	dict	statistics for each piece

Citation

Please cite gym-tetris if you use it in your research.

@misc{gym-tetris,
  author = {Christian Kauten},
  title = {{Tetris (NES)} for {OpenAI Gym}},
  year = {2019},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/Kautenja/gym-tetris}},
}

References

The following references contributed to the construction of this project.

1. Tetris (NES): RAM Map. Data Crystal ROM Hacking.
2. Tetris: Memory Addresses. NES Hacker.
3. Applying Artificial Intelligence to Nintendo Tetris. MeatFighter.