Note 8/Sept/2023: It's been a long time since I worked on this! I've tried and failed to start working on an update multiple times, but I still want to do it someday. For the time being, if you have questions, you can contact me on Discord at @josbird as mentioned at the bottom of the description. I can't guarantee I'll remember all the details of how it works, but I'll do my best to help!

Welcome to Josbird's Cursor Menu!

NEW UPDATE: VERSION 1.1! Many improvements over version 1.0. See update log for major details. New quick guide below!

Note: if you need to make changes to a mode that still uses the 1.0 version of Josbird's Cursor Menu, I've converted and saved the old guide here.

Table of contents

• The basic structure of a button
• Creating a button
• Destroying a menu button
• Detecting button presses
• Modifying buttons
• Getting the properties of an existing button
• Workshop Settings
• Considerations for the Workshop's 128 texts limit
• Planned features
• Update log

The basic structure of a button

Each button is defined by an array with 13 values, as described in the following table:

In order to assist with sizing click areas, I recommend turning on Debug Mode in the Workshop Settings menu during development.

Back to top

Creating a button

As of version 1.1, creating a button works similarly to (for example) Create Effect or Create HUD Text. Buttons persist between openings of the menu, and exist in a per-player context.

To create a button at any time during your script, do the following:

1. Set the player variable newButton equal to the properties you want the new button to have, according to the properties listed in the table above.
2. Use Call Subroutine to run the createMenuButton subroutine.
3. The button will be created.
4. After running the subroutine, the player variable lastMenuButtonID will contain the ID of the button you just created, similar to Last Created Entity or Last Text ID. To store the button for later modification, save the contents of lastMenuButtonID to another variable.

rule("Create ultimate button")
{
    event
    {
        Ongoing - Each Player;
        All;
        All;
    }

    conditions
    {
        Has Spawned(Event Player) == True;
    }

    actions
    {
        Event Player.newButton = Array(Custom String("Fill Ultimate"), Custom String("ult"), Null, 3, 0, 1, 1, 0.300, Color(Aqua), Color(
            Yellow), True, True, True);
        Call Subroutine(createMenuButton);
        Event Player.UltimateButton = Event Player.lastMenuButtonID;
    }
}

Note that these properties are stored in an internal array, so they do not update unless the array itself is updated. This means that any time you want to change the text, size, position, or any other property of a button while the menu is open, you must use the modifyMenuButton subroutine as detailed in Modifying a button.

Back to top

Destroying a menu button

As of version 1.1, creating a button works similarly to (for example) Destroy Effect or Destroy Icon. You will need to have a valid button ID obtained from saving the value of lastMenuButtonID after creating a button, in order to destroy the button corresponding to that ID. To destroy an existing button at any time during your script, do the following:

1. Set the player variable destroyButtonID equal to the ID of the button you want to destroy.
2. Use Call Subroutine to run the destroyMenuButton subroutine.
3. The button will be destroyed. No additional actions are necessary.

If there is an issue with the ID passed to destroyMenuButton, the subroutine will log an error to the inspector.

rule("Destroy ultimate button")
{
    event
    {
        Ongoing - Each Player;
        All;
        All;
    }

    conditions
    {
        Is Button Held(Event Player, Button(Melee)) == True;
    }

    actions
    {
        Event Player.destroyButtonID = Event Player.UltimateButton;
        Call Subroutine(destroyMenuButton);
    }
}

Back to top

Detecting button presses

As stated in the basic structure of a button, whenever a button is clicked, the currActionID variable is set equal to that button's Action ID for up to one server tick. Using this, you can detect button presses by setting up a rule that checks when currActionID is equal to the desired action.

rule("Fill ultimate charge")
{
    event
    {
        Ongoing - Each Player;
        All;
        All;
    }

    conditions
    {
        Event Player.currActionID == Custom String("ult");
    }

    actions
    {
        Set Ultimate Charge(Event Player, 100);
        Communicate(Event Player, Thanks);
    }
}

Keep in mind that an Action ID does not have to be a Custom String. If I wanted to have a variety of buttons that did a similar action, but with a different value for each one, I could set those buttons' action IDs to, say, a number between 101 and 109. Then I could use one rule whose conditions check that the ID is within that range, then subtracts 100, and now I can perform some action based on that "argument" of a number from 1 to 9. An action ID could even be an array, with the first index determining the action type and the rest of the indices indicating multiple arguments!

Back to top

Modifying buttons

The properties of a button are stored internally by the script in an array. For this reason, buttons are not capable of reevaluation the same way a normal workshop effect or text is. However, buttons are not entirely static, and can be modified as detailed below.

As of version 1.1, modifying the properties of a button is handled internally. You will need to have a valid button ID obtained from saving the value of lastMenuButtonID after creating a button, in order to modify the button corresponding to that ID. You will also need the index of each property you want to change according to the table in the basic structure of a button, as well as a value you want to change that property to. Then you must do the following:

1. Set the player variable buttonModification to an array containing the following values:

   Array Index	Value
   0	The ID of the button to be modified
   1	The index of the first property to be changed
   2	The new value of the corresponding property
   3+	(Optional) Additional index-value pairs for other properties you want to change

2. Use Call Subroutine to run the modifyMenuButton subroutine.

3. The button will be modified. No additional actions are necessary.

If there is an issue with the arguments passed to modifyMenuButton, the subroutine will log an error to the inspector.

Note that scale does not reevaluate in In-World Texts. To resize a button, you must toggle its visibility after modifying its size.

rule("Move ultimate button")
{
    event
    {
        Ongoing - Each Player;
        All;
        All;
    }

    conditions
    {
        Is Button Held(Event Player, Button(Melee)) == True;
    }

    actions
    {
        Event Player.buttonModification = Array(Event Player.UltimateButton, 5, 0);
        Call Subroutine(modifyMenuButton);
    }
}

Back to top

Getting the properties of an existing button

Sometimes, you may want to modify a button property based on its previous value instead of replacing it entirely. In this case, you can use getButtonProperties to get a copy of the button's properties array, which you can then use to find the current value of a specific property, modify it, then pass back to modifyMenuButton.

1. Set the player variable getProperties equal to the ID of the button whose properties you want to retrieve.
2. Use Call Subroutine to run the getButtonProperties subroutine.
3. After running the subroutine, the player variable getProperties will be replaced with an array corresponding to the properties of the button, according to the table in the basic structure of a button.

rule("Get ultimate button action ID")
{
    event
    {
        Ongoing - Each Player;
        All;
        All;
    }

    conditions
    {
        Is Button Held(Event Player, Button(Melee)) == True;
    }

    actions
    {
        Event Player.getProperties = Event Player.UltimateButton;
        Call Subroutine(getButtonProperties);
        Small Message(Event Player, Custom String("Fill Ultimate button's action ID: '{0}'", Event Player.getProperties[1]));
    }
}