TIC-80 Top Games Downloader

Download the top-rated TIC-80 cartridges and save them locally with ranking numbers. This repo ships single-file executables for Windows, macOS, and Linux under GitHub Releases.

Get the app

1. Open this repository’s “Releases” page.
2. Download the file for your OS:

• Windows: tic80-downloader-windows-x64.exe
• macOS (Apple Silicon): tic80-downloader-macos-arm64
• Linux (x64): tic80-downloader-linux-x64

Where files are saved

• The app creates a folder named tic80_games next to the executable and stores all downloaded .tic cartridges inside it.

How to run

Windows (x64)

• Double-click tic80-downloader-windows-x64.exe.
• If Windows SmartScreen shows a warning, select “More info” then “Run anyway”.
• A console window will show progress with pages and downloads.

macOS (arm64 / Apple Silicon)

• Move tic80-downloader-macos-arm64 to your Downloads or Desktop.
• First run options:
  • Finder: Right-click the file → Open → Open (bypasses Gatekeeper once), or
  • Terminal:

    cd ~/Downloads
    chmod +x ./tic80-downloader-macos-arm64
    # If macOS blocks the app, remove quarantine:
    xattr -d com.apple.quarantine ./tic80-downloader-macos-arm64
    ./tic80-downloader-macos-arm64
    

• Progress is printed in the Terminal. Files are saved to tic80_games.

Linux (x64)

• In Terminal:

  chmod +x ./tic80-downloader-linux-x64
  ./tic80-downloader-linux-x64
  

• Progress is printed in the Terminal. Files are saved to tic80_games.

Verifying downloads (checksums)

Releases include SHA-256 checksums. To verify:

• Windows (PowerShell):

  Get-FileHash .\tic80-downloader-windows-x64.exe -Algorithm SHA256
  

• macOS / Linux:

  shasum -a 256 tic80-downloader-*
  

Compare the output to the checksum listed in the Release notes.

What the app does

• Visits TIC-80’s “Top rated” pages (first N pages).
• Collects game page links in rank order.
• Downloads each cartridge as .tic, prefixing file names with their rank (e.g., 001-somegame.tic).
• Default settings:
  • Base site: https://tic80.com/
  • Category URL: https://tic80.com/play?cat=0&sort=2
  • Pages to scrape: 10
  • Delay between requests: 1s

Advanced: build from source (optional)

Prerequisites: Python 3.12+

Install dependencies and build a single-file executable with PyInstaller.

• Windows:

  py -3.12 -m pip install --upgrade pip
  py -3.12 -m pip install requests beautifulsoup4 tqdm pyinstaller
  py -3.12 -m pyinstaller --onefile --name tic80-downloader-windows-x64 main.py
  # Executable will be in .\dist\tic80-downloader-windows-x64.exe
  

• macOS (arm64):

  python3.12 -m pip install --upgrade pip
  python3.12 -m pip install requests beautifulsoup4 tqdm pyinstaller
  python3.12 -m pyinstaller --onefile --name tic80-downloader-macos-arm64 main.py
  # Executable will be in ./dist/tic80-downloader-macos-arm64
  

• Linux (x64):

  python3.12 -m pip install --upgrade pip
  python3.12 -m pip install requests beautifulsoup4 tqdm pyinstaller
  python3.12 -m pyinstaller --onefile --name tic80-downloader-linux-x64 main.py
  # Executable will be in ./dist/tic80-downloader-linux-x64
  

Release automation (CI)

This repository includes a GitHub Actions workflow that:

• Builds single-file executables on Windows, macOS (arm64), and Linux (x64) with Python 3.12.
• Names artifacts consistently as:
  • tic80-downloader-windows-x64.exe
  • tic80-downloader-macos-arm64
  • tic80-downloader-linux-x64
• Publishes a GitHub Release automatically and attaches the built executables and checksums on tags matching v*.

Trigger a release:

git tag v0.1.0
git push origin v0.1.0

Configuration

The defaults (pages to scrape, delay, output directory) are defined in main.py. To change behavior, edit the file and rebuild, or run from source:

python -m pip install -r <deps>
python main.py

Notes

• Be considerate: the app waits between requests to avoid overwhelming the TIC-80 site.
• If downloads fail intermittently, run the app again; existing files are skipped by name.

License

Choose a license (e.g., MIT) and add it as LICENSE if you plan to share binaries publicly.