2026 World Cup — Knockout Tournament in Your Terminal

A mini World Cup game in pure Python (no external dependencies): it simulates the Round of 16 with the real 2026 World Cup teams all the way to the final — live scoreboard, goal commentary, extra time, penalty shootouts, upsets, records and your own predicted champion.

Every run draws a random bracket and different results. Use --seed N to replay the exact same tournament.

Requirements

• Python 3.10+ (standard library only — nothing to install).
• Unix-like system (Linux/macOS): the live keyboard controls use termios/tty, which are POSIX-only. Windows terminals run the game with reduced interactivity (no per-key controls).

How to run

python3 worldcup.py            # main menu + normal animation (same as the CLI)
python3 -m worldcup            # equivalent module form
python3 worldcup.py --fast     # whole tournament in seconds, no menu
python3 worldcup.py --seed 42  # replay the exact same tournament

Command-line options

Option	Description
--fast	Skips the menu and plays at full speed (no animation).
--seed N	Fixes the random seed so the same tournament is reproduced every time (great for sharing).
--export FILE	Writes the full tournament (champion, all scores, top scorer, ranking) to FILE as JSON.

python3 worldcup.py --fast --seed 42      # both flags work together
python3 worldcup.py --fast --export out.json --seed 42  # save results too

Controls during a match

Key	Action
Enter / Space	Skip the current match
p	Skip all remaining matches
+ / =	Speed up the animation
-	Slow down the animation

What's in the game

• Full knockout bracket: Round of 16 → quarter-finals → semi-finals → third-place playoff → final, with the 16 real 2026 World Cup Round of 16 teams (each with a strength rating and 3 star players).
• Random bracket draw on every run, plus a different "day form" per team in each match.
• Live scoreboard with a minute-by-minute progress bar.
• Extra time and sudden-death penalty shootout when it's level.
• Play-by-play commentary with star scorers, event phrases and a terminal bell on goals; half-time at the 45'.
• Cheer for a team (highlighted in cyan; special elimination/final celebration moments).
• Pre-tournament champion prediction.
• Upset summaries and end-of-tournament awards: top scorer, biggest blowout, undefeated champion.
• Champions history and records persisted in history.json (see the "History" menu option).

Preview

  =====================================================
      2026 WORLD CUP  -  KNOCKOUT IN THE TERMINAL
       16 teams. 1 champion. 90 minutes of tension.
  =====================================================


  ROUND OF 16
    Brazil 2-1 France
    Argentina 3-2 England
    Spain 1-0 Portugal
    Norway 2-2 Switzerland   (4-3 on penalties)

  SEMI-FINALS
    Brazil 3-1 Germany
    Argentina 2-1 Spain

  FINAL
    Brazil 4-2 Argentina

  --- Brazil vs Argentina (FINAL) ---
  Brazil 2 - 1 Argentina      67'   [██████████████░░░░]   74%
  GOAL BY RAPHINHA! What a goal!

  Half-time:  Brazil 1 - 0 Argentina

  -> Brazil 4 - 2 Argentina

  =====================================================
  CHAMPION: BRAZIL !!!
  Runner-up: Argentina
  3rd place: France
  4th place: England
  =====================================================

  Brazil - run:  France 2x1  Norway 3x1  Germany 3x1  Argentina 4x2
  Goals: 12 for / 5 against

  TOURNAMENT AWARDS
  Biggest blowout: Spain 5 - 0 Portugal
  Undefeated champion: Brazil
  Top scorer: Raphinha with 5 goal(s)

  UPSETS OF THE TOURNAMENT
  UPSET! Switzerland beat Germany

That's the kind of output you see (this exact preview is a static demo produced by make_screenshot.py). Output is random unless you pass --seed.

Project layout

.
├── worldcup/             # Python package
│   ├── __init__.py       # public API re-exports
│   ├── __main__.py       # python -m worldcup
│   ├── cli.py            # argparse, menu, tournament flow
│   ├── simulation.py     # match engine, penalties, brackets
│   ├── terminal.py       # raw-mode input, drawing, colors
│   ├── io.py             # history.json, results export
│   ├── data.py           # teams and phrases
│   └── state.py          # shared mutable state + ANSI styling
├── worldcup.py           # thin entry shim (python3 worldcup.py)
├── make_screenshot.py    # regenerates the ASCII preview (screenshot.txt)
├── pyproject.toml        # packaging, console entry point, lint config
├── tests/test_game.py    # regression tests (python3 -m unittest)
├── .github/workflows/ci.yml  # CI: syntax, tests, lint on every push/PR
└── CONTRIBUTING.md       # guide for contributors

Install as a command (optional)

pip install .          # adds the `worldcup` command
worldcup --fast --seed 7

The worldcup script is a console entry point defined in pyproject.toml (from the worldcup.cli module).

Development

Quick syntax check:

python3 -m py_compile worldcup.py
python3 -m compileall -q worldcup

Run the test suite:

python3 -m unittest discover -s tests -v

Lint and type-check (Black, flake8 and mypy are applied in CI):

pip install black flake8 mypy
black --check worldcup tests
flake8 worldcup tests
mypy worldcup

See CONTRIBUTING.md for guidelines on opening issues and pull requests.

Notes

• Brackets and results are random every run — there is no "fixed" champion.
• Use --seed N to share/replay a specific tournament.
• NO_COLOR and TERM=dumb are respected (no colors), useful for CI and logs.
• The terminal cursor is restored on every exit path, including Ctrl+C.