Mods:Settings

Mods can have settings.

To start adding settings to your mod, you need a settings folder in your mod.

The settings folder must be in the mod's root.

JECS side

To use your settings, you must first define them in JECS.

Language

Just like components, you can define the actual names for your settings in a language file in your mod's languages folder.

The file name for the language file doesn't matter.

There are currently 6 pages of settings in the game. They are:

• MHG.SettingsMenu.Pages.Audio
• MHG.SettingsMenu.Pages.Controls
• MHG.SettingsMenu.Pages.Gameplay
• MHG.SettingsMenu.Pages.Graphics
• MHG.SettingsMenu.Pages.Multiplayer
• MHG.SettingsMenu.Pages.UserInterface

To define a name for a mod's heading, use whatever page you think fits best for your settings, and do this:

MHG.SettingsMenu.Pages.Gameplay.Headings.<your heading name>: "your heading name or whatever"

You can then use that in a settingsdata file.

You can have as many as you desire.

To define a name for a setting in your mod, do something like this:

Author.YourMod.YourSettingName: "Setting name"

The game will use that to give your setting in settingsdata a proper name.

Settings can also have descriptions.

Author.YourMod.YourSettingName.Description: """
    A nice description for your setting.
    """

settingsdata

For some reason, the game only loads files in your settings folder that contain "settingsdata" in their name.

That means your file MUST contain "settingsdata" somewhere in its filename, e.g.: MyEpicSettings_settingsdata.jecs or settingsdata.jecs or asdasdasdsettingsdataasdas.jecs.

to ACTUALLY start using settings, you must define them in a settingsdatafile.

Every setting MUST be at minimum like this:

Author.YourMod.YourSettingName:
    Page: Gameplay
    Heading: <your heading name>

or else the game won't show it into the settings menu.

Settings can have these two optional keys:

• PreviewText
• PerformanceImpact

PreviewText

• Hide (default)
• On_Off
• Lower_Higher

PerformanceImpact

• Hide (default)
• Negligible
• Low
• Medium
• High
• Extreme
• Insane

You can also use numbers 0-6 for the PerformanceImpact

Settings can also have specific keys depending on what they are supposed to be.

Float and Int sliders expect these keys:

• Min
• Max
• SliderInterval
• DecimalPlacesToDisplay

Textboxes expect this key: CharacterLimit. It is an integer.

some examples for both of these:

Float/Int Sliders

Author.ModName.MyIntSlider:
    Page: Audio
    Heading: <your heading name>
    Min: 10
    Max: 100
    SliderInterval: 5

Textboxes

Author.ModName.MyTextbox:
    Page: Audio
    Heading: <your heading name>
    CharacterLimit: 27

settingsdata Controls

Your settings can be controlled by other settings so you can hide/show certain settings depending on the state of other settings.

For example, you could have a toggle that when on, shows some sliders.

There are 4 types of controls you can use for a setting. They are:

• ToggleControls
• ToggleAntiControls
• DropdownControls
• DropdownAntiControls

To start using controls on your setting, just add the Controls to your setting like this:

Author.ModName.MyTextbox:
    Page: Audio
    Heading: <your heading name>
    CharacterLimit: 27
    Controls:

And then start adding your controls, like this:

Author.ModName.MyTextbox:
    Page: Audio
    Heading: <your heading name>
    CharacterLimit: 27
    Controls:
        ToggleControls:
           - Author.ModName.MyToggle1
        ToggleAntiControls:
           - Author.ModName.MyToggle2
        DropdownControls:
            -
                DropdownTextID: Author.ModName.MyDropdown1
                Option: None
        DropdownAntiControls:
            -
                DropdownTextID: Author.ModName.MyDropdown2
                Option: "hello"

The entry in DropdownAntiControls is for Setting_DropdownDynamic as it uses strings.

The entry in DropdownControls is for Setting_DropdownEnum.

C# side

I recommend assigning your variables when using settings, as not doing so for strings can cause them to be null, which is really bad.

If you end up making this mistake, check settings_profile1.jecs for any keys that are null, delete them, and assign your strings to something like string.Empty.

Your variables also have to be static, or the game won't expose them in the settings menu.

I also suggest putting your mod settings in a dedicated class for settings.

There are 9 types of settings you can use:

• Setting_Secret
• Setting_Toggle
• Setting_SliderInt
• Setting_SliderFloat
• Setting_ColorPicker
• Setting_TextBox
• Setting_TexturePicker
• Setting_DropdownEnum
• Setting_DropdownDynamicColor24 is used for Setting_ColorPicker. It is found in the JimmysUnityUtilities namespace.

The setting attributes are found in the LogicSettings namespace. If you define a setting in your JECS settingsdata file, but don't use it in your code, it won't be shown in the settings menu.

Setting_Secret

This will create a secret setting in settings_master.jecs, which is found in Logic World's root folder, where the game's exe is found.

The variable type can be any normal type, like an int, string, bool, etc.

The string it takes in is the name of the key you will find in settings_master.jecs.

[Setting_Secret("FoxFireFive.SettingsExampleMod.Secret.SecretSettingExample")]
public static int SecretSettingExample { get; set; } = 0;

Setting_Toggle

A simple toggle button

The string it takes in is the name of a key in a settingsdata file.

[Setting_Toggle("FoxFireFive.SettingsExampleMod.ToggleExample")]
public static bool ToggleExample { get; set; } = false;

Setting_SliderInt

A slider that only works on integers. If you try to set its value to 4.5173 in the settings menu, it will round up to 5.

The string it takes in is the name of a key in a settingsdata file.

[Setting_SliderInt("FoxFireFive.SettingsExampleMod.SliderIntExample")]
public static int SliderIntExample { get; set; } = 0;

Setting_SliderFloat

A slider that works on floats.

The string it takes in is the name of a key in a settingsdata file.

[Setting_SliderFloat("FoxFireFive.SettingsExampleMod.SliderFloatExample")]
public static float SliderFloatExample { get; set; } = 0;

Setting_ColorPicker

It lets you pick a color for whatever you decide.

The string it takes in is the name of a key in a settingsdata file.

[Setting_ColorPicker("FoxFireFive.SettingsExampleMod.ColorPickerExample")]
public static Color24 ColorPickerExample { get; set; } = Color24.White;

Setting_TextBox

It lets you type in text that you can use for whatever you decide. Used in the multiplayer menu for setting your offline name.

The string it takes in is the name of a key in a settingsdata file.

If this is null, or not assigned, it will cause problems.

[Setting_TextBox("FoxFireFive.SettingsExampleMod.TextBoxExample")]
public static string TextBoxExample { get; set; } = string.Empty;

Setting_TexturePicker

It lets you pick a texture for whatever you decide.

The first string it takes is the name of a key in a settingsdata file.

The second string it takes is some kind of search pattern. I don't really know what it is. It's used to get settingsdata files like so: settings/*settingsdata*.

[Setting_TexturePicker("FoxFireFive.SettingsExampleMod.TexturePickerExample", "example_textures/*")]
public static string TexturePickerExample { get; set; } = string.Empty;

It sets the string to a value that you can use like this:

Texture2D texture = ModAssetsTextures.GetTexture(TexturePickerExample, new TextureLoadParams(false, true), TextureLoadMode.RequireFullSize);

Setting_DropdownEnum

It's a dropdown of enums.

The first string it takes is the name of a key in a settingsdata file.

The second param is the enum it's going to use.

There are two more params but they are irrelevent, unless someone wants to document them here.

It sets the variable it's on to whatever you select in the settings menu.

public enum MyEnum
{
    None, Hello, World, Lorem, Ipsum, Jimmy, Logic, CSharp
}

[Setting_DropdownEnum("FoxFireFive.SettingsExampleMod.DropdownEnumExample", typeof(MyEnum))]
public static MyEnum DropdownEnumExample { get; set; } = MyEnum.None;

If you don't create a language file for your enums, it will display a really long name that is undesirable. This is talked about in the JECS side of this article.

Setting_DropdownDynamic

Sometimes you need a dropdown with a variable amount of stuff in it. This is what you use.

The first string it takes is the name of a key in a settingsdata file.

The second param is the location of your getDropdownItemsMethod, which in the example mod is Loader.

The third param is the name of your getDropdownItemsMethod, which in the example mod is GetDropdownItems.

The only type I know of that works is string.

[Setting_DropdownDynamic("FoxFireFive.SettingsExampleMod.DropdownDynamicExample", typeof(Loader), "GetDropdownItems")]
public static string DropdownDynamicExample { get; set; } = string.Empty;

public static string[] GetDropdownItems()
{
    return ["hello", "bobby", "inverter", "peanut"];
}

End

Hopefully I didn't forget anything., cause there was a lot.

The example mod for this page: https://github.com/FoxFireFive0135/LW_SettingsExampleMod