PUSHPLAY

Add games from anywhere

Open Add game from the library. Every option works with a controller. Only your own and private GitHub repos need you to sign in, and that happens on your phone.

Start here: no account needed

Free starter games

Arcade Sampler, a cabinet of twelve tiny games from a synthwave racer to mini golf, and Motion Lab, where your phone is the controller. On first launch, choose Free starter games. Already have games? Add them any time:

  1. Go to Add game → Paste repo URL.

  2. Enter this, then choose Watch repo:

Visual-Zone-Development/pushplay-games

They install on their own, and so does every game added to them later.

Any game on the web

Lots of games live on a website: the browser games people share on X, like breakroombash.com and pokebonk.com, jam entries, your own. If it plays in a browser, it plays in PushPlay, full screen and with a controller.

  1. Go to Add game → Game website.

  2. Type the address. pokebonk.com is enough.

More about game websites, including how to set the artwork for your own.

On a phone or tablet

The PushPlay app (coming soon to iPhone, iPad and Android) works the same way for your own games: Library → Add game → Connect GitHub, pick the repo, and its game is in your Library. A public repo can be added by its address with no sign-in. A phone plays web builds, so a game with only a Windows or Linux build shows up with a note saying so. Its Library also starts with Start with these, and Discover lists every game that plays on the device in your hand. Websites, zips and folders are added on a Steam Deck or PC. Get the app.

From GitHub

Watch a repo, and PushPlay installs its games and every update after that. It checks when it starts and every two minutes, never during play. Public repos work without signing in; private ones need it.

Sign in with your phone

  1. Go to Add game → Connect GitHub (it is My repositories once you are signed in). A short code and a QR code appear.

  2. Scan the QR code, or open github.com/login/device on any phone or computer, and enter the code.

  3. Approve PushPlay, then choose which repos to share with it: all of them, or just the ones with games. You can change this later in GitHub’s settings.

The sign-in is kept encrypted by your system’s keychain. Code expired? Press X for a new one.

Add game, My repositories: a sign-in code and QR code
Add game → My repositories, before signing in.

Pick repos to watch

Once you’re signed in, My repositories lists the repos you shared. Press A to watch one, Y to stop watching, X to refresh. Each repo shows a badge:

READYHas builds PushPlay can install straight away.
PLAYS AS-ISA plain HTML game; it plays from the latest commit.
WEB PAGEHas an index.html but isn’t marked as a game. Add a pushplay.json or the pushplay-game topic.
NEEDS BUILD SETUPNothing to install yet. Press A for Set up auto-builds.
WATCHINGAlready in your library and kept up to date.

Or paste a link

Add game → Paste repo URL takes any of these, so a public repo works without signing in:

owner/repo
https://github.com/owner/repo
[email protected]:owner/repo.git
Add game, Paste repo URL

What makes a repo installable

PushPlay reads pushplay.json at the top of the repo first: it says what the game is called and how it is described. Without one, it goes by the repo’s name and description. The game’s files then come from the first of these it finds.

A checked buildA release tagged pushplay-latest, made by the one workflow file a repo can add. Each version was played to catch problems, and one repo can hold many games.
Release zipsA published release with zipped builds attached. "release" in pushplay.json names them; otherwise names like Game-Windows.zip, Game-Linux.zip or a single Game.zip are read. The newest release that has one is used. Each device installs its own build, or the web one. A game with no build for your device still shows, greyed out. How names are read.
A web game in the repoindex.html at the root or in dist/, docs/ or build/, played from the latest commit.
None of thesePress A on it for Set up auto-builds. PushPlay opens a pull request adding the workflow file and a starter pushplay.json. Merge it, and each version is checked and published. Any watched repo can have this, from its row or the game’s page. That pull request is the only thing PushPlay ever writes to GitHub.

Downloads are checked against their SHA-256 before installing. Stop watching a repo and the games you installed stay; ones you never installed go away. Turn off Settings → Install new games and updates automatically to approve each one yourself. Making the repo? See every way to start, Bring your own game or the worked examples.

From a zip, folder or link

For games that aren’t on GitHub: an itch.io download, a build a friend sent you, a folder on an SD card.

Zip or folder on the device

  1. Go to Add game → Zip or folder on device.

  2. Pick a place along the top: Downloads, Home, or an SD card or USB drive. Folders that look like a game are marked GAME, and zips ZIP.

  3. Press A on a zip or game folder to install it, or to open a folder. Press Y to add the highlighted folder as it is.

Getting files onto a Steam Deck: download them in Desktop Mode, or copy them to an SD card from another computer.

Add game, Zip or folder on device, browsing Downloads

Download from a link

Add game → Download from URL takes a direct link to a .zip: an itch.io download, a GitHub release asset, anything that downloads a zip. If the link is a web page rather than a file, use Website instead.

Add game, Download from URL

What counts as a game

A zip with a single folder inside is unwrapped first. With a pushplay.json, PushPlay does what it says (see the manifest). Without one, it looks for:

Webindex.html at the top, or in dist/, build/, docs/ or web/
LinuxA .x86_64 file (Godot, Unity), an .AppImage, or another Linux program
WindowsAn .exe (installers and uninstallers are skipped)
MacAn .app

Adding the same game again updates it, and the previous build is kept: its page has Roll back if the new one misbehaves.

From a website

  1. Go to Add game → Game website.

  2. Enter the address. example.com is enough.

  3. PushPlay opens the page, takes its name, description and picture, and adds it to your library.

Website games play live, so they need an internet connection, and they’re always the site’s newest version. Games without controller support still work: the d-pad moves between the page’s buttons and A presses them, and in game the buttons act as arrow keys, Space, Esc, Z, X and Enter.

Add game, Game website

Run a game site? Choose how it looks

Put a pushplay.json next to your page (at /pushplay.json for a site’s home page) to set the name, description and artwork. Every field is optional, and paths are relative to the file:

{
  "name": "Paper Panic",
  "description": "Defend the breakroom from a storm of paper airplanes.",
  "art": { "cover": "art/cover.png", "hero": "art/hero.png" },
  "controls": "gamepad",
  "players": "1-2",
  "tags": ["arcade", "co-op"]
}

Without one, PushPlay uses the page’s og: and twitter: tags and its title, then a screenshot of the game. Covers are 720×500 and banners 1920×450.

Playing

Every screen works with a controller, a keyboard or a mouse, and the hints along the bottom switch to match whichever you’re using. With a mouse, click anything, including those hints; the mouse’s back button goes back.

ControllerKeyboardDoes
D-pad / left stickArrow keysMove around
AEnterChoose
BEscBack
X / YX / YExtra actions, shown at the bottom of each screen
Start / SelectF / VFavorite / filter in the library
L1 / R1[ and ]Switch tabs
Hold Start + Select (1.5 s)F10, or hold Esc (1 s)Pause menu in a web game (on touch: tap ≡)
Hold Start + Select (3 s)–Close a native game, after a confirm (Steam Deck and Linux)
The pause menu over a game
Hold Start + Select in a web game for the pause menu.