Tetro TUI tackles a classic problem in terminal games: terminals historically lack the ability to detect key releases and modifier keys properly, which are essential for fine-grained input timing in a game like Tetris. This Rust-based terminal tetromino-stacking game uses the kitty keyboard protocol to overcome these limitations, enabling accurate DAS (delayed auto shift), ARR (auto repeat rate), and other timing mechanics. Beyond that, it offers a variety of game modes, rendering styles, and a rich customization surface, all packed into a cross-platform Rust binary.
What tetro tui does and how it works
Tetro TUI is a terminal user interface game written in Rust that brings the familiar tetromino stacking experience to the terminal with multiple twists. It supports various rendering modes, including ASCII, Unicode, and a retro Elektronika 60 style, along with 10 different color palettes, making it visually flexible across terminal types.
The game implements multiple tetromino rotation systems such as Ocular, Classic Left/Right, and Super Rotation System, catering to different player preferences and rulesets. Timing mechanics fundamental to Tetris gameplay — DAS, ARR, Soft Drop Factor (SDF), Line Clear Delay (LCD), and Auto Repeat Entry (ARE) — are precisely implemented, ensuring gameplay fidelity.
Under the hood, the project is built in Rust, leveraging its performance, safety, and cross-platform capabilities. It distributes through crates.io for easy Rust integration but also offers platform-specific binaries for broader accessibility.
The architecture centers on a terminal UI built with Rust’s ecosystem tools, but what really distinguishes it is the input system. Standard terminal input models do not send key release events and struggle with modifier keys, making accurate timing-based inputs difficult. Tetro TUI circumvents this by using the kitty terminal keyboard protocol, which supports key release detection and modifier keys, enabling the game to implement timing mechanisms with a level of precision rarely seen in terminal games.
Additional features include highscore tracking, replay recording, detailed gameplay statistics, and savefile management with configurable persistence, making it more than a casual terminal toy.
How tetro tui tackles terminal input limitations with the kitty protocol
The core technical strength of Tetro TUI lies in its input handling. Most terminal applications rely on the standard input system, which is limited to key press events without key release signals. This makes implementing fine-grained input timing mechanics like DAS and ARR challenging or impossible.
Tetro TUI leverages the kitty keyboard protocol, a specialized terminal input extension that augments standard input with key release events and modifier key support. This allows the game to detect when keys are pressed and released independently, enabling a precise measurement of how long a key is held down — which is essential for implementing the delayed auto shift (DAS) and auto repeat rate (ARR) mechanics that define modern Tetris gameplay.
Here’s the tradeoff: kitty protocol support requires the user’s terminal to be kitty or kitty-compatible, reducing the universality of the game’s input handling. However, for users with compatible terminals, the input responsiveness and accuracy are significantly improved compared to traditional terminal games.
The codebase integrates this via a dedicated input module that translates kitty protocol events into game input events. This involves parsing terminal escape sequences and managing input state machines to track key press durations and modifiers.
This approach is clever because it sidesteps the historical limitation of terminal input without resorting to heavier GUI frameworks or external input capture tools. It keeps the game lightweight and terminal-native while enabling a quality of input control that is rare in this space.
Explore the project and quickstart
To get started with Tetro TUI, the repository provides a straightforward installation method via Cargo, Rust’s package manager. From the command line, you can install it with:
cargo install tetro-tui
This command downloads, compiles, and installs the latest version of the game from crates.io, making it available as a CLI executable. From there, you can launch the game in your terminal.
Beyond the executable, the repository’s README and source code organize key resources such as configuration files for color palettes, input settings, and game mode definitions. The codebase is modular, with dedicated sections for rendering, input processing, game logic, and persistence.
The README also documents the various game modes — including Swift (40 lines), Classic Marathon, Master, Puzzle, Cheese, and Combo — giving players a range of challenges.
Verdict: who benefits from tetro tui and its limitations
Tetro TUI is well-suited for developers and terminal enthusiasts who enjoy classic games in a terminal environment but want better input fidelity than typical terminal games provide. Its use of the kitty keyboard protocol demonstrates an informed engineering tradeoff: sacrificing some terminal compatibility in exchange for precise input handling crucial for gameplay quality.
As a Rust project, it is also a good study in cross-platform terminal UI design and input handling. The code is surprisingly clean and well-structured given the complexity of timing mechanics and input event processing.
The main limitation is terminal compatibility. If your terminal does not support kitty protocol, you won’t get the full experience, especially around input timing. This is a necessary tradeoff given the constraints of terminal input models.
Overall, Tetro TUI is a solid example of pushing terminal games beyond their typical input limitations with a pragmatic and well-implemented solution. It’s worth checking out both for its gameplay and as a case study in terminal input engineering.
Related Articles
- nh: a Rust-based unified CLI for the Nix ecosystem with enhanced search and ergonomics — nh is a Rust CLI tool consolidating Nix, NixOS, and Home Manager commands with improved ergonomics, speed, and Elasticse
- CC Switch: unified management for AI coding CLIs in a cross-platform Rust desktop app — CC Switch is a Rust-based cross-platform desktop app that centralizes management of AI coding CLIs like Claude Code and
- Vaultwarden: a resource-efficient Rust implementation of the Bitwarden server API — Vaultwarden is a lightweight, Rust-based server compatible with the Bitwarden API, optimized for self-hosting with low r
→ GitHub Repo: Strophox/tetro-tui ⭐ 541 · Rust