search

Bolt-Scripts / MHR-InGame-ModMenu-API

A user-friendly IMGUI inspired API for drawing in-game settings menus for REF mods in MHRise
13 stars 4 forks source link

readme

ModOptionsMenu

Example

Look at the ModUI_ExampleTest.lua file for a more detailed example to get your feet wet.


local modUI = require("ModOptionsMenu.ModMenuApi");

local someSettingValue = false;
local optionIdx = 1;

local options = {"Option1", "Option2"};

local name = "Example Mod";
local description = "It's just a test mod.";
local modObj = modUI.OnMenu(name, description, function()

    local changed;

    modUI.Header("Header");

    changed, someSettingValue = modUI.CheckBox("CheckBox", someSettingValue, "Some optional toolip style message here.");

    changed, optionIdx = modUI.Options("Options", optionIdx, options);

    --and so much more

end)


API

local ModUI = require("ModOptionsMenu.ModMenuApi")

Do something like this to import the api into your script. It can be called anything you'd like.

ModUI.OnMenu(name, description, uiCallback)

Register your mod to the options menu.

Params:

Returns: an object containing the mod's data

Notes:

Technically you can register multiple mods through this but I would advise against it.
Make sure to only call this once for the menu you want to add and NOT inside of some kind of update function.

ModUI.Header(text)

Displays a non-interactable header message to divide your ui sections.

Notes:

Displaying two headers right next to each other allows one to be selectable with a gamepad.

ModUI.FloatSlider(label, curValue, min, max, toolTip, isImmediateUpdate)

Draws a float slider.

Params:

Returns: (tuple of) wasChanged, newValue

Notes:

Keep in mind this value only has precision to the nearest hundreth due to the game's limitations.

ModUI.Slider(label, curValue, min, max, toolTip, isImmediateUpdate)

Draws an integer slider.

Params:

Returns: (tuple of) wasChanged, newValue

ModUI.Options(label, curValue, optionNames, optionMessages, toolTip, isImmediateUpdate)

Draws a cycle-able set of options for the user to choose between.

Params:

Returns: (tuple of) wasChanged, newIndex

Notes:

lua is NOT zero indexed, and neither is the input/output index of this function.
The tables you give should be declared as variables OUTSIDE the scope of your UI callback.
This is to avoid creating a new table every frame causing the UI to redraw every frame which breaks things.

ModUI.CheckBox(label, curValue, toolTip)

An easily clickable checkbox useful for on/off values where the user doesn't have to manually select on or off

Params:

Returns: (tuple of) wasChanged, onOffValue

ModUI.Toggle(label, curValue, toolTip, (optional)togNames[2], (optional)togMsgs[2], isImmediateUpdate)

Basically a wrapper around ModUI.Options that only takes two options and returns the result as a boolean instead of an index

Params:

Returns: (tuple of) wasChanged, onOffValue

Notes:

The tables you give should be declared as variables OUTSIDE the scope of your UI callback.
This is to avoid creating a new table every frame causing the UI to redraw every frame which breaks things.

ModUI.Button(label, prompt, isHighlight, toolTip)

Draws clickable element in the GUI

Params:

Returns: (boolean) wasClicked

ModUI.Label(label, displayValue, toolTip)

Just draws some text

Params:

ModUI.PromptYN(promptMessage, callback(result))

Displays a system message prompt with an option to select yes or no.

Params:

Notes:

The result in the callback will be true if the user selected `Yes`, and false if `No`.

ModUI.PromptMsg(promptMessage, callback)

Displays a system message prompt.

Params:

Notes:

The normal UI is not updated while the prompt is open.


Rich Text:

The game has its own sort of 'rich text' functionality, currently I only really know how to use colors.
I think there's a system for displaying button icons through text but you'd have to figure that out yourself.

Built-in Colors:

ModUI.AddTextColor(colName, colHexStr)

Params:


Layout Functions:

Notes:

You can have fairly dynamic UI layouts, but keep in mind every time something changes the entire UI needs to be rebuilt. Also the practical limits of how many elements you can have in one menu is untested currently.


Rare Functions: