Potato Tomato 3

Play online: dixonsolutions.github.io/potatoetomatoe3

Browse and play unblocked HTML5 games in the browser or as a Tauri 2 desktop app. Download individual games for offline play via the separate puller backend service.

Features

• Game catalog with search, categories, favourites, and recommendations
• Per-game offline download — download, delete, and switch between online/offline versions on each game page
• Offline downloads in the browser too — the web build saves same-origin games into IndexedDB and caches its own shell, so a downloaded game still plays with no network; third-party-hosted titles still need the desktop app, which can scrape them. See docs/offline-downloader.md
• Downloaded only filter on the games browse page
• Universal touch console — glass on-screen joystick + buttons for mobile (same-origin / mirrored games), on the web as well as the app; see docs/touch-console.md
• Shrek: Escape from the Swamp bundled with a pre-built offline copy
• Tauri desktop shell + Flatpak packaging with public OSTree remote on GitHub Pages

Quick start (web)

pnpm install
pnpm dev          # web dev + offline downloader (opens browser)
pnpm app          # Tauri desktop + offline downloader
pnpm console-test # native dev harness: touch console + proxy injection
pnpm puller-test  # native dev harness: puller health + download lifecycle

Development harnesses are documented in docs/dev-test-harnesses.md.

Offline download runs in a bundled puller backend that starts automatically with pnpm app (Tauri) and packaged Flatpak/AppImage builds. Downloaded games are stored in app data (~/.local/share/com.potatotomato.games/games/), not in the git repo.

For web dev only, pnpm dev also starts the puller. User-downloaded offline/ folders under static/games/ are gitignored.

If game thumbnails or online shells are missing after a fresh clone, restore from the last build:

pnpm games:restore-from-build   # copies online/ + metadata from build/games/

Desktop (Tauri)

pnpm install
pnpm tauri:dev    # starts Vite + Tauri; puller auto-spawns in debug builds
pnpm tauri:build  # production binary in src-tauri/target/release/

Linux deps: libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf

Closing the window hides to the system tray (StatusNotifierItem). Quit from the tray menu to exit. See docs/desktop-tray.md.

Flatpak (Linux desktop)

App ID: com.potatotomato.games

Install from the public remote (recommended)

Requires Flatpak and the Flathub remote:

# One-time setup
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Remove a broken remote from earlier attempts, if present
flatpak remote-delete potatotomato 2>/dev/null || true

flatpak remote-add --user --if-not-exists --no-gpg-verify potatotomato \
  https://dixonsolutions.github.io/potatoetomatoe3/potatotomato.flatpakrepo

# Install and run (branch is stable, not master)
flatpak install --user potatotomato com.potatotomato.games
flatpak run com.potatotomato.games

Updates:

flatpak update --user com.potatotomato.games

Install from a GitHub Release bundle

If the remote is unavailable (e.g. server has no summary file), install the .flatpak asset from GitHub Releases:

# With GitHub CLI:
gh release download -R dixonSolutions/potatoetomatoe3 -p '*.flatpak' -D /tmp

# Or download com.potatotomato.games-<version>.flatpak from the Releases page, then:
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user /tmp/com.potatotomato.games-*.flatpak
flatpak run com.potatotomato.games

Build locally

Build the Tauri app and puller sidecar on the host first, then package with Flatpak:

git clone --recurse-submodules https://github.com/dixonSolutions/potatoetomatoe3.git
cd potatoetomatoe3
# If you already cloned without submodules:
git submodule update --init --recursive

flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install -y flathub org.gnome.Platform//50 org.gnome.Sdk//50

# Tauri build deps (Debian/Ubuntu)
sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf

pnpm install --frozen-lockfile
pnpm puller:bundle:linux
pnpm tauri:build:flatpak
pnpm flatpak:install   # build + install to ~/.local/share/flatpak
pnpm flatpak:run

Puller service

The puller runs as a separate Node package at puller/. It exposes:

Endpoint	Method	Description
/api/offline/health	GET	Service health
/api/offline/status	GET	All games' online/offline status
/api/offline/status/:gameId	GET	Single game status
/api/offline/:gameId/download	POST	Start offline download
/api/offline/:gameId/progress	GET	Download progress
/api/offline/:gameId	DELETE	Remove offline copy
/games/:gameId/...	GET	Serve offline game files

Strategies: embed (Unity/Google Sites — Shrek) and generic (iframe wget mirror).

See docs/offline-downloader.md for details.

Touch controls for mobile require same-origin (mirrored) game documents — see docs/touch-console.md.

Project structure

PotatoeTomatoe3/
├── puller/              # Offline download backend (Playwright + HTTP API)
├── src/                 # SvelteKit frontend
├── src-tauri/           # Tauri Rust shell (+ puller sidecar)
├── static/games/        # Game catalog (gitignored except shrek-escape)
├── flatpak/             # Flatpak manifest
├── scripts/             # Catalog generators, port importers
└── docs/                # Architecture & release docs

CI / releases

Every push to main runs .github/workflows/release.yml:

1. Builds Flatpak + puller sidecar
2. Publishes a GitHub Release with a .flatpak bundle
3. Deploys the web app plus OSTree Flatpak repo to GitHub Pages (/flatpak/ + potatotomato.flatpakrepo)

See docs/release.md for CI details and troubleshooting.

Scripts

Script	Description
pnpm dev	Web dev server (opens browser)
pnpm app	Tauri desktop app
pnpm puller:start	Start puller backend
pnpm games:restore-from-build	Restore online shells from build/games
pnpm tauri:dev	Alias for pnpm app
pnpm flatpak:build	Local Flatpak build
pnpm port-game	Import a game from tag2game

License

MIT — game assets are third-party content where applicable.