v0.x

Attributes List

A collection of attributes to create custom UIs for your own behaviours

Class Attributes

The following attributes are only available to use with your behaviour classes.

CustomName

[CustomName(string name)]

Sets a custom name shown in the header bar, otherwise the header bar is hidden.

[CustomName("My Fancy Controller")]
public class MyUdonSharpBehaviour : UdonSharpBehaviour {}

HelpMessage

[HelpMessage(string message)]

Displays a box with some text below the controller's header bar and above the rest of the UI. Usually used to describe the purpose of the behaviour if it is not obvious, or to warn user about anything in particular.

[HelpMessage("This behaviour should be enabled at all times")]
public class MyUdonSharpBehaviour : UdonSharpBehaviour {}

OnBeforeEditor

[OnBeforeEditor(string methodName)]

Calls the specified method every editor update loop before all the editor code was executed. The SerializedObject is passed to your method as a parameter which you can use to perform any necessary modifications.

[OnBeforeEditor("BeforeEditor")]
public class MyUdonSharpBehaviour : UdonSharpBehaviour {
  public void BeforeEditor(SerializedObject obj) {
    // do stuff
  }
}

OnAfterEditor

[OnAfterEditor(string methodName)]

Calls the specified method every editor update loop after all the editor code was executed. This will contain all the latest values before they are saved into the object. The SerializedObject is passed to your method as a parameter which you can use to perform any necessary modifications.

[OnAfterEditor("AfterEditor")]
public class MyUdonSharpBehaviour : UdonSharpBehaviour {
  public void AfterEditor(SerializedObject obj) {
    // do stuff
  }
}

OnValuesChanged

[OnValuesChanged(string methodName)]

Calls the specified method whenever any value has been changed by the user in the inspector. The SerializedObject is passed to your method as a parameter which you can use to perform any necessary modifications.

If you need to react to a specific value change - use a field-level OnValueChanged attribute

[OnValuesChanged("ValuesChangeHandler")]
public class MyUdonSharpBehaviour : UdonSharpBehaviour {
  public void ValuesChangeHandler(SerializedObject obj) {
    // do stuff
  }
}

Field Attributes

These attributes are meant to go on public fields of your Controller. They serve as UI building blocks and provide an ability to react to value changes, for example if you would like to do something specific in the scene when user checks a checkbox.

Note: these attributes use a property modifier approach, as unity doesn't allow stacking multiple property drawers otherwise. Make sure to use them in combination with a [UTEditor] or an [UTEditor] attribute, or they will not do anything. Both of those should go last in the chain, right before the public keyword.

Attribute Order

Some attributes affect whether the field is displayed or not, for those - order of the attributes is important. Attributes are evaluated in reverse - from last (the one before the public/private keywords) to first. You can manually adjust the order of the attribute without changing its actual position by adding an extra int parameter at the end. Most attributes will respect the visibility value passed to them and hide themselves. Here's an example.

// This will not hide the SectionHeader but will hide the field itself
[HideIf("@someBool")]
[SectionHeader("Test")]
[UTEditor]
public float foo;

// This will hide the SectionHeader and the field itself
[SectionHeader("Other Test")]
[HideIf("@someBool")]
[UTEditor]
public float var;

public bool someBool;

This kind of behaviour is intentional and is helpful in cases where you only want to hide the field but leave the Section Header for the fields below, etc.

Many of these attributes can be combined to form more elaborate UI systems, so something like this is completely normal

[OnValueChanged("HandleChange"]
[HelpBox("Value cannot be negative", "CheckValueValidity")]
[HideIf("@!transition")]
[HideLabel] [UTEditor]
public float duration;

Common Parameters

Some attributes share parameter names. One of such parameters is methodName. In most cases you will be able to pass either a method, or a variable name to it (where it makes sense, there are exceptions, and they are mentioned separately).

// Will execute `ShouldShowBox` to determine whether the box should be visible
[HelpBox("", "ShouldShowBox")] [UTEditor];
public bool active;

// Must return `bool`
public bool ShouldShowBox() {
  return active;
}

To use a variable instead of a method - prefix the variable name with @, you can also invert the variable value by adding ! after that.

// Will show if active is `true`
[HelpBox("", "@active")] [UTEditor];
public bool active;

// Will show if active is `false`
[HelpBox("", "@!active")] [UTEditor];
public bool active;

This can be any public variable of a class, doesn't have to be specifically the same variable. You can use something like [HideInInspector] for storing the state of the box without displaying it in the editor.

SectionHeader

[SectionHeader(string title)]

Displays a visual separator box with some text

[SectionHeader("General")][UTEditor]
public Transform sourceTransform;

HelpBox

[HelpBox(string message, [string methodName])]

Displays a box with a help message. You can conditionally hide and show the box based on a method or variable. See Common Parameters for more info.

// Always visible
[HelpBox("This option disables rotation transfer")]
[UTEditor]
public bool ignoreRotation;

// Only visible if provided variable is set to `true`
[HelpBox("This option disables rotation transfer", "@ignoreRotation")]
[UTEditor]
public bool ignoreRotation;

// Only visible if provided variable is set to `false`
[HelpBox("This option disables rotation transfer", "@!ignoreRotation")]
[UTEditor]
public bool ignoreRotation;

// Only visible if the provided method returns `true`
[HelpBox("This option disables rotation transfer", "ShowIgnoreHelp")]
[UTEditor]
public bool ignoreRotation;

public bool ShowIgnoreHelp() {
  return ignoreRotation;
}

HideIf

[HideIf(string methodName)]

Hides the field based on the provided method or variable. See Common Parameters for more info.

public bool enableEffects = true;

// Hides the field if `enableEffects` is unchecked
[HideIf("@!enableEffects")]
[UTEditor]
public float effectsDuration;

public bool skipTransition;

// Hides the field if `skipTransition` is checked
[HideIf("This option disables rotation transfer", "@skipTransition")]
[UTEditor]
public float transitionDuration;

// Hides the fields if the provided method returns true
public bool enableEffects;
public float effectsDuration;

[HideIf("HideExtras")]
[UTEditor]
public bool extraOption1;

[HideIf("HideExtras")]
[UTEditor]
public bool extraOption2;

public bool HideExtras() {
  return enableEffects && effectsDuration > 0;
}

HideLabel

[HideLabel]

Simply hides the field label and draws the value field only. Helpful in combinations with things like Horizontal attribute

// Will show the checkbox only
[HideLabel] [UTEditor]
public bool active;

OnValueChanged

[OnValueChanged(string methodName)]

Calls provided method when the value of the variable changes, so you can react to it in the UI. Has some special behaviour when used together with ListView.

Due to limitations of Udon - the use of #if !UDONSHARP_COMPILER && UNITY_EDITOR is required for the handler methods

For regular fields the method signature should look like public void MethodName(SerializedProperty value)

// Will call the provided method with the fresh value every time it changes
[OnValueChanged("ToggleLights")] [UTEditor]
public bool lightsActive;

// Incoming value will be the new value, while the current variable will not be updated yet.
// This allows you to compare old and new values.
#if !COMPILER_UDONSHARP && UNITY_EDITOR
public void ToggleLights(SerializedProperty value) {
  // cast to the expected type first
  var val = value?.boolValue;
  if (value) {
    // do something here
  } else {
    // do something here
  }
}
#endif

For array type fields the method signature is public void MethodName(SerializedProperty value, int index)

[OnValueChanged("HandleArrayChange")] [UTEditor]
public string[] namesList;

#if !COMPILER_UDONSHARP && UNITY_EDITOR
public void HandleArrayChange(SerializedProperty value, int index) {
  // if value is `null` - the value at `index` was removed
  if (value == null) {
    // handle removal
    return;
  }
  // if `index` is out of range of the current array - a new value was added
  if (index == namesList.length) {
    // handle addition of new value
    return;
  }
  // handle change of an existing value
}
#endif

When used with ListView the method signature should be different: public void MethodName(object lValue, object rValue, int index), where lValue and rValue represent the left and right variable of the list view at the changed index.

You only need to attach [OnValueChanged] to the first instance of a particular ListView.

[OnValueChanged("HandleChange")
[ListView("Events List")][UTEditor]
public UdonBehaviour[] udonTargets;

[ListView("Events List")][UTEditor]
public string[] udonEvents;

// Handle a change of row values
#if !COMPILER_UDONSHARP && UNITY_EDITOR
public void HandleChange(SerializedProperty lValue, SerializedProperty rValue, int index) {
  // when the value is removed - both will be null
  if (lValue == null && rValue == null) {
    // handle the removal of a row at `index` here
    return;
  }
  // when the value is added - `index` will be out of range of the current list
  if (index == udonTargets.Length) {
    // handle addition of new row
    return;
  }
  var lCasted = (UdonBehaviour) lValue?.objectReferenceValue;
  var rCasted = rValue?.stringValue;
  // handle change of an existing values
}
#endif

If you wish to get a full value instead of just the changed elements in both Array types and the ListView powered blocks, you will need to use a different signature.

  • For regular arrays: public void MethodName(SerializedProperty[] value)

  • For ListView blocks: public void MethodName(SerializedProperty[] lValue, SerializedProperty[] rValue)

If you also want to update some other value on the same object inside the change handler function - you need to accept an incoming SerializedObject as well

  • For regular arrays: public void MethodName(SerializedObject obj, SerializedProperty[] value)

  • For ListView blocks: public void MethodName(SeriazliedObject obj, SerializedProperty[] lValue, SerializedProperty[] rValue)

You can then use it to update properties like obj.FindProperty("someProp").floatValue = 0.01f

[OnValueChanged("HandleArrayChange")] [UTEditor]
public string[] namesList;

// Log current array value as `Values: array[0], array[1]...`
#if !COMPILER_UDONSHARP && UNITY_EDITOR
public void HandleArrayChange(SerializedProperty[] value) {
  var casted = value.ToList();
  // don't forget to grab the value of needed type or cast it from i.objectReferenceType as <yourTargetType>
  Debug.LogFormat("Values: {0}", string.Join(", ", casted.Select(i => i.floatValue).ToArray()));
}
#endif

// Works for `ListView too
[OnValueChanged("Hand`leChange")
[ListView("Events List")][UTEditor]
public UdonBehaviour[] udonTargets;

[ListView("Events List")][UTEditor]
public string[] udonEvents;

// Log current `ListView` value as `Event: udonEvents[i], Target udonTargets[i].name`
#if !COMPILER_UDONSHARP && UNITY_EDITOR
public void HandleChange(SerializedProperty[] lValue, SerializedProperty[] rValue) {
  var cLeft = leftVal.ToList();
  var cRight = rightVal.ToList();
  var eventNames = new List<string>();
  for (int i = 0; i < cLeft.Count; i++) {
    var behName = cLeft[i].objectReferenceValue != null
      ? (cRight[i].objectReferenceValue as UdonBehaviour).name
      : "null";
    eventNames.Add($"Event: {cRight[i].stringValue}, Target: {behName}");
  }
  Debug.Log(string.Join("\n", eventNames));
}
#endif

[OnValueChanged("HandleSliderChange")] [RangeSlider(0, 2) [UTEditor]
public float someFloat = 0.2f;

public bool someBoolProp;

// Modify another property in response to a value change
#if !COMPILER_UDONSHARP && UNITY_EDITOR
public void HandleSliderChange(SerializedObject obj, SerializedProperty value) {
  obj.FindProperty("someBoolProp").boolValue = value.floatValue > 1;
}
#endif

Check CustomUISample.cs for live examples!

Horizontal

[Horizontal(string groupName)]

Combines two fields into a horizontal group based on the provided name. You can define variables in any order, they can even have other variables between them. The fetching is done purely by the group name.

// When using object types its pretty common to use a `[HideLabel]` attribute to make the UI cleaner
[Horizontal("Group")] [HideLabel] [UTEditor]
public GameObject varA;

// Only 2 variables per group are supported at this time
[Horizontal("Group")] [HideLabel] [UTEditor]
public string varB;

// You can have many groups in a controller
[Horizontal("OtherGroup")] [Udon Public]
public int varC;

[Horizontal("OtherGroup")] [Udon Public]
public int varD;

ListView

[ListView(string name, [string addMethodName], [string addButtonText])]

Combines two arrays into a connected list of elements.

This is a cornerstone attribute of UdonToolkit. Due to dictionaries not being exposed in Udon we have to split things into separate arrays which makes navigating logically connected pieces of data very annoying, as well as forcing you to manually keep track of having enough elements in both arrays.

ListView covers that use case and provides some extras when combined with the Popup attribute.

[ListView("Udon Events List")] [UTEditor]
public UdonBehaviour[] udonTargets;

[ListView("Udon Events List")] [UTEditor]
public string[] udonEvents;

You can provide a custom add method to have full control on how the arrays are populated. It is also a good way to create something in the scene, like an instance of a prefab or a basic GameObject and set it as the list value at the same time.

You only need to configure the extra parameters in the first instance of ListView for a particular group.

// You can also customize the add button text via an extra argument
[ListView("Udon Events List", "AddEvent", "Add new Event")] [UTEditor]
public UdonBehaviour[] udonTargets;

// No need to define extra configuration here, the first instance of `ListView` for that group name is going to be used
[ListView("Udon Events List")] [UTEditor]
public string[] udonEvents;

// The addition is fully relegated to your custom method, you can do whatevery you find suitable in here
public void AddEvent() {
  var newTargets = udonTargets.ToList();
  newTargets.Add(null);
  udonTargets = newTargets.ToArray();

  var newEvents = events.ToList();
  newEvents.Add($"NewEvent_{events.Length}");
  events = newEvents.ToArray();
}

Combining it with a [Popup] attribute is the way this is used the most across Udon Toolkit's behaviours. Creating list of Udon events and Animator triggers becomes a matter of a single line of code that handles everything behind the scenes.

[ListView("Udon Events List")] [UTEditor]
public UdonBehaviour[] udonTargets;

// You can combine many attributes together, here we use `Popup` to automatically populate the events list for us
[ListView("Udon Events List")]
[Popup("behaviour", "@udonTargets", true)]
public string[] udonEvents;

You can read more about [Popup] and how it can be populated right here

RangeSlider

[RangeSlider(float min, float max)]

Provides a slider to control the value in a predefined range, supports both floats and ints.

[RangeSlider(1, 10)] [UTEditor]
public float floatValue;

// If the value is int - slider will auto snap to only int values
[RangeSlider(3, 20)] [UTEditor]
public int intValue;

Popup

[Popup(string methodName)]

Shows a popup with options to choose from and support for multiple sources of data. Only supported on string variable types at this time.

You can provide a method, or a variable, to populate the popup options list. See Common Parameters for more info.

// Use a variable to populate the popup options
[SectionHeader("Popups")] [Popup("@popupOptions")] [UTEditor]
public string popupVar;

[NonSerialized] public string[] popupOptions = {"foo", "bar", "fizz", "buzz"};

// You can also use a method to calculate options dynamically
[SectionHeader("Popups")] [Popup("GetOptions")] [UTEditor]
public string popupVar;

public string[] GetOptions() {
  return new [] { "foo", "bar", "fizz", "buzz" };
}

// The method can accept a serialized property if you want to dynamically generate the options
#if !COMPILER_UDONSHARP && UNITY_EDITOR
public string[] GetOptions(SerializedProperty prop) {
  return new [] { $"options for {prop.name}" };
}
#endif

PopupSource and ShaderPropTypes are both DEPRECATED since UdonToolkit v0.4.0, documentation is provided for legacy reasons

DEPRECATED [Popup(PopupSource sourceType, string methodName, [[ShaderPropType shaderPropType], [bool hideLabel]])]

[Popup(PopupSource sourceType, string methodName, [[ShaderPropType shaderPropType], [bool hideLabel]])]

By providing an explicit sourceType other than Method you can use the built-in Toolkit's ability to fetch a list of Animator Triggers, Udon Behaviour Custom Events or Shader Properties of a particular type. If there are no triggers or events available - the UI will inform you about it.

There are plans to add more sources in the future, like Material properties and other native elements.

You can combine this with [ListView] attribute to achieve dictionary-style results for Udon Behaviours. When used inside ListView - the popup method will be called with the Serialized Property of the current element on the opposing array (see example below).

// a namespace to work with Lists
#if !COMPILER_UDONSHARP && UNITY_EDITOR
using System.Collections.Generic;
#endif
// We use `[Horizontal]` to visually connect the source and the popup
[Horizontal("AnimationTrigger")] [HideLabel] [UTEditor]
public Animator animator;

// Using an Animator source type to auto fetch Triggers from the `animator` variable
[Horizontal("AnimationTrigger")] [Popup("animator, "@animator", true)] [UTEditor]
public string somePopupVar;

[Horizontal("BehaviourTrigger")] [HideLabel] [UTEditor]
public UdonBehaviour behaviour;

// Using an UdonBehaviour source type to auto fetch Custom Events from the `behaviour` variable
[Horizontal("BehaviourTrigger")] [Popup("behaviour", "@behaviour", true)] [UTEditor]
public string behaviourPopupVar;

[Horizontal("ShaderProperty")] [HideLabel] [UTEditor]
public Shader shader;

// Using a Shader source type to auto fetch `float` Shader Properties from the `shader` variable
[Horizontal("ShaderProperty")] [Popup("shader", "@shader", true)] [UTEditor]
public string shaderPopupVar;

// You can also specify which type of shader proeprty to grab
[Popup("shader", "@shader","vector", false)] [UTEditor]
public string shaderPopupVectorVar;

[ListView("Test List")]
public Transform[] transforms;

[ListView("Test List")]
[Popup("GetChildrenOptions")]
public string[] selectedChildren;

#if !COMPILER_UDONSHARP && UNITY_EDITOR
// prop in this case is the element of `transforms` array on the current index
public string[] GetChildrenOptions(SerializedProperty prop) {
  var transObj = (Transform) prop.objectReferenceValue;
  if (transObj == null) {
    return new[] { "-- no transform set --"};
  }
  var childList = new List<string>();
  for (int i = 0; i < transObj.childCount; i++) {
    var child = transObj.GetChild(i);
    childList.Add(child.name);
  }

  return childList.ToArray();
}
#endif

Toggle

[Toggle([string label])]

Toggle-type button for boolean fields.

Combines well with things like [HideIf] attribute to toggle parts of the UI on and off to hide things that are unused in a particular toggle state.

// Use the variable name as the toggle label
[Toggle] [UTEditor]
public bool addSFX;

// Combine with [HideIf] to hide a variable that is irrelevant if the toggle is `false`
[HideIf("@!addSFX")] [Udon Public]
public float someThirdVar;

// Use a custom toggle label
[Toggle("Custom Label")] [UTEditor]
public bool extraToggle;

UTEditor

[UTEditor]

A helper attribute that allows UdonToolkit's stackable Attribute system to works. Most attributes won't work without it.

TL;DR: Unity doesn't like having multiple PropertyDrawer attributes, so UdonToolkit technically tries to behave like a single PropertyDrawer with a bunch of modifiers stacked on top. Due to that the modifiers need a "base" to work off, [UTEditor] is that base. I have a full talk that goes over it

Has no visual effects by itself.

// This will display a section header
[SectionHeader("General")] [UTEditor]
public bool active = true;

Disabled

[Disabled([string methodName])]

Disables the editing of the provided field completely, or based on the provided methodName. Useful when manually populating fields via editor scripts (like with OnValueChanged) or in runtime.

When used with ListView it should be put on the first field in the list view.

// Make a field read only
[Disabled]
public bool toggleThings;

// Make a field read only based on a method return value
[Disabled("GetDisabled")]
public float disabledFloat;

public bool GetDisabled() {
  return gameObject.activeSelf;
}

public bool allowEditing;

// Make a list view read only
[ListView("Stuff")][Disabled("@!allowEditing")][UTEditor]
public Transform[] objects;

[ListView("Stuff")][UTEditor]
public string[] objectDescriptions;

Method Attributes

These attributes are meant to be added to your public methods and are handled separately. The UI for these is rendered after the main inspector is done, so they will always be at the bottom.

Button

[Button(string text, [bool activeInEditMode])]

Displays a button that calls the specified method, useful for in-editor testing.

The main use case here is to expose your custom events as buttons in the inspector or provide some extra functionality to speed up iteration process.

Currently, these buttons are disabled unless you enter play mode.

// Creates and Interact button to trigger the builtin Udon Interact event
[Button("Interact")]
public void Interact() {
  // UTController base class stores the currently attached UdonBehaviour here
  if (uB == null) return;
  uB.Interact();
}

// Creates a button that will send a custom event to your behaviour on click
[Button("Activate")]
public void Activate() {
  if (uB == nul) return;
  uB.SendCustomEvent("Activate");
}

// Creates a button that will be clickable in edit mode
[Button("Editor Action", true)]
public void DoEditorStuff() {
  Debug.Log("We're doing editor stuff!");
}
PreviousAttributes OverviewNextGuides Overview

Last updated