Terminal Arcade

A collection of small games you play in your terminal.
Built as a friendly place to make your first ever pull request.

---

Play it

You need Python 3.10 or newer. Nothing else — no pip install, no dependencies, no setup.

git clone https://github.com/pushpam2404/terminal-arcade.git
cd terminal-arcade
python3 -m arcade

  _____                  _             _
 |_   _|__ _ _ _ __  ___(_)_ _  __ _ | |
   | |/ -_) '_| '  \/ -_) | ' \/ _` || |
   |_|\___|_| |_|_|_\___|_|_||_\__,_||_|
         _   ___  ___   _   ___  ___
        /_\ | _ \/ __| /_\ |   \| __|
       / _ \|   / (__ / _ \| |) | _|
      /_/ \_\_|_\\___/_/ \_\___/|___|

  1. Guess the Number
     Find the secret number in as few guesses as you can
  2. Hangman
     Guess the word before the drawing is finished
  3. Rock Paper Scissors
     Best of five against the computer
  4. Tic Tac Toe
     The classic, against a computer that plays at random
  5. Coin Flip
     Call it right three times in a row
  6. Dice Roll
     Pick a total and see how close two dice land
  7. Magic 8-Ball
     Ask a question and receive a mysterious answer
  8. Scramble
     Unscramble the letters to find the hidden word

  9. High scores
  10. Quit

  What would you like to play?

---

What it looks like

These excerpts were captured while playing with NO_COLOR=1 python3 -m arcade. Words and computer moves vary from game to game.

Hangman: a round in progress

The board shows the letters found, remaining wrong guesses, and letters already tried.

     +---+
     |   |
     O   |
         |
         |
         |
    =========

  Word:  _ e _ _ _ _ _ _ _
  Wrong guesses left: 5
  Already tried: e x

  Guess a letter:

Tic Tac Toe: a finished round

You play X. Empty squares keep their numbers so you can choose your next move. Here, the three X marks across the top row win the game.

     X | X | X
    ---+---+---
     4 | 5 | 6
    ---+---+---
     7 | O | O

  X wins!

---

Where to look, and what to ignore

A repository looks like a lot of folders the first time you open one. Almost none of them are yours to worry about. Here is the honest breakdown.

🎯 Your work goes here

Folder	What is in it
arcade/games/	One file per game. Most beginner issues are "add a game" or "fix a game", and they happen in one file in this folder. If you only ever open one directory in this repo, open this one.
arcade/	The shared bits every game uses — the menu (main.py), the ASCII art (art.py), asking the player questions (input_utils.py), high scores (scoreboard.py). Intermediate issues live here.
tests/	The automated tests. Some issues ask you to add one; tests/test_<name>.py matches arcade/<name>.py.

📖 Worth reading, not editing

File	Why
docs/how-to-add-a-game.md	The single most useful file in the repo. Follow it start to finish and you have a merged PR.
docs/architecture.md	How the pieces fit together. Read it when you get curious, not before.
CONTRIBUTING.md	The workflow: claim an issue, branch, commit, open a PR.

🙈 Safe to ignore completely

You will never need to touch any of these, and nothing in your issue will require it.

Thing	What it actually is
.github/	Robots. The checks that run on your PR, the issue templates, the bot that assigns you an issue when you comment /claim. Maintainer territory.
ruff.toml, pyproject.toml	Settings for the code checker.
.gitignore	A list of files Git should not track.
LICENSE, SECURITY.md, CODE_OF_CONDUCT.md	Standard paperwork every open source project carries.
.pytest_cache/, .ruff_cache/, __pycache__/	Junk your own computer generates when you run the tests. Already ignored by Git.

The short version: open an issue, it tells you the file. That file is almost always in arcade/games/. Everything else is scenery.

---

🎃 Contributing — read this bit

This repository exists so you can make your first pull request. That is not marketing. The issues were written specifically for people who have never contributed to open source before.

The fastest way in

1. Browse the open good first issue list. Some are already claimed; the label status: claimed marks those
2. Comment /claim on one — a bot assigns it to you within seconds
3. Read CONTRIBUTING.md
4. Open a pull request with Closes #<issue number> in the description

Three kinds of work here

🎮 Add a game	One new file, one line in a list. Step-by-step guide with working code
🐛 Fix a bug	Known bugs are written up as issues, each naming the exact file and function
✨ Improve a game	Difficulty levels, better ASCII art, an opponent that actually tries to win

Every issue tells you the file to open, what "done" looks like, and how to check your work. If an issue does not do that, it is our mistake — say so and we will fix it.

---

Full file tree, for reference

Everything marked ignore is infrastructure. It is listed only so that nothing in the repo looks mysterious.

terminal-arcade/
├── arcade/
│   ├── __main__.py      # python -m arcade starts here
│   ├── main.py          # the menu and the list of games
│   ├── art.py           # ASCII banners and colours
│   ├── input_utils.py   # asking the player questions
│   ├── scoreboard.py    # high scores
│   └── games/           # ← one file per game. YOUR WORK GOES HERE
├── tests/               # pytest — some issues ask you to add one
├── docs/
│   ├── how-to-add-a-game.md   # ← read this first
│   └── architecture.md
│
├── .github/             # ignore — CI checks, issue templates, bots
├── ruff.toml            # ignore — code-checker settings
├── pyproject.toml       # ignore — packaging metadata
├── .gitignore           # ignore
├── LICENSE              # ignore — MIT
├── SECURITY.md          # ignore
└── CODE_OF_CONDUCT.md   # ignore

What CI checks, and what can actually stop your PR

Two things, and only two:

Blocks the merge	Why
A test fails	Something in tests/ broke.
A real bug is found	An undefined variable, an unused import, a mutable default argument — code that is genuinely wrong.

Everything else is advice. Formatting never blocks you — untidy spacing, single quotes instead of double, imports in the wrong order, a missing newline at the end of a file. Those appear as suggestions in the log and are ignored by the gate. Your pull request merges either way.

This is deliberate. Nobody's first contribution should be rejected by a robot over four spaces of whitespace.

Running the tests

Tests need pytest, which is the only thing in this project that does:

python3 -m pip install pytest
python3 -m pytest

Design rules

• Standard library only. Ever. This gets used at events on campus Wi-Fi, and pip install failing must never be why someone cannot take part
• One file per game. So contributors never collide with each other
• Every game returns a score from play(), and main.py decides what to do with it
• Only input_utils calls input(), so "that is not a number" behaves the same everywhere

More detail in docs/architecture.md.

Who runs this

Maintained by OS & DevX, GITHUB Community GITAM, as a Hacktoberfest practice repository. The kickoff session and both PR Debug Clinics from the October event have already taken place. New contributions are still welcome; the issue list is the current picture of what is open.

License

MIT