Widgets

Vermintide Mod Framework provides a mod options menu as a centralized way of managing mod settings.

Values are stored using the Settings module and can be read/written using VMFMod:get and VMFMod:set. Settings managed by a widget must have a valid value for the widget.

Widgets are defined inside the options property of the mod_data table.

• widgets - options widgets definition
• collapsed_widgets - list of setting_ids of widgets that should be collapsed by default (used only when mod is initialized for the first time).

All widgets (except group) have the setting_id and default_value fields.

When the widgets are created, all widgets with an unset setting will be initialized to default_value. This happens before the mod is loaded.

Starting Point

Define options and widgets.

--[ _data.lua ](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/-_data.lua-)
return {
  name = "",
      . . .
  options = {
    widgets = {

      {
        --[ Widget Settings ](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/-Widget-Settings-)
      },

    }
  }
}

Widget types

Generic widget data specific for all widgets (with few exceptions).

{
  setting_id    = "setting_id",
  type          = "group/checkbox/dropdown/keybind/numeric",
  title         = "title_localization_id",
  tooltip       = "tooltip_localization_id",
  default_value = --[value](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/value),  -- all widgets, except 'group'
  sub_widgets   = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) } -- 'group', 'checkbox', 'dropdown' widgets
}

Options

• setting_id [string] Setting's identifier which will be used to save the value currently picked in this widget as the regular setting. This string will be also used as localization_id for widget's title, if title is not specified, and setting_id .. "_description" as tooltip's localization_id, if tooltip is not specified.
• type [string] Widget type.
• title [string?] Localization id of the widget's title.
• tooltip [string?] Localization id of the widget's tooltip.
• default_value [any] If setting with setting_id wasn't set before, it will be set to this value. (Exception: 'group' widget does not require default_value)
• sub_widgets [table] Child widgets of current widget. They can be hidden by either collapsing parent widget or by meeting some condition in parent widget.

It is advised to not specify title and tooltip, as it will add more visual clutter without any benefits, since setting_id is already used to localize the title and tooltip. So in the next examples they will be skipped.

Checkbox

• Setting type: [boolean]

Simple togglable widget with two states (on/off).

{
  setting_id    = "setting_id",
  type          = "checkbox",
  default_value = true,
  sub_widgets   = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) } -- optional
}

Options

Child widgets will be hidden when widget's setting is set to false.

Dropdown

• Setting type: [boolean | number | string]

Widget that allows to have 2 and more options to be picked from.

{
  setting_id    = "setting_id",
  type          = "dropdown",
  default_value = --[value](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/value),
  options = {
    {text = "option_one_localization_id",   value = --[value](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/value), show_widgets = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) }},
    {text = "option_two_localization_id",   value = --[value](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/value), show_widgets = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) }},
    {text = "option_three_localization_id", value = --[value](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/value), show_widgets = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) }},
    {text = "option_four_localization_id",  value = --[value](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/value), show_widgets = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) }},
    {text = "option_five_localization_id",  value = --[value](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/value), show_widgets = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) }}
  },
  sub_widgets = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) } -- optional
}

Options

• options [table] List of selectable options.
  • text [string] Option's localization_id.
  • value Widget's setting will be set to this value, when this option is picked.
  • show_widgets [table?] Table with indices of sub_widgets that will become visible, when this option is picked. If not specified, all sub_widgets will be hidden.

Group

This widget doesn't do anything by itself. It just groups other widgets.

{
  setting_id  = "setting_id",
  type        = "group",
  sub_widgets = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) }
}

This is the only widget that doesn't do anything with its setting. It's needed only for widget identifying.

Child widgets can be hidden only by widget collapsing.

Keybind

• Setting type: [table] (keybind data)

Allow the user to bind keys to actions.

!> Do not ship a mod with pre-binded keybinds unless it's absolutely necessary. You should let users define their own keybinds.

!> There are no checks for duplicated keybinds.

{
  setting_id      = "setting_id",
  type            = "keybind",
  default_value   = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) },
  keybind_global  = true,       -- optional
  keybind_trigger = "pressed/held",
  keybind_type    = "function_call/view_toggle/mod_toggle",
  function_name   = "whatever",   -- required, if (keybind_type == "function_call")
  view_name       = "whatever"    -- required, if (keybind_type == "view_toggle")
  transition_data = { --[...](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/...) } -- required, if (keybind_type == "view_toggle")
}

Widget's setting must be a table with 0-4 elements. 0 elements means the keybind is not specified. Specified keybind has to have at least [1] element. Elements [2], [3] and [4] are optional. All 4 elements should have a string type.

Options

• keybind_global [boolean?] If true, keybind will be triggered even when pressed in some menu / loading screen etc.
• keybind_trigger [string] when specified keybind's action is triggered.
  • pressed Keybind is pressed.
  • held 2 times: when keybind is pressed and when it's released.
• keybind_type [string] specifies keybind's action.
  • function_call Calls function, specified as mod.function_name. If keybind_trigger is held, calls it 2 times and passes true as the first parameter on the first call.
  • view_toggle Opens / closes custom view with view_name name.
  • mod_toggle Toggles mod's state (enables / disables it).
• function_name [string] Mod's function name to be called (keybind_type is "function_call").
• view_name [string] Custom view's name to be toggled (keybind_type is "view_toggle").
• transition_data [table] Transition data used for view toggling (keybind_type is "view_toggle").
  • open_view_transition_name [string?] Transition name which is used to open view. Only transitions registered for this view can be used.
  • close_view_transition_name [string?] Transition name which is used to close view.
  • open_view_transition_params [any?] Parameter to be passed to open view transition and to 'on_enter' view method.
  • open_view_transition_params [any?] Parameter to be passed to close view transition and to 'on_exit' view method.
  • transition_fade [boolean?] If screen should be faded to black for a moment when opening view and when closing it.

Numeric

• Setting type: [number]

Allow the user to select a number in a valid range.

Widget that allows user to set number value within certain range via widget's slider or manually.

{
  setting_id      = "setting_id",
  type            = "numeric",
  default_value   = 0,
  range           = {-100, 100},
  unit_text       = "unit_text_localization_id", -- optional
  decimals_number = 2                            -- optional
}

Options

• range [table] Defines minimum and maximum number's value. Must contain 2 elements of number type, such that range[1] < range[2]
• unit_text [string?] The localization_id of text which will be appended to the numeric value. It will be visible only in mod options and will not be appended to actual setting's value.
• decimals_number [any] Allowed number of decimal digits for widget's setting's value.

Text

• Setting type: [text]

Allow the user to type in a freeform string.

{
  setting_id      = "setting_id",
  type            = "text",
  default_value   = "Hello, World",
  max_length      = 15,             -- optional
  validate        = function(value) -- optional
      return true                   -- optional
  end                               -- optional
}

Options

• max_length [number?] Defines the maximum number of characters allowed in the value.
• validate [function?] Defines a custom function which can restrict what values are considered valid for this setting. It takes a [string] input and returns true if the input should be considered valid, or false/nil otherwise. If both max_length and validate are defined, then values will have to pass both checks.

Example

-- FILE: ./scripts/mods/my_mod/my_mod_data.lua
return {
  --[ other mod data ](/Vermintide-Mod-Framework/Vermintide-Mod-Framework/wiki/-other-mod-data-)
  options = {
    widgets = {
      {
        setting_id    = "foobar",
        type          = "checkbox",
        default_value = false,
      },
    },
  },
}

Keys

Main keys

Key Name	Value
Backspace	backspace
Tab	tab
Enter	enter
Caps Lock	caps lock
Space	space
Page Up	page up
Page Down	page down
End	end
Home	home
Left	left
Up	up
Right	right
Down	down
Insert	insert
Delete	delete
0	0
1	1
2	2
3	3
4	4
5	5
6	6
7	7
8	8
9	9
A	a
B	b
C	c
D	d
E	e
F	f
G	g
H	h
I	i
J	j
K	k
L	l
M	m
N	n
O	o
P	p
Q	q
R	r
S	s
T	t
U	u
V	v
W	w
X	x
Y	y
Z	z
Windows (Meta)	win
Right Windows (Meta)	right win
Numpad 0	numpad 0
Numpad 1	numpad 1
Numpad 2	numpad 2
Numpad 3	numpad 3
Numpad 4	numpad 4
Numpad 5	numpad 5
Numpad 6	numpad 6
Numpad 7	numpad 7
Numpad 8	numpad 8
Numpad 9	numpad 9
Numpad *	numpad *
Numpad +	numpad +
Numpad -	numpad -
Numpad .	numpad .
Numpad /	numpad /
Numpad Enter	numpad enter
F1	f1
F2	f2
F3	f3
F4	f4
F5	f5
F6	f6
F7	f7
F8	f8
F9	f9
F10	f10
F11	f11
F12	f12
Num Lock	num lock
Scroll Lock	scroll lock
Browser Back	browser back
Browser Forward	browser forward
Browser Refresh	browser refresh
Browser Stop	browser stop
Browser Search	browser search
Browser Favorites	browser favorites
Browser Home	browser home
Volume Mute	volume mute
Volume Down	volume down
Volume Up	volume up
Next Track	next track
Previous Track	previous track
Stop	stop
Play/Pause	play pause
Mail	mail
Media	media
Start Application 1	start app 1
Start Application 2	start app 2
; (Semicolon)	;
= (Equals sign)	=
, (Comma)	,
- (Hyphen-minus)	-
. (Full stop)	.
/ (Solidus)	/
` (Grave accent)	`
[ (Left square bracket)	[
\ (Reverse solidus)	\
] (Right square bracket)	]
' (Apostrophe)	'
Mouse Left	mouse left
Mouse Right	mouse right
Mouse Middle	mouse middle
Mouse Extra 1	mouse extra 1
Mouse Extra 2	mouse extra 2
Mouse Wheel Up	mouse wheel up
Mouse Wheel Down	mouse wheel down
Mouse Wheel Left	mouse wheel left
Mouse Wheel Right	mouse wheel right

Modifiers

Key Name	Value
Ctrl	ctrl
Alt	alt
Shift	shift