Creating a custom Menu

This tutorial will explain how to create a mod that adds a new menu that’s viewable by a footer in the main menu.

Setup

First, create a new folder with this mod.json:

{
        "Name": "CustomMenuTutorial",
        "Description": "Custom menu tutorial",
        "LoadPriority": 1,
        "Scripts": [
                {
                        "Path": "ui/custom_menu.nut",
                        "RunOn": "UI",
                        "UICallback": {
                                "Before": "AddCustomMenu"
                        }
                }
        ]
}

Then create custom_menu.nut in ./mod/scripts/vscripts/ui.

Minimal Example

Create AddCustomMenu in custom_menu.nut like this and make it global:

global function AddCustomMenu

void function AddCustomMenu()
{
        AddMenu( "CustomMenu", $"resource/ui/menus/custommenu.menu", CustomMenu_Init )
}

AddCustomMenu will get called when the UI vm is initializing and instantiate your menu. You can access your menu with GetMenu( "CustomMenu" ) after it has been initialized.

Next, create the file that defines the layout of your menu. It’s already referenced in the above code at $"resource/ui/menus/custommenu.menu". Create the file ./mod/resource/ui/menus/custommenu.menu and paste this code in it.

.menu configuration

resource/ui/menus/custommenu.menu
{
        menu
        {
                ControlName Frame
                xpos 0
                ypos 0
                zpos 3
                wide f0
                tall f0
                autoResize 0
                visible 1
                enabled 1
                pinCorner 0
                PaintBackgroundType 0
                infocus_bgcolor_override "0 0 0 0"
                outoffocus_bgcolor_override "0 0 0 0"

                Vignette // Darkened frame edges
                {
                        ControlName ImagePanel
                        InheritProperties MenuVignette
                }

                Title // The title of this menu
                {
                        ControlName Label
                        InheritProperties MenuTitle
                        labelText "#CUSTOM_MENU_TITLE"
                }


/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// Content
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

                SomeLabel // A label that is placed in the middle of the screen
                {
                        ControlName Label

                        labelText "Some Label"

                        auto_wide_tocontents 1 // Set width automatically relative to the label content

                        xpos %50
                        ypos %50
                }

                SomeButton // A button that is placed directly beneath the label
                {
                        ControlName RuiButton
                        InheritProperties RuiSmallButton

                        tall 50
                        wide 250

                        labelText "Some Button"
                        textAlignment center

                        pin_to_sibling SomeLabel
                        pin_corner_to_sibling TOP
                        pin_to_sibling_corner BOTTOM
                }

/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// Footer
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

                FooterButtons // Allow adding footers to this menu
                {
                        ControlName                     CNestedPanel
                        InheritProperties       FooterButtons
                }
        }
}

Now you’ll need to define CustomMenu_Init. This is the function previously defined that contains all initializations needed for this menu.

First, create an instantiated struct for variables that should be available in the scope of your custom menu script.

struct {
        var menu
} file

At the moment, this struct can only contain your menu. To set it, edit AddCustomMenu like this:

 void function AddCustomMenu()
 {
        AddMenu( "CustomMenu", $"resource/ui/menus/custommenu.menu", CustomMenu_Init )
+       file.menu = GetMenu( "CustomMenu" )
 }

Now, define CustomMenu_Init. It doesn’t need to be global.

void function CustomMenu_Init()
{
        AddMenuFooterOption( file.menu, BUTTON_B, "#B_BUTTON_BACK", "#BACK" )
}

This adds a footer to your menu, that allows the user to navigate back.

Adding a footer to the Main menu

Currently, there is no way to access your menu. You can open your (or any other menu) with AdvanceMenu.

AdvanceMenu( GetMenu( "CustomMenu" ) )

This is useful for callbacks triggered by button presses like from footers. To add a footer to the Main menu, first edit your mod.json code callbacks:

 "Scripts": [
        {
                "Path": "ui/custom_menu.nut",
                "RunOn": "UI",
                "UICallback": {
+                       "Before": "AddCustomMenu", // <- Notice the added comma
+                       "After": "AddCustomMenuFooter"
                }
        }
 ]

We need a new callback that’s run after all menus are initialized to add any footers to them. Create the global function AddCustomMenuFooter in custom_menu.nut like this:

void function AddCustomMenuFooter()
{
        AddMenuFooterOption(
                GetMenu( "MainMenu" ), // Get the main menu. We want to add a footer to this one. Change this if you want to add a footer to another menu
                BUTTON_X, // This sets the gamepad button that will trigger the click callback defined later
                PrependControllerPrompts( BUTTON_X, " Custom Menu" ), // This is the text that will show as the label of the footer if a gamepad is used
                "Custom Menu", // This is the label text of the footer if no gamepad is used
                void function( var button ) // This is the click callback.
                {
                        /*
                                This is an anonymous function.
                                It will be run every time the footer is pressed.
                        */
                        AdvanceMenu( file.menu )
                }
        )
}

Scripting Menu Logic

Adding a Counter

We’ll use the button we defined earlier in the .menu file to increase a number of clicks and the label to show how often the user has clicked that button.

first, add someLabel and clicks to the file struct. Then define the label in the AddCustomMenu and add a callback to the button.

 struct {
        var menu
+       var someLabel
+       int clicks
 } file

 void function AddCustomMenu()
 {
        AddMenu( "CustomMenu", $"resource/ui/menus/custommenu.menu", CustomMenu_Init )
        file.menu = GetMenu( "CustomMenu" )
+       file.someLabel = Hud_GetChild( file.menu, "SomeLabel" )

+       var someButton = Hud_GetChild( file.menu, "SomeButton" )
+       Hud_AddEventHandler( someButton, UIE_CLICK, OnSomeButtonClick )
 }

Now you need to define the OnSomeButtonClick callback that’s triggered when the button is activated.

void function OnSomeButtonClick( var button )
{
        file.clicks++
        Hud_SetText( file.someLabel, format( "clicked the button %i times", file.clicks ) )
}

Adding a Reset Button

First you need to add a definition in your custommenu.menu file:

ResetButton
{
        ControlName RuiButton
        InheritProperties RuiSmallButton

        tall 50
        wide 250

        labelText "Reset Counter"
        textAlignment center

        pin_to_sibling SomeButton
        pin_corner_to_sibling TOP
        pin_to_sibling_corner BOTTOM
}

Then add a UIE_CLICK callback for the button. It also makes sense to move the code that updates the label text to it’s own function so it can be reused by the reset button.

 void function AddCustomMenu()
 {
        AddMenu( "CustomMenu", $"resource/ui/menus/custommenu.menu", CustomMenu_Init )
        file.menu = GetMenu( "CustomMenu" )
        file.someLabel = Hud_GetChild( file.menu, "SomeLabel" )

        var someButton = Hud_GetChild( file.menu, "SomeButton" )
+       var resetButton = Hud_GetChild( file.menu, "ResetButton" )

        Hud_AddEventHandler( someButton, UIE_CLICK, OnSomeButtonClick )
+       Hud_AddEventHandler( resetButton, UIE_CLICK, OnResetButtonClick )
 }

 void function OnSomeButtonClick( var button )
 {
        file.clicks++
-       Hud_SetText( file.someLabel, format( "clicked the button %i times", file.clicks ) )
+       UpdateClickLabel()
 }

 void function OnResetButtonClick( var button )
 {
        file.clicks = 0
+       UpdateClickLabel()
 }

+void function UpdateClickLabel()
+{
+       Hud_SetText( file.someLabel, format( "clicked the button %i times", file.clicks ) )
+}

Resetting the Counter when the Menu is closed

You can add callbacks for menu events, for example when a menu is closed or opened.

If you want to reset the counter if the menu is closed, edit AddCustomMenu like this:

 void function AddCustomMenu()
 {
        AddMenu( "CustomMenu", $"resource/ui/menus/custommenu.menu", CustomMenu_Init )
        file.menu = GetMenu( "CustomMenu" )
        file.someLabel = Hud_GetChild( file.menu, "SomeLabel" )

        var someButton = Hud_GetChild( file.menu, "SomeButton" )
        var resetButton = Hud_GetChild( file.menu, "ResetButton" )

        Hud_AddEventHandler( someButton, UIE_CLICK, OnSomeButtonClick )
        Hud_AddEventHandler( resetButton, UIE_CLICK, OnResetButtonClick )

+       AddMenuEventHandler( file.menu, eUIEvent.MENU_CLOSE, OnCloseCustomMenu )
 }

And define the callback OnCloseCustomMenu to simply call OnResetButtonClick.

void function OnCloseCustomMenu()
{
        OnResetButtonClick( null )
}