Skip to Content
Mod BuilderManifest Reference

Manifest Reference

The manifest.json file is the configuration document that defines your mod’s structure, options, and metadata. This reference covers the complete schema and all available fields.

Complete Schema

{
  "Version": 1,
  "Guid": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
  "Name": "string",
  "Description": "string",
  "IconPath": "string",
  "Options": [
    {
      "Name": "string",
      "Description": "string",
      "Include": ["string"],
      "Image": "string",
      "SubOptions": [
        {
          "Name": "string",
          "Description": "string",
          "Include": ["string"],
          "Image": "string"
        }
      ]
    }
  ]
}

Root Fields

Version

"Version": 1
PropertyValue
Typenumber
RequiredYes
ValueAlways 1

The manifest format version. Currently only version 1 is supported.

Guid

"Guid": "a1b2c3d4-e5f6-4789-abcd-ef0123456789"
PropertyValue
Typestring
RequiredYes
FormatUUID v4

A unique identifier for your mod. Auto-generated when creating a new project. Do not modify unless you know what you’re doing. Changing the GUID creates a “new” mod in users’ libraries.

Name

"Name": "My Awesome Mod"
PropertyValue
Typestring
RequiredYes
Max LengthRecommended < 50 characters

The display name shown in mod managers and listings.

Description

"Description": "A brief explanation of what this mod does"
PropertyValue
Typestring
RequiredYes
NoteCan be empty string ""

A short description of the mod’s purpose and features.

IconPath

"IconPath": "icon.png"
PropertyValue
Typestring
RequiredNo
FormatRelative file path

Path to the mod’s thumbnail image, relative to the mod root folder.

Supported formats: PNG, JPEG, WebP

Recommended size: 256x256 or 512x512 pixels

Options

"Options": [...]
PropertyValue
Typearray
RequiredNo
ItemsOption objects

An array of configurable options for the mod. Omit entirely for simple mods without options.

Option Object

{
  "Name": "High Quality Textures",
  "Description": "4K resolution texture pack",
  "Include": ["High Quality Textures"],
  "Image": "High Quality Textures/preview.png",
  "SubOptions": [...]
}

Name

PropertyValue
Typestring
RequiredYes

The display name for this option.

Description

PropertyValue
Typestring
RequiredYes
NoteCan be empty string

Explanation of what enabling this option does.

Include

"Include": ["FolderName"]
PropertyValue
Typestring[]
RequiredConditional
ConditionRequired if no SubOptions

Array of folder paths to include when this option is enabled. Paths are relative to the mod root.

Image

PropertyValue
Typestring
RequiredNo

Relative path to a preview image for this option.

SubOptions

PropertyValue
Typearray
RequiredConditional
ConditionRequired if no Include
ItemsSubOption objects

Array of sub-options for nested choices within this option.

Rule: An option must have either Include OR SubOptions, not both empty.

SubOption Object

{
  "Name": "Gold Variant",
  "Description": "Luxurious gold finish",
  "Include": ["Weapon Skins/Gold Variant"],
  "Image": "Weapon Skins/Gold Variant/preview.png"
}

SubOptions have the same fields as Options except they cannot contain nested SubOptions.

Name

PropertyValue
Typestring
RequiredYes

Description

PropertyValue
Typestring
RequiredYes
NoteCan be empty string

Include

PropertyValue
Typestring[]
RequiredNo

Image

PropertyValue
Typestring
RequiredNo

Examples

Minimal Mod (No Options)

{
  "Version": 1,
  "Guid": "12345678-1234-4123-8123-123456789abc",
  "Name": "Simple Texture Mod",
  "Description": "Replaces default textures"
}

Mod with Icon

{
  "Version": 1,
  "Guid": "12345678-1234-4123-8123-123456789abc",
  "Name": "Enhanced Effects",
  "Description": "Better particle effects for explosions",
  "IconPath": "icon.png"
}

Mod with Options

{
  "Version": 1,
  "Guid": "12345678-1234-4123-8123-123456789abc",
  "Name": "Quality Selector",
  "Description": "Choose your texture quality",
  "IconPath": "icon.png",
  "Options": [
    {
      "Name": "Ultra Quality",
      "Description": "4K textures, highest quality",
      "Include": ["Ultra Quality"],
      "Image": "Ultra Quality/preview.png"
    },
    {
      "Name": "Performance",
      "Description": "1K textures, better FPS",
      "Include": ["Performance"],
      "Image": "Performance/preview.png"
    }
  ]
}

Mod with SubOptions

{
  "Version": 1,
  "Guid": "12345678-1234-4123-8123-123456789abc",
  "Name": "Weapon Customization",
  "Description": "Multiple weapon skin variants",
  "IconPath": "icon.png",
  "Options": [
    {
      "Name": "Primary Weapon Skins",
      "Description": "Choose a skin for primary weapons",
      "SubOptions": [
        {
          "Name": "Default",
          "Description": "Keep original appearance",
          "Include": []
        },
        {
          "Name": "Gold",
          "Description": "Golden finish",
          "Include": ["Primary Weapon Skins/Gold"],
          "Image": "Primary Weapon Skins/Gold/preview.png"
        },
        {
          "Name": "Carbon Fiber",
          "Description": "Carbon fiber wrap",
          "Include": ["Primary Weapon Skins/Carbon Fiber"],
          "Image": "Primary Weapon Skins/Carbon Fiber/preview.png"
        }
      ]
    }
  ]
}

Validation Rules

Required Fields

  • Version must be 1
  • Guid must be valid UUID format
  • Name must be non-empty string
  • Description must be present (can be empty)

Option Rules

  • If Options array exists, it must contain at least one option
  • Each option must have Name and Description
  • Each option must have Include OR SubOptions (at least one)

Path Rules

  • All paths are relative to the mod root folder
  • Paths are case-sensitive
  • Use forward slashes (/) as separators
  • No leading or trailing slashes

Build-Time Cleaning

When building, the manifest is cleaned:

  • Empty Description fields are kept (required)
  • Empty IconPath is removed
  • Empty Image fields are removed
Creating ModsOverview