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. Only the following colors are supported for buttons:

 #BABABC  #6C73D1  #FF00ED  #FFC200  #00A0FF  #00B5FF  #F3FFAE  #43C731  #43C631  #1274A4  #1274A5  #B03B3B  #0021FF  #359029  #00E9FF  #00FF21  #FFF700  #AA3A3A  #43C732  #00D4FF  #B03C3C  #00F4FF  #00BFFF  #4EC4FF  #615DDF  #100C08  #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

• TextColor string: The color of the text on the 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.IsDestroyed: Tests if any UI element has been destroyed. Also returns true if passed nil.

UI.Alert: Pops up a dialog with a message and an Okay button to close the message. Call this as simply UI.Alert(msg). Only one mod can use this at a time.

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.

UI.InterceptNextTerritoryClick: Added in 5.17.0. After calling this function, the next time the player clicks a territory on the map, your mod will be notified of the click. After calling this, you should also instruct the player to click a territory, and it's also a good idea to let them know they can move dialogs out of the way to see the map.

• Callback function: Pass a function that will be called on the next click. This function will be passed a TerritoryDetails object, which can be used to get the Territory ID or the name of the territory that was clicked. This function can also be called with nil if the intercept request is cancelled, which can happen if another mod calls UI.InterceptNextTerritoryClick before a territory is clicked. If you want to cancel the intercept request, you can return WL.CancelClickIntercept from the callback which will make the client behave as if you never called intercept. Return nil, or leave off the return statement entirely, for normal operation.

UI.InterceptNextBonusLinkClick: Added in 5.17.0. After calling this function, the next time the player clicks a bonus link on the map, your mod will be notified of the click. After calling this, you should also instruct the player to click a bonus link, and it's also a good idea to let them know they can move dialogs out of the way to see the map.

• Callback function: Pass a function that will be called on the next click. This function will be passed a BonusDetails object, which can be used to get the bonus ID or the name of the bonus that was clicked. This function can also be called with nil if the intercept request is cancelled, which can happen if another mod calls UI.InterceptNextBonusLinkClick before a bonus link is clicked. If you want to cancel the intercept request, you can return WL.CancelClickIntercept from the callback which will make the client behave as if you never called intercept. Return nil, or leave off the return statement entirely, for normal operation.