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 to see changes replicated in the data source asset. Update the value of the Vector3 property in the data source asset to see changes replicated in the UI Builder ViewportThe user’s visible area of an app on their screen.
See in Glossary. Drag 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. The Vector3 Label in the Inspector window changes to the text you entered in the previous step.ExampleObject.asset, change Vector 3 Value to random numbers. The Vector3Field in the UI Builder Viewport changes to the numbers you entered. The FloatField changes to the sum of the numbers you entered.ExampleObject.asset, drag 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.