Mod Loader/Reference/Settings API
Players can change your plugin's options from the game's Mod Settings menu. The loader provides toggles, sliders, and buttons. Your plugin decides what each option does. This API is available in Mod Loader 0.6.43 and later.
Make a settings tab
First create your BepInEx config entries, then pass them to ModSettingsApi.Register on Unity's main thread. The first argument is a stable ID for your tab; the second is the name players see. Keep the returned tab so you can remove it when your plugin unloads.
using System;
using BepInEx;
using BepInEx.Configuration;
using DressmakerMods;
[BepInPlugin("example.settings", "Settings Example", "1.0.0")]
[BepInDependency("yuu.dressmaker.mods", "0.6.43")]
public sealed class SettingsExample : BaseUnityPlugin
{
private ConfigEntry<bool> logChanges;
private ConfigEntry<float> spacing;
private ModSettingsTab tab;
private void Awake()
{
logChanges = Config.Bind("General", "LogChanges", true);
spacing = Config.Bind("General", "SpacingCm", 2f);
spacing.SettingChanged += OnSpacingChanged;
tab = ModSettingsApi.Register("example.settings", "Spacing example",
new ModToggleSetting("Log changes", "Write spacing changes to the game log.", logChanges),
new ModSliderSetting("Spacing", "A sample spacing value in centimetres.",
spacing, 0.5f, 10f, suffix: " cm"),
new ModActionSetting("Show spacing", "Read the current value.", ShowSpacing));
}
private string ShowSpacing() => $"Spacing: {spacing.Value:0.0} cm";
private void OnSpacingChanged(object sender, EventArgs e)
{
if (logChanges.Value) Logger.LogInfo(ShowSpacing());
}
private void OnDestroy()
{
if (spacing != null) spacing.SettingChanged -= OnSpacingChanged;
tab?.Dispose();
}
}
Open Mod Settings > Spacing example. Move the slider, then press Apply beside Show spacing: the button reports the number you selected. With Log changes enabled, moving the slider also writes the value to BepInEx/LogOutput.log. This sample stores a spacing value; it does not move accessories. To use that value for placement, add a rule through the Accessory Placement API.
Choose a control
| Control | Use it for | Example |
|---|---|---|
| Toggle | An on/off option stored as ConfigEntry<bool>.
|
new ModToggleSetting("Log changes", "Write changes to the log.", logChanges)
|
| Slider | A number stored as ConfigEntry<float>. Give it a minimum and maximum.
|
new ModSliderSetting("Spacing", "Spacing in cm.", spacing, 0.5f, 10f)
|
| Action | A button that runs a Func<string> when clicked.
|
new ModActionSetting("Show spacing", "Read the current value.", ShowSpacing)
|
Each control has a short title and a description shown to the player. A slider can also use wholeNumbers: true for steps of one, or suffix: "%" to show units. The minimum and maximum must be finite numbers, and the maximum must be larger. Long lists scroll within the settings window.
Use an existing tab
If your settings belong in one of the loader's tabs, use the matching method below. Your mod's name appears as a heading below the built-in controls. Players can scroll down to reach it.
| Tab | Method |
|---|---|
| Gameplay | ModSettingsApi.RegisterInGameplay
|
| Accessories | ModSettingsApi.RegisterInAccessories
|
| Appearance | ModSettingsApi.RegisterInAppearance
|
| Recovery | ModSettingsApi.RegisterInRecovery
|
| Keybinds | ModSettingsApi.RegisterInKeybinds
|
| Graphics | ModSettingsApi.RegisterInGraphics
|
For example, to put the spacing controls from the example above in Accessories, replace its registration with:
tab = ModSettingsApi.RegisterInAccessories("example.settings", "Spacing example",
new ModToggleSetting("Log changes", "Write spacing changes to the game log.", logChanges),
new ModSliderSetting("Spacing", "Spacing in centimetres.", spacing, 0.5f, 10f, suffix: " cm"),
new ModActionSetting("Show spacing", "Read the current value.", ShowSpacing));
Open Mod Settings > Accessories and scroll to Spacing example. The controls work the same way as they do in a separate tab. Keep the OnDestroy method from the example: disposing tab removes the section.
All six methods take the same arguments as Register. Give each section its own ID, even when sections are in different tabs. To split a mod's settings between Gameplay and Appearance, for example, register two sections and keep both handles.
RegisterInKeybinds adds ordinary settings below the shortcut list in both the Game controls and Mod shortcuts views. To add an actual rebindable shortcut, use the Keybind API.
These methods are available in Mod Loader 0.6.107 and later; RegisterInAccessories is also available in 0.6.106. Set your plugin's dependency to [BepInDependency("yuu.dressmaker.mods", "0.6.107")] when using the new methods.
Apply changes while the game is running
Config.Bind stores the toggle and slider in your plugin's BepInEx config file. Read spacing.Value wherever your code needs the current value. If a change must trigger work immediately, use SettingChanged, as the full example does above. It subscribes once in Awake and unsubscribes in OnDestroy. Action buttons call your function and display its returned message; they do not store a setting.
C# signatures
ModSettingsTab ModSettingsApi.Register(string id, string title, params ModSetting[] settings)
ModSettingsTab ModSettingsApi.RegisterInGameplay(string id, string title, params ModSetting[] settings)
ModSettingsTab ModSettingsApi.RegisterInAccessories(string id, string title, params ModSetting[] settings)
ModSettingsTab ModSettingsApi.RegisterInAppearance(string id, string title, params ModSetting[] settings)
ModSettingsTab ModSettingsApi.RegisterInRecovery(string id, string title, params ModSetting[] settings)
ModSettingsTab ModSettingsApi.RegisterInKeybinds(string id, string title, params ModSetting[] settings)
ModSettingsTab ModSettingsApi.RegisterInGraphics(string id, string title, params ModSetting[] settings)
ModToggleSetting(string title, string description, ConfigEntry<bool> entry)
ModSliderSetting(string title, string description, ConfigEntry<float> entry,
float minimum, float maximum, bool wholeNumbers = false, string suffix = "")
ModActionSetting(string title, string description, Func<string> action)
All registration methods reject an empty ID or title, a duplicate ID, and an empty or invalid settings list. Use an ID based on your plugin's ID so it stays unique. Dispose the returned ModSettingsTab when the plugin unloads.
Shared accessibility settings
AccessibilitySettings exposes the loader's existing config entries so another plugin can read or reuse them:
AccessibilitySettings.StillSewingGuides AccessibilitySettings.SoftSewingGuideColors AccessibilitySettings.StillCuttingArrow AccessibilitySettings.StillPatternWarnings AccessibilitySettings.SewingView
Brightness and Saturation remain in the API for compatibility, but are obsolete and unused.