Skip to content

3. Controls

Jump to bottom
Alumopper edited this page Nov 5, 2025 · 1 revision

Tip

This page will introduce you about the basic controls offered by Floating UI.

Common Data

Before we start, we need to know some common data used by all controls.

We define the following format to represent data structures:

data Example: <base data type> {
    fieldName: fieldType = default_value_if_exist
    # if the fieldType is end with `?`, means this field is optional or may be null.
    # (type1|type2) represents a union type

    fieldName: value
    # this field should be the given value

    fieldName: data {
        # indicates this field is a compound tag
    }
}

Here are some common field types:

Type Description Example
string, int, float ... Primitive NBT type "Hello", 1, 0.5
list<type> List of NBT data [1, 2, 3]
nbt Any type of NBT data -
float[n], string[n], ... Array of primitive NBT data with given size [1, 2, 3], ["Hello", "World"]
UUID A UUID int array [I;0,0,0,1]
event A namespace ID of a function "example:event/click"

And here are some compound data types:

Item

Represents an item shown by an item display. It has a structure similar to item stack NBT but adds a item_model field to specify the item model, eliminating the need to set minecraft:item_model item component.

data Item {
    # item' namespace id. If the namespace is `minecraft` then it can be omitted.
    id: string? = "glass_pane"

    # count of the item
    count: byte? = 1

    # components of the item
    components: nbt?

    # the same as `item_model` component
    item_model: string?
}

Animation

See the [Animation](./2. Overview#animation) section.

Control Data

Note

An "abstract" control is a control that cannot be created directly, but can be inherited by other controls.

Note

If a control inherits from another control, it will inherit all properties (including layout data, stored data, scores) and functions of the parent control.

Quick Reference:

Control Description
Control (Abstract) The most basic control, containing common fields for all controls.
TextControl (Abstract) The most basic text control, containing common fields for all text controls.
Button A simple interactive control that supports left and right mouse button clicks.
List A simple list control.
NumberBox A simple number input control.
Panel A simple container control.
Sprite A simple image control.
StackPanel A container control arrange children controls automatically.
TextBlock A simple text area.

Control (Abstract)

Control is most control's parent class, containing common fields for all controls.

Layout Data

abstract data Control {
    # the position of the control
    x: double?
    y: double?
    z: double?

    # the size of the control
    size: float[2]?

    # A quaternion. The rotation of the control 
    rotation: float[4]? = [0f, 1f, 0f, 0f]

    # The model to display, same as `item_display` field in item display entity data. Describes item model transform applied to item.
    display: string? = "rotation"

    # The item to display
    item: Item?

    # custom data stored by the control
    custom_data: nbt?

    # event triggered when the cursor moves into the control
    move_in: event?

    # event triggered when the cursor moves out of the control
    move_out: event?

    # event triggered when the cursor moves over the control
    move: event?

    # event triggered when the cursor clicks the control
    right_click: event?
    left_click: event?

    # event triggered when the control is initialized
    init: event?
}

Stored Data

Tip

What is stored data?

data StoredControl {
    
    name: string?

    size: float[2]

    move_in: event?
    move_out: event?
    move: event?
    right_click: event?
    left_click: event?
    roll: event?
    init: event?

    custom_data: nbt?

    # the layout data of the control
    ui: Control
}

Scoreboard

  • floating_ui.uid: the uid of the control
  • floating_ui.visible: whether the control is visible.
  • floating_ui.size0/1: the width/height of the control x10000
  • floating_ui.size0/1_without_scale: the width/height of the control x10000 without scaled
  • floating_ui.root_x/y/z: The the control'x/y/z position relative to the root control x10000
  • floating_ui.parent_x/y/z: The the control'x/y/z position relative to the parent control x10000
  • floating_ui.root_x/y/z_without_scale: The the control'x/y/z position relative to the root control x10000 without scale
  • floating_ui.parent_x/y/z_without_scale: The the control'x/y/z position relative to the parent control x10000 without scale

Functions

Note

All functions should be executed as the control item display entity.

  • floating_ui:element/control/_play_animation

    Play an animation on the control.

    Parameter Description
    storage floating_ui:input animate.id The id of the animation to play
    score delay floating_ui.temp The delay of the animation. Defaults to 0.
    storage floating_ui:input animate.data The animation data.

    See Animation

Tip

Parameters table above tells you how to assign a value for each parameter by using commands.

For example, the first parameter storage floating_ui:input animate.id means this parameter is a storage nbt data so you may use data command, and the second parameter score delay floating_ui.temp means this parameter is a score so you may use scoreboard command.

  • floating_ui:element/control/_set_offset

    Set the offset of a control.

    Parameter Description
    storage floating_ui:input temp.x/y/z Three-dimensional offset

  • floating_ui:element/control/_set_scale

    Set the scale of a control. This function will also affect all child controls.

    Parameter Description
    score scale floating_ui.temp Scale, both x and y

  • floating_ui:element/control/_set_visible

    Set the visibility of a control.

    Parameter Description
    score @s floating_ui.visible Visibility. 0 for invisible, 1 for visible

  • floating_ui:element/control/_move

    Move a control and its children.

    Parameter Description
    storage floating_ui:input move.x/y X/Y offset

TextControl (Abstract)

TextControl is the parent class of all text controls, containing common fields for all text controls. Because text display entities cannot store custom data, a text control is split into two entities: a item display and a text display. The item display stores custom data and serves as a UI node. It also provides access to the corresponding text display entity.

Layout Data

abstract data TextControl {

    # the position of the text display
    x: double?
    y: double?
    z: double?

    # font size. Only exist in input.
    fontsize: float? = 2.0f

    # the rotation of the text display.
    rotation: float[4]? = [0f, 1f, 0f, 0f]

    # event triggered when the cursor moves into the text display
    move_in: event?

    # event triggered when the cursor moves out of the text display
    move_out: event?
}

Stored Data

data TextControlStored {
    x: float
    y: float
    z: float

    fontsize: float
    rotation: float[4]

    move_in: event?
    move_out: event?
    move: event?
    right_click: event?
    left_click: event?

    # the layout data of the control
    ui: TextControl
}

Button: Control

A simple interactive control that supports left and right mouse button clicks. By default a button displays an item. But if content field is set, it will display the specific content control instead.

Layout Data

data Button: Control {
    type: "button"

    # event triggered when the left mouse button is clicked on the button
    left_click: event?
    
    # event triggered when the right mouse button is clicked on the button
    right_click: event?

    # the content of the button
    content: Control?
}

Functions

  • floating_ui:element/button/_dispose

    Dispose this button and its content control.

    No parameters.

List: Control

List is a simple list control. It can contain other controls and display them in a list view. Users can scroll the list to select a control or see more controls.

Layout Data

data List: Control {
    type: "list"

    child: list<Control>?
}

Scoreboard

  • floating_ui.list.childCount: the number of child controls in the list
  • floating_ui.list.index: the index of the selected control
  • floating_ui.list.childIndex: the index of the child control in the list (This score is assigned to child controls)
  • floating_ui.list.minIndex: the min index of the child controls the list is displaying
  • floating_ui.list.maxIndex: the max index of the child controls the list is displaying

Functions

  • floating_ui:element/list/_add

    Add a child control to the list.

    Parameter Description
    storage floating_ui:input element The layout data of the element to add

  • floating_ui:element/list/_dispose

    Dispose this list and all child controls.

    No parameters.

NumberBox: Control

NumberBox is a simple number input control. Users can select a value by scrolling. A number box can have a minimum and maximum value, and if users try to select a value outside the range, an event will be triggered.

Layout Data

data NumberBox: Control {
    type: "numberbox"

    # the default value of the number box when created
    value: float?
    
    # the minimum and maximum value of the number box
    min: float?
    max: float?

    # event triggered when the value of the number box changes
    value_change: event?

    # event triggered when the value of the number box exceeds the maximum value
    value_exceed_max: event?

    # event triggered when the value of the number box is less than the minimum value
    value_below_min: event?
}

Stored Data

data NumberBoxStored: ControlStored {
    value: float
    min: float
    max: float
    
    value_change: event?
    value_exceed_max: event?
    value_below_min: event?
}

Scoreboard

  • floating_ui.numberbox.value: The current value of the number box
  • floating_ui.numberbox.min: The minimum value of the number box
  • floating_ui.numberbox.max: The maximum value of the number box

Functions

  • floating_ui:element/numberbox/_add_value

    Adds a value to the number box. This function will trigger events.

    Parameter Description
    score value floating_ui.temp The value to add

  • floating_ui:element/numberbox/_add_value_silent

    Same as floating_ui:element/numberbox/_add_value, but will not trigger events.

  • floating_ui:element/numberbox/_dispose

    Disposes the number box.

  • floating_ui:element/numberbox/_remove_value

    Removes a value from the number box. This function will trigger events.

    Parameter Description
    score value floating_ui.temp The value to remove

  • floating_ui:element/numberbox/_remove_value_silent

    Same as floating_ui:element/numberbox/_remove_value, but will not trigger events.

  • floating_ui:element/numberbox/_set_value

    Sets the value of the number box. This function will trigger events.

    Parameter Description
    score value floating_ui.temp The value to set

  • floating_ui:element/numberbox/_set_value_silent

    Same as floating_ui:element/numberbox/_set_value, but will not trigger events.

Panel: Control

Panel is a simple container control. It can contain other controls.

Layout Data

data Panel: Control {
    type: "panel"

    child: list<(Control|TextControl)>?
}

Functions

  • floating_ui:element/panel/_add

    Add a child control to the panel.

    Parameter Description
    storage floating_ui:input element The child control to add.

  • floating_ui:element/panel/_dispose

    Dispose the panel and all its child controls.

    No parameters.

Sprite: Control

Sprite is a simple image control. It just display an item so it doesn't have any other fields.

Layout Data

data Sprite: Control {
    type: "sprite"
}

Functions

  • floating_ui:element/sprite/_dispose

    Dispose the sprite.

    No parameters.

StackPanel: Control

StackPanel is a container control. Elements in the stack panel will be automatically arranged rather than overlapping.

Layout Data

data StackPanel: Control {
    type: "stackpanel"

    child: list<(Control|TextControl)>?

    # the gap between elements
    gap: float? = 0f

    # the alignment of elements, can be "left", "center" or "right"
    direction: string? = "left"
}

Stored Data

data StackPanelStored: ControlStored {
    gap: float
    align: string
}

Scoreboard

  • floating_ui.stackpanel.gap: the gap between elements
  • floating_ui.stackpanel.align: the alignment of elements. Available values are LEFT=0, CENTER=1 and RIGHT=2.

Functions

  • floating_ui:element/stackpanel/_add

    Add a child control to the stackpanel.

    Parameter Description
    storage floating_ui:input element The child control to add.

  • floating_ui:element/stackpanel/_dispose

    Dispose the stackpanel and all its child controls.

    No parameters.

TextBlock: TextControl

TextBlock is a basic text area.

Warning

Due to the limitation of text display entities, we cannot acquire the exact size of the text display. Floating UI will try to estimate the size of the text display, but it may not be accurate.

Tip

You can still set the displaying item of the item display, it can be used as a background.

Layout Data

data TextBlock: TextControl {
    type: "textblock"

    # the text to display. If it's a list, it will display multiple lines
    text: (string | list<string>)?

    # the alignment of the text. Can be "left", "center", "right"
    align: string? = "left"
}

Stored Data

data TextBlockStored: TextControlStored {
    size: float[2]
    text: string?
    align: string
}

Scoreboard

  • floating_ui.size0/1: the width/height of the control x10000
  • floating_ui.size0/1_without_scale: the width/height of the control x10000 without scaled
  • floating_ui.root_x/y/z: The the control'x/y/z position relative to the root control x10000
  • floating_ui.parent_x/y/z: The the control'x/y/z position relative to the parent control x10000
  • floating_ui.root_x/y/z_without_scale: The the control'x/y/z position relative to the root control x10000 without scale
  • floating_ui.parent_x/y/z_without_scale: The the control'x/y/z position relative to the parent control x10000 without scale
  • floating_ui.text.line_count: The number of lines in the text. May be inaccurate due to unexpected wraps.

Function

  • floating_ui:element/textblock/_dispose

    Dispose a textblock.

    No parameters.

  • floating_ui:element/textblock/_set_text

    Set the text of a textblock.

    Parameter Description
    storage floating_ui:input temp.text The text to set. Can be a string for single line or a string list for multi-line.

Clone this wiki locally