A Python desktop game: a country flag appears on screen, the player types the country name, and earns a point for each correct guess. Built as a first Python module project to practise core language concepts — data loading, image processing, GUI programming, string matching, and file I/O.
Flags sourced from the country-flags-dataset on Hugging Face (194 countries, CC0 1.0 public domain licence).
| Library | Purpose |
|---|---|
tkinter (stdlib) |
Desktop GUI window and widgets |
| Pillow | Image resizing and display |
| datasets | Downloading the flag dataset |
difflib (stdlib) |
Fuzzy string matching for guess tolerance |
json (stdlib) |
Reading dataset metadata and saving high score |
# 1. Clone and enter the repo
git clone https://github.com/YOUR_USERNAME/flag-game.git
cd flag-game
# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Build the local flag dataset (one-time, ~10MB download)
python3 build_dataset.py
# 5. Play
python3 main.pyflag-game/
├── build_dataset.py # one-time script to download and save flags
├── main.py # game entry point
├── data.json # generated flag metadata (gitignored)
├── flags/ # cached PNG flag images (gitignored)
├── highscore.json # saved best score (gitignored)
├── requirements.txt
└── README.md
build_dataset.py runs once at setup. It downloads all 194 flags from
Hugging Face, resizes each to fit a 400×400 box using Pillow, saves them
as PNGs in flags/, and writes data.json — a metadata index mapping
each country code to its display name.
main.py loads that local dataset and runs the game loop:
show a random flag → accept a guess → compare using fuzzy matching →
update score → repeat until all 194 flags are shown.
Fuzzy matching (difflib.SequenceMatcher) accepts guesses that are
at least 80% similar to the correct answer, so minor typos
("Afganistan" for "Afghanistan") are still marked correct.
High score is saved to highscore.json after each completed game.
If the new score beats the saved best, the game shows a blue
"NEW HIGH SCORE!" message.
- Local caching over live API calls — flags are downloaded once and stored locally. The game runs offline, with no latency between rounds and no risk of API failures during a demo.
- Hugging Face dataset — CC0 licence means no legal ambiguity. Compared to scraping a CDN, this approach is reproducible, cleaner, and requires no API key.
- tkinter — ships with Python, so no extra installation is needed
for end users beyond
pip install -r requirements.txt.
- Difficulty modes (blur or pixelate the flag)
- Continent filter (Europe only, Africa only, etc.)
- Per-round countdown timer
- Two-player hot-seat mode