UIs

UIs stands for User Interfaces, and UI scripting API (Application Programming Interface) allows creating custom Graphical UIs using JS scripts (if you don't know how to script, see the linked page).

Mechanism

The way it works is you create a UI builder using mappet.createUI(), and then use this UI builder to populate it with different UI components. Once the UI is built, you can send it to a player using IScriptPlayer.openUI(IMappetUIBuilder) function.

User input handling

Most of UI components offer user input (clickable components, keybinds, data input: text, toggles, numbers, etc.). This data can be handled by providing the script and function to mappet.createUI(String, String) that should handle the input.

In that script, you can query the data and last handled component that user interacted it.

function main(c)
{
    /* Create a UI builder which later can be sent */
    var ui = mappet.createUI(c, "handler").background();
    var textbox= ui.textbox().id("name").tooltip("Enter your name:");

    /* Position text box in the middle of the screen */
    textbox.rxy(0.5, 0.5).wh(160, 20).anchor(0.5);

    /* Send configured UI screen to the player */
    c.getSubject().openUI(ui);
}

function handler(c)
{
    var s = c.getSubject();
    var uiContext = s.getUIContext();

    if (uiContext.getLast() === "name")
    {
        s.send(uiContext.getData().getString("name"));
    }
}

To handle the data, you must specify component's ID using UIComponent.id(String) function (like it was done in the example above: ui.textbox().id("name")). If a component that can send the data has no ID, no data will be sent.

For further guidance, refer to either online or in-game documentation about UI scripting. If you'll have troubles with documentation, feel free to ask on the Discord server.

Documentation

Documentation about UI API can be found in the UI package. Alternatively, check UI API section of in-game scripting documentation. There are plenty of copy-pastable code examples which you can play around and learn:

Example

Here is a very basic example of a custom UI that adds a button in the middle of the screen, and upon clicking the button, it will drop a diamond on top of player's head.

function main(c)
{
    /* Create a UI builder which later can be sent */
    var ui = mappet.createUI(c, "handler").background();
    var button = ui.button("Give me a diamond!").id("button");

    /* Position button in the middle of the screen */
    button.rxy(0.5, 0.5).wh(160, 20).anchor(0.5);

    /* Send configured UI screen to the player */
    c.getSubject().openUI(ui);
}

/**
 * This is a UI handler, it gets called every time GUI on the 
 * client side will send UI data. 
 * 
 * mappet.createUI(c, "handler") is the line in main function 
 * that is responsible for setting script handler.
 */
function handler(c)
{
    var s = c.getSubject();
    var uiContext = s.getUIContext();

    /* Check if the last active element was button */
    if (uiContext.getLast() === "button")
    {
        var pos = s.getPosition();
        var diamond = mappet.createItem("minecraft:diamond");

        c.getWorld().dropItemStack(diamond, pos.x, pos.y + 2, pos.z);
    }
}