Mod API Reference:UI

Mods can put UI (user interface) onto the screen when called from one of the Client Present hooks. This page describes how to create and update UI elements.

UI elements are created by accessing the UI global. For example, mods can call UI.CreateButton(...) to create a button. Any UI element listed below can be created in a similar manner.

Behind the scenes, these objects are implemented using Unity's UI and layout system. Being familiar with Unity's UI system will make understanding how to build UI easier, but it's not a requirement.

Parents

All UI constructors take a single parent argument. This allows you to construct hierarchies. For example, mods can create a vertical stack of three buttons like this:

 local vert = UI.CreateVerticalLayoutGroup(rootParent);
 local btn1 = UI.CreateButton(vert);
 local btn2 = UI.CreateButton(vert);
 local btn3 = UI.CreateButton(vert);

When a mod is called to present UI, it will be passed a root UI element (rootParent). Your mod should pass the rootParent to a UI element that will be the root of all other elements you need. This element is most often a VerticalLayoutGroup, as shown in the example above.

You can never make more than one element a child of the rootParent. If you need more than one, simply make your own container to house them.

Properties

UI elements have properties that can be read or set. For example, Buttons have a Text property that allows you to set the text that appears on the button.

To read or write a UI element's property, you must use getter/setter functions named GetX() and SetX(). For example, to set the text of a button you can write btn1.SetText('Click me!') and can retrieve it using btn1.GetText().

All getter and setter functions return the UI element, which means you can chain them together to easily set lots of properties. For example:

 UI.CreateButton(vert)
   .SetText('Click me!')
   .SetColor('#00FF00')
   .SetOnClick(someFunction);

Common Properties

All UI elements have the following properties:

• PreferredWidth number: How wide the element prefers to be. It may not be this wide if there is not enough space, and it may be wider if FlexibleWidth is greater than 0. Defaults to -1, which is a special value meaning the object will meansure its own size based on its contents.
• PreferredHeight number: How tall the element prefers to be. It may not be this tall if there is not enough space, and it may be taller if FlexibleHeight is greater than 0. Defaults to -1, which is a special value meaning the object will meansure its own size based on its contents.
• FlexibleWidth number: A number from 0 to 1 indicating how much of the remaining space this element wishes to take up. Defaults to 0, which means the element will be no wider than PreferredWidth. Set it to 1 to indicate the object should grow to encompass all remaining horizontal space it can.
• FlexibleHeight number: A number from 0 to 1 indicating how much of the remaining space this element wishes to take up. Defaults to 0, which means the element will be no taller than PreferredHeight. Set it to 1 to indicate the object should grow to encompass all remaining vertical space it can.

UI Elements

Empty: A simple UI element that displays nothing. This can be used as a container or to create space.

VerticalLayoutGroup: A container that stacks its children vertically.

HorizontalLayoutGroup: A container that stacks its children horizontally.

Label: A way to display text on the screen.

• Text string: The text to display.
• Color string: The color of the text. Pass this as a string in #RRGGBB format.

Button: A button that players can click on to do something.

• Text string: The text to display on the button.
• Color string: The color of the button. Pass this as a string in #RRGGBB format.
• TextColor string: The color of the text on teh button. Pass this as a string in #RRGGBB format.
• OnClick function: Pass the name of a lua function to be called whenever the player clicks the button.
• Interactable bool: If false, the control will be grayed out and unusable by the player.

CheckBox: A toggleable check box that players can check and uncheck.

• IsChecked bool: Whether the check box is checked or unchecked.
• Text string: The label displayed to the right of the check box.
• OnValueChanged function: Pass the name of a lua function to be called whenever the IsChecked property changes, either by your code or by the player clicking the check box.
• Interactable bool: If false, the control will be grayed out and unusable by the player.

TextInputField: A box where players can type a string.

• Text string: The string that appears in the box, or that players typed.
• PlaceholderText string: The text that appears in the box grayed out when it's empty. For example, "Enter name here..."
• CharacterLimit integer: The maximum number of characters that players can type into this text field.
• Interactable bool: If false, the control will be grayed out and unusable by the player.

NumberInputField: Allows players to input a number. Presents an input box and a slider that are linked, so players can either use the box to type a number or slide the slider. This makes it friendly for mobile users who don't have a hardware keyboard, while also allowing any number to be entered if someone wants to exceed the range allowable by the slider.

• Value number: The value to show in the box+slider, or the value entered by the player.
• WholeNumbers bool: If true, only integers will be selectable by the player. If false, partial numbers will be selectable. Defaults to true.
• SliderMinValue number: The minimum value selectable by the slider. Numbers below this can still be entered by typing them into the box, so ensure to always validate the number you retrieve.
• SliderMaxValue number: The maxium value selectable by the slider. Numbers above this can still be entered by typing them into the box, so ensure to always validate the number you retrieve.
• BoxPreferredWidth number: Allows setting the preferred width of just the box. See Common Properties above.
• SliderPreferredWidth number: Allows setting the preferred width of just the slider. See Common Properties above.
• Interactable bool: If false, the control will be grayed out and unusable by the player.

Helper Functions

UI.Destroy: Destroys (removes) any UI that the mod previously created. Simply pass a UI element created by one of the UI.CreateXXX functions to UI.Destroy and it will disappear forever.

UI.Alert: Pops up a dialog with a message and an Okay button to close the message. Call this as simply UI.Alert(msg)

UI.PromptFromList: Pops up a dialog with a series of buttons to choose from. This takes two arguments:

• Message string: Text to appear at the top of the dialog.
• Options array: A list of options, each of which will show up as a button. Each entry in this array should be a table with two fields, text and selected. text populates the text that will appear on that button, and selected is a zero-argument function that gets called if the player selects that option.

Colors in the browser

Only the following list of colors will work in UJS, due to javascript.

00A0FF

00B5FF

F3FFAE

43C731

43C631

1274A4

1274A5

B03B3B

0021FF

359029

00E9FF

00FF21

FFF700

AA3A3A

43C732

00D4FF

B03C3C

00F4FF

00BFFF

4EC4FF

FFFF00

615DDF

100C08

943E3E

0000ff

4effff

59009d

008000

ff7d00

ff0000

606060

00ff05

ff697a

94652e

00ff8c

ff4700

009b9d

23a0ff

ac0059

ff87ff

ffff00

943e3e

feff9b

ad7e7e

b70aff

ffaf56

ff00b1

8ebe57

DAA520

990024

00FFFF

8F9779

880085

00755E

FFE5B4

4169E1

FF43A4

8DB600

40826D

C04000

FFDDF4

CD7F32

C19A6B

C09999

B0BF1A

3B7A57

4B5320

664C28

893F45

D2691E

36454F

FF00FF

76FF7A

100C08