> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patch.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json A mod theme={null}
{
  "$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"
    }
  ]
}
```

```json A game that plays in Patch theme={null}
{
  "$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 }
  }
}
```

> [!NOTE]
>
> 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](https://docs.patch.gg/api-reference/introduction.md#errors) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.