Terminal Tetris

Modern guideline Tetris, played in your terminal. Pure Python 3 — no pip packages required.

Install

pipx install tetris-tui        # or: pip install tetris-tui
terminal-tetris

Straight from source, no PyPI needed:

pipx install git+https://github.com/ErenSuner/terminal-tetris
terminal-tetris

From a clone, with nothing installed at all:

git clone https://github.com/ErenSuner/terminal-tetris
cd terminal-tetris
python tetris.py

The installed command is terminal-tetris; python -m terminal_tetris works too. Windows, macOS and Linux terminals are all supported (Windows uses msvcrt plus a console-mode call for ANSI, POSIX uses termios + select).

Controls

Flags

--ascii turns itself on when the console code page cannot encode box drawing characters.

Rules

Follows guideline Tetris:

• SRS rotation with wall kick tables (the I piece uses its own table), plus a simple 180° kick set.
• 7-bag randomness: all seven tetrominoes in every window of seven pieces.
• Hold + a five-piece next queue + ghost piece.
• Lock delay of 0.5 s; moves and rotations reset the timer, at most 15 times (no infinite spin).
• Scoring: single 100, double 300, triple 500, tetris 800 (× level). T-spin 400/800/1200/1600, T-spin mini 100/200/400. Back-to-back difficult clears (tetris or T-spin) ×1.5. Combo is 50 × combo × level.
• Level goes up every 10 lines; drop speed is (0.8 - (level-1) × 0.007) ^ (level-1) seconds per row.

Combo and records

• Combo meter: the COMBO bar in the left panel fills while the chain holds (x3 ▓▓▓░░) and empties when it breaks. The banner also prints the points earned: B2B TETRIS x3 COMBO +1800.
• Personal records: score, lines, level, longest combo and time are each tracked separately. The panel shows the BEST score; it turns gold the moment you pass it in-game, and the screen prints YENI REKOR! on game over. Records are written on game over and on quit — the lines and combo of an unfinished run count too. File: %APPDATA%\terminal-tetris\records.json on Windows, otherwise $XDG_DATA_HOME or ~/.local/share/terminal-tetris/records.json. If the file is missing or corrupt the game silently starts from zero.

There is no animation in the playfield: whatever the engine holds is what gets drawn. Flashes, drop trails and border glows were tried and removed — they broke the retro feel.

Structure

tetris.py                     run from a clone
terminal_tetris/cli.py        entry point: flags, main loop, key mapping
terminal_tetris/terminal.py   raw mode, non-blocking key reads, alt screen, UTF-8
terminal_tetris/pieces.py     tetromino shapes, SRS rotation and kick tables
terminal_tetris/board.py      10x40 playfield: collision, locking, line clears
terminal_tetris/engine.py     gravity, lock delay, 7-bag, hold, scoring, T-spin
terminal_tetris/render.py     ANSI frame builder and panels
terminal_tetris/scores.py     atomic JSON writes for personal records

board, pieces and engine know nothing about the terminal; the tests drive the engine directly.

Tests

python -m unittest discover -s tests -t .

Notes

• Terminals do not report key-up events, so real DAS/ARR tuning is impossible; the OS key repeat rate sets the horizontal repeat speed.
• Below 46x24 the game does not crash, it shows a warning.
• The key help on the bottom row is packed to fit the window: with room to spare, key + action spread over several lines; in a narrow window the labels drop but every key stays visible.
• Every exit path, Ctrl+C included, restores the cursor, echo and normal screen.
• Banner lifetime is measured through game.elapsed: the engine stamps the time of the last clear and the renderer looks at its age. Pausing stops that clock too.

Releasing

Publishing runs on GitHub Actions via PyPI Trusted Publishing — no API token is stored. Bump version in pyproject.toml, then:

git tag v1.0.0
git push origin v1.0.0

.github/workflows/release.yml runs the tests on Linux/macOS/Windows against Python 3.9 and 3.13, checks that the tag matches the packaged version, builds the sdist and wheel, and uploads them to PyPI.

License

MIT — see LICENSE.