Control Types - Exit-9B/MCM-Helper GitHub Wiki

MCM Control Types

The following control types are available:

Empty
Header
Text
Toggle
HiddenToggle
Slider
Stepper
Menu
Enum
Color
Keymap
Input

Empty

Empty controls are used to add empty space between other controls. They cannot be interacted with.

{
  "type": "empty"
}

Header

A header control shows a decorated title text. It can be used to group several controls together under a common category. Header options cannot be interacted with.

{
  "text": "Main Section",
  "type": "header"
}

Text

A text control displays a generic text/value pair. You can make it behave like a button by assigning an action to it. For example, you could set up a text option for an "Uninstall" button.

{
  "text": "My text here",
  "type": "text",
  "help": "Displays a text/value pair.",
  "valueOptions": {
    "value": "My value"
  },
  "action": {                     // Optional. Allows you to make the control behave as a button.
    "type": "CallFunction",
    "form": "MCM_Demo.esp|800",   // Optional. Only required if using a different form than the config script.
    "scriptName": "MyScript",     // Optional. Only required if using a different script than the config script.
    "function": "SetIntensity",
    "params": [50.0]
  }
}

Toggle

A toggle control displays a text label and a check box.

{
  "text": "Mod Enabled",
  "type": "toggle",
  "help": "Controls whether the mod is enabled."
}

HiddenToggle

A hiddenToggle is an ON/OFF control that is not displayed in the menu (and therefore does not advance the cursor). You can use it to have the value of a global variable or script property be a groupControl (see Group Conditions).

{
  "type": "hiddenToggle",
  "text": "Invisible toggle control, this will not be displayed",
  "groupControl": 2,
  "valueOptions": {
    "sourceType": "PropertyValueInt",
    "sourceForm": "MCM_Demo.esp|800",
    "propertyName": "pShouldEnableGroup2"
  }
}

Slider

Unlike the previous control types, slider controls are dialog-based. This means selecting the option won't immediately result in a setting change event, but instead a dialog is opened. The dialog prompts the user to choose a value within a specified range.

With the formatString property you can embed the slider value in a string, e.g. "Every {0} hours", where {0} is replaced by the current value. The number inside the brackets sets the decimal places: A value of 1 with format string {2} is displayed as 1.00.

{
  "text": "Demo Slider",
  "type": "slider",
  "help": "A standard slider with constraints. Range: 0-1, Step: 0.01.",
  "valueOptions": {
    "min": 0,
    "max": 1,
    "step": 0.01,
    "formatString": "{2}"
  }
}

Stepper

A stepper allows a single selection from multiple choices. It will step to the next choice every time it is selected. Its value is stored and retrieved as an integer indicating an index.

{
  "text": "Demo Stepper",
  "type": "stepper",
  "help": "A stepper allows a single selection from multiple choices.",
  "valueOptions": {
    "options": ["On", "Off"]
  }
}

{
  "text": "Demo Menu",
  "type": "menu",
  "help": "A menu allows a single selection from multiple choices.",
  "valueOptions": {
    "options": ["Option 1", "Option 2", "Option 3", "Option 4", "Option 5"],
    "shortNames": ["1", "2", "3", "4", "5"], // Optional. Alternate option names to display on the page.
    "sourceForm": "MCM_Demo.esp|800",        // Optional. Only required if using a different form than the config script.
    "scriptName": "MyScript",                // Optional. Only required if using a different script than the config script.
    "propertyName": "pSelectedMenuOption"
  }
}

Additionally, unlike most controls, there is a special Papyrus function for altering the options displayed in a menu control at runtime.

; Dynamically override menu options via script.
; The supplied ID must refer to a menu or enum control.
Function SetMenuOptions(string a_ID, string[] a_options, string[] a_shortNames = none) native

Enum

An enum control is similar to a menu control, but its value is stored and retrieved as an integer indicating an index, rather than a string. Like menu controls, enum controls can also have their options altered via script (added in v1.2.0 - version code 7).

{
  "text": "Demo Enum",
  "type": "enum",
  "help": "An enum allows a single selection from multiple choices.",
  "valueOptions": {
    "options": ["Option 1", "Option 2", "Option 3", "Option 4", "Option 5"],
    "shortNames": ["1", "2", "3", "4", "5"]  // Optional. Alternate option names to display on the page.
  }
}

Color

A color option shows a color swatch dialog when selected. According to the SkyUI developers, they handpicked the best colors in the world for you to choose from. Colors are passed as 0xRRGGBB hexadecimal numbers. So 0xFF0000 is red, 0xFFFFFF is white, 0x000000 is black etc. The ColorComponent script provided by SKSE can be used to easily manipulate color values in Papyrus.

{
  "text": "Demo Color",
  "type": "color"
}

Keymap

A keymap control prompts the user to press a key when it is selected. It is not dialog-based, but it may display a confirmation dialog in the event of a conflict.

MCM Helper provides the capability to easily implement hotkeys to execute an action when a key is pressed. These hotkeys must be defined in keybinds.json. See Hotkeys.

id: The hotkey identifier. This must match the keybind definition in keybinds.json.
ignoreConflicts: (Optional) Suppresses warning messages when the user chooses a key that conflicts with another mod action or game function. Defaults to false if not specified.

{
  "id": "demo_hotkey",
  "text": "Demo Keymap",
  "type": "keymap",
  "help": "This hotkey does something cool.",
  "ignoreConflicts": false     // Optional. Defaults to false.
}

Alternatively, the keymap control can simply store a keycode as an integer. These can be implemented as hotkeys using SKSE's RegisterForKey function.

{
  "text": "Demo Keymap",
  "type": "keymap",
  "ignoreConflicts": false,
  "valueOptions": {
    "sourceType": "PropertyValueInt",
    "sourceForm": "MCM_Demo.esp|800",
    "propertyName": "pKeyCode"
  }
}

Input

An input control shows a text input dialog when selected, which allows the user to enter a text string with the keyboard.

{
  "text": "Demo Input",
  "type": "input",
  "valueOptions": {
    "sourceForm": "MCM_Demo.esp|800",   // Optional. Only required if using a different form than the config script.
    "scriptName": "MyScript",           // Optional. Only required if using a different script than the config script.
    "propertyName": "pUserInput"
  }
}