Game Mod Descriptor

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

{
  "$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.

"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.

"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.

"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.

"display-name": "HD Texture Pack"

maker

Type: string
Required: No Identifies the creator, author, or team responsible for the mod.

"maker": "Texture Artists United"

Type: string
Required: No Path to a banner image file for the mod. Typically displayed in Dolphin’s game list or mod selection interface.

"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

Patch Object Example

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

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

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

Complete Example

{
  "$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:

^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:

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

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

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.

Building

Architecture

Contributing

Technical Specs

Schema Overview

Root Object

Required Properties

Optional Properties

Example Structure

Field Specifications

type

version

base-file

display-name

maker

banner

Riivolution Object

riivolution Properties

patches Array

options Array

Complete Example

Validation Rules

Type Pattern

Required Fields

Type Constraints

Usage in Dolphin

Building

Architecture

Contributing

Technical Specs

​Schema Overview

​Root Object

​Required Properties

​Optional Properties

​Example Structure

​Field Specifications

​type

​version

​base-file

​display-name

​maker

​banner

​Riivolution Object

​riivolution Properties

​patches Array

​options Array

​Complete Example

​Validation Rules

​Type Pattern

​Required Fields

​Type Constraints

​Usage in Dolphin

Schema Overview

Root Object

Required Properties

Optional Properties

Example Structure

Field Specifications

type

version

base-file

display-name

maker

banner

Riivolution Object

riivolution Properties

patches Array

options Array

Complete Example

Validation Rules

Type Pattern

Required Fields

Type Constraints

Usage in Dolphin