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.
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 nameExampleWebweb, html5, browser, webglRocket-HTML5.zipSteam Deck and Linuxlinux, linux64, steamos, deck (add arm64 for Arm)Rocket-Linux.zipWindowswindows, win, win64Rocket-Windows.zipMacmac, macos, osx (add arm64 or x64 to split them)Rocket-macOS.zipOnly one zip, with no platform in its name? That works too: PushPlay looks inside for an
index.html, a.x86_64, an.exeor an.app. Source, symbols and server zips are ignored.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.
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.
Give it a name, tags and art (optional)
Add a pushplay.json at the top of the repo.
releasesays 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.zipmatchesRocket-1.2.0-Linux.zip. Everything butid,nameandreleaseis 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.
Put
index.htmlwhere PushPlay looksAt the root of the repo, or in
dist/,docs/orbuild/.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 topicpushplay-game(repo page → ⚙ next to About). It plays either way; with the manifest it has its own name, tags and art.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.
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.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
buildscript is built with it, and any other repo ships as it is.
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()orprompt() - 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
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