tetro-tui

Tetro TUI - Terminal Game

Tetro TUI is a terminal-based but modern tetromino-stacking game that is customizable and cross-platform.

6 more demo images available;

Ways to Run

Download & Run

1. Download a release for your platform (Linux/MacOS/Windows/...) if available.
2. Navigate to the application binary (tetro-tui/tetro-tui.exe/...) and run it in a terminal

Quick Install

Cargo (crates.io):

cargo install tetro-tui
#  tetro-tui

Arch Linux (aur.archlinux.org):

yay -S tetro-tui # Or paru, etc.
#  tetro-tui

Compile from source

Tetro TUI is written in Rust 1.95.0 and can be compiled as usual:

git clone https://github.com/Strophox/tetro-tui
cd tetro-tui
cargo run

FAQ

How does the base game work?

Tetro TUI is about tetromino pieces falling from the sky and stacking inside a 2D playing field. When horizontal lines are filled they automatically clear away and everything 'stacked' above moves down.

A skilled player may keep playing indefinitely. Different game modes will change up the gameplay while still using the same base mechanics.

How good is it in terms of configuration / features?

We provide a solid amount of customization options / features for casual and (potentially) experienced players alike:

• Graphics: Unicode/ASCII/Elektronika styles, old-terminal-compatible or very modern designs, 10 color palettes, hard drop/piece lock/line clear effects and much more.
• Game keybinds: to your heart's desire.
• Gameplay/handling: Various rotation systems, piece randomizers, adjustable preview, timings (DAS¹, ARR¹, SDF¹, LCD, ARE), IRS/IHS/.. (¹caveat).
• Game mode miscellany: Regular ('Marathon'), Swift ('40-Lines'), Classic & Master (unlocked after Regular), Puzzle, Cheese, Combo, Custom (select: win condition, initial gravity, toggle: gravity progress, no top out, cmdline flags: start board, seed).
• Highscores, replays, statistics, ... - can be viewed as well as backed up with a simple savefile.

Visuals can be customized together with your underlying terminal settings. E.g. one can set a bigger font to scale the game, or use cool-retro-term for a nostalgic look etc.

See also: Big overview of actual Tetro TUI v3.5 menus:

- Title screen -

• New Game
• Settings
• Scores and Replays
• All-Time Stats
• About
• Quit [←↓↑→/Enter/Esc/Del] or Vim, Press [?] to view keybinds anytime

+ Start New Game +

• Regular: Clear 160 lines as gravity increases.
• Swift: How quickly can you clear 40 lines?
• (unlocked after Regular) Classic (lvl 0+)(*): 'NES' Gameplay/Graphics settings recommended.
• (unlocked after Regular) Master: Clear 320 lines at instant gravity.
• Puzzle: Clear 24 hand-crafted puzzles (feat. the Ocular rotation system)
• Cheese-40: Efficiently eat through some lines. Limit∈[None, Some(10), Some(11), .., Some(40), ..]
• Survival: Lines regenerate as you place more pieces.
• Combo-30: Get consecutive line clears. Limit∈[None, Some(10), Some(11), .., Some(30), ..]
• (unlocked with Ctrl+U) Placement: Practice placing pieces.
• (unlocked with Ctrl+U) Ascent: Experimental gamemode (requires 180° rot.)
• Custom: [Del]=reset
  • Initial fall delay = 1.000000000s (Gravity: 1.00 Hz)
  • Progressive gravity ∈ [on, off]
  • Limit ∈ [None, TimeElapsed(300s), .., PointsScored(200), .., PiecesLocked(100), .., LinesCleared(40), ..]
• (available after using Ctrl+S) Game save

# Graphics Settings #

• Slot ∈ [Default, Guideline, Terminal compatibility, Focus+, Minimal, I⠐⢷⠗ Braille, Elektronika 60, NES; Custom I/II/..]
• Tile colors ∈ [Terminal default, Just white, ANSI, Tetro Pastel, Guideline, Gruvbox, Solarized, Terafox, Fahrenheit, Matrix, Sequoia, Just amber, NES levels]
• UI colors ∈ [Terminal default, Just black/white, Tetro Dark, Gruvbox Dark, Solarized Light, Matrix, Sequoia, Just amber, NES, OneHalfDark]
• UI style ∈ [ASCII, Frame UTF8, Rounded frame UTF8, No frame UTF8, No hold/next-frame, Braille, Elektronika 60]
• Hard drop effect ∈ [None, Particle trail ASCII, Particle trail 2 ASCII, Particle beam ASCII, Colored beam UTF8, White beam UTF8, Braille helix]
• Lock effect ∈ [None, Flash white, Transforming ASCII, Pulsing block UTF8, Spiraling Braille]
• Line clear effect ∈ [None, Disappear halfway, Disappear instantly, Blink, Flash white, Clear left-to-right, Clear outward, White clear inward, Burn outward, Pop, Pop (more), Confetti (gratuitous), Stardust, Blast, Sparks, Sparks Braille, Sparks ASCII]
• Tile/Tetromino symbols ∈ [ASCII, Blocks UTF8, Braille, NES simulacra, Elektronika 60]
• Small tetromino symbols ∈ [Dots ASCII, Blocks UTF8, Braille]
• Mini tetromino symbols ∈ [Letters, Braille]
• Normalsized tetromino previews ∈ [unlimited, 1, 2 ..]
• Frames rendered per second ∈ [5, 10, .., 60, ..]
• Grid ∈ [on, off]
• Piece shadow ∈ [on, off]
• Upcoming spawn preview (if stack high) ∈ [on, off]
• Uniform locked tiles ∈ [on, off]
• Main HUD ∈ [on, off]
• Include basic keybinds HUD ∈ [on, off]
• Show active/held buttons ∈ [on, off]
• Lock delay visualizer ∈ [on, off]
• FPS counter ∈ [on, off]

@ Game Keybinds @

• Slot (modifiable preset) ∈ [Default, Guideline, Control+, Terminal finesse, Vim; Custom I/II/..]
• MoveLeft, MoveRight;
• RotateLeft, RotateRight, Rotate180;
• DropSoft, DropHard;
• TeleDown, TeleLeft, TeleRight;
• HoldPiece.

Settings/Adjust-Gameplay/

• Slot ∈ [Default, Guideline, Finesse+, Elektronika 60, Gameboy, NES; Custom I/II/..]
• Piece rotation ∈ [Ocular, ClassicL, ClassicR, Super]
• Piece randomization ∈ [Uniformly random, Classic (Reroll 1x), Rerollx 2x, .., 7-Bag, 14-Bag, .., Balance out, Recency (^2.5), Recency (^2.6), ..]
• Piece preview count ∈ [0, 1, .., 4, ..]
• Delayed auto move (DAS) ∈ [0ms, 1ms, .., 167ms, ..]
• Auto repeat rate (ARR) ∈ [0ms, 1ms, .., 33ms, ..]
• Delayed soft drop ∈ [None, Some(5ms), Some(10ms), .., Some(100ms), ..]
• Soft drop rate (SDF) ∈ [raise gravity to 30 Hz, ..; 0x gravity, 0.25x gravity, .., 15x, .., inf x gravity]
• Line clear duration (LCD) ∈ [0ms, 5ms, .., 200ms, ..]
• Spawn delay (ARE) ∈ [0ms, 5ms, .., 50ms, ..]
• Allow spawn manipulation (hold-IRS/IHS/IMS/ITS) ∈ [on, off]
• Convert double-tap to teleport ∈ [None, Some(5ms), Some(10ms), ..]

§ Advanced Settings §

• Save ∈ ["--Nothing", "Only settings,stats --No scores,replays", "Only settings,stats,scores --No replays", "Everything (settings,stats,scores,replays)"]
• Renderer used ∈ [Main, Halfblock, Braille]
• Pause on focus lost ∈ [on, off]
• 'Blindfold' game ∈ [on, off]
• Assume enhanced-key-events available ∈ [on, off]

Why do some gameplay preferences (DAS/ARR/SDF...) or some keybinds (Ctrl/Shift/Alt/...) not work for me?

It is likely that your current terminal provides too little input information to enable custom timings¹ or those special keys. (¹Instead, DAS/ARR/SDF will be determined by how quickly your terminal sends key-repeat events.) If possible use an enhanced terminal like Kitty or Alacritty (also others) for flawless game handling.

Explanation:

The fundamental problem lies in how terminals usually send input signals.

• Due to historical reasons, most will only send "key pressed" but not "key released again". This makes it impossible to implement mechanics such as: "If [←] is pressed, move left with a certain speed until key is released again."
  • Affected mechanics: Generally unable to actually 'hold' any buttons; DAS & ARR & SDF determined by terminal (& holding Soft Drop may 'accidentally' lock the piece), unable to hold Teleport, unable to hold for IRS/IHS/IMS/ITS.
  • Note that some terminals e.g. on Windows do send key-release signals, without this being auto-detected: Use the override in Advanced Settings for such cases.
• Also due to history, modifier keys can only modify 'actual' text signals and are never sent by themselves.
  • Affected mechanics: Cannot register modifier Ctrl/Alt/Shift/Win/⌘/... as individual key presses.

Precisely these issues are fixed with 'enhanced keyboard events' / 'kitty keyboard protocol'.

Where's the config file? Will it clutter my system?

The application will not store anything by default and 'Keep save file' needs to be opted in;

The exact location of the config file is shown in the Advanced Settings menu and is based on dirs::config_dir():

• Usually /home/yourname/.config/.tetro-tui_v1.0_savefile.json
• or C:/User/yourname/AppData/Roaming/.tetro-tui_v1.0_savefile.json

Savefile grows primarly due to number/length of saved replays. As a rule of thumb, 1min of gameplay with fast inputs adds ≲ 1 kB. If you end up with a lot of play time but can't/don't want to spare the kB / MB, you can:

• Delete some entries (// just their replay data) in Scores and Replays using [Del] (// [Alt+Del]).
• Configure which categories of data get stored in the first place on program exit (see Advanced Settings).

Experienced players: How does it compare to (or deviate from) common stacker games?

At the time of writing we implement all the most common mechanics found in the wild (and then some). Groups of (e.g. gameplay) settings are bundled in a 'slot'(= settings template/profile) which allows us to provide common presets as well as our suggested defaults.

See list of notable differences:

Keybinds:

• Default controls suggested to be WASD + Arrow keys (reasoning: We prefer to assign movement and rotation to separate hands instead of mixing; do not use Shift key due to common terminal limitations).
• Dedicated buttons supplied for Rotate 180°, Teleport Down ('Sonic Drop') and Teleport Left/Right.

Gameplay:

• Default rotation system suggested to be the Ocular Rotation System (reasoning: Ocular is designed to be symmetrical, intuitive and flexible (in different ways) compared to the quirky / sometimes asymmetrical 'Super' Rot.Sys.).
• Default piece randomizer suggested to be a Recency Randomizer (reasoning: 'Recency' is biased toward 'fairly' choosing less recent pieces but still technically allowing arbitrary piece sequences, compared to the 'overdeterministic' 7-Bag).
• Points (score) bonus system is currently kept custom and simple.
  • '1pt for simple line clear, with increasing bonus for larger lineclears, combos, spins and perfect clears.'
  • Note: 'Allspin' without 'minis' (reasoning: we are not preoccupied with just 'T-spins').
  • Note: Combos, without 'back-to-back' (reasoning: Back-to-back incentivizes playing special maneuvers, but those already yield disproportionate score bonus by themselves).
  • Exact formula: point_bonus = lineclears*lineclears * if is_spin{ 4 }else{ 1 } * if is_perfect{ 4 }else{ 1 } + (combo - 1)
• Time-based lock reset limit (reasoning: Providing a 'hard time limit before lock'(= N⋅current lock delay) seems more flexible/natural than 'hard move limit before lock'(=N 'moves').
• Default speed/gravity/fall curve is slightly less aggressive but very close to standard (reason: We use a simpler formula).

Graphics:

• Default palette is more pastel (reasoning: Uniform perceptual brightness, 'looks pretty').

See list of core game engine mechanics:

• Available player actions:
  • Move left/right,
  • Rotate left/right/180°
  • Drop soft/har