Setting Types, Storage, and Persistence

The MCM offers three mechanisms for modders to store mod settings.

1. Papyrus
2. Mod Settings
3. Global Values

The following MCM controls accept values:

Control Type	Value Type
Toggle	Bool, Int
Slider	Float, Int
Enum	Int
Color	Int
Keymap	Int
Text	String
Menu	String
Input	String

To specify a value (Bool, Int, or Float) source type, set sourceType in the control's valueOptions.
Text (String) source types are used automatically for the appropriate controls depending on the id or propertyName properties.

Valid options for sourceType are:

• PropertyValueBool
• PropertyValueInt
• PropertyValueFloat
• ModSettingBool
• ModSettingInt
• ModSettingFloat
• GlobalValue (added in v1.1.0 - version code 6)

Papyrus

The MCM can read and write to Papyrus script properties.

To ensure your Papyrus Properties are accessible to the MCM, ensure that they are declared as Auto Properties.

Example

Example property declarations in a Papyrus script:

int Property MyIntProperty = 4 Auto
float Property MyFloatProperty = 1.5 Auto
bool Property MyBooleanProperty = True Auto

An enum control retrieving its value from MyIntProperty on the MCM_Demo.esp|80E quest:

{
  "text": "Enum Demo",
  "type": "enum",
  "help": "Enum demo with four options.",
  "valueOptions": {
    "options": ["Option 1", "Option 2", "Option 3", "Option 4"],
    "sourceType": "PropertyValueInt",
    "sourceForm": "MCM_Demo.esp|80E", // Optional. Only required if using a different form than the config script.
    "scriptName": "MCM_DemoScript",   // Optional. Only required if using a different script than the config script.
    "propertyName": "MyIntProperty",
    "defaultValue": 0                 // Optional. This value will be selected when resetting to default.
  }
}

The sourceForm field accepts the plugin name and the form ID of the form that the Property resides in.

For example, if your quest has the formID 0000173E, then you would specify "MyMod.esp|173E" as the form parameter. This tells the MCM where the property is located in.

If sourceForm is not specified, then the default value is the quest that the config script is attached to.

ModSettings

ModSettings are a convenient storage mechanism for mod settings that mods can use to store data.

All mod settings must be defined in MCM\Config\ModName\settings.ini.

User settings live in MCM\Settings\ModName.ini. This file is automatically created and updated by the MCM.

ModSettings are recommended if the setting should persist for the game installation, and if it is desirable for users to share configuration files with others.

The data type for each setting is determined based on the first letter. Always ensure that you are using one of these prefixes.

• b: Bool
• f: Float
• i: Int
• r: Color (Comma-separated R,G,B values; Papyrus helper functions available from ColorComponent script)
• s: String
• u: Unsigned Int

Example

{
  "id": "fSliderValue:Main",
  "text": "Demo Slider",
  "type": "slider",
  "help": "A standard slider with constraints. Range: 1-100, Step: 1.",
  "valueOptions": {
    "min": 1,
    "max": 100,
    "step": 1,
    "sourceType": "ModSettingFloat"
  }
}

Papyrus functions are available for retrieving and setting ModSettings, either locally in your config script or globally from the MCM script.

Config script:

; Obtains the value of a mod setting.
int Function GetModSettingInt(string a_settingName) native
bool Function GetModSettingBool(string a_settingName) native
float Function GetModSettingFloat(string a_settingName) native
string Function GetModSettingString(string a_settingName) native

; Sets the value of a mod setting.
Function SetModSettingInt(string a_settingName, int a_value) native
Function SetModSettingBool(string a_settingName, bool a_value) native
Function SetModSettingFloat(string a_settingName, float a_value) native
Function SetModSettingString(string a_settingName, string a_value) native

MCM script:

; Obtains the value of a mod setting.
int Function GetModSettingInt(string a_modName, string a_settingName) native global
bool Function GetModSettingBool(string a_modName, string a_settingName) native global
float Function GetModSettingFloat(string a_modName, string a_settingName) native global
string Function GetModSettingString(string a_modName, string a_settingName) native global

; Sets the value of a mod setting.
Function SetModSettingInt(string a_modName, string a_settingName, int a_value) native global
Function SetModSettingBool(string a_modName, string a_settingName, bool a_value) native global
Function SetModSettingFloat(string a_modName, string a_settingName, float a_value) native global
Function SetModSettingString(string a_modName, string a_settingName, string a_value) native global

Global Values

Settings can be stored as floats via the existing GlobalValue system. If a setting type is specified as a GlobalValue in the menu's JSON descriptor, the value of the setting is retrieved from the specified GlobalValue form from the game. Value changes in the menu will update the GlobalValue accordingly.

GlobalValues are stored internally as floats. They can also be used for integers and boolean values, but modders should note that large integers stored in floats will suffer from precision loss.

GlobalValues are recommended if the setting should be saved with the savegame/character or is not suitable for storage outside the savegame.

Example

{
  "text": "Game Hour",
  "type": "slider",
  "help": "This slider controls the current time of day. Range: 0-23",
  "valueOptions": {
    "min": 0,
    "max": 23,
    "step": 1,
    "sourceType": "GlobalValue",
    "sourceForm": "Skyrim.esm|38",
    "defaultValue": 12             // Optional. This value will be selected when resetting to default.
  }
}