Adding Custom Game Settings via Mods

As of update 10, it is possible for mods to add their own gameplay settings into the game. Settings can be very useful, and this article will teach you everything about adding them to your own mod!

By default, mod settings will be in the misc group. If your mod adds multiple settings, it may be a good idea to create a new group for them. More on that later.

• Creating your setting
• Adding l10n to your settings
• Extra attributes
• Creating a new group

All settings are added through the mod.lua, in a new settings table like shown at the bottom here:

return {
	author		= "modAuthor",
	version		= "1",
	title		= "modTitle",
	description	= "modDesc",
 
	scripts		= {
	    "yourScript.lua",
	},
 
	settings	= {
 
        },
}

There are 3 different types of settings that the game works with: checkbox, range and select, which all have different uses.

• checkbox : The setting is either active or not active.‏‏‎ ‎‏‏‎ ‎‏‏‎ ‎‏‏‎ ‎‎‎‎‎‎‏‏‎ ‎‏‏‎ ‎‏‏‎ ‎‏‏‎ ‎‏‏‎ ‎‏‏‎ ‎‏‏‎ ‏‏‎ ‎‏‏‎ ‎‏‏‎ ‎‎‏‏‎ (‎See how to add )
• range : A number slider between a minimum and max value. (See how to add )
• select : Lets you pick between a list of different options. ‏‏‎ ‎‏‏‎ ‏‏‎ ‎‏‏‎‎ ‎‏‏ ‎‎‏‏‎ (See how to add )

Learn how to add each of them below!

This is the simplest type of setting. It's a toggle, meaning it is either active or not active.
In most cases, you will simply use this to change the value of a variable.

Here's an example of adding a checkbox setting:

-- Remember that this is in mod.lua
settings	= {
    {
	category		= "gameplay",
	name			= "yourModSetting",
        group 			= GameplaySettings.GROUPS.YOURGROUP,
        type			= "checkbox",
        get			= function()		
            return GameplaySettings.yourModSetting;				
        end,
        set			= function(value)	
            GameplaySettings.yourModSetting = value;						
        end,
        defaultValue		= true,
    },
},

Where you see the GameplaySettings.yourVariable variable, replace yourVariable with the name of your variable.

• The category defines what main area the setting will be in (gameplay, audio, graphics…). In almost all cases, mod settings will use gameplay, as in the example above.
• Our name property should be set to something which reflects your mod. This is not what will be displayed ingame, as you will add l10n entries later.
• The type specifies what type of setting this is. For a checkbox, this should naturally be set to checkbox.
• Our get function will be returning the current value of the setting variable. In most cases you should leave this as it is.
• The set function is called whenever we change our setting in the menu and save it. The function argument, value, will be a boolean (true or false).
  You can leave the function body as it is, or define your own set of actions (usually by calling an external function)
• Lastly, defaultValue specifies if the setting should be active or not by default. true == active, false == not active.

That's it, your 'checkbox' setting is now set up and ready to be used!
You can access the setting value by referring to the GameplaySettings.yourVariable variable. Make sure not to overwrite it anywhere outside of the set function.

Ingame, the setting will look something like this:

Next up is the range setting. This will create a slider between two number values. It is a bit more advanced than a checkbox setting.

Here's an example of adding a range setting:

-- Remember that this is in mod.lua
settings	= {
    {
	category		= "gameplay",
	name			= "yourModSetting",
        type			= "range",
        get			= function()		
            return GameplaySettings.yourModSetting;			
        end,
        set			= function(value)	
            GameplaySettings.yourModSetting	= value;		
        end,
        defaultValue		= 15,
        min			= 10,
        max			= 30,
        format			= "%.0f",
        wholeNumbers		= true,
    },
},

Where you see the GameplaySettings.yourVariable variable, replace yourVariable with the name of your variable.

• The category defines what main area the setting will be in (gameplay, audio, graphics…). In almost all cases, mod settings will use gameplay, as in the example above.
• Our name property should be set to something which reflects your mod. This is not what will be displayed ingame, as you will add l10n entries later.
• The type specifies what type of setting this is. For a range, this should naturally be set to range.
• Our get function will be returning the current value of the setting variable. In most cases you should leave this as it is.
• The set function is called whenever we change our setting in the menu and save it. The function argument, value, will be a number.
  You can leave the function body as it is, or define your own set of actions (usually by calling an external function)
• defaultValue specifies what the default value of the setting should be. Make sure this is a number between min and max.
• min : The lowest value of the slider.
• max : The highest value of the slider.
• format : This is how your values will be formulated. The number in “%.0f” practically controls the amount of decimal places your values will use. 0 means no decimals.
  If wholeNumbers is set to true, the format should always have 0 decimals, as in the example.
• wholeNumbers : Specifies if the range should use whole numbers (1,2,3…) or count in decimals depending on the format (for 2 decimal places: 1.01, 1.02, 1.03…)

That's it, your 'range' setting is now set up and ready to be used!
You can access the setting value by referring to the GameplaySettings.yourVariable variable. Make sure not to overwrite it anywhere outside of the set function.

Ingame, the setting will look something like this:

This type allows you to create a list of specific options that the player can choose between. It is the most advanced type of setting.

Here's an example of adding a select setting:

-- Remember that this is in mod.lua
settings	= {
    {
	category		= "gameplay",
	name			= "yourModSetting",
        type			= "select",
 
        get			= function()		
            return GameplaySettings.yourModSetting;			
        end,
        set			= function(value)	
            GameplaySettings.yourModSetting	= value;		
        end,
        defaultValue		= 1,
        values				= {
            {
                name		= "option1",
                value		= 0,
            },
            {
                name		= "option2",
                value		= 1,
            },
            {
                name		= "option3",
                value		= 2,
            },
        },
    },
},

Where you see the GameplaySettings.yourVariable variable, replace yourVariable with the name of your variable.

• The category defines what main area the setting will be in (gameplay, audio, graphics…). In almost all cases, mod settings will use gameplay, as in the example above.
• Our name property should be set to something which reflects your mod. This is not what will be displayed ingame, as you will add l10n entries later.
• The type specifies what type of setting this is. For a 'select' setting, this should naturally be set to select.
• Our get function will be returning the current value of the setting variable. You can leave this as it is or define your own set of actions.
• The set function is called whenever we change our setting in the menu and save it. The function argument, value, will usually be a number.
  You can leave the function body as it is, or define your own set of actions (usually by calling an external function)
• defaultValue specifies what the default value of the setting should be. Make sure this number matches up to the desired value.
• values :
  • name : The name of this option. This is important for what will be displayed for the options ingame. More on that in a few moments.
  • value : The numbered value this option should have.

That's it, your 'select' setting is now set up and ready to be used!
You can access the setting value by referring to the GameplaySettings.yourVariable variable. Make sure not to overwrite it anywhere outside of the set function.

Ingame, the setting will look something like this:

As you have probably noticed if you already tried out your new setting, the name and description will look something like this:

So will the names of the options if you have a select setting.
That's not very informative about what the setting does, so let's fix that!

Incase you're not familiar, l10n is a system used for localisation.
When the game needs to display a line of text, it will usually do a call to l10n.get('nameOfString') and in return get the correct text to display in the correct language. However, we'll be adding l10n for our settings a bit differently.

Just like for the settings themselves, we'll add l10n entries to a new table in the mod.lua:

settings	= {
},
 
l10n		= {
    {
        language	= "en",
        key		= "l10n_key",
        value		= "Your l10n text #1",
    },
},

For the name of the setting you'll want to use this as the key:

key	= "ui_settings_gameplay_yourModSetting",

• Replace yourModSetting with the same name as you used when creating the setting.
  

The value should be replaced with the actual setting name you want displayed ingame. Make sure to keep the quotes“”, those are important!

It should then look something like this:

{
    language	= "en",
    key		= "ui_settings_gameplay_yourModSetting",
    value	= "Your setting name",
},

Now do the exact same for the description, only this time, add _desc to the end of the key and change the value to your description text:

{
    language	= "en",
    key		= "ui_settings_gameplay_yourModSetting_desc",
    value	= "Your setting description",
},

Congratulations, your settings now have proper names and descriptions ingame that can be translated into various languages if you wish.
For example, to add a translation for german, you would add an additional l10n exactly the same as above, but change the language from en to de:

{
    language	= "de",
    key		= "ui_settings_gameplay_yourModSetting_desc",
    value	= "Beschreibung für Ihre Einstellung",
},    

If you want to learn more about localisation, translation and using l10n in WRS, have a look at this article

{
    language	= "en",
    key		= "ui_settings_gameplay_settings_yourModSetting_option1",
    value	= "First option",
},
{
    language	= "en",
    key		= "ui_settings_gameplay_settings_yourModSetting_option2",
    value	= "Second option",
},

You get the point, one for every option.
And here, replace yourModSetting_option1 with the name you specified for the corresponding value. (and for option2 etc)

To add a name and description for your group, add l10n entries as following:

{
    language	= "en",
    key		= "ui_settings_gameplay_category_yourGroup",
    value	= "Mod group",
},
{
    language	= "en",
    key		= "ui_settings_gameplay_category_yourGroup_desc",
    value	= "Contains settings used by your mod.",
},

• Replace yourGroup in the key with the string you used for your group. (See the group example further down)
• Change the values for the name and description to whatever you like.

There are some extra attributes you can assign to your settings. Here's what they do and how to use them:

The ignoreL10N attribute can be used if you have a 'select' setting.
If this is set to true, the options will not try to look for any localized string, but rather display exactly what the name is set to.
This is useful for example if your options are named with numbers that shouldn't be translated.

Here's an example of adding ignoreL10N:

{
    category		= "gameplay",
    name		= "yourModSetting",
    type		= "select",
    ignoreL10N	        = true,
    ...
},

The customL10NFunction is a function that you can choose to include when creating your 'select' setting.
A use case example is if you want to include a number in your name or display very similar texts without adding a new l10n entry for every value.

Here's an example of adding a customL10NFunction:

{
    category		= "gameplay",
    name		= "yourModSetting",
    type		= "select",
    customL10NFunction	= function(value)
        return l10n.format("ui_settings_gameplay_settings_yourModSetting", value)
    end;
    ...
},

The hidePrevNextValue attribute can be used on a 'select' setting. and does exactly what the name suggests; it hides the other options except the one which is currently selected.
Use this if your text is too long and overlaps with the other options.

Here's an example of adding hidePrevNextValue:

{
    category		= "gameplay",
    name		= "yourModSetting",
    type		= "select",
    hidePrevNextValue	= true,
    ...
},

If your mod has multiple settings, you may want to organise them in a new group.

To add a new group, simply add the group directly to the setting with a string like this:

settings	= {
    {
	category	= "gameplay",
	name		= "yourModSetting",
        group 		= "yourGroup,
        ...

Make sure to use the same group name for all the settings you want in that group.

Remember to add l10n entries for your group, see how here