A collection of classic arcade games that run entirely in your terminal — no browser, no GUI, no dependencies beyond Python. This project is built for personal and educational purposes only. It's a playground for learning terminal UI development with Textual and Rich — feel free to explore, tinker, and build on it.

If you find this useful, consider giving it a ⭐ — it helps others discover the project.

Play fully interactive ASCII games straight from the command line. Built with Textual and Rich — smooth keyboard input, live rendering, and zero latency.

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.

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).

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

# Clone the repo
git clone https://github.com/dakshp26/terminal-arcade.git
cd terminal-arcade

# Install dependencies and run
uv sync
uv run main.py

Or with pip:

pip install textual rich
python main.py

terminal_games/
├── app.py               # App root (Textual)
├── screens/
│   └── menu.py          # Game selection menu
└── games/
    ├── protocol.py      # TerminalGame interface
    ├── registry.py      # Game registry
    ├── serpentine/
    │   ├── model.py     # Pure game logic
    │   └── screen.py    # TUI screen
    ├── starfall/
    │   ├── model.py     # Pure game logic
    │   └── screen.py    # TUI screen
    ├── tictactoe/
    │   ├── model.py     # Pure game logic
    │   └── screen.py    # TUI screen
    └── minefield/
        ├── model.py     # Pure game logic
        └── screen.py    # TUI screen

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

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.

# Run tests
uv run pytest

# Lint
uv run ruff check .

# Format
uv run ruff format .

Contributions are welcome. To add a game, fix a bug, or improve the TUI:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-game
3. Make your changes and add tests
4. Open a pull request

Please keep game logic (model) free of UI imports so tests stay fast and framework-independent.

All contributions will be licensed under the license terms.

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.