patch.json

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

{
  "$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"
    }
  ]
}

{
  "$schema": "https://patch.gg/schemas/manifest/v1.json",
  "project": "mira/lantern-run",
  "version": "0.3.0",
  "runs_in": "patch",
  "files": ["dist/**"],
  "web": {
    "entry": "dist/index.html",
    "aspect_ratio": "16:9",
    "players": { "min": 1, "max": 2 }
  }
}

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
`patch`	No	Game
`patch`	Yes	Remix
`host_game`	No	Mod
`host_game`	Yes	Crossover mod

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.

Get started

Make

Examples

Kind

Fields

Games

Install steps

Paths

Validation

Versions of the schema

​Examples

​Kind

​Fields

​Games

​Install steps

​Paths

​Validation

​Versions of the schema

Examples

Kind

Fields

Games

Install steps

Paths

Validation

Versions of the schema