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

The primary function of this class is to modify the UI, not to create it. The UI API is used to create UI on Objects or on the screen (Global).

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.
hide( id) Hides the given UI element. Unlike the "active" attribute, hide triggers animations.
load( xml) Replaces the targeted XML script with the string provided.
setAttribute( id,  attribute,  value) Sets the value of a specified attribute of a UI element.
show( id) Displays the given UI element. Unlike the "active" attribute, show triggers animations.
setAttributes( id,  data) Updates the value of the supplied attributes of a UI element.

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.

Important

This will return the value from the XML UI, not the dynamic UI. For example, if you had a toggle and clicked it on-screen, using getAttribute on isOn would still return false. This is because elements are not synced between clients by default.

If you wanted them synced you could, using the toggle's onValueChanged function, do a UI.setAttribute(...) to make that element's isOn equal true.

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.
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.

Important

This will return the value from the XML UI, not the dynamic UI. For example, if you had a toggle and clicked it on-screen, using getAttribute on isOn would still return false. This is because elements are not synced between clients by default.

If you wanted them synced you could, using the toggle's onValueChanged function, do a UI.setAttribute(...) to make that element's isOn equal true.

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.


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.
UI.hide("testElement")

load(...)

 Replaces the targeted XML script with the string provided.

Warning

This will OVERWRITE currently existing XML that is already on the target Global/object.

load(xml)

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

setAttribute(...)

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

Important

This will override the dynamic 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)

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.
UI.show("testElement")

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 dynamic 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"
}
UI.setAttributes("exampleText", attributeTable)