Tutorial:Mod settings
This tutorial aims to explain how to create and use mod settings and the gui that mods can create. It corresponds to factorio version 0.15.
Mod settings
Each mod can specify settings that users can change outside or inside the game. These settings can be accessed from inside the data stage or the control stage depending on their setting_type and allow to conditionally create or modify prototypes and to add configuration options to control scripts.
Where and when mod settings are defined
Mod settings are defined in the settings stage. This stage is loaded before the prototype stage. There are three files in which settings can be defined:
- settings.lua
- settings-updates.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 natural sort order. Next, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). 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 remote interface available.
How to define mod settings
Mod settings are defined and modified by using the data table. This works the same way as other prototypes. An example would be:
data:extend({
{
type = "bool-setting",
name = "my-mod-first-setting",
setting_type = "runtime-global",
default_value = true,
order = "a"
}
})
As you can see, the setting has multiple properties. Each setting supports the following standard protoype 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)
The name property
The name of the settings prototype should be unique to avoid mod conflicts since all mods share the data table (the "prototype space"). Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.
The type property
There are four types of mod settings:
- bool-setting - a true/false checkbox
- int-setting - a signed 64 bit integer textfield (or selection dropdown)
- double-setting - a double precision floating point textfield (or selection dropdown)
- string-setting - a string textfield (or selection dropdown)
Depending on the type, the prototype also allows or requires additional properties:
- bool-setting:
- default_value (bool, required) - defines the default value of the setting, in this case whether the checkbox is checked or not
- int-setting:
- default_value (int, required) - defines the default value of the setting
- minimum_value (int, optional) - defines the lowest possible number
- maximum_value (int, optional) - defines the highest possible number
- allowed_values (array(int), optional) - makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield
- double-setting:
- default_value (double, required) - defines the default value of the setting
- minimum_value (double, optional) - defines the lowest possible number
- maximum_value (double, optional) - defines the highest possible number
- allowed_values (array(double), optional) - makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield
- string-setting:
- default_value (string, required) - defines the default value of the setting
- allow_blank (boolean, optional) - defaults to false, defines whether it's possible for the user to set the textfield to empty and apply the setting
- allowed_values (array(string), optional) - makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield
The setting_type property
There are the overall kinds of settings:
- startup: This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
- runtime-global: This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
- runtime-per-user: This kind of setting 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's settings are used.
This "setting_type" also determines in which tab the setting is showed in the mod settings menu.