Subscribe to download
[v41] Mod Config Menu

Howdy y'all.

This mod was born out of frustrations with the limitations of Mod Options. Instead of waiting for it to be eventually updated to include features I needed, I've built a new mod configuration manager from scratch instead. They can be used alongside each other, they shouldn't be conflicting, however to use MCM a different setup is required from modders.

The v42 version of this mod can be found here: https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=3386620985


A very basic structure of a MCM implementation could look like this:


This piece of code will result in this:



Allow me now to elaborate in detail what each bit does. First we check, if MCM is even installed at all:


If it isn't, the rest of the MCM code will simply not run, but your mod can still function properly, it will just not be configurable and have all variables retain the value that you originally set them to.

However if MCM is present, then the next step is creating an Option Table for your mod:


Let's go over the individual arguments.

"Mod_id" is the unique identifier that MCM uses to keep track of your mod and the data it keeps saved for you. You only have to make sure that you pick an identifier that's unique and won't conflict with any other mod. Changing the identifier will make MCM "forget" about any data it might have saved about your mod.

"DisplayStr" is the string that will be displayed at the very top of your options section.

If "bExtraTab" is set to "true", then your mod will get its very own tab in the option screen, instead of sharing one page with other mods. This makes sense for large mods with overwhelmingly many options, but otherwise you should keep it to "false"


We are now getting into the interesting part. "AddModOption" is the function that describes a UI element that can be used to drive the value of a variable.

"Option_id" is another identifier that should be unique, however it only needs to be unique within your own mod.

"Option_type" determines what type of UI element this option will be, there are several to choose from for different purposes, we will get into them later.

"DefaultValue" sets the initial value of your option, it's most convenient to just place the variable here that you wish to have MCM manipulate, and place your default value there instead.

"OptionData" provides additional data to drive behavior of your UI element. It's highly dependent on what UI type you have chosen, some don't require any OptionData at all, in which case you can leave this argument as "nil". We will cover the rest later.

"DisplayStr" is the name of the option that users are going to see on their screen.

"TooltipStr" will have its contents displayed when the user hovers over your option with the mouse.

"CommitValueFunc" is the function that will be called, when your option has been manipulated by the user. You can use it to directly assign the value that MCM returns to your variable.

And that's pretty much it. The basic process for creating each option involves the same function, until you have everything you need.


"text" - A text box that you can enter any strings into.
Value Type: String
OptionData: nil

"number" - A text box that only takes numeric values
Value Type: Number
OptionData: Table with following structure
{
(optional) min = [Lower bound of acceptable values]
(optional) max = [Upper bound of acceptable values]
(optional) step = [Number that all entered numbers must be divisible by, they will be rounded if need be. Set to 1 to only allow integers]
}

"number_slider" - A slider that can be dragged with the mouse to produce numeric values
Value Type: Number
OptionData: same as "number" but all fields are mandatory to define

"checkbox" - A single checkbox that can be either ticked or unticked
Value Type: Boolean
OptionData: nil

"checkbox_multi" - An array of checkboxes, each with their own value
Value Type: Table of Boolean values, corresponding to one tickbox each
OptionData: Table with Strings, containing the labels for each individual tick box

"color" - A color picker
Value Type: Table with following structure
{
(mandatory) r = [Number from 0 to 1]
(mandatory) g = [Number from 0 to 1]
(mandatory) b = [Number from 0 to 1]
}
OptionData: nil

"combobox" - A dropdown menu offering a finite amount of choices
Value Type: Number (to use as an index in your own code)
OptionData: Table with Strings, containing the labels for each individual dropbox entry

"keybind" - A special option, that doesn't return a value when set in the options menu, but invokes the function in "CommitValueFunc" when the user presses the associated key.
DefaultValue: Key code to bind action to initially.
OptionData: nil
CommitValueFunc: Function to run when key is pressed.

AddModOptionTable is a syntactic alternative to AddModOption, that takes a table instead of loose arguments:


Using this is identical in effect to AddModOption, it's simply a different way of conveying the same information to MCM, which may be more convenient in some cases.

MCM can also allow modders to add additional options to Sandbox. It works similarly to normal mod options, but is more restricted at the moment. I will provide short documentation for it later.

If you still want something clarified, feel free to give me a shout. I also included a working example mod, that implements the various different option types. Feel free to copy implementations from there or use them as a reference.



If you want to help improve MCM, whether that is by fixing bugs, extending functionality or making the UI prettier to look at, you can contribute and submit pull requests on github:

https://github.com/MerelyMezz/PZModConfigMenu

I don't have any particular guidelines for contributing yet, but I reserve the right to reject PRs if I have gripes with them.

Workshop ID: 2815552312
Mod ID: MCM_ExampleMod
Mod ID: ModConfigMenu