Skip to content

mwse.mcm⚓︎

The MCM library provides a set of objects to make creating mod configurations as easy as possible.

In addition, many MCM components implement useful UI structures that can be used outside the MCMs. These are documented here. For example, you can use mwse.mcm.createSlider(someMenu, {...}) to use labeled sliders from the MCM in your custom menu. Be warned, however, that MCM components require the parent element to have the correct formatting to appear. They tend to work best with menus that utilize widthProportional and autoHeight.

Functions⚓︎

mwse.mcm.createActiveInfo⚓︎

Creates a new ActiveInfo inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, ActiveInfo's UI element tree won't be created. To do so, use ActiveInfo's create method:

local myActiveInfo = mwse.mcm.createActiveInfo({ ... })
myActiveInfo:create(parent)

The same is done by this function if you pass both parent and data arguments.

local info = mwse.mcm.createActiveInfo(parent, { label = ..., text = ..., description = ..., variable = ..., defaultSetting = ..., inGameOnly = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createActiveInfo.data, string): The UI element inside which the new ActiveInfo will be created.
  • data (table, string): Optional. If passing only a string, it will be used as the ActiveInfo's label.
    • label (string): Optional. The ActiveInfo's label.
    • text (string): Optional. The ActiveInfo's text.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): Optional. A variable for this setting.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • inGameOnly (boolean): Default: false.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMActiveInfo)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createButton⚓︎

Creates a new Button inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, Button's UI element tree won't be created. To do so, use Button's create method:

local myButton = mwse.mcm.createButton({ ... })
myButton:create(parent)

The same is done by this function if you pass both parent and data arguments.

local button = mwse.mcm.createButton(parent, { label = ..., buttonText  = ..., description = ..., leftSide  = ..., variable = ..., defaultSetting = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createButton.data): The UI element inside which the new Button will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown next to the button.
    • buttonText (string): Optional. Text shown inside the button.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • leftSide (boolean): Default: true. If true, the button will be created on the left and label on the right.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): Optional. A variable for this Button.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • callback (fun(self: mwseMCMButton)): Optional. The custom function called when the player interacts with this Button.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMButton)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createConfigVariable⚓︎

Creates a new ConfigVariable.

local variable = mwse.mcm.createConfigVariable({ id = ..., path = ..., defaultSetting = ..., inGameOnly = ..., numbersOnly = ..., restartRequired = ..., restartRequiredMessage = ..., converter = ... })

Parameters:

  • variable (table)
    • id (string): Key in the config file used to store the variable.
    • path (string): Location of the config file relative to Data Files/MWSE/config/.
    • defaultSetting (unknown): Optional. If there is no value stored by the id key in the config file, it will be initialized to this value.
    • inGameOnly (boolean): Default: false. If true, the setting containing this variable will be disabled if the game is on main menu.
    • numbersOnly (boolean): Default: false. If true, only numbers will be allowed for this variable in TextFields.
    • restartRequired (boolean): Default: false. If true, updating the setting containing this variable will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The default text is a localized version of: "The game must be restarted before this change will come into effect.".
    • converter (fun(newValue): unknown): Optional. This function is called when the value of the variable is changed. The function can modify the new value before it is saved.

Returns:

mwse.mcm.createCustom⚓︎

Creates a new Custom variable.

local variable = mwse.mcm.createCustom({ id = ..., getter = ..., setter = ..., inGameOnly = ..., numbersOnly = ..., restartRequired = ..., restartRequiredMessage = ..., converter = ... })

Parameters:

  • variable (table)
    • id (string): Optional. The unique identifier for the variable.
    • getter (fun(self: mwseMCMCustomVariable): unknown): The custom getter function.
    • setter (fun(self: mwseMCMCustomVariable, newValue: unknown)): The custom setter function.
    • inGameOnly (boolean): Default: false. If true, the setting containing this variable will be disabled if the game is on main menu.
    • numbersOnly (boolean): Default: false. If true, only numbers will be allowed for this variable in TextFields.
    • restartRequired (boolean): Default: false. If true, updating the setting containing this variable will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The default text is a localized version of: "The game must be restarted before this change will come into effect.".
    • converter (fun(newValue): unknown): Optional. This function is called when the value of the variable is changed. The function can modify the new value before it is saved.

Returns:

mwse.mcm.createCycleButton⚓︎

Creates a new mwseMCMCycleButton inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, cycle button's UI element tree won't be created. To do so, use cycle button's create method:

local myButton = mwse.mcm.createCycleButton({ ... })
myButton:create(parent)

The same is done by this function if you pass both parent and data arguments.

local button = mwse.mcm.createCycleButton(parent, { label = ..., description = ..., options = ..., leftSide  = ..., variable = ..., defaultSetting = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createCycleButton.data): The UI element inside which the new cycle button will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown next to the button.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • options (tes3uiCycleButtonOption[]): This table holds the text and variable value for each of the cycle button's options.
    • leftSide (boolean): Default: true. If true, the button will be created on the left and label on the right.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable for this cycle button.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • callback (fun(self: mwseMCMCycleButton)): Optional. The custom function called when the player interacts with this cycle button.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMCycleButton)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createDropdown⚓︎

Creates a new Dropdown inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, Dropdown's UI element tree won't be created. To do so, use Dropdown's create method:

local myDropdown = mwse.mcm.createDropdown({ ... })
myDropdown:create(parent)

The same is done by this function if you pass both parent and data arguments.

local dropdown = mwse.mcm.createDropdown(parent, { label = ..., description = ..., options = ..., variable = ..., defaultSetting = ..., idleColor = ..., overColor = ..., pressedColor = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createDropdown.data): The UI element inside which the new Dropdown will be created.
  • data (table): Optional.
    • label (string): Optional. The text shown above the dropdown.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • options (mwseMCMDropdownOption[]): This table holds the text and variable value for each of the dropdown's options.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable for this setting.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • idleColor (number[]): Default: tes3ui.getPalette(tes3.palette.normalColor). The idle color for dropdown. Needs to be an RGB trio in the range [0.0, 1.0].
    • overColor (number[]): Default: tes3ui.getPalette(tes3.palette.normalOverColor). The color used when the mouse if hovering over the dropdown. Needs to be an RGB trio in the range [0.0, 1.0].
    • pressedColor (number[]): Default: tes3ui.getPalette(tes3.palette.normalPressedColor). The color used when the dropdown is being pressed. Needs to be an RGB trio in the range [0.0, 1.0].
    • callback (fun(self: mwseMCMDropdown)): Optional. The custom function called when the player interacts with this Setting.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMDropdown)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createGlobal⚓︎

Creates a new mwseMCMGlobal variable.

local variable = mwse.mcm.createGlobal({ id = ..., numbersOnly = ..., converter = ... })

Parameters:

  • variable (table, string): If passing only a string, it will be used as variable's id.
    • id (string): The id of the Morrowind Global.
    • numbersOnly (boolean): Default: false. If true, only numbers will be allowed for this variable in TextFields.
    • converter (fun(newValue): unknown): Optional. This function is called when the value of the variable is changed. The function can modify the new value before it is saved.

Returns:

mwse.mcm.createGlobalBoolean⚓︎

Creates a new GlobalBoolean variable.

local variable = mwse.mcm.createGlobalBoolean({ id = ... })

Parameters:

  • variable (table, string): If passing only a string, it will be used as variable's id.
    • id (string): The id of the Morrowind Global.

Returns:

Creates a new Hyperlink inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, Hyperlink's UI element tree won't be created. To do so, use Hyperlink's create method:

local myHyperlink = mwse.mcm.createHyperlink({ ... })
myHyperlink:create(parent)

The same is done by this function if you pass both parent and data arguments.

local hyperlink = mwse.mcm.createHyperlink(parent, { text = ..., description = ..., url = ..., label = ..., inGameOnly = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createHyperlink.data): The UI element inside which the new Hyperlink will be created.
  • data (table): Optional.
    • text (string): The Hyperlink's text.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • url (string): The URL for this hyperlink.
    • label (string): Optional. The Hyperlink's label. Shown above the Hyperlink's text.
    • inGameOnly (boolean): Default: false.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMHyperlink)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createInfo⚓︎

Creates a new Info inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, Info's UI element tree won't be created. To do so, use Info's create method:

local myInfo = mwse.mcm.createInfo({ ... })
myInfo:create(parent)

The same is done by this function if you pass both parent and data arguments.

local info = mwse.mcm.createInfo(parent, { label = ..., text = ..., description = ..., variable = ..., defaultSetting = ..., inGameOnly = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createInfo.data, string): The UI element inside which the new Info will be created.
  • data (table, string): Optional. If passing only a string, it will be used as the Info's label.
    • label (string): Optional. The Info's label.
    • text (string): Optional. The Info's text.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): Optional. A variable for this setting.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • inGameOnly (boolean): Default: false.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMInfo)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createKeyBinder⚓︎

Creates a new KeyBinder inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, KeyBinder's UI element tree won't be created. To do so, use KeyBinder's create method:

local myKeyBinder = mwse.mcm.createKeyBinder({ ... })
myKeyBinder:create(parent)

The same is done by this function if you pass both parent and data arguments.

local button = mwse.mcm.createKeyBinder(parent, { label = ..., description = ..., allowCombinations  = ..., allowMouse  = ..., keybindName = ..., leftSide  = ..., variable = ..., defaultSetting = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createKeyBinder.data): The UI element inside which the new KeyBinder will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown next to the button.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • allowCombinations (boolean): Default: true. If true, the keybinder will let the user use modification keys: Shift, Ctrl, and Alt when rebinding.
    • allowMouse (boolean): Default: false. If true, the keybinder will let the user use mouse buttons and scroll wheel in this keybinder. In that case the variable will have mwseKeyMouseCombo layout, mwseKeyCombo otherwise.
    • keybindName (string): Optional. The keybind name. Shown in the popup menu header. This string is formatted into a localized version of "SET %s KEYBIND.". If none is provided the popup has "SET NEW KEYBIND." as header text.
    • leftSide (boolean): Default: true. If true, the button will be created on the left and label on the right.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable for this KeyBinder.
    • defaultSetting (mwseKeyCombo): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • callback (fun(self: mwseMCMKeyBinder)): Optional. The custom function called when the player interacts with this KeyBinder.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMKeyBinder)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createMouseOverInfo⚓︎

Creates a new MouseOverInfo inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, MouseOverInfo's UI element tree won't be created. To do so, use MouseOverInfo's create method:

local myMouseOverInfo = mwse.mcm.createMouseOverInfo({ ... })
myMouseOverInfo:create(parent)

The same is done by this function if you pass both parent and data arguments.

local info = mwse.mcm.createMouseOverInfo(parent, { label = ..., text = ..., description = ..., variable = ..., defaultSetting = ..., inGameOnly = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createMouseOverInfo.data, string): The UI element inside which the new MouseOverInfo will be created.
  • data (table, string): Optional. If passing only a string, it will be used as the MouseOverInfo's label.
    • label (string): Optional. The MouseOverInfo's label.
    • text (string): Optional. The MouseOverInfo's text.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): Optional. A variable for this setting.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • inGameOnly (boolean): Default: false.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMMouseOverInfo)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createOnOffButton⚓︎

Creates a new OnOffButton inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, OnOffButton's UI element tree won't be created. To do so, use OnOffButton's create method:

local myOnOffButton = mwse.mcm.createOnOffButton({ ... })
myOnOffButton:create(parent)

The same is done by this function if you pass both parent and data arguments.

local button = mwse.mcm.createOnOffButton(parent, { label = ..., description = ..., leftSide  = ..., variable = ..., defaultSetting = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createOnOffButton.data): The UI element inside which the new OnOffButton will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown next to the button.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • leftSide (boolean): Default: true. If true, the button will be created on the left and label on the right.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable of given class for this Button.
    • defaultSetting (boolean): Default: false. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • callback (fun(self: mwseMCMOnOffButton)): Optional. The custom function called when the player interacts with this Button.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMOnOffButton)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createParagraphField⚓︎

Creates a new ParagraphField inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, ParagraphField's UI element tree won't be created. To do so, use ParagraphField's create method:

local myParagraphField = mwse.mcm.createParagraphField({ ... })
myParagraphField:create(parent)

The same is done by this function if you pass both parent and data arguments.

local paragraphField = mwse.mcm.createParagraphField(parent, { label = ..., buttonText = ..., variable = ..., numbersOnly = ..., description = ..., height = ..., sNewValue = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createParagraphField.data): The UI element inside which the new ParagraphField will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown above the text field.
    • buttonText (string): Optional. The text shown on the button next to the input field. The default text is a localized version of: "Submit".
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): Creates a variable of given class for this setting.
    • numbersOnly (boolean): Default: false. If true, only numbers will be allowed in this TextField.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • height (integer): Optional. Fixes the height of the paragraph field to a custom value.
    • sNewValue (string): Optional. The message shown after a new value is submitted. This can be formatted with a '%s' which will be replaced with the new value. The default text is a localized version of: "New value: '%s'".
    • callback (fun(self: mwseMCMParagraphField)): Optional. This allows overriding the default implementation of this method
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMParagraphField)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createPercentageSlider⚓︎

Creates a new PercentageSlider inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, PercentageSlider's UI element tree won't be created. To do so, use PercentageSlider's create method:

local mySlider = mwse.mcm.createPercentageSlider({ ... })
mySlider:create(parent)

The same is done by this function if you pass both parent and data arguments.

local slider = mwse.mcm.createPercentageSlider(parent, { label = ..., variable = ..., defaultSetting = ..., min = ..., max = ..., step = ..., jump = ..., decimalPlaces = ..., description = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., convertToLabelValue = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createPercentageSlider.data): The UI element inside which the new PercentageSlider will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown above the slider. If left as a normal string, it will be shown in the form: [label]: [self.variable.value]. If the string contains a '%s' format operator, the value will be formatted into it.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable for this setting.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • min (number): Default: 0. Minimum value of slider.
    • max (number): Default: 1. Maximum value of slider.
    • step (number): Default: 0.01. How far the slider moves when you press the arrows.
    • jump (number): Default: 0.05. How far the slider jumps when you click an area inside the slider.
    • decimalPlaces (integer): Default: 2. The number of decimal places of precision. Must be a positive integer.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • callback (fun(self: mwseMCMPercentageSlider)): Optional. The custom function called when the player interacts with this Setting.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • convertToLabelValue (fun(self: mwseMCMPercentageSlider, variableValue: number): number, string): Optional. Define a custom formatting function for displaying variable values.
    • postCreate (fun(self: mwseMCMPercentageSlider)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createPlayerData⚓︎

Creates a new PlayerData variable.

local variable = mwse.mcm.createPlayerData({ id = ..., path = ..., defaultSetting = ..., restartRequired = ..., restartRequiredMessage = ..., converter = ... })

Parameters:

  • variable (table)
    • id (string): Key of entry used on the tes3.player.data table.
    • path (string): Path to id relative to tes3.player.data. The subtable keys need to be split by dots. It's best to at least store all your mwseMCMPlayerData fields in a table named after your mod to avoid conflicts.
    • defaultSetting (unknown): Optional. If id does not exist in the tes3.player.data field, it will be initialized to this value. It's best to initialize this yourself though, as this will not create the value until you've entered the MCM.
    • restartRequired (boolean): Default: false. If true, updating the setting containing this variable will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The default text is a localized version of: "The game must be restarted before this change will come into effect.".
    • converter (fun(newValue): unknown): Optional. This function is called when the value of the variable is changed. The function can modify the new value before it is saved.

Returns:

mwse.mcm.createSlider⚓︎

Creates a new Slider inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, Slider's UI element tree won't be created. To do so, use Slider's create method:

local mySlider = mwse.mcm.createSlider({ ... })
mySlider:create(parent)

The same is done by this function if you pass both parent and data arguments.

local slider = mwse.mcm.createSlider(parent, { label = ..., variable = ..., defaultSetting = ..., min = ..., max = ..., step = ..., jump = ..., decimalPlaces = ..., description = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., convertToLabelValue = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createSlider.data): The UI element inside which the new Slider will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown above the slider. If left as a normal string, it will be shown in the form: [label]: [self.variable.value]. If the string contains a '%s' format operator, the value will be formatted into it.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable for this setting.
    • defaultSetting (unknown): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • min (number): Default: 0. Minimum value of slider.
    • max (number): Default: 100. Maximum value of slider.
    • step (number): Default: 1. How far the slider moves when you press the arrows.
    • jump (number): Default: 5. How far the slider jumps when you click an area inside the slider.
    • decimalPlaces (integer): Default: 0. The number of decimal places of precision. Must be a nonnegative integer.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • callback (fun(self: mwseMCMSlider)): Optional. The custom function called when the player interacts with this Setting.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • convertToLabelValue (fun(self: mwseMCMSlider, variableValue: number): number, string): Optional. Define a custom formatting function for displaying variable values.
    • postCreate (fun(self: mwseMCMSlider)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

Example: DecimalSlider

The following example shows how to create a slider that keeps the variable value a floating point number with precision of 2 decimal places.

--- @type tes3uiElement, table
local myPage, myConfig
mwse.mcm.createSlider{
    parent = myPage,
    label = "My slider",
    variable = mwse.mcm.createTableVariable{ id = "someval", table = myConfig },
    min = 0.00,
    max = 1.00,
    step = 0.01,
    jump = 0.05,
    decimalPlaces = 2
}
Example: DistanceSlider

The following example shows how the convertToLabelValue parameter can be used to create a slider for a config setting that handles distances. The config setting will be stored using game units, but the displayed value will be in real-world units. Recall that 1 game unit corresponds to 22.1 feet, and 1 foot is 0.3048 meters.

--- @type tes3uiElement, table
local myPage, myConfig
mwse.mcm.createSlider{
    parent = myPage,
    label = "My distance slider",
    variable = mwse.mcm.createTableVariable{ id = "distance", table = myConfig },
    convertToLabelValue = function(self, variableValue)
        local feet = variableValue / 22.1
        local meters = 0.3048 * feet
        if self.decimalPlaces == 0 then
            return string.format("%i ft (%.2f m)", feet, meters)
        end
        return string.format(
            -- if `decimalPlaces == 1, then this string will simplify to
            -- "%.1f ft (%.3f m)"
            string.format("%%.%uf ft (%%.%uf m)", self.decimalPlaces, self.decimalPlaces + 2),
            feet, meters
        )
    end,

    max = 22.1 * 10,    -- max is 10 feet
    step = 22.1,        -- increment by 1 foot
    jump = 22.1 * 5,
}
Example: SkillSlider

Here is an (admittedly less practical) example to help highlight the different ways convertToLabelValue can be used. In this example, it will be used to create a slider that stores a tes3.skill constant in the config, and then displays the name of the corresponding skill.

--- @type tes3uiElement, table
local myPage, myConfig
mwse.mcm.createSlider{
    parent = myPage,
    label = "My skill slider",
    variable = mwse.mcm.createTableVariable{ id = "skillId", table = myConfig },
    convertToLabelValue = function(self, variableValue)
        local skillName = tes3.getSkillName(math.round(variableValue))
        if skillName then
            return skillName
        end
        return "N/A"
    end,

    max = 26 -- there are 27 skills and indexing starts at 0
}

mwse.mcm.createTableVariable⚓︎

Creates a new TableVariable.

local variable = mwse.mcm.createTableVariable({ id = ..., table = ..., defaultSetting = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., converter = ... })

Parameters:

  • variable (table)
    • id (string): Key in the config file used to store the variable.
    • table (table): The table to save the data to.
    • defaultSetting (unknown): Optional. If id does not exist in the table, it will be initialised to this value.
    • inGameOnly (boolean): Default: false. If true, the setting containing this variable will be disabled if the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating the setting containing this variable will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The default text is a localized version of: "The game must be restarted before this change will come into effect.".
    • converter (fun(newValue): unknown): Optional. This function is called when the value of the variable is changed. The function can modify the new value before it is saved.

Returns:

mwse.mcm.createTemplate⚓︎

Creates a new Template.

local template = mwse.mcm.createTemplate({ name = ..., label = ..., headerImagePath = ..., onClose = ..., searchChildLabels = ..., searchChildDescriptions = ..., onSearch = ..., pages = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ... })

Parameters:

  • data (table, string): If passing only a string, it will be used as the Template's name.
    • name (string): Optional. The name field is the mod name, used to register the MCM, and is displayed in the mod list on the lefthand pane.
    • label (string): Optional. Used in place of name if that argument isn't passed. You need to pass at least one of the name and label arguments. If headerImagePath is not passed, a UI element will be created with label as text.
    • headerImagePath (string): Optional. Set it to display an image at the top of your menu. Path is relative to Data Files/. The image must have power-of-2 dimensions (i.e. 16, 32, 64, 128, 256, 512, 1024, etc.).
    • onClose (fun(modConfigContainer: tes3uiElement)): Optional. Set this to a function which will be called when the menu is closed. Useful for saving variables, such as TableVariable.
    • searchChildLabels (boolean): Default: true. If true, default search handler will search through all the page and setting label and text fields in this MCM template.
    • searchChildDescriptions (boolean): Default: true. If true, default search handler will search through all the page and setting description fields in this MCM template.
    • onSearch (fun(searchText: string): boolean): Optional. A custom search handler function. This function should return true if this mod Template should show up in search results for given searchText.
    • pages (mwseMCMPage.new.data[]): Optional. You can create pages for the template directly here. The entries in the array must specify the class of the page.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMTemplate)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createTextField⚓︎

Creates a new TextField inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, TextField's UI element tree won't be created. To do so, use TextField's create method:

local myTextField = mwse.mcm.createTextField({ ... })
myTextField:create(parent)

The same is done by this function if you pass both parent and data arguments.

local textField = mwse.mcm.createTextField(parent, { label = ..., buttonText = ..., variable = ..., numbersOnly = ..., description = ..., press = ..., sNewValue = ..., minHeight = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createTextField.data): The UI element inside which the new TextField will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown above the text field.
    • buttonText (string): Optional. The text shown on the button next to the input field. The default text is a localized version of: "Submit".
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable for this setting.
    • numbersOnly (boolean): Default: false. If true, only numbers will be allowed in this TextField.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • press (fun(self: mwseMCMTextField)): Optional. This allows overriding the default implementation of this method. Can be overriden to add a confirmation message before updating. This function should call self:update() at the end.
    • sNewValue (string): Optional. The message shown after a new value is submitted. This can be formatted with a '%s' which will be replaced with the new value. The default text is a localized version of: "New value: '%s'".
    • minHeight (integer): Optional. The minimum height set on the self.element.border UI element.
    • callback (fun(self: mwseMCMTextField)): Optional. This allows overriding the default implementation of this method. See its description.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMTextField)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.createVariable⚓︎

Creates a new Variable.

local variable = mwse.mcm.createVariable({ id = ..., inGameOnly = ..., numbersOnly = ..., restartRequired = ..., restartRequiredMessage = ..., converter = ... })

Parameters:

  • variable (table, string): Optional. If passing only a string, it will be used as variable's id.
    • id (string): Optional. The unique identifier for the variable.
    • inGameOnly (boolean): Default: false. If true, the setting containing this variable will be disabled if the game is on main menu.
    • numbersOnly (boolean): Default: false. If true, only numbers will be allowed for this variable in TextFields.
    • restartRequired (boolean): Default: false. If true, updating the setting containing this variable will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The default text is a localized version of: "The game must be restarted before this change will come into effect.".
    • converter (fun(newValue): unknown): Optional. This function is called when the value of the variable is changed. The function can modify the new value before it is saved.

Returns:

mwse.mcm.createYesNoButton⚓︎

Creates a new YesNoButton inside given parent menu.

The canonical way to use this function is to pass a parent and data arguments. If passing only data table, YesNoButton's UI element tree won't be created. To do so, use YesNoButton's create method:

local myYesNoButton = mwse.mcm.createYesNoButton({ ... })
myYesNoButton:create(parent)

The same is done by this function if you pass both parent and data arguments.

local button = mwse.mcm.createYesNoButton(parent, { label = ..., description = ..., leftSide  = ..., variable = ..., defaultSetting = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ... })

Parameters:

  • parent (tes3uiElement, mwse.mcm.createYesNoButton.data): The UI element inside which the new YesNoButton will be created.
  • data (table): Optional.
    • label (string): Optional. Text shown next to the button.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • leftSide (boolean): Default: true. If true, the button will be created on the left and label on the right.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): A variable for this Button.
    • defaultSetting (boolean): Default: false. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • callback (fun(self: mwseMCMYesNoButton)): Optional. The custom function called when the player interacts with this Button.
    • inGameOnly (boolean): Default: false. If true, the setting is disabled while the game is on main menu.
    • restartRequired (boolean): Default: false. If true, updating this Setting will notify the player to restart the game.
    • restartRequiredMessage (string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMYesNoButton)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

mwse.mcm.register⚓︎

A convenience function that registers the mod's configuration menu using its mwseMCMTemplate.

You don't need to call mwse.registerModConfig if calling this function.

mwse.mcm.register(template)

Parameters:

mwse.mcm.testKeyBind⚓︎

This function check whether a certain key combination is currently pressed. It will only check ctrl, shift and alt modifier keys, matching the KeyBinder. It doesn't check mouse.

local pressed = mwse.mcm.testKeyBind(keybind)

Parameters:

Returns:

  • pressed (boolean)