TUI Tetris

Classic NES-style Tetris in your terminal. Play solo or challenge a friend over P2P.

Quick start · Game modes · P2P matches · Controls

TUI Tetris brings NES-style A-Type play to a modern terminal. The game uses a 10×20 field and the original level-color cycle.

The engine includes NES gravity, Nintendo rotation, line scoring, entry delay, DAS, and the biased reroll randomizer. OpenTUI draws exact 8×8 tile forms.

Gameplay

Quick start

npx tuitetris

Or install the command globally:

npm install --global tuitetris
tuitetris

Classic starts at level 0. Press m to select Casual, Competitive, or Modern play.

Ghostty gives the intended exact 8×8 tile output. Inside Herdr, the game keeps that artwork but reuses small cached tile images instead of retransmitting the complete playfield whenever a piece moves. Terminals without Kitty or Sixel image support—including the Codex integrated terminal—and passthrough multiplexers such as tmux, Zellij, and GNU Screen use a stable 2×1 terminal-cell renderer.

To override renderer detection, set TUITETRIS_RENDERER=native, TUITETRIS_RENDERER=tiles, or TUITETRIS_RENDERER=cells before the command.

Game modes

Mode	Start command	Rules
Classic	tuitetris	NES-style play at level 0. Space rotates clockwise.
Competitive	tuitetris --level 18	Classic rules with a level-18 start.
Modern	tuitetris --modern	Adds a landing ghost and hard drop. Space locks the piece immediately.

Classic lets you select a starting level from 0 through 19. Play continues beyond that range: level 29 is the classic one-row-per-frame kill screen, and the engine can continue past it like the NES game.

Modern hard drop awards two points for each descended row. Modern does not add hold, wall kicks, or modern rotation rules.

P2P friend matches

Start a best-of-three match:

# The host selects the mode and level.
tuitetris --host --mode classic --level 18 --name RAMOS

Send the printed ticket to one friend. Then the friend runs this command:

tuitetris --join 'tuitetris1_…' --name FRIEND

The host's --level selection is embedded in the ticket and applies to both players in every round. The joining player cannot override it.

Iroh connects both players through authenticated QUIC. It uses a direct P2P path when possible and an encrypted relay path when necessary.

Both players receive the same piece seed. The first player to win two score-based rounds wins the match.

After one player tops out, the other player continues until the score is higher. An exact score tie starts a new round.

Caution

Share the match ticket only with the intended player. The ticket and a direct connection can reveal your public IP address.

This feature is for trusted friend matches. Signed state messages identify each endpoint, but they do not provide anti-cheat protection.

Read the P2P protocol and security notes for the message format, identity model, match rules, and privacy limits.

Controls

Key	Action
Left / h	Move left.
Right / l	Move right.
Down / j	Soft drop.
Up / x / k	Rotate clockwise.
z	Rotate counterclockwise.
Space	Rotate in Classic. Hard drop in Modern.
p	Pause a solo game.
r	Restart a solo game.
m	Open the solo mode menu.
s	Turn sound on or off.
q / Escape	Quit. This action forfeits an active P2P match.

The game does not play a sound for movement or rotation. It plays cues for locks, line clears, Tetrises, level changes, and game over.

Development

Install Bun 1.3 or newer, then run the game from a source checkout:

bun install
bun run start

Run the local quality commands:

bun test
bun run typecheck
bun run fmt:check

Build and smoke-test the standalone executable:

bun run build:smoke

Tagged releases produce native Apple Silicon and Intel macOS executables plus a Homebrew formula. See the distribution guide for npm, release, and tap instructions.

Run the live two-endpoint Iroh transport test:

bun run test:iroh

Built with OpenTUI and Iroh.