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

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

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.

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

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.

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.