Miliastra Wonderland Lua API

ClientUIBaseControl

The base type that represents the common fields and functions of all Client Controls. Contains functions for changing fields, setting state, and managing event listeners.

Client Controls are destroyed and recreated whenever the client enters a loading screen, such as when teleporting or reconnecting.

Methods36 

function ClientUIBaseControl:AddKeyEventListener(eventType: EnumItem.KeyEventType, callback: fun() -> boolean)

Registers a key event listener to the Client Control.

  • The callback function must return a boolean which determines whether to mark the event as complete. If marked as complete, subsequent key event listeners of the same event type will be called, even if on a different root-level ContainerControl.

See:

Parameters
eventTypeEnumItem.KeyEventType

The key event type to listen for.

callbackfun() -> boolean

The callback function, returning a boolean representing whether to mark the event as completed.

function ClientUIBaseControl:AddNavigationEventListener(eventType: EnumItem.ControllerNavigationEventType, callback: fun() -> nil)

Registers a controller navigation event listener.

See:

Parameters
eventTypeEnumItem.ControllerNavigationEventType

The controller navigation type to listen for.

callbackfun() -> nil

The function to call when the event is triggered.

function ClientUIBaseControl:FindChild(path: string) -> ClientControlType | nil

Gets a child by relative hierarchy path.

  • If multiple children with the same path exist, the first by descending sibling index order is returned.
  • Returns nil if there are no children with the specified path.

Consider the following hierarchy:

Root
└─ ChildA
   ├─ ChildB
   └─ ChildC

When called on Root to get ChildC, the path would be "ChildA/ChildC"

Parameters
pathstring

The path used to retrieve a child, using / as the delimiter.

Returns
ClientControlType | nil

The first child with the specified path.

function ClientUIBaseControl:GetControllerNavigation(navigationDir: EnumItem.ControllerNavigationDir) -> (navigationMode EnumItem.ControllerNavigationMode, navigationTarget ClientControlType | nil)

Returns the navigation mode and target for the specified direction.

See:

Parameters
navigationDirEnumItem.ControllerNavigationDir

The direction to get navigation settings for.

Returns
navigationModeEnumItem.ControllerNavigationMode

The navigation mode for the specified direction.

navigationTargetClientControlType | nil

The target Client Control. Only set for the Specified navigation mode.

function ClientUIBaseControl:GetAnchorMax() -> (x NormalizedPercentage, y NormalizedPercentage)

Returns the maximum anchors as a normalized percentage of the parent's size, originating from the bottom-left corner of the parent's bounding box.

Returns
xNormalizedPercentage

The maximum x anchor.

yNormalizedPercentage

The maximum y anchor.

function ClientUIBaseControl:GetAnchorMin() -> (x NormalizedPercentage, y NormalizedPercentage)

Returns the minimum anchors as a normalized percentage of the parent's size, originating from the bottom-left corner of the parent's bounding box.

Returns
xNormalizedPercentage

The minimum x anchor.

yNormalizedPercentage

The minimum y anchor.

function ClientUIBaseControl:GetAnchoredPosition() -> (x number, y number)

Returns the position of the pivot point relative to the anchor point.

  • If anchorMin equals to anchorMax on a given axis, the anchor point for that axis resolves to anchorMin.
  • If anchorMin does not equal to anchorMax on a given axis, the anchor point is interpolated between the minimum and maximum anchors based on the control's pivot percentage for that axis.
Returns
xnumber

The x-axis distance of the pivot point relative to the anchor point.

ynumber

The y-axis distance of the pivot point relative to the anchor point.

function ClientUIBaseControl:GetChild(name: string) -> child ClientControlType | nil

Gets a child by name.

  • If multiple children with the same name exist, the first by descending sibling index order is returned.
  • Returns nil if there are no children with the specified name.
Parameters
namestring

The name used to retrieve a child.

Returns
childClientControlType | nil

The first child with the specified name.

function ClientUIBaseControl:GetChildren() -> ClientControlType[]

Returns the Client Control's children in descending sibling index order.

Returns
ClientControlType[]

The sequence of children controls.

function ClientUIBaseControl:GetLocalRotation() -> (x number, y number, z number)

Gets the local rotation of the Client Control.

Returns
xnumber

The local x rotation of the Client Control.

ynumber

The local y rotation of the Client Control.

znumber

The local z rotation of the Client Control.

function ClientUIBaseControl:GetLocalScale() -> (x number, y number, z number)

Returns the local scale of the Client Control.

Returns
xnumber

The local x scale of the Client Control.

ynumber

The local y scale of the Client Control.

znumber

The local z scale of the Client Control.

function ClientUIBaseControl:GetPivot() -> (x DecimalPercentage, y DecimalPercentage)

Returns the position of the Client Control's pivot as a decimal percentage of its dimensions originating from the bottom-left corner of its bounding box.

Returns
xDecimalPercentage

The x position of the pivot as a decimal percentage of the Client Control's width.

yDecimalPercentage

The y position of the pivot as a decimal percentage of the Client Control's height.

function ClientUIBaseControl:GetScript(scriptPrefabIndex: number) -> script Script | nil

Gets the instance of a script attached to the Client Control by Script Mapping ID.

  • Returns nil if the script with the specified Script Mapping ID is not attached to the Client Control.
Parameters
scriptPrefabIndexnumber

The Script Mapping ID used to retrieve a script instance.

Returns
scriptScript | nil

The script instance with the specified Script Mapping ID.

function ClientUIBaseControl:GetScriptByPath(path: string) -> script Script | nil

Gets the instance of a script attached to the Client Control by file path, relative to the external_lua_file folder.

  • Returns nil if the script with the specified file path is not attached to the Client Control.
Parameters
pathstring

The file path of the script, excluding the file extension.

Returns
scriptScript | nil

The script instance with the specified path.

function ClientUIBaseControl:GetScripts() -> scripts Script[]

Returns a sequence of all scripts attached to the Client Control.

Returns
scriptsScript[]

The sequence of attached scripts.

function ClientUIBaseControl:GetSiblingIndex() -> index number

Returns the 0-indexed position of the Client Control in the parent's list of children.

  • Higher-index siblings are rendered on top of lower-index siblings.
  • Children are listed in descending sibling order in the editor.
  • Returns -1 for root-level ContainerControls.
Returns
indexnumber

The 0-indexed position of the Client Control in the parent's list of children.

function ClientUIBaseControl:GetSizeDelta() -> (deltaX number, deltaY number)

Returns the difference in size between the Client Control and the distance between its minimum and maximum anchors.

  • If anchorMin equals to anchorMax on a given axis, the delta for that axis represents the Client Control's size along that axis.
Returns
deltaXnumber

The size offset between the width of the Client Control and its x-axis anchor bounds.

deltaYnumber

The size offset between the height of the Control and its y-axis anchor bounds.

function ClientUIBaseControl:RemoveAllKeyEventListeners()

Removes all key event listeners from the Client Control.

function ClientUIBaseControl:RemoveAllNavigationEventListeners()

Removes all controller navigation event listeners from the Client Control.

function ClientUIBaseControl:RemoveKeyEventListener(eventType: EnumItem.KeyEventType, callback: fun() -> boolean)

Removes the specified key event listener from the Client Control.

See:

Parameters
eventTypeEnumItem.KeyEventType

The event type to remove the callback from.

callbackfun() -> boolean

The callback function to remove.

function ClientUIBaseControl:RemoveKeyEventListeners(eventType: EnumItem.KeyEventType)

Removes all key event listeners for the specified event type from the Client Control.

See:

Parameters
eventTypeEnumItem.KeyEventType

The event type to clear listeners from.

function ClientUIBaseControl:RemoveNavigationEventListener(eventType: EnumItem.ControllerNavigationEventType, callback: fun() -> nil)

Removes the specified controller navigation event listener from the Client Control.

See:

Parameters
eventTypeEnumItem.ControllerNavigationEventType

The event type to remove the callback from.

callbackfun() -> nil

The callback function to remove.

function ClientUIBaseControl:RemoveNavigationEventListeners(eventType: EnumItem.ControllerNavigationEventType)

Removes all listeners for the specified event type from the Client Control.

See:

Parameters
eventTypeEnumItem.ControllerNavigationEventType

The event type to clear listeners from.

function ClientUIBaseControl:SetActive(active: boolean)

Sets the active status of the Client Control.

  • If the active status is changed, the corresponding lifecycle functions are called (OnEnable when true and OnDisable when false).
Parameters
activeboolean

Whether to set as active.

function ClientUIBaseControl:SetAnchorMax(x: NormalizedPercentage, y: NormalizedPercentage)

Sets the maximum anchors as a normalized percentage of the size of the parent, originating from the bottom-left corner of the parent's bounding box.

Parameters
xNormalizedPercentage

The maximum x anchor.

yNormalizedPercentage

The maximum y anchor.

function ClientUIBaseControl:SetAnchorMin(x: NormalizedPercentage, y: NormalizedPercentage)

Sets the minimum anchors as a normalized percentage of the size of the parent, originating from the bottom-left corner of the parent's bounding box.

Parameters
xNormalizedPercentage

The minimum x anchor.

yNormalizedPercentage

The minimum y anchor.

function ClientUIBaseControl:SetAnchoredPosition(x: number, y: number)

Sets the position of the pivot point relative to the anchor point.

  • If anchorMin equals to anchorMax on a given axis, the anchor point for that axis resolves to anchorMin.

See:

Parameters
xnumber

The x position of the pivot point relative to the anchor point.

ynumber

The y position of the pivot point relative to the anchor point.

function ClientUIBaseControl:SetAsFirstSibling() -> unknown boolean

Sets the Client Control as the first child (index 0) of its parent.

  • Throws an error if called before OnStart or during OnDestroy.
  • Returns false only when called on a root-level ContainerControl.

See:

Returns
unknownboolean

Always true?

function ClientUIBaseControl:SetAsLastSibling() -> unknown boolean

Sets the Client Control as the last child (greatest index) of its parent.

  • Throws an error if called before OnStart or during OnDestroy.
  • Returns false only when called on a root-level ContainerControl.

See:

Returns
unknownboolean

Always true?

function ClientUIBaseControl:SetControllerNavigation(navigationDir: EnumItem.ControllerNavigationDir, navigationMode: EnumItem.ControllerNavigationMode, navigationTarget: ClientControlType | nil)

Sets the controller navigation mode for a specific navigation direction.

  • If Enum.ControllerNavigationMode.Specified is passed and the navigation target is nil, the navigation mode will be set to None.

See:

Parameters
navigationDirEnumItem.ControllerNavigationDir

The navigation direction to apply the navigation mode to.

navigationModeEnumItem.ControllerNavigationMode

The navigation mode to use.

navigationTargetClientControlType | nil

The navigation target. Required if the Specified navigation mode is passed, otherwise this parameter is ignored.

function ClientUIBaseControl:SetLocalRotation(x: number, y: number, z: number)

Sets the local rotation of the Client Control.

Parameters
xnumber

The local x rotation of the Client Control.

ynumber

The local y rotation of the Client Control.

znumber

The local z rotation of the Client Control.

function ClientUIBaseControl:SetLocalScale(x: number, y: number, z: number)

Sets the local scale of the Client Control.

Parameters
xnumber

The local x scale of the Client Control.

ynumber

The local y scale of the Client Control.

znumber

The local z scale of the Client Control.

function ClientUIBaseControl:SetPivot(x: DecimalPercentage, y: DecimalPercentage)

Sets the position of the Client Control's pivot as a decimal percentage of its dimensions originating from the bottom-left corner of its bounding box.

Parameters
xDecimalPercentage

The x position of the pivot as a decimal percentage of the width.

yDecimalPercentage

The y position of the pivot as a decimal percentage of the height.

function ClientUIBaseControl:SetSiblingIndex(index: integer) -> success boolean

Sets the 0-indexed position of the Client Control in the parent's list of children.

  • Throws an error if called before OnStart or during OnDestroy.
  • Returns false only when called on a root-level ContainerControl.

See:

Parameters
indexinteger

The 0-indexed position in the parent's list of children. Automatically clamped within the valid range of indexes.

Returns
successboolean

Whether the sibling index was changed.

function ClientUIBaseControl:SetSizeDelta(deltaX: number, deltaY: number)

Sets the size offset between the Client Control and the its anchor bounds.

  • If anchorMin equals to anchorMax on a given axis, the delta for that axis represents the Client Control's size along that axis.
Parameters
deltaXnumber

The size offset between the Client Control's width and x-axis anchor bounds.

deltaYnumber

The size offset between the Client Control's height and y-axis anchor bounds.

function ClientUIBaseControl:SetVisible(visible: boolean)

Sets the visibility status of the Client Control.

Parameters
visibleboolean

Whether to set as visible.

Fields25

ClientUIBaseControl.alive : boolean

[Read] Whether the Client Control is instantiated.

ClientUIBaseControl.id : number

[Read] The runtime ID of the Client Control.

ClientUIBaseControl.prefabIndex : number

[Read] The template index of the Client Control.

ClientUIBaseControl.active : boolean

[Read] Whether the Client Control is active. While active, attached scripts will call lifecycle functions.

ClientUIBaseControl.activeInHierarchy : boolean

[Read] Whether the Client Control is active, factoring in the active states of its parent hierarchy.

ClientUIBaseControl.visible : boolean

[Read] Whether the Client Control is visible.

ClientUIBaseControl.name : string

[Read/Write] The name of the Client Control.

ClientUIBaseControl.parent : ClientControlType | nil

[Read/Write] The parent of the Client Control. Always nil for root-level ControlContainers.

ClientUIBaseControl.anchoredPositionX : number

[Read/Write/Tweenable] The x position of the Client Control's pivot point relative to its anchor point. See ClientUIBaseControl.GetAnchoredPosition for detailed behavior.

ClientUIBaseControl.anchoredPositionY : number

[Read/Write/Tweenable] The y position of the Client Control's pivot point relative to its anchor point. See ClientUIBaseControl.GetAnchoredPosition for detailed behavior.

ClientUIBaseControl.sizeDeltaX : number

[Read/Write/Tweenable] The size offset between the width of the Client Control and its x-axis anchor bounds.

ClientUIBaseControl.sizeDeltaY : number

[Read/Write/Tweenable] The size offset between the height of the Client Control and its y-axis anchor bounds.

ClientUIBaseControl.anchorMinX : NormalizedPercentage

[Read/Write/Tweenable] The minimum x anchor represented as a normalized percentage of the parent's width originating from the bottom-left corner of the parent's bounding box.

ClientUIBaseControl.anchorMinY : NormalizedPercentage

[Read/Write/Tweenable] The minimum y anchor represented as a normalized percentage of the parent's height originating from the bottom-left corner of the parent's bounding box.

ClientUIBaseControl.anchorMaxX : NormalizedPercentage

[Read/Write/Tweenable] The maximum x anchor represented as a normalized percentage of the parent's width originating from the bottom-left corner of the parent's bounding box.

ClientUIBaseControl.anchorMaxY : NormalizedPercentage

[Read/Write/Tweenable] The maximum y anchor represented as a normalized percentage of the parent's height originating from the bottom-left corner of the parent's bounding box.

ClientUIBaseControl.pivotX : DecimalPercentage

[Read/Write/Tweenable] The x position of the pivot point represented as a decimal percentage of the Client Control's width originating from the bottom-left corner of its bounding box.

ClientUIBaseControl.pivotY : DecimalPercentage

[Read/Write/Tweenable] The y position of the pivot point represented as a decimal percentage of the Client Control's height originating from the bottom-left corner of its bounding box.

ClientUIBaseControl.localScaleX : number

[Read/Write/Tweenable] The local x scale of the Client Control.

ClientUIBaseControl.localScaleY : number

[Read/Write/Tweenable] The local y scale of the Client Control.

ClientUIBaseControl.localScaleZ : number

[Read/Write/Tweenable] The local z scale of the Client Control.

ClientUIBaseControl.localRotationX : number

[Read/Write/Tweenable] The local x rotation of the Client Control.

ClientUIBaseControl.localRotationY : number

[Read/Write/Tweenable] The local y rotation of the Client Control.

ClientUIBaseControl.localRotationZ : number

[Read/Write/Tweenable] The local z rotation of the Client Control.

ClientUIBaseControl.canControllerFocus : boolean

[Read/Write] Whether the Client Control can be focused by controller navigation.