Options

Module Definition

The module is inherited from ModuleBase. So base parameters can be found there.

Module name

The name of the module you use as the meta of the module definition is 'Options' or 'OptionModule' if _force_search is set to true in the module definition.

XML Structure

<Options save_file loaded_callback auto_build_menu auto_load>
    <options name node_name title_id desc_id build_items>
        <merge_data ...> ... </merge_data>
        <option name type value_changed converter enabled_callback default_value disabled title_id desc_id hidden>
            <merge_data ...> ... </merge_data>
        </option>
        <option type="multichoice" values_tbl save_value ...> ...
            <values> <value_node value/> ... </values>
        </option>
        <option type="number" min max step show_value ...> ... </option>
        <option type="bool" ...> ... </option>
        <option type="colour" alpha scale_factor step min max ...> ... </option>
        <option type="vector" scale_factor step min max ...> ... </option>
        <option_group build_menu ...> ... </option_group>
        <option_set not_pre_generated items_tbl populate_items ...>
            <items> </items>
            <item_parameters ...> ... </item_parameters>
        </option_set>
    </options>
</Options>

<Options save_file loaded_callback auto_build_menu auto_load>

Parameter	Type	Description
save_file	String	Filename of the save file, relative to the SavePath. [DEFAULT: 'ModName_Options.txt']
loaded_callback	String	Function path/name of a function which should be called when the Options are loaded.
auto_build_menu	Boolean	Determines if the menu should be automatically built. [DEFAULT: True]
auto_load	Boolean	Determines if the options should be automatically loaded. [DEFAULT: True]

<options name node_name title_id desc_id build_items>

Parameter	Type	Description
name	String	The base name of the options group. Only required if it is an option_set or option_group.
node_name	String	The name of the node that holds the options.
title_id	String	The localization id of the title of the button for this options node
desc_id	String	The localization id of the description of the button for this options node
build_items	Boolean	Determines if the items in the menu should be created

<merge_data ...> ... </merge_data>

Any additional parameters which should be included in the item/node definition

<option name type value_changed converter enabled_callback default_value disabled title_id desc_id hidden>

Every value type uses these parameters

Parameter	Type	Description
name	String	The name of option [REQUIRED]
type	String	The option type. Options are multichoice, number, bool, colour, color, vector, rotation and table
value_changed	String	Function path/name which is called once the value of the option has been changed. This is given the parameters 'name' and 'value' of the option.
converter	String	Function path/name which is called to convert the value of option once GetValue param #2 is given 'true'
enabled_callback	String	Function path/name which should return a bool that determines if the option is enabled
default_value	Any	The default value of the option
disabled	Boolean	Determines if the option is disabled
title_id	String	Localization id of the title of the option. [DEFAULT: ModNameOptionNameTitleID]
desc_id	String	Localization id of the description of the option. [DEFAULT: ModNameOptionNameDescID]
hidden	Boolean	Determines if the option is hidden in the menu

<option type="multichoice" values_tbl save_value ...> ...

Parameter	Type	Description
values_tbl	String	Path/Name of a table that holds all the values for the multichoice option (BeardLib reads the string and finds the object with the name/path) Example: self.MyValues or MyGlobalClass.MyValues
save_value	Boolean	Determines if the value of the option should be saved or the index. This is useful if you have a variable amount of values which may have ones inserted in the middle or the end and the value should be retained.

<values> <value_node value/> ... </values>

This allows you to define the multichoice items in the xml. value_node automatically assigns the index depending on its location inside <values>

<option type="number" min max step show_value ...> ... </option>

Parameter	Type	Description
min	Number	The minimum value of the option in the menu
max	Number	The maximum value of the option in the menu
step	Number	The step value of the option in the menu
show_value	Boolean	Determines if the value should be shown on the option in the menu

<option type="colour" alpha scale_factor step min max ...> ... </option>

Parameter	Type	Description
alpha	Boolean	Determines if there should be an option for the alpha of the colour in the menu.
scale_factor	Number	What the values of the colour are scaled up to. E.g. 255 so that it is more intuitive for the user.
step	Number	The step of the options for the colour
min	Number	The minimum value of the options for the colour
max	Number	The maximum value of the options for the colour

<option type="vector" scale_factor step min max ...> ... </option>

scale_factor, step, min, max Same as in the colour option.

<option type="table"/>

The table option type is used to save tables into the options config, the menu will not create anything for this item, mostly this item is the same as the others just that default_value is a table like seen in here:

<option name="Something" type="table">
    <default_value/>
</option>

<option_group build_menu ...> ... </option_group>

Same parameters as defined in the main options docs. The option_group can hold sub_menus in the form of option_groups or option_sets and sub options. The option_group is used for grouping of similar options, this will create a sub menu in the parent node for the options.

Parameter	Type	Description
build_menu	Boolean	Determines if this sub menu should be built in the options menu

<option_set not_pre_generated items_tbl populate_items ...>

The option set is used to create a collection of options which have similar parameters. This is used in PD:TH Hud to create the options for Heist Specific colour grading, as it generates the set of options based on the values from the tweak_data.

Parameter	Type	Description
not_pre_generated	Boolean	Determines if the options are pre_generated. This should be used if you are saving options which are not fixed and you just want to store values. This is used in the BeardLib-Editor to save the prefabs for the map editor.
items_tbl	String	Path/Name of a table which contains data for the items which are part of the option_set. It should be setup like a table of sub tables which contains the item parameters for an option, these will overwrite any of the `item_parameters		that were defined.
populate_items	String	Path/name of a function which returns a table for the items. See: above detail.

<items> </items>

This can be used to define the items for the option set. See: 'items_tbl' definition above.

<item_parameters ...> ... </item_parameters>

Item parameters as defined in the docs for the 'option' node.

Example

See: Mod Template

Functions

Function	Description
SetValue(String name, Any value)	Sets value of option name (can be a path to it example ui/hud/color1) to value
GetValue(String name)	Returns the value of the option name
GetOption(String name)	Return the option name. The table pretty much has the same data as defined in the XML but also has "value"
ResetToDefaultValues(String path, Boolean shallow, Boolean no)	Resets the options. path is the path to the option group that should be reset (leave as an empty string to reset all), shallow determines if the reset should only happen in the current table and not in the sub options too, no_save determines if after resetting the options the function shouldn't save the changes
Save()	Saves the options

There are more functions but as they are mostly used in the class itself they are not defined here.