PUSHPLAY

Worked examples

Each one is a whole repo: its files, its pushplay.json and, where it has one, its workflow file. Find the one closest to your game and copy from it. Every manifest here is run through the real check before the site is published.

Whichever you pick, it ends the same way: in PushPlay, Add game → Connect GitHub, pick the repo, and the game is in your Library. Not sure where to start? What do you have? →

A plain HTML game

A web game that runs from its files as they are. It plays with no setup at all; the manifest gives it a name, tags and art.

The repo

index.html
game.js
pushplay.json          (optional)
cover.png  hero.png    (optional)

pushplay.json

{
  "id": "paper-panic",
  "name": "Paper Panic",
  "description": "Defend the breakroom from a storm of paper airplanes.",
  "entry": {
    "web": "index.html"
  },
  "art": {
    "cover": "cover.png",
    "hero": "hero.png"
  },
  "controls": "gamepad",
  "inputs": [
    "gamepad",
    "keyboard"
  ],
  "players": "1-2",
  "tags": [
    "arcade",
    "co-op"
  ]
}
  • PushPlay plays the latest commit of the default branch, and every push after that.
  • Everything the page loads has to be in the repo: a game should work with no internet.

The starter, from the template or new-game

A JavaScript game whose title, pause and settings screens already work with every input. GitHub checks and publishes every push.

The repo

index.html  game.js
input.js  menu.js  fit.js  audio.js  save.js  settings.js  prompts.js  touch.js
pushplay.json
art/cover.svg  art/hero.svg
.github/workflows/pushplay.yml

pushplay.json

{
  "id": "my-game",
  "name": "My Game",
  "description": "A starter game: a title screen, a pause menu and settings that work with every input.",
  "version": "0.1.0",
  "entry": {
    "web": "index.html"
  },
  "art": {
    "cover": "art/cover.svg",
    "hero": "art/hero.svg"
  },
  "controls": "gamepad",
  "inputs": [
    "gamepad",
    "keyboard",
    "mouse",
    "touch"
  ],
  "players": "1",
  "tags": [
    "starter"
  ]
}

.github/workflows/pushplay.yml

name: PushPlay

on:
  push:
    branches: ['**']
    paths-ignore: ['**/*.md']
  release:
    types: [published]
  workflow_dispatch:

jobs:
  pushplay:
    uses: Visual-Zone-Development/pushplay-kit/.github/workflows/build.yml@v1
    permissions:
      contents: write
      id-token: write
  • Make it with Use this template, or npx github:Visual-Zone-Development/pushplay-kit new-game my-game in an empty folder.
  • npx github:Visual-Zone-Development/pushplay-kit dev plays it on your computer and npx github:Visual-Zone-Development/pushplay-kit check runs the same check as GitHub.

Godot, playing from your normal releases

Your release workflow already exports the game and attaches a zip per platform. Add one file and nothing else changes.

The repo

project.godot  export_presets.cfg  scenes/ …
.github/workflows/release.yml      (yours, unchanged)
pushplay.json
art/cover.png  art/hero.png        (optional)

pushplay.json

{
  "id": "star-drift",
  "name": "Star Drift",
  "description": "Race a little ship through asteroid fields. One to four players.",
  "release": {
    "linux-x64": "StarDrift-linux.zip",
    "windows-x64": "StarDrift-windows.zip"
  },
  "launch": {
    "linux-x64": {
      "args": [
        "--fullscreen"
      ]
    }
  },
  "art": {
    "cover": "art/cover.png",
    "hero": "art/hero.png"
  },
  "controls": "gamepad",
  "inputs": [
    "gamepad",
    "keyboard"
  ],
  "players": "1-4",
  "tags": [
    "racing",
    "space"
  ]
}
  • Give each file’s name as it appears in your release. If it changes with each version, put * where it changes: StarDrift-*-linux.zip matches StarDrift-1.2.0-linux.zip.
  • entry is only needed when a zip holds more than one program; otherwise leave it out.
  • The Linux zip is what a Steam Deck plays. A Windows-only game does not run on a Deck.
  • A phone plays web builds. If you also export for the web, attach that zip to your releases and name it here ("web": "StarDrift-web.zip"): the game then plays on your phone too (Library → Add game in the app). To list it on Discover as well, add the workflow file from the starter example: it packages each release you publish from these same zips, so nothing is exported twice.

Godot, exported in the PushPlay workflow

No releases yet, or you want a build on every push. Your job exports the folders and hands them over.

The repo

project.godot  export_presets.cfg  scenes/ …
pushplay.json
art/cover.png  art/hero.png
.github/workflows/pushplay.yml

pushplay.json

{
  "id": "moss-runner",
  "name": "Moss Runner",
  "description": "Sprint through an overgrown ruin, wall-jumping past traps to beat your best time.",
  "version": "1.0.0",
  "entry": {
    "web": "index.html",
    "linux-x64": "moss-runner.x86_64"
  },
  "build": {
    "outputs": {
      "web": "export/web",
      "linux-x64": "export/linux"
    }
  },
  "web": {
    "isolated": true
  },
  "art": {
    "cover": "art/cover.png",
    "hero": "art/hero.png"
  },
  "controls": "gamepad",
  "inputs": [
    "gamepad",
    "keyboard"
  ],
  "players": "1",
  "tags": [
    "platformer",
    "speedrun"
  ]
}

.github/workflows/pushplay.yml

name: PushPlay

on:
  push:
    branches: [main]
    paths-ignore: ['**/*.md']
  workflow_dispatch:

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Install Godot and its export templates here, the way your release workflow does.
      - name: Export
        run: |
          mkdir -p export/web export/linux
          godot --headless --export-release "Web" export/web/index.html
          godot --headless --export-release "Linux" export/linux/moss-runner.x86_64
      - uses: actions/upload-artifact@v4
        with:
          name: pushplay-export
          path: export

  pushplay:
    needs: export
    uses: Visual-Zone-Development/pushplay-kit/.github/workflows/build.yml@v1
    permissions:
      contents: write
      id-token: write
    with:
      artifact: pushplay-export
      artifact-path: export
  • "Web" and "Linux" are the preset names in your export_presets.cfg. The export command is the commonly used form: check Godot’s documentation for your version.
  • Keep web.isolated only if the web export uses threads.
  • You can also export by hand and commit the export/ folders; then the plain workflow file from the starter example is enough.

Unity, a WebGL build

Build for WebGL from the editor, commit the folder, and let GitHub check it.

The repo

Assets/  ProjectSettings/ …
Builds/WebGL/index.html  Builds/WebGL/Build/ …
pushplay.json
art/cover.png  art/hero.png
.github/workflows/pushplay.yml

pushplay.json

{
  "id": "orbit-golf",
  "name": "Orbit Golf",
  "description": "Putt a ball around tiny planets, using their gravity to curve every shot into the hole.",
  "version": "1.0.0",
  "entry": {
    "web": "index.html"
  },
  "build": {
    "outputs": {
      "web": "Builds/WebGL"
    }
  },
  "art": {
    "cover": "art/cover.png",
    "hero": "art/hero.png"
  },
  "controls": "gamepad",
  "inputs": [
    "gamepad",
    "keyboard",
    "mouse"
  ],
  "players": "1",
  "tags": [
    "golf",
    "space",
    "physics"
  ]
}

.github/workflows/pushplay.yml

name: PushPlay

on:
  push:
    branches: ['**']
    paths-ignore: ['**/*.md']
  release:
    types: [published]
  workflow_dispatch:

jobs:
  pushplay:
    uses: Visual-Zone-Development/pushplay-kit/.github/workflows/build.yml@v1
    permissions:
      contents: write
      id-token: write
  • The folder must hold everything the page loads.
  • A web build plays everywhere: handhelds, PCs, Discover and the phone app.

Rust or C++, native builds on two runners

A program for Linux and one for Windows, each built on its own runner and handed over together.

The repo

Cargo.toml  src/ …
pushplay.json
art/cover.png  art/hero.png
.github/workflows/pushplay.yml

pushplay.json

{
  "id": "cave-diver",
  "name": "Cave Diver",
  "description": "Dive deeper into a flooded cave on one tank of air, mapping tunnels as you go.",
  "version": "1.0.0",
  "entry": {
    "linux-x64": "cave-diver",
    "windows-x64": "cave-diver.exe"
  },
  "build": {
    "outputs": {
      "linux-x64": "dist/linux",
      "windows-x64": "dist/windows"
    }
  },
  "art": {
    "cover": "art/cover.png",
    "hero": "art/hero.png"
  },
  "controls": "gamepad",
  "inputs": [
    "gamepad",
    "keyboard"
  ],
  "players": "1",
  "tags": [
    "exploration",
    "roguelike"
  ]
}

.github/workflows/pushplay.yml

name: PushPlay

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build:
    strategy:
      matrix:
        include:
          - { os: ubuntu-latest, folder: linux, file: cave-diver }
          - { os: windows-latest, folder: windows, file: cave-diver.exe }
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - run: cargo build --release
      - run: mkdir -p dist/${{ matrix.folder }} && cp target/release/${{ matrix.file }} dist/${{ matrix.folder }}/
        shell: bash
      - uses: actions/upload-artifact@v4
        with:
          name: build-${{ matrix.folder }}
          path: dist

  combine:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          pattern: build-*
          merge-multiple: true
          path: dist
      - uses: actions/upload-artifact@v4
        with:
          name: pushplay-export
          path: dist

  pushplay:
    needs: combine
    uses: Visual-Zone-Development/pushplay-kit/.github/workflows/build.yml@v1
    permissions:
      contents: write
      id-token: write
    with:
      artifact: pushplay-export
      artifact-path: dist
  • Already attach these builds to your releases? Use "release" as in the first Godot example and skip this workflow.
  • With no web build, both pictures are required, the game is not played by the check, and it plays only on the systems you built for.
  • Inside PushPlay a native game is started with PUSHPLAY=1 in its environment, so it can show “Quit to library” there and nowhere else.
  • These are the commonly used forms of those actions; check their documentation for your versions.

Ren’Py or Love2D, one zip for two systems

A distribution that holds the Linux and Windows programs in one zip. Name the same file for both and say which program each system starts.

The repo

game/ …
pushplay.json
art/cover.png  art/hero.png

pushplay.json

{
  "id": "tea-and-ghosts",
  "name": "Tea and Ghosts",
  "description": "A short visual novel about running a tea shop for the recently departed.",
  "release": {
    "linux-x64": "TeaAndGhosts-*-pc.zip",
    "windows-x64": "TeaAndGhosts-*-pc.zip"
  },
  "entry": {
    "linux-x64": "TeaAndGhosts.sh",
    "windows-x64": "TeaAndGhosts.exe"
  },
  "art": {
    "cover": "art/cover.png",
    "hero": "art/hero.png"
  },
  "controls": "keyboard-mapped",
  "inputs": [
    "keyboard",
    "mouse"
  ],
  "players": "1",
  "tags": [
    "visual novel",
    "cozy"
  ]
}
  • The file and program names are examples: use the ones in your own build.
  • A Love2D game exported for the web is a web build: treat it like the Unity example, with the exported folder in build.outputs.web.

More

Every manifest field, what the check requires of each kind of game, and how a game tells it is inside PushPlay: the build guide. How PushPlay reads a repo: Bring your own game.

Check any of these on your own machine: npx github:Visual-Zone-Development/pushplay-kit check