Project Info

Overview

This repository provides a custom Tetris environment for reinforcement learning using the Gymnasium API.

Core implementation: env/tetris.py

Features

  • Gymnasium-compatible environment class (Tetris) with reset, step, render, and close.
  • Two difficulty levels:
    • easy: left, right, drop, idle.
    • hard: left, right, drop, idle, rotate.
  • Natural gravity: each step advances the piece downward automatically.
  • Reward shaping:
    • line clear rewards: 1/4/9/16 for clearing 1/2/3/4 lines,
    • small survival reward per step,
    • negative reward on game over.
  • Observation modes:
    • board: 2D binary board,
    • dict: board plus current piece metadata,
    • features: handcrafted 4D feature vector.
  • Time and score tracking in info for RL logging:
    • score,
    • elapsed_time_seconds,
    • lines_cleared_total, etc.
  • Two render backends:
    • ascii (terminal),
    • pygame (windowed graphics).

Project Structure

.
├─ env/
│  ├─ tetris.py
│  └─ __init__.py
├─ rl_method/
│  └─ dqn_agent.py
├─ utils/
│  ├─ human_play.py
│  ├─ random_env_test.py
│  └─ __init__.py
├─ run_utils.sh
├─ play.bat
├─ requirements.txt
└─ README.md

Requirements

Installation

Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Linux / macOS / WSL

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Quick Start

1. Run random smoke test

python -m utils.random_env_test

Or via bash helper:

bash run_utils.sh test

2. Play manually (ASCII)

python -m utils.human_play --render-backend ascii --difficulty hard

3. Play manually (Pygame window)

python -m utils.human_play --render-backend pygame --difficulty hard

Windows shortcut:

play.bat

Controls (Human Play)

  • A / Left Arrow: move left
  • D / Right Arrow: move right
  • S / Down Arrow: drop current piece immediately
  • W / Up Arrow (hard mode): rotate
  • Space (hard mode): drop current piece immediately
  • Q / Esc: quit

Environment API Notes

  • reset() returns (observation, info).
  • step(action) returns (observation, reward, terminated, truncated, info).

Important info fields include:

  • score
  • elapsed_time_seconds
  • step_count
  • lines_cleared
  • lines_cleared_total
  • difficulty

Example: Use in Python

from env.tetris import Tetris

env = Tetris(
		difficulty="hard",
		observation_mode="board",
		render_backend="pygame",
		render_mode="human",
)

obs, info = env.reset(seed=42)
done, truncated = False, False

while not done and not truncated:
		action = env.action_space.sample()
		obs, reward, done, truncated, info = env.step(action)

env.close()

Notes

  • The environment prefers gymnasium, with a fallback import for legacy gym.
  • For headless training, use render_mode=None and render_backend="ascii".
  • For visual debugging, use render_backend="pygame".