LTS 2022.3

Object Field

An Object Field is a control where the user can assign an object or asset to a subject. The object field can be configured to receive any object type, such as images, audio clips, textures, terrains.

Implementation references

Scripting API and implementation references.

UI Toolkit

IMGUI

Overview

Examples of an unassigned field with no icon and an assigned field with an object icon, displayed in light and dark themes

Object fields display the object icon when an object is assigned

The object field can be configured to receive any object type
Allowable objects include any type of asset such as images, audio clips, textures, terrains, and materials
Objects can be assigned either by drag and drop or by selecting an object using the object picker

Object fields APIs

An example of an empty object field on the left and a cube mesh object field with an object icon on the right

An empty object field and cube mesh object field with object icon

Object fields in UI Toolkit

UI Builder

About UI Builder ->

UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}

UI Toolkit

ObjectField

Reference for an object field

Docs ->

Object fields in IMGUI

IMGUI

EditorGUI.ObjectField

Makes a field to receive any object type

Docs ->

Guidance

When to use

An object field is an input field that is used when a user needs to assign an object or asset to a subject.

How to use

Avoid hidden or implicit behavior when the object field is unset.
If unsetting the object field changes its behavior, consider hiding the control behind an explicit decision that the user must make (such as a toggles or dropdowns) to make sure the user knows what to expect
Objects can be assigned either by drag and drop, by code or by selecting an object using the object picker
To use the object picker the user must first set up the object type; the object type can include images, audio clips, textures, terrains, and materials

Style

Picker window headers

Example of an object picker for materials with the “Select Materials” header displayed

Object picker for materials with the header “Select Material”

If there is no object type defined for the object field, the object picker window header is “select” by default
If an object type is defined for the object field, the picker window header refers to this type, such as “Select Material” for textures

Drag and drop highlight

Three stages of drag and drop using material for an example with the idle stage on the left, the material dragged in the center and the material assigned on the right

Dragging a material in the material object field

In addition to using the object field button to assign objects, users can drag and drop objects to the object field body.

When an object is being dragged on an object field, its entire body will be highlighted in blue.

Object types

Allowing scene objects

Use allowSceneObjects to allow scene objects to be assigned to the object field.

Unity manual - object types

For more information on allowing scene objects go to Unity Manual > Object Field ->

Setting up object types

Users can set up the object parameter to be a project asset and set the type of object to be any type of asset.

Change GameObject parameter in obj, typeof(GameObject) to define different object types.

Ensure that the allowSceneObjects parameter is false if the object reference is stored as part of an asset, since assets cannot store references to objects in a scene view.

Assigning an object

Two ways to assign an object, with the drag and drop method shown on the left and the object picker window on the right

Assigning a material by drag and drop (left) and using picker window (right)

Users can assign an object to the object field by;

Clicking on object field button to open the picker window and choose the object
Dragging an object from the projects panel onto the object field body. Note that the object type needs to match the object field

Locating assigned objects

An animated image showing a cursor locating a material asset in the project panel by clicking on the object icon

Locating material asset in the project window by clicking the object icon

Clicking the object field body will highlight the assigned objects and their path in the project panel.

Formatting

Anatomy and layout

Anatomy

An annotated image showing the numbered parts of an object field

Anatomy of an object field and its key parts

A numeric field can contain and be paired with the following elements:
‍
1. Control label
2. Object icon
3. Object label
4. Object field button
5. Body (container)

1. Control label

Labels should be placed to the left of the object field and be should be simple and clear, relating to the nature of content.

2. Object icon

Icon representing the type of object picked.

3. Object label

Label of the picked object.

4. Object field button

Button to open up the picker modal.

5. Body (container)

The body of the object field is the container where content (icons, object icon and label, object field button) is displayed.

Interaction states

An object field’s five interactive states in light and dark themes

An object field's interactive states

Default

Default state of an object field.

Hover

When hovering over an object field body the border will be highlighted.
When hovering over the object field button, both the button and border will be highlighted.