> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dolphin-emu/dolphin/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Mod Descriptor

> JSON schema specification for Dolphin game modification descriptors

The Game Mod Descriptor is a JSON schema that defines how game modifications (mods) are packaged and loaded in Dolphin Emulator. This format enables proper integration of game mods, particularly those using the Riivolution patch system.

## Schema Overview

The descriptor file uses JSON Schema to validate mod configuration files. The official schema is available at:

```
https://raw.githubusercontent.com/dolphin-emu/dolphin/master/docs/game-mod-descriptor.json
```

## Root Object

The root object must be a valid JSON object with the following required and optional properties.

### Required Properties

| Property    | Type    | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| `type`      | string  | Must be exactly `"dolphin-game-mod-descriptor"` |
| `version`   | integer | Descriptor format version number                |
| `base-file` | string  | Path to the base game file this mod applies to  |

### Optional Properties

| Property       | Type   | Description                      |
| -------------- | ------ | -------------------------------- |
| `display-name` | string | Human-readable name for the mod  |
| `maker`        | string | Author or creator of the mod     |
| `banner`       | string | Path to banner image for the mod |
| `riivolution`  | object | Riivolution patch configuration  |

## Example Structure

```json theme={null}
{
  "$schema": "https://raw.githubusercontent.com/dolphin-emu/dolphin/master/docs/game-mod-descriptor.json",
  "type": "dolphin-game-mod-descriptor",
  "version": 1,
  "base-file": "path/to/game.iso",
  "display-name": "My Game Mod",
  "maker": "Mod Author",
  "banner": "path/to/banner.png",
  "riivolution": {
    "patches": [
      {
        "xml": "patch.xml",
        "root": "/path/to/mod/files",
        "options": [
          {
            "section-name": "Main Options",
            "option-id": "feature1",
            "option-name": "Enable Feature 1",
            "choice": 1
          }
        ]
      }
    ]
  }
}
```

## Field Specifications

### type

**Type**: `string`\
**Pattern**: `^dolphin-game-mod-descriptor$`\
**Required**: Yes

Must exactly match the string `"dolphin-game-mod-descriptor"`. This identifies the file as a valid Dolphin game mod descriptor.

```json theme={null}
"type": "dolphin-game-mod-descriptor"
```

### version

**Type**: `integer`\
**Required**: Yes

Indicates the version of the descriptor format being used. This allows for future schema evolution while maintaining backward compatibility.

```json theme={null}
"version": 1
```

### base-file

**Type**: `string`\
**Required**: Yes

Path to the base game file (ISO, WBFS, etc.) that this mod applies to. Can be relative or absolute.

```json theme={null}
"base-file": "games/MyGame.iso"
```

### display-name

**Type**: `string`\
**Required**: No

Human-readable name for the mod as it should appear in Dolphin's interface.

```json theme={null}
"display-name": "HD Texture Pack"
```

### maker

**Type**: `string`\
**Required**: No

Identifies the creator, author, or team responsible for the mod.

```json theme={null}
"maker": "Texture Artists United"
```

### banner

**Type**: `string`\
**Required**: No

Path to a banner image file for the mod. Typically displayed in Dolphin's game list or mod selection interface.

```json theme={null}
"banner": "assets/mod-banner.png"
```

## Riivolution Object

The `riivolution` object configures Riivolution-based patches, which are commonly used for Wii game modifications.

### riivolution Properties

| Property  | Type  | Required | Description                   |
| --------- | ----- | -------- | ----------------------------- |
| `patches` | array | Yes      | Array of patch configurations |

### patches Array

Each patch object in the `patches` array has the following structure:

| Property  | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| `xml`     | string | Yes      | Path to the Riivolution XML patch file   |
| `root`    | string | Yes      | Root directory for patch file operations |
| `options` | array  | Yes      | Array of option configurations           |

<Accordion title="Patch Object Example">
  ```json theme={null}
  {
    "xml": "riivolution/patch.xml",
    "root": "/mods/mygame",
    "options": [
      {
        "section-name": "Graphics",
        "option-id": "hd_textures",
        "option-name": "HD Textures",
        "choice": 1
      },
      {
        "section-name": "Gameplay",
        "option-id": "difficulty",
        "option-name": "Hard Mode",
        "choice": 0
      }
    ]
  }
  ```
</Accordion>

### options Array

Each option object configures a specific Riivolution option.

| Property       | Type    | Required | Description                                |
| -------------- | ------- | -------- | ------------------------------------------ |
| `choice`       | integer | Yes      | Selected choice index for this option      |
| `section-name` | string  | No       | Name of the section this option belongs to |
| `option-id`    | string  | No       | Unique identifier for the option           |
| `option-name`  | string  | No       | Display name for the option                |

<Note>
  The `choice` property is required and specifies which choice is selected for this option (typically 0 for disabled, 1+ for enabled/variants).
</Note>

## Complete Example

```json theme={null}
{
  "$schema": "https://raw.githubusercontent.com/dolphin-emu/dolphin/master/docs/game-mod-descriptor.json",
  "type": "dolphin-game-mod-descriptor",
  "version": 1,
  "base-file": "games/SuperMarioGalaxy.iso",
  "display-name": "Super Mario Galaxy HD Remaster",
  "maker": "Community HD Team",
  "banner": "assets/smg-hd-banner.png",
  "riivolution": {
    "patches": [
      {
        "xml": "riivolution/smg-hd.xml",
        "root": "/mods/smg-hd",
        "options": [
          {
            "section-name": "Graphics Enhancements",
            "option-id": "hd_textures",
            "option-name": "4K Texture Pack",
            "choice": 1
          },
          {
            "section-name": "Graphics Enhancements",
            "option-id": "hd_ui",
            "option-name": "HD UI Elements",
            "choice": 1
          },
          {
            "section-name": "Audio",
            "option-id": "orchestral_music",
            "option-name": "Orchestral Soundtrack",
            "choice": 0
          },
          {
            "section-name": "Gameplay",
            "option-id": "difficulty",
            "option-name": "Difficulty Mode",
            "choice": 0
          }
        ]
      }
    ]
  }
}
```

## Validation Rules

### Type Pattern

The `type` field must match the exact pattern:

```regex theme={null}
^dolphin-game-mod-descriptor$
```

### Required Fields

At the root level:

* `type`
* `version`
* `base-file`

Within `riivolution` object:

* `patches`

Within each patch object:

* `xml`
* `root`
* `options`

Within each option object:

* `choice`

### Type Constraints

| Field          | Constraint                      |
| -------------- | ------------------------------- |
| `type`         | Must be string matching pattern |
| `version`      | Must be integer                 |
| `base-file`    | Must be string                  |
| `display-name` | Must be string                  |
| `maker`        | Must be string                  |
| `banner`       | Must be string                  |
| `patches`      | Must be array                   |
| `xml`          | Must be string                  |
| `root`         | Must be string                  |
| `options`      | Must be array                   |
| `section-name` | Must be string                  |
| `option-id`    | Must be string                  |
| `option-name`  | Must be string                  |
| `choice`       | Must be integer                 |

## Usage in Dolphin

To use a game mod descriptor:

1. Create a JSON file following this schema
2. Place it in Dolphin's load directory alongside your game files
3. Configure the mod options as needed in the `riivolution.patches` array
4. Launch the game through Dolphin

Dolphin will automatically detect and apply the mod according to the descriptor configuration.

<Warning>
  Ensure all file paths in the descriptor (base-file, xml, root, banner) are correct relative to your Dolphin installation. Invalid paths will cause the mod to fail loading.
</Warning>