Tetro TUI - Cross-platform Terminal Game

A cross-platform terminal game where tetrominos fall and stack.

Ways to Run

Download

1. Download a release for your platform (windows, linux/unix/macos) if available.
2. Open your favorite terminal (preferably Kitty or Alacritty).
3. Run the application (e.g. ./tetro-tui or tetro-tui.exe).

Compile from source

1. Ensure Rust installed.
2. git clone https://github.com/Strophox/tetro-tui or manually download the source code.
3. Go inside tetro-tui/ and go cargo run.

Install via cargo

Tetro TUI is available on crates.io. It can be installed via cargo like so:

cargo install tetro-tui

Then you can run the game with tetro-tui.

FAQ

How does the game work?

Tetro is about tetromino pieces falling from the sky and stacking on a rectangular playing field.

Whenever a line is filled up horizontally, it clears away, and the rest of what you 'stacked' moves down. This way a skilled player can keep playing without Blocking Out the entire board.

How good is customization?

For what started as a small project, solid:

• Graphics: Unicode/ASCII/Electronika, 10 default color palettes, FPS, toggle effects...
• Keybinds: to your heart's desire.
• Gameplay/Handling: Rotation system, tetromino generator, preview count; DAS, ARR, SDF, LDC, ARE (timings), IRS/IHS
• Gamemode selection: 40-Lines, Marathon, Time Trial, Master; Puzzle, Cheese, Combo; Custom mode (choose initial gravity, gravity progress on/off, custom/no goal, commandline options: start board or seed).

Terminal customizations can carry over to game graphics, e.g. using cool-retro-term:

What was the motivation behind this project?

This is a passion project. The addition of the many features stem from personal motivation to make them available and make things enjoyable.

The result is (hopefully!) solid customizability; Editable json savefiles, compressed game replays, nontrivial gamemodes, a compile-time modding system, and almost as many modern stacker game mechanics as one could fit.

Maintaining high Rust code quality, especially in the game logic, was also important.

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

The application will not store anything UNLESS 'Keep save file' is opted in.

The exact location of the config file is visible in the Settings TUI menu:

• Location based on dirs::config_dir() (e.g. C:/User/username/AppData/Roaming/.tetro-tui_1.0.0_savefile.json, /home/username/.config/.tetro-tui_..),
• Otherwise directory of execution.

Savefile size may grow primarily due to saved replays (though good care has been taken to compress those well). You can choose past games to delete in the Scores and Replays menu.

Experienced Stackers: Why do timing-settings (DAS/ARR/SDF etc.) not always apply?

TL;DR use a terminal like kitty (or some other) for 'true' (smooth) gameplay experience. In all other cases some timing configurations depend on how your terminal/keyboard/OS simulates key-repetitions.

The problem lies in how terminals only send 'key-pressed-once' signals, but none 'key-released-again'. This makes it impossible to implement mechanics like: "If [←] is pressed, move left repeatedly until key is released again". Precisely this issue is fixed with 'kitty protocol' / 'progressive enhancement' / 'enhanced keyboard events'.

Experienced Stackers: How 'polished' are the precision mechanics?

Quote from the Falling Tetromino Engine powering the actual game logic:

The engine aims to compete on the order of modern tetromino stackers; It incorporates many features found in such games. Experienced players may be familiar with most of the following mechanics:

• Variable gravity/fall delay, possibly in-between 'frames', '20G' (fall delay = 0s),
• Simple but flexible programming of custom fall and lock delay progressions (DelayParameters),
• (Arbitrary) piece preview,
• Pre-spawn action toggle ('Initial Hold/Rotation System'),
• Rotation systems: 'Ocular' (engine-specific, playtested), 'Classic', 'Super',
• Tetromino generators: 'Uniform', 'Stock' (generalized Bag), 'Recency' (history), 'Balancerelative',
• Spawn delay (ARE),
• Delayed auto-shift (DAS),
• Auto-repeat rate (ARR),
• Soft drop factor (SDF),
• Lenient-lock-delay-reset toggle (reset lock delay even if rotation fails),
• Lock-reset-cap factor (~maximum time before lock delay cannot be reset),
• Line clear delay (LCD),
• Custom win/loss conditions based on stats: time, pieces, lines, score,
• Hold piece,
• Higher score for higher lineclears and spins ('allspin')
• Game reproducibility (PRNG),
• Available player actions: MoveLeft, MoveRight; RotateLeft, RotateRight, RotateAround (180°); DropSoft, DropHard, TeleDown ('Sonic drop'), TeleLeft, TeleRight, HoldPiece.

Experienced Stackers: In which ways is it unlike familiar stacker games?

The project took its liberties to adapt/experiment with certain aspects of game mechanics (to try and improve it):

• Custom Ocular Rotation System, instead of the 'odd' industry standard.
• Default controls set to WASD + Arrow.
• Recency/History generator instead of 'overdeterministic' 7-bag.
• Scoring system is different, more simplified.
  • 'Allspin' (no 'minis') instead of preoccupation with 'T-spins'.
  • Combos, but no back-to-back.
  • Exact formula is: score_bonus = if is_perfect_clear{ 4 }else{ 1 } * if is_spin{ 2 }else{ 1 } * lineclears * 2 - 1 + (combo - 1)
• Additional controls for Teleport Down (a.k.a. 'Sonic Drop') / Left / Right.
• Different lock reset implementation ('max 15 moves' vs. 'max 10⋅current lock delay')
• Speed/Gravity/Fall curve slightly adapted.

Experienced Stackers: What's the "Ocular Rotation System"?

A 'better' implementation of tetromino rotation, based off visual intuition and symmetry:

The Ocular Rotation System affords:

• Rotation based on 'where it looks like the piece should be able to go'.
• Symmetric (mirrored) situations should lead to symmetric (mirrored) outcomes.
• Tetrominos should not teleport up/down too much.

Visual heatmap comparison of rotation systems:

CLI Enthusiasts: How was the Terminal User Interface (TUI) programmed?

This basic but hopefully decent TUI was programmed directly using the amazing Crossterm. Crossterm handles all the placement of (colored) characters and reading inputs from the terminal. We implement custom diff'ing so I/O does not bottleneck smooth rendering.

How do I navigate the TUI? Can I see a table of all the controls?

General TUI menu controls:

Keys	~Meaning
↓ ↑ / j k	Navigate up/down
← → / h l	Change value
Enter/e	Select
Esc/q, Back/b	Go back
Del/d	Delete/reset
1 2 3...	Quickselect option 1,2,3 ... (→new game menu)
Shift+...	'Accelerate certain controls'
Shift+Del/d	Delete replay (→scores&replays menu)
Ctrl+C	Abort application

Default game controls:

Key	Action
Esc	Pause game
←	Move left
→	Move right
A	Rotate left (CCW)
-	Rotate around (180°)
D	Rotate right (CW)
↓	Soft drop
↑	Hard drop
-	Teleport down
-	Teleport left
-	Teleport right
Space	Hold piece
Ctrl+D	Forfeit game
Ctrl+E	Store seed (→custom mode)
Ctrl+S	Store savepoint (→new game menu)
Ctrl+Alt+B	Toggle on/off visibility of tiles ('Blindfold')
Ctrl+C	Abort application

Replay controls:

Key	Action
Esc/q, Back/b	Stop replay
Space	Pause replay
↓ ↑ / j k	Speed up / Slow down replay by 0.25
Shift+↓ ↑ / Shift+j k	Speed up / Slow down replay by 0.05
← → / h l	Skip forward/backward 1s in time
Shift+→ / Shift+l	Skip forward one user input and pause
Enter/e	Enter playable game from replay position
Ctrl+E	Store seed (→custom mode)
Ctrl+S	Store savepoint (→new game menu)
Ctrl+C	Abort application

License

Licensed under MIT.

Provenance

100% human-sourced spaghetti code

Color palettes used:

• Gruvbox, Solarized, Terafox, Fahrenheit, matrix, Sequoia Monochrome.

Acknowledgements

Special Thanks to:

• GrBtAce, KonSola5 and bennxt – for support early in development
• Dunspixel – for inspiration regarding 'O'-spin
• madkiwi – for advice regarding 4wide-6res combo layouts
• and RayZN and ˗ˋˏthe One and Onlyˎˊ˗ – for advice regarding the Tetro logo