Version: 2023.2+
Want to learn how to create runtime data binding? Use this example to get started. This example creates a data source asset and uses UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Builder to bind the data source to a UI.
This example demonstrates the following:
You can find the completed files that this example creates in this GitHub repository.
This guide is for developers familiar with the Unity Editor, UI Toolkit, and C# scripting. Before you start, get familiar with the following:
Create a data source asset that contains the properties you want to bind to. In this example, you create a ScriptableObject
asset named ExampleObject
that contains a string
property, a Vector3
property, and a float
property. The float
property is a read-only property that returns the sum of the x
, y
, and z
values of the Vector3
property. The data source asset also contains a local converter that converts a float
to a Color
and a string
.
Create a project in Unity with any template.
In the Assets
folder of your project, create a C# script named ExampleObject.cs
with the following content:
using Unity.Properties;
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;
[CreateAssetMenu]
public class ExampleObject : ScriptableObject
{
[InitializeOnLoadMethod]
public static void RegisterConverters()
{
// Create local Converters
var group = new ConverterGroup("Value To Progress");
// Converter groups can have multiple converters. This example converts a float to both a color and a string.
group.AddConverter((ref float v) => new StyleColor(Color.Lerp(Color.red, Color.green, v)));
group.AddConverter((ref float value) =>
{
return value switch
{
>= 0 and < 1.0f/3.0f => "Danger",
>= 1.0f/3.0f and < 2.0f/3.0f => "Neutral",
_ => "Good"
};
});
// Register the converter group in InitializeOnLoadMethod to make it accessible from the UI Builder.
ConverterGroups.RegisterConverterGroup(group);
}
[Header("Bind to multiple properties")]
public string vector3Label;
public Vector3 vector3Value;
[CreateProperty]
public float sumOfVector3Properties => vector3Value.x + vector3Value.y + vector3Value.z;
[Header("Binding using a converter group")]
[Range(0, 1)] public float dangerLevel;
}
From the menu, select Assets > Create > Example Object. This creates an asset in the Assets
folder of your project.
Rename the asset as ExampleObject.asset
.
Create a UI that binds to the data source asset you created in the previous step. In this example, you create a UXML file that contains a VisualElement with a Vector3Field, a FloatField, and a Label as its child elements.
Assets
folder of your project, create a UXML file named ExampleObject.uxml
.ExampleObject.uxml
file to open it in UI Builder.Bind the UI to the data source asset you created in the previous step. Set the data source for the root VisualElement and bind the label
and value
properties of the Vector3Field elements to the vector3Label
and the vector3Value
properties of the data source asset.
Bind the value
property of the Float to the sumOfVector3Properties
property of the data source asset.
Bind the properties of the Label to the properties of the data source asset and apply the type converter for the Label.
In the Hierarchy panel, select the Label.
In the Inspector panel, right-click the Text property and select Add binding.
In the Add Binding window, do the following:
Select Add binding to save your changes.
In the Inspector panel, expand the Background field.
Right-click the Color property and select Add binding.
In the Add Binding window, do the following:
Select Add binding to save your changes.
Save and close UI Builder. Your ExampleObject.uxml
file looks like the following content:
<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
<ui:VisualElement data-source="ExampleObject.asset" name="VisualElement" >
<ui:Vector3Field label="Vec3 Field">
<Bindings>
<ui:DataBinding property="label" data-source-path="vector3Label" binding-mode="ToSource" />
<ui:DataBinding property="value" data-source-path="vector3Value" />
</Bindings>
</ui:Vector3Field>
<ui:FloatField label="Float Field" value="42.2">
<Bindings>
<ui:DataBinding property="value" data-source-path="sumOfVector3Properties" binding-mode="ToTarget" />
</Bindings>
</ui:FloatField>
<ui:Label text="Label" data-source-path="dangerLevel">
<Bindings>
<ui:DataBinding property="text" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
<ui:DataBinding property="style.backgroundColor" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
</Bindings>
</ui:Label>
</ui:VisualElement>
</ui:UXML>
Update the label text of the Vector3Field in the data source asset to see changes replicated in the UI. Update the value of the Vector3 property in the UI to see changes replicated in the data source asset. Move the slider of the danger level in the data source to see changes replicated in the Label.
Assets
folder of your project, select the ExampleObject.asset
file.ExampleObject.asset
changes to the numbers you entered.ExampleObject.asset
, move the Danger Level slider. The text and the background color of the Label in the UI Builder Viewport change according to the value of the Danger Level.