Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/vortex-api/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).

### Added

- A JSON Schema for `info.json`, published as `@nexusmods/vortex-api/schemas/info.schema.json`, and an [`info.json` reference](./docs/INFO-JSON.md) covering every field, including `contributes`. Add `"$schema": "https://unpkg.com/@nexusmods/vortex-api/schemas/info.schema.json"` to your `info.json` for editor completion
- `GameUid`, the id of a game in the Nexus Mods game catalogue, with its brander
- `IMainPageOptions`: `menuIcon` property, a Material Symbol by name (such as `"settings"`) or an SVG path as `{ path }`, for the page's icon in the menu. A misspelled symbol name fails the typecheck
- Game info entries from `registerGameInfoProvider` accept `type: "path"`, shown as a link that opens the file or folder. The built-in `game-path` entry uses it
Expand Down
7 changes: 3 additions & 4 deletions packages/vortex-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ For packaging and distributing extensions, see [How to package a game extension]

For API changes between versions, see the [Changelog](CHANGELOG.md).

For the fields of an extension's `info.json`, including `contributes`, see the [`info.json` Reference](docs/INFO-JSON.md).

For a full list of events extensions can listen to or emit, see the [Events Reference](docs/EVENTS.md).

For notable open-source extensions with advanced patterns, see the [Example Extensions](docs/EXAMPLES.md).
Expand All @@ -30,10 +32,7 @@ A Vortex extension is a JavaScript module that exports an `init` function. The f

`info.json`

- `name` - the display name of your extension.
- `author` - the extension author's name.
- `version` - the version of your extension.
- `description` - a short description of what your extension does.
- Describes your extension to Vortex: its name, version, and the games it contributes. See the [`info.json` reference](docs/INFO-JSON.md) for every field and the JSON Schema that gives your editor completion.

`index.js`

Expand Down
162 changes: 162 additions & 0 deletions packages/vortex-api/docs/INFO-JSON.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
# `info.json` Reference

Every Vortex extension has an `info.json` at the top level of its folder. It tells Vortex what the extension is and, through `contributes`, which games it supports, without running any of the extension's code.

Vortex never reads your `package.json`. That file belongs to npm and your build. If you build your extension with a tool that generates `info.json` from `package.json`, the generated file is the one Vortex reads, and it only contains what the tool wrote.

## Editor completion

The package ships a JSON Schema for `info.json`. Point your file at it to get completion and field documentation in editors that support JSON Schema, such as VS Code:

```json
{
"$schema": "https://unpkg.com/@nexusmods/vortex-api/schemas/info.schema.json",
"name": "My Game Support",
"version": "1.0.0"
}
```

If you have the package installed you can also reference the file from `node_modules/@nexusmods/vortex-api/schemas/info.schema.json`. Vortex ignores the `$schema` key.

The schema describes the shape of the file: types, required keys and structure. It doesn't enforce every rule, so a file that passes the schema can still be invalid. The rules for values are listed below and in each field's description. Unknown keys are allowed everywhere, at the top level and inside `contributes`.

## Fields

| Field | Required | Meaning |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `name` | yes | Display name of the extension. |
| `version` | yes | Version of the extension, as a semver string. |
| `author` | no | Display name of the author. Shown as `<unknown>` when missing. |
| `description` | no | Short description of what the extension does. Shown as `<missing>` when missing. |
| `id` | no | Stable identifier, used by other extensions that call `requireExtension`. Pick one and keep it across versions. |
| `namespace` | no | i18next namespace for the extension's translations. |
| `contributes` | no | What the extension contributes. See below. |
| `gameId` | no | Deprecated. See [`gameId`](#gameid-deprecated). |

Vortex also writes a `modId` key when it installs an extension. You don't write it, and it isn't part of the schema.

## `contributes`

`contributes` declares what your extension contributes in a form Vortex, Nexus Mods and other tools can read without loading it. Every field in it is optional.

An extension without `contributes` keeps working exactly as it does today. Vortex treats it as a legacy extension and never rejects it. Older Vortex versions ignore the key, so you can add it now.

If `contributes` is invalid, the extension loads as if it had none and Vortex logs a warning naming your extension and what failed. One invalid field makes all of `contributes` invalid, so fix the warning rather than relying on the fallback.

### `contributes.games`

The games your extension registers, keyed by the id you pass to `registerGame`. The typical extension supports one game that has its own page on Nexus Mods, and needs only this:

```json
{
"name": "Stardew Valley Support",
"version": "1.0.0",
"contributes": {
"games": {
"stardewvalley": { "nexusGameId": 1303, "name": "Stardew Valley" }
}
}
}
```

The key `stardewvalley` is the `id` the extension passes to `registerGame`. `nexusGameId` is the game's id on Nexus Mods, and `name` is how listings that can't run the extension show it.

Rules for the keys: each is a non-empty string and none starts with `tier-0-`, which Vortex reserves. Registering an id that isn't listed is an error. A game may be an empty object, which declares the game and nothing else.

Each game can set these fields:

- `nexusGameId`: the Nexus Mods game this game's mods are published on, as a positive integer. Leave it out if the game has no page on Nexus Mods. It can't be `null`. Several games can declare the same one, as Skyrim Special Edition and Skyrim VR both do with 1704.
- `gameUid`: the game's id in the Nexus Mods game catalogue, a non-empty string. Vortex doesn't check its structure, because catalogue ids are opaque. Write it in any case, Vortex lowercases it.
- `name`: a non-empty listing name, for places that can't run your extension. Vortex itself shows the name you pass to `registerGame`.

#### Supporting two games

An extension that registers several games lists each under the id it passes to `registerGame`. Here, one extension supports a game and its sequel, and each has its own page on Nexus Mods, so neither needs a `gameUid`. The ids are made up:

```json
{
"name": "My Game Support",
"version": "1.0.0",
"contributes": {
"games": {
"mygame": { "nexusGameId": 1111, "name": "My Game" },
"mygame2": { "nexusGameId": 2222, "name": "My Game 2" }
}
}
}
```

#### When `gameUid` is required

A game resolves to the declared `gameUid` if there is one, otherwise to the game its `nexusGameId` belongs to, otherwise to nothing. So declare `gameUid` when your game is not the one its `nexusGameId` belongs to, or when it isn't on Nexus Mods at all.

Skyrim VR is the first case: its mods are published on the Skyrim Special Edition page (1704), so `nexusGameId` alone would resolve to Skyrim Special Edition. Give it its own `gameUid`. Skyrim Special Edition is the game 1704 belongs to, so it doesn't need one:

```json
{
"name": "Skyrim Support",
"version": "1.0.0",
"contributes": {
"games": {
"skyrimse": { "nexusGameId": 1704, "name": "Skyrim Special Edition" },
"skyrimvr": {
"nexusGameId": 1704,
"gameUid": "d88c5de7-353b-5d60-87be-bec5caa6244a",
"name": "Skyrim VR"
}
}
}
}
```

A game that isn't on Nexus Mods at all has no `nexusGameId` to fall back on, so `gameUid` is the only thing that identifies it:

```json
{
"name": "My Unlisted Game Support",
"version": "1.0.0",
"contributes": {
"games": {
"myunlistedgame": {
"gameUid": "00000000-0000-0000-0000-000000000000",
"name": "My Unlisted Game"
}
}
}
}
```

The `gameUid` above is a placeholder. Look up the real one as described next.

#### Finding a game's ids

Look the game up on [NexusDB](https://nexusdb.nexusmods.com), the catalogue's own site. It lists the `gameUid` of every game, including those whose mods are published on another game's page. A developer dialog on Nexus Mods game pages that shows `game_id` and `game_uid` is planned, and this page will link it once it exists.

### `contributes.gameEnhancements`

For games your extension is relevant to without registering them, such as a tool, a mod type or an installer that works with games other extensions provide. This is advisory.

Each entry sets exactly one of `gameUid` and `nexusGameId`. Setting both, or neither, makes `contributes` invalid.

- `gameUid` targets one game.
- `nexusGameId` targets every game whose mods are published on that Nexus Mods game.

An extension that enhances every game published on Fallout New Vegas (130):

```json
{
"name": "Fallout New Vegas Sanity Checks",
"version": "1.0.0",
"contributes": {
"gameEnhancements": [{ "nexusGameId": 130 }]
}
}
```

## `gameId` (deprecated)

`gameId` is superseded by `contributes.games`. Vortex doesn't read it, but the Nexus Mods data platform still does, so leave it in place if your extension already has it.

- A number, or a string of digits, is the Nexus Mods game id: `2304` or `"2304"`.
- Any other string without whitespace is the game's domain on Nexus Mods: `"skyrimspecialedition"`.
- Anything else is ignored: an empty string, `0`, a negative number, a display name such as `"Game: My Game"`, a list or an object.
4 changes: 3 additions & 1 deletion packages/vortex-api/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,13 @@
"exports": {
".": {
"types": "./lib/api.d.ts"
}
},
"./info.schema.json": "./schemas/info.schema.json"
},
"files": [
"lib",
"bin",
"schemas",
"README.md",
"docs"
],
Expand Down
125 changes: 125 additions & 0 deletions packages/vortex-api/schemas/info.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://unpkg.com/@nexusmods/vortex-api/schemas/info.schema.json",
"title": "Vortex extension info.json",
"description": "The info.json file at the top level of a Vortex extension. The schema describes shape only: types, required keys and structure. Rules about values are written in each field's description. Vortex checks them and falls back to its legacy behaviour when `contributes` breaks one. Unknown keys are allowed everywhere.",
"type": "object",
"required": ["name", "version"],
"properties": {
"$schema": {
"type": "string",
"description": "Points editors at this schema for completion and field docs. Vortex ignores it."
},
"name": {
"type": "string",
"description": "Display name of the extension."
},
"version": {
"type": "string",
"description": "Version of the extension, as a semver string such as `1.2.0`."
},
"author": {
"type": "string",
"description": "Display name of the extension's author. Shown as `<unknown>` when missing."
},
"description": {
"type": "string",
"description": "Short description of what the extension does. Shown as `<missing>` when missing."
},
"id": {
"type": "string",
"description": "Stable identifier for the extension, used when other extensions require it with `requireExtension`. Pick one and keep it across versions."
},
"namespace": {
"type": "string",
"description": "i18next namespace for the extension's translations."
},
"contributes": {
"$ref": "#/$defs/contributes"
},
"gameId": {
"type": ["integer", "string"],
"deprecated": true,
"description": "Deprecated: use `contributes.games` instead. Vortex doesn't read it, but the Nexus Mods data platform still does. A number or a string of digits is the Nexus Mods game id (`2304`). Any other string without whitespace is the game's domain on Nexus Mods (`skyrimspecialedition`). Anything else is ignored."
}
},
"examples": [
{
"name": "Skyrim Support",
"version": "1.0.0",
"contributes": {
"games": {
"skyrimse": {
"nexusGameId": 1704,
"name": "Skyrim Special Edition"
},
"skyrimvr": {
"nexusGameId": 1704,
"gameUid": "d88c5de7-353b-5d60-87be-bec5caa6244a",
"name": "Skyrim VR"
}
}
}
},
{
"name": "Fallout New Vegas Sanity Checks",
"version": "1.0.0",
"contributes": {
"gameEnhancements": [{ "nexusGameId": 130 }]
}
}
],
"$defs": {
"contributes": {
"type": "object",
"description": "What the extension contributes, readable without running it. Every field is optional. Vortex reads it only when it is valid. One invalid field makes all of `contributes` invalid, and the extension then loads as if it had none, with a warning. Older Vortex versions ignore this key.",
"properties": {
"games": {
"type": "object",
"description": "The games the extension registers, keyed by the id it passes to `registerGame`. Keys must be non-empty and must not start with `tier-0-`, which is reserved. Registering an id that isn't listed is an error. An empty object for a game declares the game and nothing else.",
"additionalProperties": {
"$ref": "#/$defs/game"
}
},
"gameEnhancements": {
"type": "array",
"description": "Games the extension is relevant to without registering them, for example a tool or a mod type that works with several games. Advisory.",
"items": {
"$ref": "#/$defs/gameEnhancement"
}
}
}
},
"game": {
"type": "object",
"properties": {
"nexusGameId": {
"type": "integer",
"description": "The Nexus Mods game this game's mods are published on. Must be a positive integer, and `null` isn't allowed. Leave it out when the game has no page on Nexus Mods. Several games may declare the same one: Skyrim Special Edition and Skyrim VR both publish on 1704."
},
"gameUid": {
"type": "string",
"description": "The game's id in the Nexus Mods game catalogue, found on NexusDB (https://nexusdb.nexusmods.com). Must be non-empty. Required when the game isn't the one its `nexusGameId` belongs to (Skyrim VR on 1704), or when it isn't on Nexus Mods. Any case is accepted, Vortex lowercases it."
},
"name": {
"type": "string",
"description": "Name for listings that can't run the extension. Must be non-empty. Vortex itself shows the name passed to `registerGame`."
}
}
},
"gameEnhancement": {
"type": "object",
"description": "Sets exactly one of `gameUid` and `nexusGameId`. Setting both, or neither, makes `contributes` invalid.",
"properties": {
"gameUid": {
"type": "string",
"description": "Enhances exactly this game. Same rules as `gameUid` on a game."
},
"nexusGameId": {
"type": "integer",
"description": "Enhances every game whose mods are published on this Nexus Mods game. Same rules as `nexusGameId` on a game."
}
}
}
}
}
Loading
Loading