Terminal Arcade

Play games in the terminal while your coding agents run

Play classic arcade games straight from your terminal. No browser, no GUI, just Python. Built with Textual and Rich for smooth keyboard input, live rendering, and zero latency. It's an open playground for learning terminal UI development. Explore the code, tinker with it, and build your own games.

If you find it fun and interesting, consider giving it a ⭐. It helps others discover the project.

---

Requirements

• Python 3.13+
• uv (recommended) — or pip

Quickstart

git clone https://github.com/dakshp26/terminal-arcade.git
cd terminal-arcade
uv sync
uv tool install . --with-requirements requirements.txt

You're all set — terminal-arcade is now available from any CLI and directory on your system. Happy arcading!

New games dropped? Pull and reinstall:

git pull
uv tool install . --with-requirements requirements.txt

---

Games

Serpentine Steer a growing snake around the screen to eat food. Avoid hitting walls or your own tail.	Starfall Pilot an ASCII ship at the bottom of the screen, blasting waves of descending alien craft before they reach you.	Tic Tac Toe Two-player classic. Take turns placing X and O; first to line up three in a row wins.	Minefield Uncover a grid hiding 25 mines using numbered clues. Flag every mine without triggering one.
AsterAvoid Pilot a spacecraft across the bottom and dodge a relentless barrage of accelerating asteroids falling from above.	Echo Chamber Navigate a pitch-dark cave as a bat (@); pulse sonar (space) to illuminate your surroundings, reach the exit (>) before your echo fades and the cave bats (*) find you.	Floodgate Flood-fill from the top-left: each move (1-6) picks a colour; your region updates and absorbs every touching cell of that colour. Paint the whole grid within 30 moves.	Paddleball Solo wall rally: slide a paddle along the bottom and keep the ball bouncing off the top and side walls. Arrow keys / A D / H L to move.

More on the way...

The arcade is still being built. More games are queued up and dropping soon — stay tuned by watching and starring the repo (or better yet, contribute one).

---

General Game Controls

Action	Keys
Move	Arrow keys / WASD / hjkl
Secondary Action	Space / ↑ / W
Restart	R
Menu	Esc
Quit	Ctrl+C

Project Structure

terminal_games/
├── app.py               # App root (Textual)
├── screens/
│   └── menu.py          # Game selection menu
└── games/
    ├── protocol.py      # TerminalGame interface
    ├── registry.py      # Game registry
    ├── serpentine/      # each: model.py (logic), screen.py (TUI)
    ├── starfall/
    ├── tictactoe/
    ├── minefield/
    ├── asteravoid/
    ├── echo_chamber/
    ├── floodgate/
    └── paddleball/

Game logic (model.py) is kept free of Textual/Rich imports so it stays independently testable.

Adding a New Game

1. Create terminal_games/games/<name>/ with model.py and screen.py.
2. Implement the TerminalGame protocol — game_id, title, description, build_screen().
3. Register it in terminal_games/games/registry.py → get_games().

That's it. The menu picks it up automatically.

---

License

See LICENSE for details.

This project is intended for personal and educational use only. It is not permitted to use this project for commercial purposes. The sole intention of this project is to showcase the development of terminal based games using python and open source libraries.