Creating NUI Screens

Suggested Resources

Destination Sol shares both the NUI library and NUI JSON format with Terasology. As such, most Terasology resources for NUI should be easily adaptable to work with Destination Sol. To start learning how to use NUI in general, we'd recommend the following resources:

• Terasology's NUI Tutorial
• NUI Widgets
• MigLayout - this particular layout can be very versatile if used correctly

NUI Screens

NUI screens are found in the assets/ui directory and have a file extension of .ui. The actual file format though is JSON. The JSON typically uses the following structure:

{
    "type": "MyScreen",
    "skin": "engine:default",
    "contents": {
        // Your root widget goes here. Typically this is some sort of layout.
        "type": "RelativeLayout",
        "contents": [
            // Your screen widgets here..
            {
                "type": "UILabel",
                "id": "myLabel",
                "text": "This is the default text."
            }
        ]
    }
}

NUI Skins

NUI skins are used to style widgets. They determine things like the size, scaling and appearance. These properties can be applied generally to all widgets of a type, or specifically to elements of a particular family. NUI skins are found in the assets/skins directory and have a file extension of .skin. The underlying file format is also JSON. The structure of UI skin files is as follows:

{
    "inherit": "engine:default",
    "families": {
        "familyA": {
            "elements": {
                "UIButton": {
                    "text-color": "FF0000FF"
                }
            }
        },
        "familyB": {
            "elements": {
                "UILabel": {
                    "text-align-horizontal": "left"
                },
                "font": "engine:main#1.0"
            }
        }
    },
    "elements": {
        "UIButton": {
            "font": "engine:main#2.0",
            "background": "engine:boxDisabled"
        },
        "UILabel": {
            "font": "engine:main#1.4",
            "text-align-vertical": "top",
            "modes": {
                "enabled": {
                    "text-color": "FFFFFFFF"
                },
                "disabled": {
                    "text-color": "888888FF"
                }
            }
        }
    }
}

NUI Screen Logic

All NUI screens must be backed by a class implementing the screen logic. The class should inherit from NUIScreenLayer, which provides entry points for the screen's lifecycle.

package org.destinationsol.ui.nui.screens;

import org.destinationsol.SolApplication;
import org.destinationsol.ui.nui.NUIScreenLayer;
import org.terasology.nui.widgets.UILabel;

public class MigTestScreen extends NUIScreenLayer {
    // You can reference certain in-game classes using the @In annotation
    @In
    private SolApplication solApplication;

    @Override
    public void initialise() {
        // This should only be called once, when the screen is loaded.
        // Store references to UI widgets and other one-time things here.

        // Obtain a reference to a UILabel with id myLabel
        UILabel myLabel = find("myLabel", UILabel.class);
        // Set the text of the label
        myLabel.setText("This is some text set from code.");
    }

    @Override
    public void onAdded() {
        // Do stuff to get ready for the screen being shown here.
    }

    @Override
    public void onRemoved() {
        // Clean-up before the screen closes here.
    }
}

Adding/Removing NUI screens

NUIManager is the the class responsible for managing NUI screens. It is automatically referenced in NUI screens via the nuiManager variable. You can access NUIMnaager globally using SolApplication#getNuiManager().

In order to use a screen, you need to create an instance of it. You can load a screen using NUIManager#createScreen(String).

MyScreen myScreen = (MyScreen) nuiManager.createScreen("myModule:myScreen");

To add a screen, you use NUIManager#pushScreen.

nuiManager.pushScreen(myScreen);

To remove a screen you use NUIManager#removeScreen.

nuiManager.removeScreen(myScreen);

For more complex layered UIs, a "back" action can be simulated using NUIManager#popScreen.

NUIScreenLayer previousTopScreen = nuiManager.popScreen();