PUSHPLAY

Bring your own game

You don’t need the template, an AI or anything made for PushPlay. Any GitHub repo, public or private, can be watched. If you already publish releases, you’re probably done.

One rule: PushPlay reads pushplay.json at the top of your repo first. It says what the game is called and how it is described, wherever the files come from. The files are a checked build if you set one up, else your normal releases, else (a plain HTML game) the repo itself. With no pushplay.json, PushPlay goes by the repo’s name, description and file names.

GitHub releases

Already publish releases with your builds attached? That’s all PushPlay needs. Godot, Unity, a web build, anything zipped: watch the repo and each new release becomes an update.

  1. Attach your builds as zips

    Call them whatever you like. PushPlay reads the platform from the name, so a word like these is enough:

    PlatformWords in the nameExample
    Webweb, html5, browser, webglRocket-HTML5.zip
    Steam Deck and Linuxlinux, linux64, steamos, deck (add arm64 for Arm)Rocket-Linux.zip
    Windowswindows, win, win64Rocket-Windows.zip
    Macmac, macos, osx (add arm64 or x64 to split them)Rocket-macOS.zip

    Only one zip, with no platform in its name? That works too: PushPlay looks inside for an index.html, a .x86_64, an .exe or an .app. Source, symbols and server zips are ignored.

  2. Publish the release

    PushPlay uses the newest published release that has a build in it. Prereleases and drafts are skipped, and so is a release with no zips (say, a docs fix), so the game doesn’t vanish. Each device installs its own build if there is one, otherwise the web build. Builds for other systems still show, greyed out.

  3. Watch the repo

    Add game → Connect GitHub and pick it in My repositories, or Paste repo URL for a public repo you don’t own. It is in your Library from then on.

  4. Give it a name, tags and art (optional)

    Add a pushplay.json at the top of the repo. release says which file is which exactly as it appears in the release, so nothing is guessed. If the name changes with each version, put * where it changes: Rocket-*-Linux.zip matches Rocket-1.2.0-Linux.zip. Everything but id, name and release is optional, and a change shows up without a new release.

    {
      "id": "rocket",
      "name": "Rocket",
      "description": "Thread a rocket through a canyon on one tank of fuel.",
      "tags": ["arcade", "flying"],
      "players": "1",
      "release": {
        "linux-x64": "Rocket-Linux.zip",
        "windows-x64": "Rocket-Windows.zip",
        "web": "Rocket-HTML5.zip"
      },
      "launch": { "linux-x64": { "args": ["--fullscreen"] } },
      "art": { "cover": "art/cover.png", "hero": "art/hero.png" }
    }

    No workflow of ours and nothing exported twice. This plays in the launcher on the systems your zips are for; a Linux build is what a Steam Deck needs. A phone plays web builds, so add a web zip if you want it on yours. To be listed on Discover a game needs a web build and checked builds: they are then packaged from each release you publish.

Automate it (optional)

This workflow builds a web game and attaches the zip whenever you publish a release:

name: Release builds
on:
  release:
    types: [published]
permissions:
  contents: write
jobs:
  web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build
      - run: cd dist && zip -r ../Game-HTML5.zip .
      - run: gh release upload "${{ github.event.release.tag_name }}" Game-HTML5.zip --clobber
        env:
          GH_TOKEN: ${{ github.token }}

For Godot, export each platform with godot --headless --export-release in a job with the export templates, zip each output, and upload them the same way. Want to be exact? A zip named pushplay-<platform>.zip, using one of the platform names below, always wins.

Plain HTML

For a web game that runs from its files as they are: no build step.

  1. Put index.html where PushPlay looks

    At the root of the repo, or in dist/, docs/ or build/.

  2. Mark the repo as a game

    Add a pushplay.json at the top of the repo ("entry": { "web": "index.html" }), or give the repo the topic pushplay-game (repo page → ⚙ next to About). It plays either way; with the manifest it has its own name, tags and art.

  3. Watch it

    Add game → Connect GitHub and pick it, or Paste repo URL. PushPlay installs the latest commit of the default branch, and every push after that.

Checked builds

For any game, in any engine. One small workflow file has GitHub check each version: it plays the game without a screen, draws the art and publishes the result where PushPlay picks it up, on every device, and where it can be listed on Discover. Your own release workflow keeps working as it does.

  1. Add the workflow file

    The easy way: in PushPlay, press Set up auto-builds on the game’s page, or in Settings under the repo. It opens a pull request; merge it.

    By hand: copy the workflow file to .github/workflows/pushplay.yml. It is about twenty lines and calls a build shared by every game. Nothing else goes in your repo.

  2. Say where the game’s files are

    In pushplay.json (the pull request adds a starter one), one of:

    • "release": package each release you publish from its own zips. Nothing is built twice.
    • "build": { "outputs": { "web": "export/web", "linux-x64": "export/linux" } }: the finished folders your own build makes, committed or made in the workflow.
    • Nothing: a JavaScript project with an npm build script is built with it, and any other repo ships as it is.

    Worked examples for Godot, Unity, Rust and more →

  3. Push, or publish a release

    Every push to any branch is checked. The default branch (or, for a game that plays from its releases, each published release) also publishes, to a prerelease tagged pushplay-latest. Your own releases and your “Latest” badge are untouched. A version that fails its check is skipped, and players keep the last good one.

What the check looks for

A web build is opened in a headless browser at 1280×800 (a handheld’s screen), at phone size for games made for phones, and with each input on its own. The version fails if the game:

  • throws an error or requests a file that isn’t there
  • loads anything from the internet, unless the manifest says "online": true
  • calls alert(), confirm() or prompt()
  • is still a blank screen after three seconds (thirty for an engine export, which may show a loader first)

It also needs inputs. A description, tags and your own art are asked for with a note, and the check lists what is left before you share the game: a brand-new game plays, and is published, without them. A native build is checked to be a real program for its system; it is not played. Check on your own machine first with npx github:Visual-Zone-Development/pushplay-kit check.

A finished game is best in its own repo: it gets its own releases and its own listing on Discover. While you're making games, one repo can hold many (a workshop: each in games/<id>/ with its own pushplay.json, where the id matches the folder), and npx github:Visual-Zone-Development/pushplay-kit promote <id> moves a finished one into its own repo.

The manifest: pushplay.json

It’s optional, and goes at the top of the repo (in games/<id>/ for each game of a collection). PushPlay reads it first, from the default branch, so a change shows up within minutes. Only id, name and either entry or release are required. Unknown fields are an error, so typos get caught.

{
  "$schema": "https://raw.githubusercontent.com/Visual-Zone-Development/pushplay-kit/v1/schema/manifest.schema.json",
  "id": "paper-panic",
  "name": "Paper Panic",
  "description": "Defend the breakroom from a storm of paper airplanes.",
  "version": "1.2.0",
  "entry": { "web": "index.html", "linux-x64": "PaperPanic.x86_64" },
  "art": { "cover": "art/cover.png", "hero": "art/hero.png" },
  "controls": "gamepad",
  "players": "1-2",
  "tags": ["arcade", "co-op"]
}

The $schema line gives you autocomplete and checking in most editors. See the schema, or every field in the build guide.

Fields

FieldWhat it is
idrequiredLowercase letters, numbers and dashes, up to 64. In a collection it must match the folder name.
namerequiredUp to 80 characters.
entryWhat to open for each platform, like "index.html" or "Game.x86_64". Required unless the game plays from your releases, where it is only needed when a zip holds more than one program.
releasePlay the game from your normal GitHub releases. true finds each platform’s zip by its name; { "linux-x64": "Game-*-linux.zip" } names them, with * for the part that changes.
descriptionUp to 2,000 characters. A checked build asks for at least 20.
versionAny text, shown on the game’s page.
artcover (720×500) and hero (1920×450), as paths in the repo. PNG, JPG or WebP anywhere; SVG or HTML too when the game has checked builds, which draw them.
controls"gamepad" if it has controller support, "keyboard-mapped" if it’s keyboard-only.
playersLike "1" or "1-4".
tagsUp to 8, lowercase, 24 characters each. Used by the library’s filters.
inputsWhat the whole game can be played with: any of "gamepad", "keyboard", "mouse", "touch".
launchArguments and environment for a native build, per platform: { "linux-x64": { "args": ["--fullscreen"] } }.
onlinetrue if it needs the internet. Otherwise the build check fails it for loading anything from the web.
type"web" or "native". A hint; the entry decides.
buildFor checked builds of a game with its own build: { "outputs": { "web": "export/web", "linux-x64": "export/linux" } } names the finished folder per platform; "command" runs first. A JavaScript project with an npm build script needs neither.

Platforms in entry

Use these names: web, linux-x64, linux-arm64, windows-x64, darwin-arm64, darwin-x64. Paths are relative, use forward slashes, and can’t start with / or use ...

Starting fresh?

The template is a starter game with all of this set up. Or ask a coding agent for a game.

Every way to start