2. Overview

Tip

This page will introduce you about the basic concepts and basic operations in Floating UI.

Layout Data

Layout data is a NBT data structure that describes the structure and properties of a UI. It is a JSON-like structure that can be easily understood and written.

Normally, Floating UI's function will accept layout data from storage floating_ui:input data.

A layout data is usually like this :

{
    "type":"panel",
    "size":[5f,5f],
    "child":[
        {
            "type":"textblock",
            "text":"Hello FloatingUI",
            "y":1f,
            "fontsize":2.0f
        },
        {
            "type":"button",
            "y":-1f,
            "size":[1.2f,1.2f],
            "item":{
                "id":"apple"
            }
        }
    ]
}

Like the example above, a layout data consists of a root element, which usually is container control such as panel, and child elements. Field type represents the type of the control, while size, child, text, and other fields are referred to as control properties.

In the next page, you will learn about the basic controls offered by Floating UI.

While generating a UI, each control in the layout data will be generated as a display entity, and the control's layout data will be stored in the entity's NBT. (item.components."minecraft:custom_data".data.ui)

Stored Data

We have already learned that the layout data will be stored in the display's NBT. In addition to layout data, Floating UI also stores other useful data in the display's NBT, all of which are stored under the path item.components."minecraft:custom_data".data.<xxx>. These data are called stored data.

In the next page, you will learn about all controls offered by Floating UI, but for now, let's move to learn about the event and animation in Floating UI.

Event

In Floating UI, event is a way to bind a function to a control. An event will be triggered at a specific time, such as when a button is clicked or a control is just created.

You can assign a namespace ID of a function to an event property to bind a function to an event.

{
    "type":"button",
    "click":"example:event/click"
}

When the button is clicked (either with left or right mouse button), the function example:event/click will be executed.

The executor of the function is the control itself. To access the player who triggered the event, you can use tag floating_ui_owner.

Animation

Floating UI also supports some basic interpolation animations based on display's interpolation. Animation is triggered by event.

All controls have a anim field, which is used to define animations. An animation's structure is as below:

anim: {
    <event_trigger_name>: {
        //this animation will start when the event is triggered
        value: [
            // a list of the properties to be animated
            {
                key: xxx,   //the nbt path of the display
                value: xxx  //target value
            }
        ],
        time: xxx,  //animation duration (tick)
        delay: xxx, //animation delay (tick)
        start: xxx, //event triggered when the animation starts
        end: xxx     //event triggered when the animation ends
    }
}

For example:

{
    "type":"panel",
    "anim":{
        "move_in":{
            "value":[
                {
                    "key":"transformation.scale[]",
                    "value":3f
                }
            ],
            "time":3,
            "start":"example:event/anim/start",
            "end":"example:event/anim/end"
        }
    }
}

When the cursor moves into the panel, the panel will scale up to 3 times in 3 ticks. When the animation starts, the function example:event/anim/start will be executed, and the function example:event/anim/end will be executed when the animation ends.

Access to controls

• name

All controls have a field name. During the creation of a ui, controls with name field will store their UUID in the root entity's tag item.components."minecraft:custom_data".data.names.<name>. If same name is used, the previous one will be overwritten.

• tag

All controls have a field tag. You can use entity selector like @e[tag=<tag>] to access all controls with the same tag.

• passenger and vehicle

Child controls will riding on their parent control, so through execute on passenger or execute on vehicle, you can access all child controls or its parent control if exists.

Every control can access the root control/entity via its stored data root.

Here is an example that demonstrates how to access all child controls with tag qwq of control with name owo:

# execute as the root control

# assume there is an item entity with uuid 0-0-0-0-1

# Set the Thrower to 'owo' so we can access it by `execute on origin`
# NEVER USE `$execute as @e[nbt=${nbt}]`. Its performance is a disaster.
data modify entity 0-0-0-0-1 Thrower set from entity @s item.components."minecraft:custom_data".data.names.owo

# `execute on origin` will choose control 'owo' and `on passenger` will walk through all child controls, so we use if entity to filter out the child controls with tag 'qwq'.
execute as 0-0-0-0-1 on origin on passenger if entity @s[tag=qwq] run function anything

Small Tips

• use function floating_ui:.player_tree to show a player's UI tree in the chat. And execute function floating_ui:util/tree as a root entity to show the UI tree of a root entity.