MenuBuilder - segabl/pd2-hoplib GitHub Wiki

The MenuBuilder automatically builds a mod options menu from a provided settings table and sets up all the needed menu elements and callback functions.

A minimal example usage of the MenuBuilder looks like this:

TestMod = {}
TestMod.settings = {
  toggle = true,
  value = 0
}

local builder = MenuBuilder:new("test_mod", TestMod.settings)
builder:create_menu_build_hook()

In the above example a new menu will be created in the BLT Mod Options, the setting toggle will turn into a checkbox and the setting value will turn into a slider with a minimum value of 0 and a maximum value of 1.

Customizing settings

You can provide additional settings for creating the menu elements via the optional params argument. This parameter should be a table with keys of same name as the keys in your main settings table and the values for them should be tables containing some information about that specific setting.

Setting slider values

You can specify min, max and step for a slider, which will control the minimum and maximum allowed values of that menu element, as well as the step size when the arrow keys are pressed on it. The defaults are min = 0, max = 1 and step = 0.1.

Turning a setting into multi-select menu element

If the table contains an items entry, this is used to make a multi-select menu element instead of the default slider for a number value setting.

Menu element ordering

You can specify the priority for the created menu element of a setting, which determines the sorting of elements. By default, menu elements will be sorted in the order they are added (which depends on Lua's table keys), you can overwrite that by specifying a priority value.

Dividers

If you want to add some padding around specific menu entries, you can specify a divider value which will put some space before or after the element, depending on the value. A negative number will put a divider of that size before the menu entry, positive number will put it after the entry.

Callbacks

You can add a callback function that is executed whenever that setting is changed by adding the callback key and setting it to a function.

Preventing menu element creation

If you want to prevent a specific setting from showing up in the menu altogether you can add a hidden key and setting it to true.

Adjusted example

Changing the code from the first example:

TestMod = {}
TestMod.settings = {
  toggle = true,
  value = 0
}
TestMod.values = {
  value = {
    items = { "dialog_yes", "dialog_no" },
    priority = 99,
    divider = 16,
    callback = function () log("menu item has been changed") end
  }
}

local builder = MenuBuilder:new("test_mod", TestMod.settings, TestMod.values)
builder:create_menu_build_hook()

This would result in the value setting turning into a multi-select instead and being displayed as the first element of the menu. The menu entry will have a spacing of 16 pixels to the next entry and the callback function will be called everytime the selection of the multi-select changes.

Sub-Menus

You can create sub-menus by adding table values to your settings table, and specifying some details for the sub-menu via the optional values argument will pass down those values to any child elements in that table and be used as default for them if no other values are specified.

Simple example of a sub-menu with its children elements inheriting values from it:

TestMod.settings = {
  toggle = true,
  submenu = {
    value1 = 0,
    value2 = 0
  }
}
TestMod.values = {
  submenu = {
    items = { "dialog_yes", "dialog_no" }
  }
}

local builder = MenuBuilder:new("test_mod", TestMod.settings, TestMod.values)
builder:create_menu_build_hook()

This will result in a sub-menu with both the value1 and value2 setting turning into a multi-select element.

Buttons

A setting which has a function as its value will result in a button menu element that executes that function when clicked.

Example of a button that prints text to the log file when it's clicked:

TestMod.settings = {
  button = function ()
    log("Hello World!")
  end
}

local builder = MenuBuilder:new("test_mod", TestMod.settings)
builder:create_menu_build_hook()

Localization

When creating the MenuBuilder, it looks for existing localization in the form of menu_ID_SETTING and menu_ID_SETTING_desc where ID is the id you specified when creating the MenuBuilder and SETTING is the name of the setting in the settings table. The main menu node is using menu_ID and menu_ID_desc. If these localization strings can't be found, the MenuBuilder automatically creates localization strings based on the settings names. Localization strings for menu items of multi-select elements always have to be created manually.

In the examples above, we set the identifier of the MenuBuilder to test_mod, so the localization keys it will look for to display the main menu node would be menu_test_mod and menu_test_mod_desc.

Saving and loading

Note that you don't have to call the save_settings or load_settings functions manually in most cases. Settings are loaded when the MenuBuilder is created and saved whenever you leave the mod options menu. The functions are there in case you need to save/load data manually for some special usecase.