Editing Menus

This guide does not apply to the Settings Menu. Please refer to its specific page if that's what you are looking for.

As of 0.8.3, a new service callback has been added to the game, called AddMenu. This callback can be used by modders to edit menus on the fly right before they appear on screen. This guide exists as a way to explain how this callback works and how to use it.

Prerequisites

This guide assumes that the user is capable of writing Services and Creating Menus. Please refer to these pages if anything is unclear. The user is also expected to be able to navigate the RogueEssence repository, specifically looking into its Menu folder and its subfolders.

With the advent of 0.8.3, the callback AddMenu has been added to the game. This message is sent to services just before a menu is displayed so that modders can add, remove or modify its elements at their heart's content. What can be edited and how depends on the menu itself.

There are three broader types of Menus. Each of them has one Scriptable counterpart and they are InteractableMenu, ChoiceMenu and MultiPageMenu. Being able to differentiate between them is the key to know how to interact with the menu you're looking to edit. Furthermore, we will need the menu's Label. A Label is a little string property that serves to identify a menu. Lucky for us, the game already guves us everything we need to know: if a menu has a label, its Menu Type and its Label will be displayed in the dev mode's output console every time you open it. So... let's check it out! Here's what happens when we open the OthersMenu, for example:

This is already everything we need. We can now start working on our changes.

How to edit a menu

Say we want to reproduce what the menu_tools service does in the base game. Now that we have our menu type and our label, we need to write our AddMenu callback. Since the AddMenu event message contains an argument, you will need to pass that argument on to your callback like this:
med:Subscribe("MenuTools", EngineServiceEvents.AddMenu, function(_, args) self:OnAddMenu(args[0]) end )

Now we write the function. Here's what menu_tools does:

function MenuTools:OnAddMenu(menu)
    if RogueEssence.GameManager.Instance.CurrentScene == RogueEssence.Dungeon.DungeonScene.Instance
            and menu:HasLabel() and menu.Label == "OTHERS_MENU" then
        local index = menu:GetChoiceIndexByLabel("OTH_SETTINGS")
        if index <0 then index = math.min(1, menu.Choices.Count) end
        local choices = menu:ExportChoices()
        choices:Insert(index, RogueEssence.Menu.MenuTextChoice("OTH_RECRUIT", RogueEssence.StringKey("MENU_RECRUITMENT"):ToLocal(), function () _MENU:AddMenu(RecruitmentListMenu:new().menu, false) end))
        menu:ImportChoices(choices)
    end
end

Now, what does this all mean? Let's analyze it one step at a time. First things first, this new option must only appear while inside a dungeon, so the first part of the if statement makes sure that's the case. We must then check if the menu that has been opened has a label, and, if it does, check if it's the label we're looking for.

Now that we know that this is the right menu, we want to add our new option just above Settings. Since menu elements can also have labels, we ask the menu for the index of its OTH_SETTINGS option and save that value. The function then checks if the number is valid, and defaults to slot 1 if it isn't, or even 0 if the menu is empty for some reason. If you need a label, you can look them up inside of the ILabeled.cs file.

Finally, we apply the change: We first export the current list of choices, then add our new MenuTextChoice in the spot we chose and then load our edited list using ImportChoices.

Functions

Now that we know how editing a menu looks like, it's time to explore all the tools offered by the engine.

ILabeled

These properties and functions are included in every single Menu and MenuElement in the game, including SummaryMenus.

ILabeled.Label

An optional, read-only string identifier for this object. It is recommended to always use HasLabel before accessing it.

ILabeled:HasLabel()

Returns true if the object's Label is not an empty string. False otherwise.

ILabeled:LabelContains(System.String)

Returns true if the object's Label is not empty and it contains the provided string. False otherwise.

Arguments

• substr: the string to look for.

MenuBase

These properties and functions are included in every single Menu in the game, including SummaryMenus.

MenuBase.Elements

The List of MenuElements inside this menu. This list can be interacted with directly to add or remove elements.

MenuBase.GetElementIndexByLabel(System.String)

Iterates through the Elements list and returns the index of the first element found whose Label matches the provided string. If no such element is found, it returns -1.

Arguments

• label: the label to look for.

MenuBase.GetElementIndicesByLabel(params System.String[])

Iterates through the Elements list and returns a Dictionary containing all unique strings provided and the index of the first element found whose Label matches that specific string. Every string for which no such element is found will have its index set to -1.
You can retrieve a specific label's index with ret[label]. Keep in mind that these values do not update automatically if elements are removed.

Arguments

• labels one or more labels or, alternatively, an array of labels to look for.

InteractableMenu

Any menu included in an AddMenu service message is an InteractableMenu, and will have all these properties and methods plus those described in the ILabeled and MenuBase sections.

InteractableMenu.SummaryMenus

The List of SummaryMenus used by this menu. This list can be interacted with directly to add or remove SummaryMenus.

InteractableMenu.GetSummaryIndexByLabel(System.String)

Iterates through the SummaryMenus list and returns the index of the first summary menu found whose Label matches the provided string. If no such summary menu is found, it returns -1.

Arguments

• label: the label to look for.

InteractableMenu.GetSummaryIndicesByLabel(params System.String[])

Iterates through the SummaryMenus list and returns a Dictionary containing all unique strings provided and the index of the first summary menu found whose Label matches that specific string. Every string for which no such summary menu is found will have its index set to -1.
You can retrieve a specific label's index with ret[label]. Keep in mind that these values do not update automatically if summary menus are removed.

Arguments

• labels one or more labels or, alternatively, an array of labels to look for.

ChoiceMenu

Any menu that has a list of choices to select from is a ChoiceMenu, and will have all these properties and methods plus those described in the ILabeled, MenuBase and InteractableMenu sections. Interacting with the Choices list directòy can have inconsistent results, so it's recommended to use ImportChoices and ExportChoices instead.

ChoiceMenu.Choices

The list of MenuChoice elements that can be selected in this menu.

ChoiceMenu.NonChoices

The list of elements that are not choices, but are still part of this menu. An example is the title of the OthersMenu.

ChoiceMenu.Elements

This list is actually just an alias of NonChoices. You can use either and achieve the same result, but it is recommended to use NonChoices for better code clarity.

ChoiceMenu.ExportChoices()

Returns a copy of the current Choices list that can then be edited at will.

ChoiceMenu.ImportChoices(System.Collections.Generic.List<RogueEssence.Menu.IChoosable>)

Loads a list of IChoosables as the new Choices list and runs all of the necessary steps to fully reload the menu.

Arguments

• choices: a list of IChoosable elements.

ChoiceMenu.ImportChoices(params RogueEssence.Menu.IChoosable[])

Loads an array or a parameter list of IChoosables as the new Choices list and runs all of the necessary steps to fully reload the menu.

Arguments

• choices: an array or parameter list of IChoosable elements.

ChoiceMenu.GetChoiceIndexByLabel(System.String)

Iterates through the Choices list and returns the index of the first element found whose Label matches the provided string. If no such element is found, it returns -1.

Arguments

• label: the label to look for.

ChoiceMenu.GetChoiceIndicesByLabel(params System.String[])

Iterates through the Choices list and returns a Dictionary containing all unique strings provided and the index of the first element found whose Label matches that specific string. Every string for which no such element is found will have its index set to -1.
You can retrieve a specific label's index with ret[label]. Keep in mind that these values do not update automatically if elements are removed.

Arguments

• labels one or more labels or, alternatively, an array of labels to look for.

ChoiceMenu.GetNonChoiceIndexByLabel(System.String)

Iterates through the NonChoices list and returns the index of the first element found whose Label matches the provided string. If no such element is found, it returns -1.

Arguments

• label: the label to look for.

ChoiceMenu.GetNonChoiceIndicesByLabel(params System.String[])

Iterates through the NonChoices list and returns a Dictionary containing all unique strings provided and the index of the first element found whose Label matches that specific string. Every string for which no such element is found will have its index set to -1.
You can retrieve a specific label's index with ret[label]. Keep in mind that these values do not update automatically if elements are removed.

Arguments

• labels one or more labels or, alternatively, an array of labels to look for.

MultiPageMenu

Any ChoiceMenu whose list of choices takes up -or can take up- multiple pages is a MultiPageMenu, and will have all these properties and methods plus those described in the ILabeled, MenuBase, InteractableMenu and ChoiceMenu sections. Interacting with the Choice list is, however, highly discouraged, because it would only contain one page at a time. Use ImportChoices and ExportChoices instead.

MultiPageMenu.TotalChoices

The 2d matrix of IChoosables that contains all choices inside this menu, divided per page.

MultiPageMenu.ExportChoices()

Returns a List of all IChoosables contained by the menu in the order they appear in.

MultiPageMenu.ImportChoices(System.Collections.Generic.List<RogueEssence.Menu.IChoosable>)

Loads a list of IChoosables and registers it as the new TotalChoices matrix, running all of the necessary steps to fully reload the menu.

Arguments

• choices: a list of IChoosable elements.