Menu Layout

Configuration menus are defined in MCM\Config\ModName\config.json.

This file is written in JSON - a lightweight, human-readable format.

MCM controls - such as sliders, toggle buttons, and text - are used to build up a menu.

JSON File Layout

{
  "modName": "MyAwesomeMod",          // Your plugin name, without the extension.
  "displayName": "My Awesome Mod",    // The name to be displayed in the MCM menu.
  "minMcmVersion": 1,                 // (Optional) The minimum required MCM Helper version code.
  "pluginRequirements": [...],        // (Optional) A list of required plugins.
  "cursorFillMode": "topToBottom",    // (Optional) Specify whether controls fill top-to-bottom or left-to-right.
  "content": [...],                   // (Optional) The contents of the mod configuration menu.
  "customContent": {...},             // (Optional) An external file (DDS or SWF) to display in the control panel.
  "pages": [{                         // (Optional) Subpages of the config menu.
    "pageDisplayName": "Main Page",   // The display name of the page.
    "content": [...]                  // The contents of the page.
  }]
}

Top-level properties

modName (required)

modName is the primary identifier for your mod in the MCM. This value should be set to your plugin name, without the file extension. This value must be unique and must match your directory name MCM\Config\ModName\.

e.g. For a mod named MyAwesomeMod.esp, modName should be MyAwesomeMod and all MCM config files should be placed in Data\MCM\Config\MyAwesomeMod\.

displayName (required)

displayName is the name that will be displayed in the left panel in the MCM.

minMcmVersion (optional)

(Supported from v1.2.2 - version code 9)

minMcmVersion is the minimum MCM Helper version-code that your menu requires. If the user has an older version of MCM Helper installed, they will be required to update before they can access the menu.

pluginRequirements (optional)

(Added in v1.0.2 - version code 3)

This is a list of required plugins for the configuration menu. If the user does not have a required plugin installed and enabled, they will be notified which plugins are missing.

Example

{
  "pluginRequirements": ["SomeMod.esp", "AnotherMod.esp"]
}

cursorFillMode (optional)

By default, menus are laid out left-to-right, top-to-bottom. The cursorFillMode property can be specified as topToBottom to fill top-to-bottom instead. When defining MCM controls, you can override the position of any control by adding a position property to it. Specifying "position": 1 would place a control at the top of the right-hand column, and then everything after it would fill according to the fill mode.

content (optional)

Your MCM menu layout goes here. Use MCM controls to build your menu.

For a full list of the available MCM controls, check out the MCM Controls wiki page.

Here is a simple example that displays a header titled "Hello World!" with a text control below it.

{
  ...
  "content": [
    {
      "text": "Hello World!",
      "type": "header"
    },
    {
      "text": "Welcome to the SkyUI Mod Configuration Menu!",
      "type": "text"
    }
  ]
}

customContent (optional)

This allows you to load content from an external file into the config area. This property is mutually exclusive with content, so you should only ever specify one or the other.

Supported source file formats are SWF for Flash movies and DDS for images. PNG and some other image formats may work as well, but they will most likely be imported in bad quality.

Here is a simple example of how to specify custom content.

{
  ...
  "customContent": {
    "source": "skyui/skyui_splash.swf"
  }
}

The path of the loaded file is relative to Data/Interface/. In this example, the file is located at Data/Interface/skyui/skyui_splash.swf.

customContent also supports two optional parameters for X and Y position offset. (0,0) is the top left corner of the config area. The dimensions of this area are 770x446. The horizontal center point is at (376,223), which is not exactly at half of the width because the right side holds the scroll bar. To calculate the offsets for a 256x256 image, have a look at this example:

X offset = 376 - (imageWidth / 2) = 376 - 128 = 258
Y offset = 223 - (imageHeight / 2) = 223 - 128 = 95

The corresponding JSON would look something like the following.

{
  ...
  "customContent": {
    "source": "modname/splash_256x256.dds",
    "x": 258,
    "y": 95
  }
}

pages (optional)

A configuration menu can have multiple sub-pages to group related settings. To create a page, add a new entry to the pages array. A page must have a display name (pageDisplayName) - this specifies the page label that will be shown in the left panel. Page content follows the same format as the top-level content array. Custom content can be used in the same way as well.

Example:

{
  ...
  "pages": [
    {
      "pageDisplayName": "Page 1",
      "content": [
        {
          "text": "This text is on page 1.",
          "type": "text"
        }
      ]
    },
    {
      "pageDisplayName": "Page 2",
      "content": [
        {
          "text": "This text is on page 2.",
          "type": "text"
        }
      ]
    }
  ]
}

If your mod uses sub-pages, it is recommended that your main page either be blank or use custom content. The main page will not be selectable once a different page is selected.