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

[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

For 0.15 I'm going to implement a settings system that mods can use so people using mods don't need to open and edit the mod files directly. I'm looking at what it will take to implement and I'd like to get the modding communities feedback as to what they want.

This is what I've come up with so far:

Settings definitions (per mod) will be JSON format stored in the mod folder as "settings.json".

Example:

[code]{
"double-player-health":
{
"type": "startup" or "runtime",
"data_type": "string", "int", "uint", "double", "boolean",
"default_value": ...,
"per_user": true or false,
"admin": true or false,
"name-key": "double-player-health",
"description-key": "double-player-health"
}
}[/code]


About example:

[list][*] "double-player-health" is a way to identify this setting. This is required to be unique per-mod.

[*] "type" determines where the setting is usable and when it can be changed. If "startup" is used the setting will be available during the data stage of loading but can't be changed runtime without restarting the game. If "runtime" is used the setting can only be used runtime (after a map is loaded) but can be changed runtime as well.

[*] "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.

[*] "default_value" is the default value of the setting.

[*] "per_user" determines if the setting is applied once globally for all players or if each player can define their own value for that setting. This can only be used in conjunction with "data_type" == "runtime"

[*] "admin" makes it so only an admin player can change this setting. Note this is only used when in a multiplayer game and the setting is not "type": "per_user". When a map is loaded in single player this is ignored completely regardless of the players admin status.

[*] "name-key" is the locale key used to give a human readable name to this setting.

[*] "description-key" is the locale key used to give a description of what the setting does.[/list]


Information about how settings are processed:

[list][*] Settings are loaded and setup before the data stage.

[*] "startup" settings will be available during the entire data stage, during migrations, and runtime.

[*] "runtime" settings will be available during migrations, and runtime. The reason for this: "runtime" settings can change ... runtime and if a mod used those during startup to determine some prototype information it could make the MP load mechanics unstable and cause desyncs.

[*] The map generation screen will have a section that lists the "runtime" settings to allow customization of those before generating a new map.

[*] When a setting is changed an event will be fired "on_settings_changed". This includes startup settings after loading a map.

[*] Settings are read-only for mods.

[*] Mods can read settings from other mods using the normal interface for reading their own settings by giving the mod name.

[*] `nil` is never a valid value for a setting and as such settings will return `nil` if a mod tries to read a setting that doesn't exist instead of giving an error.

[*] A game-local setting "Keep per-user settings per-save" true/false will exist. If false, the current user settings will be applied to the map after it has loaded (exactly how the keep-inventory-sorted setting works now). If true, the map settings will overwrite the user-settings on load. This will allow people to have per-map settings and not mistakenly break their games when loaded in single player should any of those settings have wide-spread effects when changed.[/list]


Logic rules about how settings will be applied:

[list][*] "startup" settings can't be changed if not playing single player. Loading a MP map in single player is still fine to allow changing startup settings.

[*] When joining a server if your startup settings don't match the server it will prompt if you want to change your settings to match the server. If yes, the settings would be changed and the game restarted.

[*] When joining a server if your runtime settings that aren't per_user don't match the server the "keep single per-user settings per-save" will determine what happens.

[*] When joining a server if your runtime per_user settings don't match the server the first action will be to sync your settings with the server and then the standard MP connection logic begins. This way, by the time you start simulating the game at all the settings have already been synced between you and the server.

[*] When a runtime setting is changed it will be sent as a normal input action which would be applied like typing in the console.

[*] When viewing the settings page and in a MP session the "startup" tab will be visible but all values will be greyed out and text will be shown telling the user why they can't be changed.

[*] When viewing the settings page and in a MP session if a player isn't an admin the "runtime" settings that are admin-only will be visible but all values will be greyed out and text will be shown telling the user why they can't be changed.

[*] After game init (not to be confused with loading a map) if any of the settings default_values have changed from the last time the game was started a notice GUI will be shown saying so and asking if the user wants to apply the new defaults or keep the values they currently have. This GUI will shown the old default_value, the current value and the new default value using coloring to indicate if they previously defined something other then the old default and give keep/use new for the ones they haven't defined non-default values for. There should be buttons not-on-the-bottom-right "use all new defaults", "keep my settings" and then a "ok" bottom on the bottom right that applies what ever the current options are selected in the GUI.[/list]


Things that need to be fleshed out still:

[list][*] 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

[*] Some system for grouping like-settings[/list]

[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.

[Rseding91]

"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.

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.

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.

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")"

[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?

[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

[justarandomgeek]

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.

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]

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"

[SAL9000]

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.

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 .

[aubergine18]

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?)

[Rseding91]

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 For now I'm just sticking with "it's per save or applied everywhere".

[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

[aubergine18]

Would be nice if this could all tie in with... viewtopic.php?f=6&t=32470

[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.

[Rseding91]

Added:

• Some system for grouping like-settings

[SAL9000]

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 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]

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]

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

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.

[Mooncat]

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

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! )

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)

[aubergine18]

I'd give color additional data such as a palette to choose from, or default color, etc.

[Mooncat]

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?