Introduction

Mod settings allow users to customize their experience and tailor the mod to their preferences. In this guide, we'll explore how to declare and utilize various types of mod settings for your mod.

Initializing Mod Settings

Before declaring any settings, it's crucial to instantiate the settings using the InstantiateSettings method. Ensure this is done at the beginning of your SettingsDeclaration method:

public override void SettingsDeclaration()
{
    base.SettingsDeclaration();
    InstantiateSettings();
}

Adding Different Types of Settings

Toggle

Toggle settings are for enabling or disabling a feature. Here's an example:

AddToggle("ID", "name", defaultValue);

Slider

Slider settings allow users to choose a value within a specified range. Example:

AddSlider("ID", "name", minValue, maxValue, defaultValue, wholeNumbers);

Dropdown

Dropdown settings provide a selection of predefined options. Example:

values[0] = "Value 1";
values[1] = "Value 2";
values[2] = "Value 3";
AddDropdown("ID", "name", values[], defaultValue);

Keybind

Keybind settings let users assign a keyboard key or combination to a function. Examples:

AddKeybind("ID", "name", defaultPrimaryKey, defaultSecondaryKey); // there is also a version without secondary keys

Input fields

Input fields let users write anything in a small box, which can later be read from the mod. Example:

AddInput("ID", "name", defaultValue, placeholderText);

Customizing Settings UI

You can add headers to group related settings:

AddHeader("text");

A smaller header, called a disclaimer, is also available:

AddDisclaimer("text");

This improves the organization and clarity of your mod settings.

Settings-related methods

OnSettingsSaved()

This method is ran every time the settings are saved.

OnSettingsReset()

This method is ran every time the settings are reset.

OnSettingsLoaded()

This method is ran every time the settings are loaded.

OnSettingValueChanged("ID")

This method is ran every time a setting value is changed (and saved). To check for a specific setting, use:

if(ID == "ExampleSettingID")
{
     // do stuff 
}

Retrieving Setting Values

After users have configured settings, you can retrieve their values using the following functions:

Dropdown Value:

int dropdownValue = GetDropdownValue("ID");

Toggle Value:

bool toggleValue = GetToggleValue("ID");

Slider Value:

float sliderValue = GetSliderValue("ID");

Primary Keybind:

KeyCode primaryKeybind = GetPrimaryKeybind("ID");

Secondary Keybind:

KeyCode secondaryKeybind = GetSecondaryKeybind("ID");

Input fields:

string value = GetInputFieldValue("ID");

These functions retrieve the current values of the respective settings, allowing you to adapt your mod's behavior based on user preferences.