terminal-games 0.3.0

A collection of classic mini games you can play right in your terminal 🎮

🎮 Terminal Games

A collection of classic mini games you can play right in your terminal! Built with Python and the blessed library for a smooth, colorful terminal UI experience.

---

🕹️ Games Included

🧱 Tetris

The classic falling blocks puzzle game! Arrange tetrominoes to complete lines and score points. Features ghost pieces, next piece preview, NES-style scoring, and increasing difficulty.

Key	Action
← → or A/D	Move piece left/right
↑ or W	Rotate piece
↓ or S	Soft drop
Space	Hard drop
P	Pause
Q	Quit to menu

🐍 Snake

Navigate the snake to eat food and grow longer — but don't run into the walls or yourself! Features bonus food, speed progression, and a gradient snake body.

Key	Action
← → ↑ ↓ or WASD	Change direction
P	Pause
Q	Quit to menu

💣 Minesweeper

The timeless puzzle of logic and deduction. Uncover cells without detonating any mines! Features three difficulty levels, flagging, chording, and flood-fill reveal.

Key	Action
← → ↑ ↓ or WASD	Move cursor
Space / Enter	Reveal cell (or chord)
F	Flag / unflag cell
C	Chord (auto-reveal neighbors)
R	Restart / new game
Q	Quit to menu

🎯 2048

Slide tiles on a 4×4 grid to combine matching numbers and reach the elusive 2048 tile! Features colorful tiles, score tracking, best score persistence within session, and the option to keep playing beyond 2048.

Key	Action
← → ↑ ↓ or WASD	Slide tiles
R	Restart game
C	Continue playing (after reaching 2048)
Q	Quit to menu

📝 Wordle

The viral word-guessing game in your terminal! You have 6 tries to guess a hidden 5-letter word. After each guess, letters light up green (right letter, right spot), yellow (right letter, wrong spot), or grey (not in the word). An on-screen keyboard tracks the letters you've already used. The answer pool and valid-guess list are derived from the original (pre-NYT) MIT-licensed Wordle source.

Key	Action
A-Z	Type a letter (yes, including Q and R)
Enter	Submit guess
Backspace	Delete last letter
Esc	Quit to menu
R (after round ends)	New word
Q (after round ends)	Quit to menu

📅 Wordle Daily

One puzzle per day — same word for every player, deterministic by date. Quit mid-puzzle and your progress resumes when you come back. Once you solve (or use all 6 guesses), you're locked out until tomorrow's puzzle. Saved state lives at ~/.terminal_games/wordle_daily.json.

Key	Action
A-Z	Type a letter
Enter	Submit guess
Backspace	Delete last letter
Esc / Q	Quit to menu (resume on next launch)

🪢 Hangman

The classic word-guessing game with a friendly twist — save the stickman by guessing letters before the gallows fills up. You have 6 wrong guesses before it's over. Hits show up green on the alphabet tracker; misses show up red.

Key	Action
A-Z	Guess a letter (yes, including Q and R)
Esc	Quit to menu
R (after round ends)	New word
Q (after round ends)	Quit to menu

---

📦 Installation

Quick Play (No Install)

The fastest way to play — runs directly without installing anything permanently:

# Using uvx (recommended, requires uv)
uvx terminal-games

# Using pipx
pipx run terminal-games

Install with pip

pip install terminal-games
terminal-games

Install with pipx (Isolated Environment)

pipx install terminal-games
terminal-games

Install with uv

uv tool install terminal-games
terminal-games

Install from Source

# Clone the repository
git clone https://github.com/ayu5h-raj/terminal-games.git
cd terminal-games

# Run directly with uv (no install needed)
uv run terminal-games

# Or install in a virtual environment
uv sync
uv run terminal-games

Install with Homebrew 🍺

brew tap ayu5h-raj/tap
brew install terminal-games

---

🚀 Usage

After installation, simply run:

terminal-games

You can also run it as a Python module:

python -m terminal_games

You'll be greeted with a beautiful menu where you can select any game using the arrow keys and Enter:

 ______                    _             __   _____
/_  __/__  _________ ___  (_)___  ____ _/ /  / ___/____ _____ ___  ___  _____
 / / / _ \/ ___/ __ `__ \/ / __ \/ __ `/ /  / /  _ / __ `/ __ `__ \/ _ \/ ___/
/ / /  __/ /  / / / / / / / / / / /_/ / /  / /_/ / /_/ / / / / / /  __(__  )
/_/  \___/_/  /_/ /_/ /_/_/_/ /_/\__,_/_/   \____/\__,_/_/ /_/ /_/\___/____/

                🎮  Classic Mini Games for your Terminal  🎮

                ▸ 🧱  Tetris  -  Arrange falling blocks to clear lines
                  🐍  Snake   -  Eat food, grow longer, don't hit yourself
                  💣  Minesweeper  -  Uncover tiles without hitting mines
                  🎯  2048    -  Slide and merge tiles to reach 2048

              ↑/↓ Navigate  •  Enter Select  •  q Quit

---

🛠️ Development

Prerequisites

• Python 3.12+
• uv (recommended) or pip

Setting Up the Dev Environment

# Clone the repo
git clone https://github.com/ayu5h-raj/terminal-games.git
cd terminal-games

# Install dependencies
uv sync

# Run the game
uv run terminal-games

# Or run as a module
uv run python -m terminal_games

Project Structure

terminal-games/
├── pyproject.toml              # Project config & dependencies
├── README.md                   # You're reading this!
├── LICENSE                     # MIT License
├── LICENSES_DATA.md            # Provenance & licenses for bundled word lists
├── terminal_games/
│   ├── __init__.py             # Package init
│   ├── __main__.py             # python -m support
│   ├── main.py                 # Menu launcher & entry point
│   ├── data/                   # Bundled word lists (shipped in the wheel)
│   │   ├── __init__.py         # importlib.resources loaders (cached)
│   │   ├── words_common.txt    # ~8.3K common English words
│   │   ├── words_5letter_valid.txt  # ~16K 5-letter words
│   │   ├── words_wordle_answers.txt # ~2.3K curated Wordle answers
│   │   └── words_wordle_valid.txt   # ~13K original-Wordle valid guesses
│   └── games/
│       ├── __init__.py         # Games package
│       ├── tetris.py           # 🧱 Tetris
│       ├── snake.py            # 🐍 Snake
│       ├── minesweeper.py      # 💣 Minesweeper
│       ├── twenty48.py         # 🎯 2048
│       ├── wordle.py           # 📝 Wordle (random + daily mode)
│       └── hangman.py          # 🪢 Hangman
├── scripts/
│   └── build_wordle_answers.py # Regenerates the Wordle word lists

Adding a New Game

1. Create a new file in terminal_games/games/ (e.g., pong.py)
2. Implement a play_pong(term: Terminal) -> None function
3. Add it to the GAMES list in terminal_games/main.py
4. That's it! The menu will pick it up automatically.

---

🗺️ Roadmap

• 🧱 Tetris
• 🐍 Snake
• 💣 Minesweeper
• 🎯 2048
• 📝 Wordle
• 📅 Wordle Daily
• 🪢 Hangman
• 🏓 Pong
• 🃏 Blackjack
• 🏃 Flappy Bird
• 🚀 Space Invaders
• 🏰 Text Adventure
• 🏆 Global high scores
• 🎨 Custom themes
• 📦 Homebrew formula

---

📋 Requirements

• Terminal size: At least 80×24 (standard terminal size). Larger terminals provide a better experience.
• Python: 3.12 or newer
• OS: macOS, Linux, or Windows (Windows Terminal recommended)
• Dependencies: blessed (installed automatically)

---

🤝 Contributing

Contributions are welcome! Whether it's a new game, bug fix, or UI improvement:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/new-game)
3. Commit your changes (git commit -m 'Add awesome new game')
4. Push to the branch (git push origin feature/new-game)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

💖 Acknowledgments

• Built with blessed — a thin, practical wrapper around terminal capabilities
• Inspired by the classic games we all grew up playing
• Managed with uv — an extremely fast Python package manager
• Word lists bundled from first20hours/google-10000-english (MIT) and dwyl/english-words (Unlicense). See LICENSES_DATA.md for details.

---

Made with ❤️ and Python 🐍
Happy Gaming! 🎮