View source for Mods:Settings

Mods can have settings.

To start adding settings to your mod, you need a <code>settings</code> 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 <code>languages</code> 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:

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

You can then use that in a <code>settingsdata</code> file.

You can have as many as you desire.


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

<code>Author.YourMod.YourSettingName: "Setting name"</code>

The game will use that to give your setting in <code>settingsdata</code> a proper name.


Settings can also have descriptions.<syntaxhighlight>
Author.YourMod.YourSettingName.Description: """
    A nice description for your setting.
    """
</syntaxhighlight>

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

That means your file MUST contain "settingsdata" somewhere it it's filename, e.g.: <code>MyEpicSettings_settingsdata.jecs</code> or <code>settingsdata.jecs</code> or <code>asdasdasdsettingsdataasdas.jecs</code>.


to ACTUALLY start using settings, you must define them in a <code>settingsdata</code>file.


Every setting MUST be at minimum like this:<syntaxhighlight>
Author.YourMod.YourSettingName:
    Page: Gameplay
    Heading: <your heading name>
</syntaxhighlight>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: <code>CharacterLimit</code>.  It is an integer.


some examples for both of these:

===== Float/Int Sliders =====
<syntaxhighlight>Author.ModName.MyIntSlider:
    Page: Audio
    Heading: <your heading name>
    Min: 10
    Max: 100
    SliderInterval: 5</syntaxhighlight>

===== Textboxes =====
<syntaxhighlight>
Author.ModName.MyTextbox:
    Page: Audio
    Heading: <your heading name>
    CharacterLimit: 27
</syntaxhighlight>

=== 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 <code>Controls</code> to your setting like this:<syntaxhighlight>
Author.ModName.MyTextbox:
    Page: Audio
    Heading: <your heading name>
    CharacterLimit: 27
    Controls:
</syntaxhighlight>And then start adding your controls, like this:<syntaxhighlight>
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"
</syntaxhighlight>The entry in <code>DropdownAntiControls</code> is for <code>Setting_DropdownDynamic</code> as it uses strings.

The entry in <code>DropdownControls</code> is for <code>Setting_DropdownEnum</code>.

== 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 <code>settings_profile1.jecs</code> for any keys that are null, delete them, and assign your strings to something like <code>string.Empty</code>.

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 <code>Setting_ColorPicker</code>. It is found in the <code>JimmysUnityUtilities</code> namespace.

The setting attributes are found in the <code>LogicSettings</code> 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 <code>settings_master.jecs</code>, 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 <code>settings_master.jecs</code>.<syntaxhighlight lang="c#">[Setting_Secret("FoxFireFive.SettingsExampleMod.Secret.SecretSettingExample")]
public static int SecretSettingExample { get; set; } = 0;</syntaxhighlight>

=== Setting_Toggle ===
A simple toggle button

The string it takes in is the name of a key in a <code>settingsdata</code> file.<syntaxhighlight lang="c#">[Setting_Toggle("FoxFireFive.SettingsExampleMod.ToggleExample")]
public static bool ToggleExample { get; set; } = false;</syntaxhighlight>

=== Setting_SliderInt ===
A slider that only works on integers. If you try to set it's 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 <code>settingsdata</code> file.<syntaxhighlight lang="c#">
[Setting_SliderInt("FoxFireFive.SettingsExampleMod.SliderIntExample")]
public static int SliderIntExample { get; set; } = 0;
</syntaxhighlight>

=== Setting_SliderFloat ===
A slider that works on floats.

The string it takes in is the name of a key in a <code>settingsdata</code> file.<syntaxhighlight lang="c#">
[Setting_SliderFloat("FoxFireFive.SettingsExampleMod.SliderFloatExample")]
public static float SliderFloatExample { get; set; } = 0;
</syntaxhighlight>

=== 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 <code>settingsdata</code> file.<syntaxhighlight lang="c#">
[Setting_ColorPicker("FoxFireFive.SettingsExampleMod.ColorPickerExample")]
public static Color24 ColorPickerExample { get; set; } = Color24.White;
</syntaxhighlight>

=== 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 <code>settingsdata</code> file.

If this is null, or not assigned, it will cause problems.<syntaxhighlight lang="c#">
[Setting_TextBox("FoxFireFive.SettingsExampleMod.TextBoxExample")]
public static string TextBoxExample { get; set; } = string.Empty;
</syntaxhighlight>

=== 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 <code>settingsdata</code> 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 <code>settingsdata</code> files like so: <code>settings/*settingsdata*</code>.<syntaxhighlight lang="c#">[Setting_TexturePicker("FoxFireFive.SettingsExampleMod.TexturePickerExample", "example_textures/*")]
public static string TexturePickerExample { get; set; } = string.Empty;</syntaxhighlight>It sets the string to a value that you can use like this:<syntaxhighlight lang="c#">Texture2D texture = ModAssetsTextures.GetTexture(TexturePickerExample, new TextureLoadParams(false, true), TextureLoadMode.RequireFullSize);</syntaxhighlight>

=== Setting_DropdownEnum ===
It's a dropdown of enums.

The first string it takes is the name of a key in a <code>settingsdata</code> 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.<syntaxhighlight lang="c#">
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;
</syntaxhighlight>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 <code>settingsdata</code> file.

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

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

The only type I know of that works is string.<syntaxhighlight lang="c#">
[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"];
}
</syntaxhighlight>

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