Tutorial:Mod settings - Revision history

Bilka: 2.0.66: color-setting forced_value

2025-09-03T17:13:23Z

2.0.66: color-setting forced_value

← Older revision		Revision as of 17:13, 3 September 2025
Line 101:		Line 101:
	* default_value - [https://lua-api.factorio.com/latest/types/Color.html Color] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/Color.html Color] - Mandatory.
	** Defines the default value of the setting.		** Defines the default value of the setting.
			* forced_value - [https://lua-api.factorio.com/latest/types/Color.html Color] - Optional.
			** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value.

	=== The order property ===		=== The order property ===

Bilka: and the rest of the links too

2025-07-07T14:11:50Z

and the rest of the links too

← Older revision		Revision as of 14:11, 7 July 2025
Line 7:		Line 7:
	== Location ==		== Location ==

	Mod settings are defined in the [https://lua-api.factorio.com/latest/~~Data~~-~~Lifecycle~~.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:		Mod settings are defined in the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
	* settings.lua		* settings.lua
	* settings-updates.lua		* settings-updates.lua
	* settings-final-fixes.lua		* settings-final-fixes.lua

	First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order\|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod <sup>(in the same order)</sup> and finally the settings-final-fixes.lua file is called for each mod <sup>(in the same order)</sup>. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [~~http~~://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.		First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order\|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod <sup>(in the same order)</sup> and finally the settings-final-fixes.lua file is called for each mod <sup>(in the same order)</sup>. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [https://lua-api.factorio.com/latest/classes/LuaRemote.html remote interface] available.

	The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory\|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.		The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory\|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.
Line 146:		Line 146:
	== Usage ==		== Usage ==
	=== Reading settings ===		=== Reading settings ===
	When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [~~http~~://lua-api.factorio.com/latest/~~Concepts~~.html~~#ModSetting~~ ModSetting concept].		When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [https://lua-api.factorio.com/latest/concepts/ModSetting.html ModSetting concept].

	In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:		In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
Line 207:		Line 207:

	=== Writing to your own settings ===		=== Writing to your own settings ===
	It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/~~Concepts~~.html~~#ModSetting~~ ModSetting] table to the setting.		It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/concepts/ModSetting.html ModSetting] table to the setting.

	Example:		Example:
Line 256:		Line 256:
	* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]		* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
	* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]		* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
	* [~~http~~://lua-api.factorio.com/latest/LuaSettings.html Lua ~~api~~ documentation on the settings table]		* [https://lua-api.factorio.com/latest/classes/LuaSettings.html Lua API documentation on the settings table]

	[[Category:Modding]]		[[Category:Modding]]

Bilka: fixed runtime docs links

2025-07-07T14:10:04Z

fixed runtime docs links

← Older revision		Revision as of 14:10, 7 July 2025
Line 167:		Line 167:
	<div class="plainlinks">		<div class="plainlinks">
	In the control stage, "runtime-global" and "runtime-per-user" are additonally available. They can be accessed as follows:		In the control stage, "runtime-global" and "runtime-per-user" are additonally available. They can be accessed as follows:
	* "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]).		* "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/classes/LuaSettings.html LuaSettings]).
	* "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/~~Concepts~~.html~~#PlayerIdentification~~ <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/~~Concepts~~.html~~#PlayerIdentification~~ <PlayerIdentification>]].mod_settings["setting-name"]</code>.		* "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/concepts/PlayerIdentification.html <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/concepts/PlayerIdentification.html <PlayerIdentification>]].mod_settings["setting-name"]</code>.
	</div>		</div>
	Example:		Example:

PennyJim: /* The type property */ Went to kindergarten to learn to count :P

2025-07-06T19:59:31Z

The type property: Went to kindergarten to learn to count :P

← Older revision		Revision as of 19:59, 6 July 2025
Line 48:		Line 48:
	=== The type property ===		=== The type property ===

	There are ~~four~~ types of mod settings:		There are five types of mod settings:

	* bool-setting - a true/false checkbox		* bool-setting - a true/false checkbox

PennyJim: /* Reading settings */ Refine the wording of the clarification + Split the different types into more legibly different things

2025-05-14T01:59:01Z

Reading settings: Refine the wording of the clarification + Split the different types into more legibly different things

← Older revision		Revision as of 01:59, 14 May 2025
Line 166:		Line 166:

	<div class="plainlinks">		<div class="plainlinks">
	In the control stage, ~~the same start~~-~~up settings~~ are available. ~~More settings become available~~: "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). ~~Settings of the setting_type~~ "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.		In the control stage, "runtime-global" and "runtime-per-user" are additonally available. They can be accessed as follows:
			* "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]).
			* "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
	</div>		</div>
	Example:		Example:

Honktown: /* Reading settings */ Slight wording to clarify startup settings are also in runtime + what runtime-global is seen as

2025-05-14T01:44:57Z

Reading settings: Slight wording to clarify startup settings are also in runtime + what runtime-global is seen as

← Older revision		Revision as of 01:44, 14 May 2025
Line 166:		Line 166:

	<div class="plainlinks">		<div class="plainlinks">
	In the control stage, the settings ~~of the setting_type~~ "runtime-global" can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). Settings of the setting_type "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.		In the control stage, the same start-up settings are available. More settings become available: "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]). Settings of the setting_type "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
	</div>		</div>
	Example:		Example:

Bilka: We renamed bool to boolean in the docs

2025-03-14T17:33:42Z

We renamed bool to boolean in the docs

Bilka: Updated links to migrated prototype docs

2024-10-25T14:39:34Z

Updated links to migrated prototype docs

← Older revision		Revision as of 14:39, 25 October 2024
Line 31:		Line 31:

	As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:		As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
	* name - [~~[Types~~/string\|string]] - Mandatory.		* name - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
	* type - [~~[Types~~/string\|string]] - Mandatory.		* type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
	* localised_name - [~~[Types~~/LocalisedString\|LocalisedString]] - Optional.		* localised_name - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
	* localised_description - [~~[Types~~/LocalisedString\|LocalisedString]] - Optional.		* localised_description - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
	* [~~[Types~~/Order\|order]] - [~~[Types~~/string\|string]] - Optional.		* [https://lua-api.factorio.com/latest/types/Order.html order] - [https://lua-api.factorio.com/latest/types/string.html string] - Optional.

	In addition to the standard properties, mod settings also contain:		In addition to the standard properties, mod settings also contain:

	* hidden - [~~[Types~~/bool\|bool]] - Optional.		* hidden - [https://lua-api.factorio.com/latest/types/bool.html bool] - Optional.
	* setting_type - [~~[Types~~/string\|string]] - Mandatory.		* setting_type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.

	=== The name property ===		=== The name property ===
Line 59:		Line 59:

	==== bool-setting ====		==== bool-setting ====
	* default_value - [~~[Types~~/bool\|bool]] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/bool.html bool] - Mandatory.
	** Defines the default value of the setting, in this case whether the checkbox is checked or not.		** Defines the default value of the setting, in this case whether the checkbox is checked or not.
	* forced_value - [~~[Types~~/bool\|bool]] - Optional.		* forced_value - [https://lua-api.factorio.com/latest/types/bool.html bool] - Optional.
	** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.<sup>[https://forums.factorio.com/viewtopic.php?p=531322#p531322]		** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.<sup>[https://forums.factorio.com/viewtopic.php?p=531322#p531322]
	</sup>		</sup>

	==== int-setting ====		==== int-setting ====
	* default_value - [~~[Types~~/int64\|int64]] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Mandatory.
	** Defines the default value of the setting.		** Defines the default value of the setting.
	* minimum_value - [~~[Types~~/int64\|int64]] - Optional.		* minimum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
	** Defines the lowest possible number.		** Defines the lowest possible number.
	* maximum_value - [~~[Types~~/int64\|int64]] - Optional.		* maximum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
	** Defines the highest possible number.		** Defines the highest possible number.
	* allowed_values - ~~[[Types/table\|~~array]] of [~~[Types~~/int64\|int64]] - Optional.		* allowed_values - array of [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
	** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.		** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
	** If only one allowed value is given, the settings is forced to be of that value.		** If only one allowed value is given, the settings is forced to be of that value.

	==== double-setting ====		==== double-setting ====
	* default_value - [~~[Types~~/double\|double]] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/double.html double] - Mandatory.
	** Defines the default value of the setting.		** Defines the default value of the setting.
	* minimum_value - [~~[Types~~/double\|double]] - Optional.		* minimum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
	** Defines the lowest possible number.		** Defines the lowest possible number.
	* maximum_value - [~~[Types~~/double\|double]] - Optional.		* maximum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
	** Defines the highest possible number.		** Defines the highest possible number.
	* allowed_values - ~~[[Types/table\|~~array]] of [~~[Types~~/double\|double]] - Optional.		* allowed_values - array of [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
	** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.		** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
	** If only one allowed value is given, the settings is forced to be of that value.		** If only one allowed value is given, the settings is forced to be of that value.

	==== string-setting ====		==== string-setting ====
	* default_value - [~~[Types~~/string\|string]] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
	** Defines the default value of the setting.		** Defines the default value of the setting.
	* allow_blank - [~~[Types~~/bool\|bool]] - Optional. - Default: false		* allow_blank - [https://lua-api.factorio.com/latest/types/bool.html bool] - Optional. - Default: false
	** Defines whether it's possible for the user to set the textfield to empty and apply the setting.		** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
	* auto_trim - [~~[Types~~/bool\|bool]] - Optional. - Default: false		* auto_trim - [https://lua-api.factorio.com/latest/types/bool.html bool] - Optional. - Default: false
	** Whether values that are input by the user should have whitespace removed from both ends of the string.		** Whether values that are input by the user should have whitespace removed from both ends of the string.
	* allowed_values - ~~[[Types/table\|~~array]] of [~~[Types~~/string\|string]] - Optional.		* allowed_values - array of [https://lua-api.factorio.com/latest/types/string.html string] - Optional.
	** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.		** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
	** If only one allowed value is given, the settings is forced to be of that value.		** If only one allowed value is given, the settings is forced to be of that value.

	==== color-setting ====		==== color-setting ====
	* default_value - [~~[Types~~/Color\|Color]] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/Color.html Color] - Mandatory.
	** Defines the default value of the setting.		** Defines the default value of the setting.

Line 109:		Line 109:
	* then finally by the setting name.		* then finally by the setting name.

	For more info on how to use the order string, see [~~[Types~~/Order]].		For more info on how to use the order string, see [https://lua-api.factorio.com/latest/types/Order.html Order].

	=== The hidden property ===		=== The hidden property ===

Lovely santa: Corrected error in example for string setting localisations

2024-10-09T18:50:51Z

Corrected error in example for string setting localisations

← Older revision		Revision as of 18:50, 9 October 2024
Line 129:		Line 129:
	<pre>		<pre>
	[mod-setting-name]		[mod-setting-name]
	my-mod-test-setting=Localized test setting name		my-mod-string-test-setting=Localized test setting name

	[mod-setting-description]		[mod-setting-description]
	my-mod-test-setting=Localized test setting description		my-mod-string-test-setting=Localized test setting description

	[string-mod-setting]		[string-mod-setting]

Bilka: Translations of the modding tutorials are allowed

2023-11-13T20:43:01Z

Translations of the modding tutorials are allowed

← Older revision		Revision as of 20:43, 13 November 2023
Line 1:		Line 1:
			{{Languages}}
	This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir\|Gangsir's modding tutorial]].		This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir\|Gangsir's modding tutorial]].

← Older revision		Revision as of 17:33, 14 March 2025
Line 39:		Line 39:
	In addition to the standard properties, mod settings also contain:		In addition to the standard properties, mod settings also contain:

	* hidden - [https://lua-api.factorio.com/latest/types/~~bool~~.html ~~bool~~] - Optional.		* hidden - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
	* setting_type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.		* setting_type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.

Line 59:		Line 59:

	==== bool-setting ====		==== bool-setting ====
	* default_value - [https://lua-api.factorio.com/latest/types/~~bool~~.html ~~bool~~] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Mandatory.
	** Defines the default value of the setting, in this case whether the checkbox is checked or not.		** Defines the default value of the setting, in this case whether the checkbox is checked or not.
	* forced_value - [https://lua-api.factorio.com/latest/types/~~bool~~.html ~~bool~~] - Optional.		* forced_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
	** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.<sup>[https://forums.factorio.com/viewtopic.php?p=531322#p531322]		** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.<sup>[https://forums.factorio.com/viewtopic.php?p=531322#p531322]
	</sup>		</sup>
Line 90:		Line 90:
	* default_value - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.		* default_value - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
	** Defines the default value of the setting.		** Defines the default value of the setting.
	* allow_blank - [https://lua-api.factorio.com/latest/types/~~bool~~.html ~~bool~~] - Optional. - Default: false		* allow_blank - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
	** Defines whether it's possible for the user to set the textfield to empty and apply the setting.		** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
	* auto_trim - [https://lua-api.factorio.com/latest/types/~~bool~~.html ~~bool~~] - Optional. - Default: false		* auto_trim - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
	** Whether values that are input by the user should have whitespace removed from both ends of the string.		** Whether values that are input by the user should have whitespace removed from both ends of the string.
	* allowed_values - array of [https://lua-api.factorio.com/latest/types/string.html string] - Optional.		* allowed_values - array of [https://lua-api.factorio.com/latest/types/string.html string] - Optional.