Tutorial:Adding New Settings - Revision history

Imbion: Imbion moved page Tutorial:Adding new Settings to Tutorial:Adding New Settings: These Lack Of Caps Are Pissing Me Off starwalker

2025-10-26T15:13:01Z

Imbion moved page Tutorial:Adding new Settings to Tutorial:Adding New Settings: These Lack Of Caps Are Pissing Me Off starwalker

← Older revision	Revision as of 15:13, 26 October 2025
(No difference)

Imbion: Imbion moved page Adding new Settings to Tutorial:Adding new Settings

2025-10-26T15:12:29Z

Imbion moved page Adding new Settings to Tutorial:Adding new Settings

← Older revision	Revision as of 15:12, 26 October 2025
(No difference)

MistressNebula: Fix links that were still broken

2025-08-31T09:26:45Z

Fix links that were still broken

← Older revision		Revision as of 09:26, 31 August 2025
Line 1:		Line 1:
	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 [[Service ~~Callbacks~~#AddMenu\|AddMenu]] service callback. Please refer to the [[Editing Menus#Prerequisites]] section to know how to interact with menus using this callback.		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 [[Service Events#EngineServiceEvents.AddMenu\|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 <code>"SETTINGS_MENU"</code>. Keep in mind that this is the label of the settings menu TITLE window. The actual settings pages are supposed to be populated indirectly by using the functions described in this page.		The label we need is literally just <code>"SETTINGS_MENU"</code>. Keep in mind that this is the label of the settings menu TITLE window. The actual settings pages are supposed to be populated indirectly by using the functions described in this page.
Line 63:		Line 63:

	And that's it!</br>		And that's it!</br>
	Except, it's not. We need to load our temporary table in the SV structure if we want to ACTUALLY save our setting. For that, we will need another service callback: [[Service ~~Callbacks~~#LoadSavedData\|LoadSavedData]].		Except, it's not. We need to load our temporary table in the SV structure if we want to ACTUALLY save our setting. For that, we will need another service callback: [[Service Events#EngineServiceEvents.LoadSavedData\|LoadSavedData]].

	This is all we need to finish the job. Once subscribed to the callback, the function below will be called as soon as the Continue button is pressed on the Top Menu, finally storing our setting inside the SV structure.		This is all we need to finish the job. Once subscribed to the callback, the function below will be called as soon as the Continue button is pressed on the Top Menu, finally storing our setting inside the SV structure.

Imbion at 17:34, 13 August 2025

2025-08-13T17:34:46Z

← Older revision		Revision as of 17:34, 13 August 2025
Line 74:		Line 74:
	end		end
	</pre>		</pre>
			[[Category:Modding]]

MistressNebula: Account for settings pages now actually having a label

2025-03-13T12:35:29Z

Account for settings pages now actually having a label

← Older revision		Revision as of 12:35, 13 March 2025
Line 1:		Line 1:
	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 [[Service Callbacks#AddMenu\|AddMenu]] service callback. Please refer to the [[Editing Menus#Prerequisites]] section to know how to interact with menus using this callback.		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 [[Service Callbacks#AddMenu\|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 <code>"SETTINGS_MENU"</code>. 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.		The label we need is literally just <code>"SETTINGS_MENU"</code>. Keep in mind that this is the label of the settings menu TITLE window. The actual settings pages are supposed to be populated indirectly by 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 ILabeled functions being the only exception.		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.

MistressNebula: Fix code oversight

2025-03-13T12:29:40Z

Fix code oversight

← Older revision		Revision as of 12:29, 13 March 2025
Line 28:		Line 28:
	The first step now is to create a [[Settings Menu Reference#SettingsPage\|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.		The first step now is to create a [[Settings Menu Reference#SettingsPage\|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 a default value 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.		It is now time to create our setting, giving it also a display name and using its previous value (or a default value if there wasn't one yet) as the starting choice for the setting. This default value is a 0-based index into the list of options, 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.		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.
Line 42:		Line 42:
	if menu:HasLabel() and menu.Label == labels.SETTINGS_MENU then		if menu:HasLabel() and menu.Label == labels.SETTINGS_MENU then
	local page = menu:AddPage("my_namespace", "My Mod")		local page = menu:AddPage("my_namespace", "My Mod")
			if not MY_SETTINGS then
	MY_SETTINGS = {		MY_SETTINGS = {
	Setting = SV.MySetting or 0		Setting = SV.MySetting or 0
	}		}
			end
	local options = {"Off", 1, 2, 3, 4, 5}		local options = {"Off", 1, 2, 3, 4, 5}
	local saveFunction = function(setting)		local saveFunction = function(setting)
Line 58:		Line 59:
	</pre>		</pre>

	The first noticeable difference is that the initial check does not care about us being in game or not anymore. We are then creating a new global table called MY_SETTINGS and loading the current state of the setting inside of it (or a default value if it doesn't exist yet).		The first noticeable difference is that the initial check does not care about us being in game or not anymore. We are then creating a new global table called MY_SETTINGS and loading the current state of the setting inside of it (or a default value if it doesn't exist yet). Of course, we also check if MY_SETTINGS already exists, because we don't want to reset the player's choices if they already opened the menu once.
	The save function has also changed to account for the two cases of being inside the game or in the top menu. We save our data directly in the SV structure if we're in game, and save in the MY_SETTINGS table if we're not.		The save function has also changed to account for the two cases of being inside the game or in the top menu. We save our data directly in the SV structure if we're in game, and save in the MY_SETTINGS table if we're not.

MistressNebula: Example 2

2024-08-27T13:51:06Z

Example 2

@@ Line 8: / Line 8: @@
 == Making a new settings page ==
-That said, adding new settings is very simple. Call <code>SettingsTitleMenu:NewPage</code>, and then register new settings with <code>SettingsPage:AddSetting</code>, like this:
+With all that said, adding new settings is very simple. Call <code>SettingsTitleMenu:NewPage</code>, and then register new settings with <code>SettingsPage:AddSetting</code>, like this:
 <pre>
@@ Line 23: / Line 23: @@
 </pre>
-Of course, the code has something more going on, so let's check that out in more detail:
+Of course, the code has something more going on, so let's check it 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 thing we need to do is, as usual, 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 [[Settings Menu Reference#SettingsPage|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, we create our settings, giving it also a display name and using its previous value (or a default value 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.
@@ Line 35: / Line 35: @@
 == Top Menu settings ==
-WIP
+As stated previously, making a setting work from the Top Menu requires a bit more work. The SV structure is already loaded when a player reaches the Top Menu, but it is also loaded again as soon as the Continue button is pressed, so any changes made to it in this state will be completely lost.

MistressNebula: Remove references, add example

2024-08-27T10:29:50Z

Remove references, add example

← Older revision		Revision as of 10:29, 27 August 2024
Line 1:		Line 1:
	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 [[Service Callbacks#AddMenu\|AddMenu]] service callback. Please refer to the [[Editing Menus#Prerequisites]] section to know how to interact with menus using this callback.		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 [[Service Callbacks#AddMenu\|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 <code>"SETTINGS_MENU"</code>. 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.		The label we need is literally just <code>"SETTINGS_MENU"</code>. 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 sole exception of~~ the ILabeled functions.		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.

	~~That said, adding new settings is very simple: just call <code>SettingsTitleMenu:NewPage</code>~~ and ~~then register new~~ settings ~~with <code>SettingsPage:AddSetting</code>~~.		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.

	~~{\|limit~~=2		== Making a new settings page ==
	~~\|__TOC__~~		That said, adding new settings is very simple. Call <code>SettingsTitleMenu:NewPage</code>, and then register new settings with <code>SettingsPage:AddSetting</code>, like this:
	\|}

	== ~~SettingsTitleMenu~~ ==		<pre>
	~~This is the~~ menu ~~included in the AddMenu callback as argument.~~		if menu:HasLabel() and menu.Label == labels.SETTINGS_MENU and menu.InGame then
			local page = menu:AddPage("my_namespace", "My Mod")

	=== ~~SettingsTitleMenu~~:~~HasPage(System~~.~~String~~) ~~===~~		local options = {"Off", 1, 2, 3, 4, 5}
	~~Returns <code>true</code> if a SettingsPage is already associated with the provided key~~, ~~<code>false</code> otherwise~~.		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)

	=~~===Arguments====~~		page.GlobalSaveAction = function() PrintInfo("SV.MySetting has been set to "..SV.MySetting) end
	* <code>key</~~code~~> ~~the unique id key to test for.~~		end
			</pre>

			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 [[Settings Menu Reference#SettingsPage\|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.

	~~=== SettingsTitleMenu:AddPage(System.String~~, ~~System.String) ===~~		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.
	~~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: <code>my_namespace</code>~~, ~~<code>my_namespace_general</code>, <code>my_namespace_qol</code>~~.

	~~====Arguments====~~		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.
	* <code>key</code> the ~~unique id key~~ of the ~~newly created~~ page.
	* <code>title</code> the localized display title of the page.

			Notice how the saveFunction and the choiceChangedFunction both accept an argument. This is because the engine always passes the [https://github.com/RogueCollab/RogueEssence/tree/master/RogueEssence/Menu/MenuElements/MenuSetting.cs MenuSetting] in question to our function. In almost all cases, all we are interested in doing is store its <code> CurrentChoice</code> value somewhere in our code, but it IS technically possible to tamper with any of the object's <code>public</code> properties and fields.

			== Top Menu settings ==
	== ~~SettingsPage ==~~		WIP
	~~This object is what gets returned by <code>SettingsTitleMenu:AddPage</code>. 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 ====~~
	* <code>name</code> the localized display name of the setting.
	* <code>options</code> a table containing a list of strings. Each string is one of the possible displayed values of the setting.
	* <code>defaultValue</code> the option this setting will show as its starting value. It must be a number between 0 and <code>#options-1</code>.
	* <code>action</code> the function that will be called when the player presses the confirm button. It will have its corresponding [https://github.com/RogueCollab/RogueEssence/blob/master/RogueEssence/Menu/MenuElements/MenuSetting.cs MenuSetting] passed to it, so that you can access its CurrentChoice parameter and use it to actually update whatever value this setting represents.
	* <code>settingChangedAction</code> 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 <code>nil</code>.

MistressNebula: Added TOC limit + small introduction changes

2024-08-25T15:36:11Z

Added TOC limit + small introduction changes

← Older revision		Revision as of 15:36, 25 August 2024
Line 1:		Line 1:
	Version 0.8.4 contained a heavy rework of the Settings menu. The new menu ~~now~~ supports multiple pages of settings, and allows modders to add new pages at will thanks to the [[Service Callbacks#AddMenu\|AddMenu]] service callback. Please refer to the [[Editing Menus#Prerequisites]] section to know how to interact with menus using this callback.		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 [[Service Callbacks#AddMenu\|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 <code>"SETTINGS_MENU"</code>. 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 by using the functions described in this page.		The settings menu's label is literally just <code>"SETTINGS_MENU"</code>. 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.		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 <code>SettingsTitleMenu:NewPage</code> and then register new settings with <code>SettingsPage:AddSetting</code>.

			{\|limit=2
			\|__TOC__
			\|}

	== SettingsTitleMenu ==		== SettingsTitleMenu ==

MistressNebula: Fully written page

2024-08-25T14:23:05Z

Fully written page

New page

Version 0.8.4 contained a heavy rework of the Settings menu. The new menu now supports multiple pages of settings, and allows modders to add new pages at will thanks to the [[Service Callbacks#AddMenu|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 <code>"SETTINGS_MENU"</code>. 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 by 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.

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

=== SettingsTitleMenu:HasPage(System.String) ===
Returns <code>true</code> if a SettingsPage is already associated with the provided key, <code>false</code> otherwise.

====Arguments====
* <code>key</code> 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: <code>my_namespace</code>, <code>my_namespace_general</code>, <code>my_namespace_qol</code>.

====Arguments====
* <code>key</code> the unique id key of the newly created page.
* <code>title</code> the localized display title of the page.

== SettingsPage ==
This object is what gets returned by <code>SettingsTitleMenu:AddPage</code>. 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 ====
* <code>name</code> the localized display name of the setting.
* <code>options</code> a table containing a list of strings. Each string is one of the possible displayed values of the setting.
* <code>defaultValue</code> the option this setting will show as its starting value. It must be a number between 0 and <code>#options-1</code>.
* <code>action</code> the function that will be called when the player presses the confirm button. It will have its corresponding [https://github.com/RogueCollab/RogueEssence/blob/master/RogueEssence/Menu/MenuElements/MenuSetting.cs MenuSetting] passed to it, so that you can access its CurrentChoice parameter and use it to actually update whatever value this setting represents.
* <code>settingChangedAction</code> 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 <code>nil</code>.