Tetris

Description	Details
Action Space	Discrete(8)
Observation Space	Dict containing three fields:
	1. board: Box (0, 9, (24, 18), uint8)
	2. active_tetromino_mask: Box (0, 1, (24, 18), uint8)
	3. holder: Box (0, 9, (4, 4), uint8)
	4. queue: Box (0, 9, (4, 20), uint8)
import	gymnasium.make("tetris_gymnasium/Tetris")

Description

This is the base Tetris environment. It is designed to be customizable and can be altered with Wrappers.

The base environment consists of the following components, which can all be adjusted either by using Wrappers or passing arguments to the environment constructor:

• Board: The playing field where the tetrominoes are placed.

• Holder: A place where the player can store a tetromino for later use.

• Queue: A queue of tetrominoes that will be spawned next.

• Randomizer: A component that generates the tetrominoes in the queue.

• Queue: A component that holds the tetrominoes that will be spawned next.

• Tetrominoes: The pieces that the player can move and rotate.

Observation Space

The observation space is a dictionary containing the following elements:

• The board: 2D-array of shape height x width (padded)

  • The padding is equal to the largest tetromino in the game, which is usually the I-Tetromino, therefore 4

• The active tetromino mask: 2D-array of shape height x width (padded) indicating where the active tetromino is placed (1) and where it is not (0)

  • This information may be used during training to help the agent distinguish between the active tetromino and the board

• The holder: 1D-array of tetrominoes (padded to the same size)

• The queue: 1D-array of tetrominoes (padded to the same size)

The observation space can be altered to your needs by using Observation wrappers.

Actions Space

The environment supports actions as defined in the Actions mapping.

Rewards

The environment assigns rewards based on the Rewards mapping.

Starting state

The environment starts with an empty board and a random tetromino rendered at the top center of the board.

Episode Termination

The episode ends, a tetromino cannot be spawned at the top of the board.

Arguments

class tetris_gymnasium.envs.tetris.Tetris(render_mode=None, width=10, height=20, gravity=True, actions_mapping=ActionsMapping(), rewards_mapping=RewardsMapping(), queue: TetrominoQueue | None = None, holder: TetrominoHolder | None = None, randomizer: Randomizer | None = None, base_pixels=None, tetrominoes=None, render_upscale: int = 10)

Tetris environment for Gymnasium.

Parameters:

• render_mode – The mode to use for rendering. If None, no rendering will be done.

• width – The width of the board.

• height – The height of the board.

• gravity – Whether gravity is enabled in the game..

• actions_mapping – The mapping for the actions that the agent can take.

• rewards_mapping – The mapping for the rewards that the agent can receive.

• queue – The TetrominoQueue to use for holding tetrominoes temporarily.

• holder – The TetrominoHolder to use for storing tetrominoes.

• randomizer – The Randomizer to use for selecting tetrominoes

• base_pixels – A list of base (non-Tetromino) Pixel to use for the environment (e.g. empty, bedrock).

• tetrominoes – A list of Tetromino to use in the environment.

• render_upscale – The factor to upscale the rendered board by.

Pixels and Tetrominoes

The base_pixels and tetrominoes arguments are used to customize the very basic components of the game. To get an overview of the meaning of these components, please refer to the dedicated section about Tetrominoes.

During the initialization of the environment, the passed tetrominoes will be preprocessed. This involves changing the binary values in the matrix to the according pixel ids. The pixel ids are later used to render the tetrominoes on the board.

The default tetrominoes and pixels are stored as constants in the environment. They are the following:

• Pixels

  • 0: Empty

  • 1: Bedrock (also used as padding / border)

• Tetrominoes

  • I, J, L, O, S, T, Z

In particular, the matrices of the default Tetrominoes (before adjusting the binary values with their respective ids) look like this:

Tetromino	Matrix	Tetromino	Matrix
I	[[0, 0, 0, 0],	J	[[1, 0, 0],
	[1, 1, 1, 1],		[1, 1, 1],
	[0, 0, 0, 0],		[0, 0, 0]]
	[0, 0, 0, 0]]
L	[[0, 0, 1],	O	[[1, 1],
	[1, 1, 1],		[1, 1]]
	[0, 0, 0]]
S	[[0, 1, 1],	T	[[0, 1, 0],
	[1, 1, 0],		[1, 1, 1],
	[0, 0, 0]]		[0, 0, 0]]
Z	[[1, 1, 0],
	[0, 1, 1],
	[0, 0, 0]]