gym-tetris
A Gymnasium environment for Tetris on The Nintendo Entertainment System (NES) based on the nes-py emulator. It currently supports CPython 3.13 and 3.14 in CI.
Installation
The preferred installation of gym-tetris is from pip:
pip install gym-tetris
Python 3.13 or newer is required. The supported CI targets are CPython 3.13 and 3.14.
Usage
Python
You must import gym_tetris before trying to make an environment.
This is because Gymnasium 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 (12 discrete actions) for the
nes_py.wrappers.JoypadSpace wrapper. There is also
SIMPLE_MOVEMENT with a reduced action space (6 actions). For exact details,
see gym_tetris/actions.py.
import gymnasium as gym
import gym_tetris
from gym_tetris.actions import MOVEMENT
from nes_py.wrappers import JoypadSpace
env = gym.make('TetrisA-v0', render_mode='rgb_array')
env = JoypadSpace(env, MOVEMENT)
observation, info = env.reset(seed=123)
terminated = False
truncated = False
for step in range(5000):
if terminated or truncated:
observation, info = env.reset(seed=123)
terminated = False
truncated = False
observation, reward, terminated, truncated, info = env.step(
env.action_space.sample(),
)
frame = env.render()
env.close()
NOTE: gym_tetris.make is just an alias to gymnasium.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 -h
gym_tetris --env TetrisA-v0 --mode human --actionspace simple
gym_tetris --env TetrisA-v0 --mode random --steps 100 --render --seed 123
gym_tetris --env TetrisA-v0 --mode random --steps 100 --no-render --actionspace simple --seed 123
gym_tetris --env TetrisB-v0 --mode random --steps 100 --render --actionspace standard
Human mode requires rendering, so --mode human --no-render is rejected.
Use --seed/-S to seed only the first environment reset in CLI playback.
Environments
There are two game modes defined in NES Tetris, namely, A-type and B-type. A-type is the standard endurance Tetris game and B-type is an arcade style mode where the agent must clear a certain number of lines to win. There are three potential reward streams: (1) the change in score, (2) the change in number of lines cleared, and (3) a penalty for an increase in board height. The table below defines the available environments in terms of the game mode (i.e., A-type or B-type) and the rewards applied.
| Environment | Game Mode | reward score | reward lines | penalize height |
|---|---|---|---|---|
TetrisA-v0 |
A-type | ✅ | ✕ | ✕ |
TetrisA-v1 |
A-type | ✕ | ✅ | ✕ |
TetrisA-v2 |
A-type | ✅ | ✕ | ✅ |
TetrisA-v3 |
A-type | ✕ | ✅ | ✅ |
TetrisB-v0 |
B-type | ✅ | ✕ | ✕ |
TetrisB-v1 |
B-type | ✕ | ✅ | ✕ |
TetrisB-v2 |
B-type | ✅ | ✕ | ✅ |
TetrisB-v3 |
B-type | ✕ | ✅ | ✅ |
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 in [0, 999] |
score |
int |
the current score of the game in [0, 999999] |
next_piece |
str |
the next piece on deck as a string |
statistics |
dict |
the number of tetriminos dispatched (by type) |
board_height |
int |
the height of the board in [0, 20] |
Publishing
PyPI releases are published by the Publish to PyPI GitHub Actions workflow
through PyPI trusted publishing, not by local twine credentials. Configure
the PyPI project publisher with owner Kautenja, repository gym-tetris,
workflow filename publish.yml, and environment pypi.
Releases should follow the current GitHub Actions flow:
- Create and push a tag that matches
pyproject.toml's version, with or without a leadingv. - Let CI build the tagged distribution artifacts.
- Publish a GitHub Release from that tag to trigger the trusted-publishing workflow.
Build distributions locally with python -m build only for verification, not
for authenticated upload.
Citation
Please cite gym-tetris if you use it in your research.
@misc{gym-tetris,
author = {Christian Kauten},
howpublished = {GitHub},
title = {{Tetris (NES)} for {Gymnasium}},
URL = {https://github.com/Kautenja/gym-tetris},
year = {2019},
}
References
The following references contributed to the construction of this project.
- Tetris (NES): RAM Map. Data Crystal ROM Hacking.
- Tetris: Memory Addresses. NES Hacker.
- Applying Artificial Intelligence to Nintendo Tetris. MeatFighter.
1 maintainer
Release files for gym-tetris 4.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gym_tetris-4.0.0.tar.gz | 38.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gym_tetris-4.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 74.2 kB
Release files / gym_tetris-4.0.0.tar.gz
| Download URL | gym_tetris-4.0.0.tar.gz |
|---|---|
| Size | 38.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6503f714684509f57285b77ea7f59547254da4c44d4776d689e5d0717f23fe9f
|
|
BLAKE2b-256 checksum How to use checksums |
cf494e4b0fc52d7a90383e9d1d00518bb50294a0b7d5511dbb68d86e0c16ac4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 18, 2026.
Transparency logRelease files / gym_tetris-4.0.0-py3-none-any.whl
| Download URL | gym_tetris-4.0.0-py3-none-any.whl |
|---|---|
| Size | 35.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
048ffa24cfb22330fd81ba89b61f3ec887db0fa6f256ccce191b3c920c86a042
|
|
BLAKE2b-256 checksum How to use checksums |
463e966bafab15d97335d572cd640f30506d5d04de9871fefceca27cc485f29a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 18, 2026.
Transparency log
