Skip to content

UI

UI, a static global class AND an Object class. It is the method to interact with custom UI elements. It allows you to read/write attributes of elements defined in the XML of the UI. It also allows you to receive information from various inputs (like buttons) on-screen and on objects.

Attention

This class allows for the manipulation of UI at runtime. It does NOT modify or fetch the original XML in the editor, but rather what is displayed as it continues to run during a game. Just like with Lua, you can only get/set dynamic values during runtime. You can use onSave and onLoad to record any data you want to persist through save/load/undo.

For more information on how to build UI elements within XML, view the UI API.

Global and Object

UI can either be placed on the screen by using the Global UI or placed on an Object using Object UI. Depending on which you are using, these commands are used differently.

Example of calling a function targeted at the Global UI:
    UI.getAttributes(id)
Example of calling a function targeted at an Object UI:
    object.UI.getAttributes(id)

Inputs

Input Elements are able to trigger a function. By default, Global UI will trigger a function in Global and Object UI will trigger a function in the Object's script. To change the target script for an input, view more details here.

When creating the input element in XML, you will select the name of the function it activates. Regardless of its name, it always will pass parameters

functionName(player, value, id)

  • player: A direct Player reference to the person that triggered the input.
  • value: The value sent by the input. A numeric value or a string, generally.
    • This is not used by buttons!
  • id:
    • This is only passed if the element was given an Id attribute in the XML.
function onButtonClick(player, value, id)
    print(player.steam_name)
    print(id)
end

Element Function Summary

Function Name Description Return  
getAttribute( id,  attribute) Obtains the value of a specified attribute of a UI element.
getAttributes( id) Returns the attributes and their values of a UI element.
getCustomAssets() Returns information on all custom assets uploaded to the UI ASSETS pane.
getValue( id) Obtains the value between elements tags, like: <Text>ValueToGet</Text>
getXml() Returns the run-time UI's XML in string format.
getXmlTable() Returns the run-time UI's XML formatted as a Lua table.
hide( id) Hides the given UI element. Unlike the "active" attribute, hide triggers animations.
setAttribute( id,  attribute,  value) Sets the value of a specified attribute of a UI element.
setAttributes( id,  data) Updates the value of the supplied attributes of a UI element.
setCustomAssets( assets) Sets the UI ASSETS (like custom images) for global or an Object.
setValue( id,  value) Updates the value between elements tags, like: <Text>ValueChanged</Text>
setXml( xml) Replaces the run-time UI with the XML string.
setXmlTable( data) Replaces the run-time UI with an XML string which is generated from a table of data.
show( id) Displays the given UI element. Unlike the "active" attribute, show triggers animations.

Element Function Details

getAttribute(...)

 Obtains the value of a specified attribute of a UI element. What it returns will typically be a string or a number.

getAttribute(id, attribute)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.
  • attribute: The name of the attribute you wish to get the value of.
self.UI.getAttribute("testElement", "fontSize")

getAttributes(...)

 Returns the attributes and their values of a UI element. It only returns the attributes (and values) for elements that have had those attributes set by the user.

getAttributes(id)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.

Return table

  • parameters: A Table with the attributes as keys and their XML value as the key's value.
    • texture: The name of the image element
    • color: The hex used for the color element's value.

IMPORTANT: This return table is an example of one you may get back from using it on a RawImage element type. The attribute keys you get back and their values will depend on the element you use the function on as well as the attributes you, the user, have assigned to it.

getCustomAssets()

 Returns information on all custom assets uploaded to the UI ASSETS pane.

Return table

  • table: An unnamed table that contains sub-tables. Each sub-table represents one asset.
    • name: The name of the image element
    • url: The URL/file location of the asset's source.
function onLoad()
    local assets = UI.getCustomAssets()
    log(assets)
end

getValue(...)

 Obtains the value between elements tags, like: <Text>ValueObtained</Text>

getValue(id)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.
string = UI.getAttribute("testElement")
print(string)

getXmlTable()

 Obtain the run-time UI formatted as a Lua table of data.

Example Returned Table: 

{
    {
        tag="HorizontalLayout",
        attributes={
            height=200,
            width=1000,
            color="rgba(0,0,0,0.7)",
        },
        children={
            {
                tag="Text",
                attributes={
                    fontSize=100,
                    color="red",
                },
                value="Example",
            },
            {
                tag="Text",
                attributes={
                    text="Message",
                    fontSize=100,
                    color="blue",
                },
            },
        }
    }
}

What the XML would look like which returns that table: 

<HorizontalLayout height="200" width="1000" color="rgba(0,0,0,0.7)">
    <Text fontSize="100" color="red">Example</Text>
    <Text text="Message" fontSize="100" color="blue" />
</HorizontalLayout>

hide(...)

 Hides the given UI element. Unlike the "active" attribute, hide triggers animations.

hide(id)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.
self.UI.hide("testElement")

setAttribute(...)

 Sets the value of a specified attribute of a UI element.

Important

This will override the run-time value from the XML UI for all players, forcing them to see the same value.

setAttribute(id, attribute, value)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.
  • attribute: The name of the attribute you want to set the value of.
  • value: The value to set for the attribute.
self.UI.setAttribute("testElement", "fontSize", 200)

setAttributes(...)

 Updates the value of the supplied attributes of a UI element. You do not need to set every attribute with the data table, an element will continue using any previous values you do not overwrite.

Important

This will override the run-time value from the XML UI for all players, forcing them to see the same value.

setAttributes(id, data)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.
  • data: A Table with key/value pairs representing attributes and their values.

Example data table

  • data: A Table with parameters which guide the function.
    • data.fontSize: Attribute's desired value value
    • data.color: Attribute's desired value

IMPORTANT: This table is an example of one you may use when setting a text UI element. The attribute keys you use and their values will depend on the element you use the function on.

attributeTable = {
    fontSize = 300,
    color = "#000000"
}
self.UI.setAttributes("exampleText", attributeTable)

setCustomAssets(...)

 Sets the UI ASSETS (like custom images) for Global or an Object. Passing nothing as a parameter results in the clearing of the UI Assets.

This function will overwrite any currently existing assets in Custom UI Assets, not add to them.

setCustomAssets(table)

  • table: An unnamed table that contains sub-tables. Each sub-table represents one asset.
    • name: The name of the image element
    • url: The URL/file location of the asset's source.
function onLoad()
    local assets = {
        {
            name = "Image 1",
            url  = "http://placehold.it/120x120&text=image1"
        },
        {
            name = "Image 2",
            url  = "http://placehold.it/120x120&text=image2"
        },
    }
    UI.setCustomAssets(assets)
end

setValue(...)

 Updates the value between elements tags, like: <Text>ValueChanged</Text>

setValue(id, value)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.
  • value: The value to put between the element tags.
UI.setValue("testElement", "New Text To Display")

setXml(...)

 Replaces the run-time UI with the XML string.

setXml(xml)

  • xml: A single string with the contents of the XML to use
self.UI.setXml("<Text>Test</Text>")

Warning

setXml takes 1 frame to update the runtime UI. This means any change or get of xml/attributes during this frame will not be recognized correctly.

setXmlTable(...)

 Replaces the run-time UI with an XML string which is generated from a table of data.

setXmlTable(data)

  • data: A table containing sub-tables. One sub-table for each element being created.
    • tag: The element type.
    • attributes: A table containing attribute names for keys. Available attribute types depend on tag's element type.
      • Optional, defaults to not being used.
      • Example key/value pairs: text="Test", color="black"
    • value: Text that appears <Text>Here</Text>, between the <> and </>.
      • Optional, defaults to an empty string.
    • children: A table containing more sub-tables, formatted as above. This does mean the sub-tables can contain their own children as well, containing sub-sub tables, etc.
      • Optional, defaults to not being used.
function onLoad()
    UI.setXmlTable({
        {
            tag="HorizontalLayout",
            attributes={
                height=200,
                width=1000,
                color="rgba(0,0,0,0.7)",
            },
            children={
                {
                    tag="Text",
                    attributes={
                        fontSize=100,
                        color="red",
                    },
                    value="Example",
                },
                {
                    tag="Text",
                    attributes={
                        text="Message",
                        fontSize=100,
                        color="blue",
                    },
                },
            }
        }
    })
end

Warning

setXmlTable takes 1 frame to update the runtime UI. This means any change or get of xml/attributes during this frame will not be recognized correctly.

show(...)

 Shows the given UI element. Unlike the "active" attribute, show triggers animations.

show(id)

  • id: The Id that was assigned, as an attribute, to the desired XML UI element.
self.UI.show("testElement")