patch.json

The file that describes a release: what it is, what it needs and how Patch installs it.

Every release has a patch.json at the root of its folder. Patch checks it when you publish, stores it with the release, and the desktop app follows it to install and launch your work.

It’s plain JSON in snake_case. Start it with the $schema line below: editors like VS Code then autocomplete and check it as you type, and coding agents can read the exact shape.

Examples

A mod

{
  "$schema": "https://patch.gg/schemas/manifest/v1.json",
  "project": "mira/lantern-mod",
  "version": "1.2.0",
  "runs_in": "host_game",
  "requires": {
    "games": [
      {
        "game": "hollow-knight",
        "stores": ["steam", "gog"],
        "builds": { "steam": ["15873461"] }
      }
    ],
    "projects": [{ "project": "mira/lantern-core", "version": "^2.0" }]
  },
  "files": ["files/**"],
  "install": [
    {
      "type": "extract",
      "from": "files/plugins.zip",
      "to": "{profile}/BepInEx/plugins"
    },
    {
      "type": "config",
      "file": "{profile}/BepInEx/config/lantern.cfg",
      "format": "ini",
      "set": { "General.Enabled": true },
      "note": "Turns the lantern on by default"
    }
  ],
  "credits": [
    {
      "files": "files/textures/**",
      "license": "CC0-1.0",
      "source": "https://example.com/texture-pack"
    }
  ]
}

Playing games in Patch’s own window is coming soon. You can already describe them in patch.json.

Kind

You don’t set a kind. Patch reads it from runs_in and from whether requires.games lists any game with the role source, meaning a game whose files your release uses:

runs_in	Uses a source game	Kind in the API	Players see
patch	No	web_game	Game
patch	Yes	remix	Remix
host_game	No	mod	Mod
host_game	Yes	crossover_mod	Crossover mod

Trust tier

You don’t set this either. Patch reads it from your install steps and shows it on the game page; the API returns it as trust_tier. Releases that run code on the player’s PC ask for their consent before the first Play.

runs_in	What the install puts on the player’s PC	Trust tier	Players see
patch	Nothing: it runs in Patch’s sandboxed web runtime	sandboxed	Runs sandboxed in patch
host_game	An extracted archive, a copied or patched executable or script (.dll, .jar, .exe, .lua…), or launch env	runs_code	Runs code on your PC
host_game	Anything else: data files and config	game_files_only	Changes game files only

An archive counts as code until Patch’s checks have looked inside it.

Fields

Field	Required	Meaning
$schema	No	The schema’s URL. Recommended, for editor checks.
project	Yes	The project, as owner/slug
version	Yes	A semver version, such as 1.2.0. Each release of a project needs a new one.
runs_in	Yes	host_game: installed into a game on the player’s PC. patch: runs in Patch’s own game window.
channel	No	Who can see the release: private, unlisted (anyone with the link) or public (listed). Defaults to public.
requires.games	For host_game	The games this release needs (below)
requires.projects	No	Other projects it needs, such as a shared library, as { "project": "owner/slug", "version": "^1.2" } with a semver range
optional	No	Projects it uses when they’re installed, in the same shape
conflicts	No	Projects that must not be installed alongside it, in the same shape
files	Yes	Globs of the files to upload, relative to patch.json, such as files/**
install	For host_game	Ordered install steps (below)
launch	No	args (a list of strings) and env (an object of strings) added when Patch launches the game
web	For patch	entry: the HTML file Patch opens. Optionally aspect_ratio, such as 16:9, and players as { "min": 1, "max": 4 }.
credits	No	Licences of bundled assets: files (a glob), license (an SPDX id such as CC0-1.0 or MIT), and optionally source (a URL) and author

Games

Each entry in requires.games names a game by its slug on Patch, such as hollow-knight.

Field	Meaning
game	The game’s slug on Patch
role	host (the default): the game your release runs in. source: a game whose files your release uses.
stores	The stores the game can come from: steam, epic, gog, xbox, ea, ubisoft, battlenet or microsoft. Leave it out to accept any store.
builds	Exact builds per store, such as { "steam": ["15873461"] }. Leave it out to accept any build.

A release that runs in a host game lists exactly one game with the role host. A release that runs in Patch can only list source games.

Install steps

install is a list of steps that the desktop app runs in order. Every step can have a note of up to 500 characters saying why it’s there, which reviewers see.

type	Fields	Does
copy	from, to	Copies a file or folder from the release
extract	from, to	Unpacks a zip from the release
patch	from, target, target_sha256	Applies a binary patch (xdelta or bsdiff) to a game file, only if the file has that SHA-256
config	file, format (ini, json, xml or cfg), set	Sets keys in a config file, creating it if needed

There are no script steps: a release can only do what these steps describe. That way Patch knows exactly what an install changes and can undo it, and reviewers can read it.

Paths

from paths are files in your release, relative to patch.json. Paths on the player’s PC start with one of these:

Variable	Expands to
{profile}	The profile folder Patch keeps for this game and set of mods
{game}	The game’s install folder
{saves}	The game’s save folder

No path can use ... Prefer {profile} wherever the game and its mod loader allow it: the game’s own folder stays untouched, and uninstalling just removes the profile.

Validation

Patch checks the manifest and the file list when you create a release. Each problem comes back as an error code with the details:

Code	When
manifest_invalid	patch.json doesn’t match the schema, a field its runs_in needs is missing, or a game is listed twice. details.issues lists each problem.
manifest_project_mismatch	project isn’t the project you’re creating the release in
files_invalid	A glob in files matches no file, a from path or web.entry isn’t among the uploaded files, or an uploaded file isn’t covered by files
unknown_host_game	A game in requires.games isn’t one Patch knows
unknown_project	A project in requires.projects, optional or conflicts doesn’t exist

Versions of the schema

This is version 1 of patch.json. New optional fields can be added to it; anything that would break an existing patch.json becomes version 2 at a new $schema URL.