Adding new Settings

Version 0.8.4 contained a heavy rework of the Settings menu. The new menu supports multiple pages of settings, and allows modders to add new pages at will thanks to the AddMenu service callback. Please refer to the Editing Menus#Prerequisites section to know how to interact with menus using this callback.

The label we need is literally just "SETTINGS_MENU". Keep in mind that this is the label of the settings menu TITLE window. The actual settings pages have no label, and are supposed to be populated indirectly thanks to the functions described in this page.

Despite the menu being technically an InteractableMenu, using any function described in the Editing Menus page is highly discouraged, with the ILabeled functions being the only exception.

Feel free to visit the Settings Menu Reference page for a more in-depth explanation of all of the functions and values provided by the settings engine specifically.

Making a new settings page

That said, adding new settings is very simple. Call SettingsTitleMenu:NewPage, and then register new settings with SettingsPage:AddSetting, like this:

if menu:HasLabel() and menu.Label == labels.SETTINGS_MENU and menu.InGame then
    local page = menu:AddPage("my_namespace", "My Mod")

    local options = {"Off", 1, 2, 3, 4, 5}
    local saveFunction = function(setting) SV.MySetting = setting.CurrentChoice end
    local choiceChangedFunction = function(setting) PrintInfo("MySetting preview: "..setting.CurrentChoice) end
    page:AddSetting("My Setting", options, SV.MySetting or 0, saveFunction, choiceChangedFunction)

    page.GlobalSaveAction = function() PrintInfo("SV.MySetting has been set to "..SV.MySetting) end
end

Of course, the code has something more going on, so let's check that out in more detail: The first thing we need to do is, of course, to make sure that we're editing the right menu. Then we check if we're in game or not. Making a setting work from the Top Menu requires a bit more work than what is shown here, so we're going avoid that entirely for now.

The first step now is to create a SettingsPage and store it in a variable. Then we prepare the structures we need for our setting: a list of options and a function that saves our settings when the player presses the confirm button. Since this is a demonstration, we will also include a function that runs every time the setting's value change, even though it is both optional and not necessary here.

Finally, we create our settings, giving it also a display name and using its previous value (or, in this case, 0 if there wasn't one yet) as the starting choice for the setting. This default value is a 0-based index, so, for this setting, valid values go from 0 to 5.

Finally, the last line registers a special function that is ran at the end of every other save actions in the page when the player confirms their changes. This is also optional, and it's included here simply for demonstration.

Notice how the saveFunction and the choiceChangedFunction both accept an argument. This is because the engine always passes the MenuSetting in question to our function. In almost all cases, all we are interested in doing is store its CurrentChoice value somewhere in our code, but it IS technically possible to tamper with any of the object's public properties and fields.

Top Menu settings

WIP