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 settings menu's label is literally just "SETTINGS_MENU". Keep in mind that this retrieves the label of the settings menu's TITLE window. The actual settings pages have no label, and are supposed to be populated using 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 sole exception of the ILabeled functions.

That said, adding new settings is very simple: just call SettingsTitleMenu:NewPage and then register new settings with SettingsPage:AddSetting.

SettingsTitleMenu

This is the menu included in the AddMenu callback as argument.

SettingsTitleMenu:HasPage(System.String)

Returns true if a SettingsPage is already associated with the provided key, false otherwise.

Arguments

• key the unique id key to test for.

SettingsTitleMenu:AddPage(System.String, System.String)

Creates and returns a new SettingsPage object, assigning it to a key and giving it a title. Using a key that already exixts results in an error. It is recommended to always use a mod's namespace as either the prefix of a page's key or the key itself. This will minimize conflicts and ensure that multiple pages for the same mod stay as close together as possible. Good examples are: my_namespace, my_namespace_general, my_namespace_qol.

Arguments

• key the unique id key of the newly created page.
• title the localized display title of the page.

SettingsPage

This object is what gets returned by SettingsTitleMenu:AddPage. This is the object that actually allows the user to add new settings to the game.

SettingsPage.GlobalSaveAction

This property is an Action; a function that takes no parameters and returns nothing. If set, it is called after all of the settings' SaveActions have been ran. PMDO uses this in its original page to bring the player back to the top menu if the language setting has been edited.

SettingsPage.AddSetting(System.String, NLua.LuaTable, System.Int32, System.Action<RogueEssence.Menu.MenuSetting>, System.Action<RogueEssence.Menu.MenuSetting>)

This function registers a new setting, giving it a name, a list of state, a starting position and some special callbacks.

Arguments

• name the localized display name of the setting.
• options a table containing a list of strings. Each string is one of the possible displayed values of the setting.
• defaultValue the option this setting will show as its starting value. It must be a number between 0 and #options-1.
• action the function that will be called when the player presses the confirm button. It will have its corresponding MenuSetting passed to it, so that you can access its CurrentChoice parameter and use it to actually update whatever value this setting represents.
• settingChangedAction the function that will be called whenever the player changes the value of this specific setting. Useful to display changes immediately. PMDO uses this in its original page to temporarily change the window borders without actually saving the setting. It will have its corresponding MenuSetting passed to it, so that you can access its CurrentChoice parameter and use it to actually update whatever temporary value this setting is tied to. Defaults to nil.