Tetris Terminal🎮

A terminal-based Tetris game written in Python using the curses library.

Features

Modern Tetris design following the Tetris Design Guideline
- Extended Placement
- Next Piece Preview
- SRS System
- Piece Holding
- Shadow Piece
- Modern Scoring System
- Modern Level System

Platform Support

Based on Python's curses module:

✅ Linux/macOS: Works out of the box
✅️ Windows: With windows-curses
Can run on basically any terminal setup, even a linux tty.

Installation & Usage

pip install tetris-terminal
tetris

Controls

Key	Action
`a`, `←`	Move left
`d`, `→`	Move right
`w`, `↑`,`x`	Rotate cw
`z`	Rotate ccw
`s`, `↓`	Soft drop
`space`	Hard drop
`c`	Hold
`p`	Pause
`q`	Quit game

CLI Options

Option	Description
`--generate-config`	Generate a default config file and exit
`--disable-config`	Ignore config file and run with built-in defaults
`--version`	Show version and exit

Multiplayer (Versus Mode)

Compete in real-time 1v1 battles over WebSocket. Clear lines to send garbage to your opponent — the last player standing wins.

flowchart LR
    subgraph A ["Client A"]
        A1[game loop]
        A2[network]
    end

    subgraph S ["Server"]
        S1[Room]
    end

    subgraph B ["Client B"]
        B1[game loop]
        B2[network]
    end

    A1 <--> S1
    S1 <--> B1
    A2 <--> S1
    S1 <--> B2

Quick Start

# Terminal 1 — start the server
tetris-server

# Terminal 2 — connect client A
tetris --server localhost:8765

# Terminal 3 — connect client B
tetris --server localhost:8765

Once both clients connect, the server matches them and the battle begins.

CLI

Command	Description
`tetris-server`	Start the WebSocket matchmaking server
`tetris`	Launch the game in single-player modes
`tetris --server HOST:PORT`	Launch the game in multiplayer mode

`tetris-server` Options

Option	Default	Description
`--host`	`0.0.0.0`	Host address to bind
`--port`	`8765`	Port to listen on
`--version`		Show version and exit

`tetris --server` Options

Option	Description
`--server HOST:PORT`	Connect to a multiplayer server (default: `localhost:8765`)
`--disable-config`	Ignore config file and run with built-in defaults
`--version`	Show version and exit

Gameplay

Garbage system: Each cleared line generates garbage based on the standard Tetris scoring — more lines at once send more garbage.
Incoming garbage is shown as a Garbage counter on the side panel.
Garbage cancellation: Clearing lines while you have pending garbage cancels an equal number of incoming lines.
No pause: Versus mode disables pause to keep both players in sync.
Opponent disconnect: If the opponent disconnects, the match ends immediately.

Configuration

`multi_play`

Connection settings for multiplayer mode.

Key	Default	Description
`host`	`"localhost"`	Server hostname or IP
`port`	`8765`	Server port

Configuration

On first run, or via tetris --generate-config, a configuration file is created at:

Platform	Path
Linux	`~/.config/tetris-terminal/config.json`
macOS	`~/Library/Application Support/tetris-terminal/config.json`
Windows	`%APPDATA%/tetris-terminal/config.json`

The config file references a JSON Schema for editor autocompletion and validation. All fields are optional — missing keys fall back to their defaults.

display

Visual appearance of the game board.

Key	Default	Description
`empty_cell`	`" "`	Empty cell character
`solid_cell`	`"██"`	Filled cell character
`shadow_cell`	`"░░"`	Shadow piece character
`bd_v`	`"│"`	Border vertical
`bd_h`	`"─"`	Border horizontal
`bd_tl`	`"╭"`	Border top-left
`bd_tr`	`"╮"`	Border top-right
`bd_bl`	`"╰"`	Border bottom-left
`bd_br`	`"╯"`	Border bottom-right
`bd_vr`	`"├"`	Border T-right
`bd_vl`	`"┤"`	Border T-left
`bd_hb`	`"┬"`	Border T-bottom
`bd_ht`	`"┴"`	Border T-top

timing

Frame rate and animation settings.

Key	Default	Description
`fps`	`30`	Frames per second
`clear_anim_flash_interval`	`0.05`	Line clear flash interval (seconds)
`clear_anim_duration`	`0.3`	Line clear animation duration (seconds)

game_rules

Gameplay parameters.

Key	Default	Description
`max_lock_down_move_count`	`15`	Max moves before piece locks down
`time_attack_duration`	`120`	Time Attack mode duration (seconds)

License

MIT License - see LICENSE for details.

Acknowledgements

Idea from tinytetris (a C implementation).

Going to be implemented(Maybe)

sound
...

Metadata

Release files for tetris-terminal 0.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tetris-terminal 0.4.3
File	Size	Uploaded
tetris_terminal-0.4.3.tar.gz	56.7 kB	Jul 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tetris-terminal 0.4.3
File	Interpreter	ABI	Platform	Reset
tetris_terminal-0.4.3-py3-none-any.whl 38.9 kB Jul 28, 2026	Python 3	none	any	Details

Total release size: 95.6 kB

Release files / tetris_terminal-0.4.3.tar.gz

Download URL	tetris_terminal-0.4.3.tar.gz
Size	56.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`2ac44dc133a63fc399974eb6f38f32b9520f3c8309a35e1b8c344d1c37d3379f`
BLAKE2b-256 checksum How to use checksums	`9787ad74394d4799a9ea4d43b125efe54e601796ac956ceb5601444553a91803`
Upload date	Jul 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / tetris_terminal-0.4.3-py3-none-any.whl

Download URL	tetris_terminal-0.4.3-py3-none-any.whl
Size	38.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ed2d2972d10037bdb50c94a4284e40d379b10974d2d2b3f5c9af1654c230e80e`
BLAKE2b-256 checksum How to use checksums	`454c40c1aa8cab8a87dc0f0643d40f89abe7226cdb1e6c433703d258252dbe6e`
Upload date	Jul 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`