[0.15] Mod setting/config interface - give your input

Place to post guides, observations, things related to modding that are not mods themselves.
Post Reply
Rseding91
Factorio Staff
Factorio Staff
Posts: 13175
Joined: Wed Jun 11, 2014 5:23 am
Contact:

[0.15] Mod setting/config interface - give your input

Post by Rseding91 »

Mod settings:

Do not conditionally 'require(...)' things: this breaks the crc checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.

Mod settings are defined per-mod using the same process as normal prototypes with their own settings files.
See the data stage here: http://lua-api.factorio.com/latest/Data-Lifecycle.html

The settings lua files are:
  • settings.lua
  • settings-updates.lua
  • settings-final-fixes.lua
As of 0.15.3 there are 4 types of settings:
  • bool-setting - true/false
  • int-setting - a signed 64 bit integer
  • double-setting - a double precision floating point number
  • string-setting - a string
Each setting supports the standard prototype properties:
  • name (string, required)
  • type (string, required)
  • localised_name (localised string, optional)
  • localised_description (localised string, optional)
  • order (string, optional)
In addition to the standard properties mod settings also contain:
  • setting_type (string, required)
    - "startup" - this setting type is available during the standard prototype data loading stage and can't be changed runtime. When joinin a server the startup settings are required to be identical to the server and if not the joining person will be asked if they want to set their settings to match the server.
    - "runtime-global" - this setting type is only available runtime in the control.lua stage and can only be changed by admins (or in single player the 1 player).
    - "runtime-per-user" - this setting type is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save settings are used.
Bool setting properties contain:
  • default_value (bool, required)
Int setting prototypes contain:
  • default_value (int, required)
  • minimum_value (int, optional)
  • maximum_value (int, optional)
  • allowed_values (array(int), optional)
Double setting prototypes contain:
  • default_value (double, required)
  • minimum_value (double, optional)
  • maximum_value (double, optional)
  • allowed_values (array(double), optional)
String setting prototype contain:
  • default_value (string, required)
  • allow_blank (boolean, optional) - defaults to false
  • allowed_values (array(string), optional)
Mod settings persistence:
  • The "mod-settings.json" file stored in the write-data folder for the game contains the local players settings between game sessions similar to the player-data.json file.
Accessing mod settings through script:
  • The global property "settings" is populated with the startup settings during the data loading stage. Runtime (the control.lua stage) the global property "settings" contains startup, runtime, and runtime-per-user settings in read-only format.
Mod settings display order:
  • Mod settings are shown in the settings GUI first sorted by mod sort order then sorted by the setting "order" string and then finally by the setting name.
outdated
If you want to get ahold of me I'm almost always on Discord.

User avatar
aubergine18
Smart Inserter
Smart Inserter
Posts: 1264
Joined: Fri Jul 22, 2016 8:51 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by aubergine18 »

"data_type" is the type of data the setting accepts. "int" is a 32 bit signed integer, "uint" is a 32 bit unsigned integer, "double" is a double precision floating point number, "boolean" is true/false.
Lua just has Number so not sure how useful this is. Also, what about 'string'?
Settings are read-only for mods.
What if a mod wants to provide it's own settings interface? EvoGUI is good example, player can change sensor settings as often a they want during game.

Other example might be a mod that wants to provide a custom GUI using icons for settings.

It would be great if mods had a way to write persistent player-specific settings that can be loaded in different games. A player might want their sensor settings to work the same in all games for example. Although it seems you're already thinking along these lines based on this...
A game-local setting "Keep per-user settings per-save" true/false will exist.
Some code mockups showing how mod might use the various APIs and settings, would help hone feedback.
Better forum search for modders: Enclose your search term in quotes, eg. "font_color" or "custom-input" - it prevents the forum search from splitting on hypens and underscores, resulting in much more accurate results.

Rseding91
Factorio Staff
Factorio Staff
Posts: 13175
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Rseding91 »

aubergine18 wrote:
"data_type" is the type of data the setting accepts. "int" is a 32 bit signed integer, "uint" is a 32 bit unsigned integer, "double" is a double precision floating point number, "boolean" is true/false.
Lua just has Number so not sure how useful this is. Also, what about 'string'?
It's mainly to restrict the input range in the GUI. So you don't need to on the mod side wonder if the player put "-5" for something like a search area setting. You can know for sure it's some non-negative value.
aubergine18 wrote:
Settings are read-only for mods.
What if a mod wants to provide it's own settings interface? EvoGUI is good example, player can change sensor settings as often a they want during game.

Other example might be a mod that wants to provide a custom GUI using icons for settings.
Then you simply do that in-game as they would do now and don't use the settings interface.
aubergine18 wrote:It would be great if mods had a way to write persistent player-specific settings that can be loaded in different games. A player might want their sensor settings to work the same in all games for example. Although it seems you're already thinking along these lines based on this...
A game-local setting "Keep per-user settings per-save" true/false will exist.
That's exactly what the settings interface is for. You'd just make a setting for "sensor settings" and the user would use it how they wanted.
aubergine18 wrote:Some code mockups showing how mod might use the various APIs and settings, would help hone feedback.
From the mod side it's all read-only so it's just syntax: if you reference "global.settings[player_index].signal" or use the new API: "settings.get("signal")"
If you want to get ahold of me I'm almost always on Discord.

User avatar
aubergine18
Smart Inserter
Smart Inserter
Posts: 1264
Joined: Fri Jul 22, 2016 8:51 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by aubergine18 »

It's mainly to restrict the input range in the GUI. So you don't need to on the mod side wonder if the player put "-5" for something like a search area setting. You can know for sure it's some non-negative value.
GUI API: It would be useful if mods had access to a slider control and also the ability to set input masks on textfield elements.
Then you simply do that in-game as they would do now and don't use the settings interface.

...

From the mod side it's all read-only so it's just syntax...
But then I lose the ability to store those settings from game-to-game (in the "proper settings") because the settings API is read-only. Can we get a read-writeable interface for persisting stuff between different games? Like a 'settings.meta' table that mods can read/write anything to?
Better forum search for modders: Enclose your search term in quotes, eg. "font_color" or "custom-input" - it prevents the forum search from splitting on hypens and underscores, resulting in much more accurate results.

User avatar
aubergine18
Smart Inserter
Smart Inserter
Posts: 1264
Joined: Fri Jul 22, 2016 8:51 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by aubergine18 »

Would be nice also if player settings could be accessed via the player object.

somePlayer.settings[modName].whatever

and player-agnostic settings from a global 'settings' object
Better forum search for modders: Enclose your search term in quotes, eg. "font_color" or "custom-input" - it prevents the forum search from splitting on hypens and underscores, resulting in much more accurate results.

justarandomgeek
Filter Inserter
Filter Inserter
Posts: 300
Joined: Fri Mar 18, 2016 4:34 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by justarandomgeek »

Rseding91 wrote:It's mainly to restrict the input range in the GUI. So you don't need to on the mod side wonder if the player put "-5" for something like a search area setting. You can know for sure it's some non-negative value.
Would be handy to have a 'signal' type that specifies any valid circuit signal, for example to designate a command signal on mod circuit entities. Probably 'entity' and 'item' types too with a corresponding prototype name restriction, though I don't have a use for those in mind right now.
Rseding91 wrote:A game-local setting "Keep per-user settings per-save" true/false will exist.
What if I want my settings for RSO to be different in different saves, but want my settings for everything else to be the same for all games?

Rseding91
Factorio Staff
Factorio Staff
Posts: 13175
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Rseding91 »

aubergine18 wrote:Would be nice also if player settings could be accessed via the player object.

somePlayer.settings[modName].whatever

and player-agnostic settings from a global 'settings' object
Yes, that part hasn't been fully thought out mostly because it's trivial to implement compared to getting the rest "right" :)
If you want to get ahold of me I'm almost always on Discord.

SAL9000
Manual Inserter
Manual Inserter
Posts: 2
Joined: Sun Sep 18, 2016 6:59 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by SAL9000 »

justarandomgeek wrote:
Rseding91 wrote:It's mainly to restrict the input range in the GUI. So you don't need to on the mod side wonder if the player put "-5" for something like a search area setting. You can know for sure it's some non-negative value.
Would be handy to have a 'signal' type that specifies any valid circuit signal, for example to designate a command signal on mod circuit entities. Probably 'entity' and 'item' types too with a corresponding prototype name restriction, though I don't have a use for those in mind right now.
Single-choice and multiple-choice variants of those might be useful as well.
justarandomgeek wrote:
Rseding91 wrote:A game-local setting "Keep per-user settings per-save" true/false will exist.
What if I want my settings for RSO to be different in different saves, but want my settings for everything else to be the same for all games?
Perhaps each setting has a "default scope", one of "global", "server", "save", "player"?
In the settings UI, extra "save" buttons would be added, which save a given setting or category/page thereof to a higher or lower scope.
For higher scopes, there's the question of whether it overrides settings in existing saves or only sets a default for new servers/saves... there's no nice "principle of least surprise" answer here. Lower scopes are more obvious, overriding the higher scope setting for that given context.
I am unsure as to whether mods may want to prevent players from using those buttons on some settings.

Admittedly, at this point I suspect that a more useful solution to this entire problem would be to provide a basic system, but allow specially-marked mods to substitute it.
Then, instead of asking for features, we can implement them ourselves :D.

User avatar
aubergine18
Smart Inserter
Smart Inserter
Posts: 1264
Joined: Fri Jul 22, 2016 8:51 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by aubergine18 »

SAL9000 wrote:Perhaps each setting has a "default scope", one of "global", "server", "save", "player"?
I like the idea of a scope=<scope> property in the settings config, but not sure that should be an end-user choice (I can see where it would be useful, but do we want to present users with such complex settings screen?)
Better forum search for modders: Enclose your search term in quotes, eg. "font_color" or "custom-input" - it prevents the forum search from splitting on hypens and underscores, resulting in much more accurate results.

Rseding91
Factorio Staff
Factorio Staff
Posts: 13175
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Rseding91 »

aubergine18 wrote:
SAL9000 wrote:Perhaps each setting has a "default scope", one of "global", "server", "save", "player"?
I like the idea of a scope=<scope> property in the settings config, but not sure that should be an end-user choice (I can see where it would be useful, but do we want to present users with such complex settings screen?)
I don't think that will ever end well and not be super confusing for everyone involved :P For now I'm just sticking with "it's per save or applied everywhere".
If you want to get ahold of me I'm almost always on Discord.

Rseding91
Factorio Staff
Factorio Staff
Posts: 13175
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Rseding91 »

Added:
  • The map generation screen will have a section that lists the "runtime" settings to allow customization of those before generating a new map.
and

Things that need to be fleshed out still:
  • Allow defining how the setting will be shown (text field, radio buttons, checkbox, list box, ...)
  • Allow defining a list of values for things like radio buttons/list boxes
If you want to get ahold of me I'm almost always on Discord.

User avatar
aubergine18
Smart Inserter
Smart Inserter
Posts: 1264
Joined: Fri Jul 22, 2016 8:51 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by aubergine18 »

Would be nice if this could all tie in with... viewtopic.php?f=6&t=32470
Better forum search for modders: Enclose your search term in quotes, eg. "font_color" or "custom-input" - it prevents the forum search from splitting on hypens and underscores, resulting in much more accurate results.

User avatar
aubergine18
Smart Inserter
Smart Inserter
Posts: 1264
Joined: Fri Jul 22, 2016 8:51 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by aubergine18 »

A color type (also, color picker should be exposed via API so mods can use it in their own UIs) which returns standard factorio color object.
Better forum search for modders: Enclose your search term in quotes, eg. "font_color" or "custom-input" - it prevents the forum search from splitting on hypens and underscores, resulting in much more accurate results.

Rseding91
Factorio Staff
Factorio Staff
Posts: 13175
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Rseding91 »

Added:
  • Some system for grouping like-settings
If you want to get ahold of me I'm almost always on Discord.

SAL9000
Manual Inserter
Manual Inserter
Posts: 2
Joined: Sun Sep 18, 2016 6:59 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by SAL9000 »

Rseding91 wrote:
aubergine18 wrote:
SAL9000 wrote:Perhaps each setting has a "default scope", one of "global", "server", "save", "player"?
I like the idea of a scope=<scope> property in the settings config, but not sure that should be an end-user choice (I can see where it would be useful, but do we want to present users with such complex settings screen?)
I don't think that will ever end well and not be super confusing for everyone involved :P For now I'm just sticking with "it's per save or applied everywhere".
Hide the complexity under a hamburger menu and/or "advanced users" option? ;)

orzelek
Smart Inserter
Smart Inserter
Posts: 3911
Joined: Fri Apr 03, 2015 10:20 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by orzelek »

For numeric settings it would be good to give min/max limits so that mod doesn't need to handle out of range values.

I might missed something but when user would be able to set "startup" settings?

Rseding91
Factorio Staff
Factorio Staff
Posts: 13175
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Rseding91 »

orzelek wrote:For numeric settings it would be good to give min/max limits so that mod doesn't need to handle out of range values.
Yeah that's something I'm planning on
orzelek wrote:I might missed something but when user would be able to set "startup" settings?
On the main menu or while playing single player games. In both instances it will force a restart if they want to apply new settings.
If you want to get ahold of me I'm almost always on Discord.

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Mooncat »

Hi,
Took me some time to read the OP and now I finally know what I can provide. :lol:

Regarding to these:
Allow defining how the setting will be shown (text field, radio buttons, checkbox, list box, ...)
Allow defining a list of values for things like radio buttons/list boxes
Here is my (crazy) thought:
Instead of defining "data_type", how about we define "gui_type" and use it to determine what will the data type be?
(By the way, underscore or hyphen? You have "data_type" and "name-key". Choose one! :P )

For example,

Code: Select all

"double-player-health":
{
  "type": "startup" or "runtime",
  "gui_type": "number",
  "default_value": 100,
  ...
}
will create a numeric textfield that user can input any number to it, and then it the number to the mod.

Some GUI types may require additional data, just like LuaGuiElement.add.
For example, if range is required, as orzelek suggested, the GUI type will be

Code: Select all

"gui_type": "slider", 
with additional data

Code: Select all

"minimum_value": 1,
"maximum_value": 200,
Some GUI types together with their additional data that I can think of:
  • "checkbox" :: boolean. No additional data.
  • "number" :: number. No additional data.
  • "slider" :: number. With "minimum_value" :: number and "maximum_value" :: number.
  • "textfield" :: string. No additional data.
  • "radio_button_number" :: number. With "options" :: array of objects:

    Code: Select all

    "options" =
    [
      { "key": "locale-key-of-this-option", "value": 1 },
      { "key": "another-locale-key", "value": 100 }
    ]
    and "default_value" will be the 1-based option index, e.g.

    Code: Select all

    "default_value" : 2
    will make the second option (value = 100) as the default value. But personally I think the first option should always be the default one.
    Returns the value of the selected option.
  • "radio_button_string" :: string. With "options" :: array of objects, just like "radio_button_number", with string values.
  • "combobox_number" :: number. With "options" :: array of objects, same as "radio_button_number". (Maybe redundant with radio buttons)
  • "combobox_string" :: string. With "options" :: array of objects, same as "radio_button_string". (Maybe redundant with radio buttons)
  • "list_number" :: array of numbers. With "options" :: array of objects, same as "radio_button_number". Default value will be an array of option indexes:

    Code: Select all

    "default_value" : [1, 2, 3, 4]
  • "list_string" :: array of strings. With "options" :: array of objects, same as "radio_button_string".
  • "color" :: Color. No additional data.

And about this:
Some system for grouping like-settings
I can think of 3 ways for doing that:
1) Add an additional layer above the settings, e.g.

Code: Select all

{
  "player-settings" :
  {
    "key" : "locale-key-of-the-header-name",
    "settings" :
    {
      "double-player-health": { ... },
      "double-enemy-health": { ... }
    }
  }
}
So this will group "double-player-health" and "double-enemy-health" inside "player-settings".
It makes the settings.json looks organized. But maybe tricky for settings that are not grouped.

2) The second way would be adding an additional field "header-key". All settings with the same localized string will be put inside the same group. (different mods may have different locale keys pointing to the same localized string)
Less organized, but less tricky for non-grouped settings, e.g. just don't provide "header-key" so it will not be grouped.

3) Modders have no control. Settings are grouped per mod. (But then will we need to localize mod names?)
(Or it is already planned, with addition of (1) or (2)? lol)
Last edited by Mooncat on Wed Sep 21, 2016 9:54 am, edited 1 time in total.

User avatar
aubergine18
Smart Inserter
Smart Inserter
Posts: 1264
Joined: Fri Jul 22, 2016 8:51 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by aubergine18 »

I'd give color additional data such as a palette to choose from, or default color, etc.
Better forum search for modders: Enclose your search term in quotes, eg. "font_color" or "custom-input" - it prevents the forum search from splitting on hypens and underscores, resulting in much more accurate results.

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: [0.15] Mod setting/config interface - give your input

Post by Mooncat »

aubergine18 wrote:I'd give color additional data such as a palette to choose from, or default color, etc.
Maybe also "radio_button_color", "combobox_color" and "list_color" for that? 8-)

Post Reply

Return to “Modding discussion”