Log-in required.

You are trying to access the internal Editor Foundations design system.
Sign-in with your Unity Google account to continue, or visit the public site.

Implementation references

Scripting API and implementation references.

Manual

Inheritance · UX essentials

Effective ways of using inheritance and overrides.

Do not use override UI patterns outside of the context of inheritance
Blue plus sign icon indicating that clicking on this will expand this content
Provide in-context hints to show where an inherited value is coming from
Blue plus sign icon indicating that clicking on this will expand this content
Provides in-context hints to show origin of inherited values
US-0321
Blue plus sign icon indicating that clicking on this will expand this content
Uses UI overrides only on objects with inheritance relationships
US-0322
Blue plus sign icon indicating that clicking on this will expand this content

Overview

Two examples of overridden properties, the first of a prefab instance and the second of a material variant.
1. Prefab instance with overridden property 2. Material variant with overridden property
  • Inheritance is a relationship where child objects receive values from an original parent object
  • A parent object defines specific properties and values, from which inheriting child objects draw their values; if changes occur to the parent object, inheriting child objects will reflect those changes automatically
  • An override is when a value set on a child object prevails over and replaces a value inherited from a parent object; an override is a feature of inheritance relationships, and has specific design and workflow patterns

When to use inheritance

Inheritance offers several advantages over individually setting values for each object:

  • Accelerate changes - when adjustments are made to a parent object, child objects automatically inherit those values without requiring additional time for manual input
  • Object management - inheritances allow easier management of large numbers of child objects that would otherwise require individual configuring and tracking
  • Reduce errors - inherited values accurately cascade down to child objects without the risk of incorrect values being introduced whenever values are manually entered
  • Reduce data redundancy and compiling speed - data values of child objects do not need to be stored and will not add additional burden to the compiling process

Terminology and diagram

An illustration of inheritance relationships and common related terminology.
Examples of inheritance relationships and their common terminology

Object

An illustration of an object which is a fundamental aspect of inheritance relationships
An object is a foundational aspect of inheritance relationships

An object is an entity or asset defined using specific properties.

Examples of objects in the Editor include:

  1. GameObjects
  2. Prefabs
  3. Materials
  4. VisualElements

Property and value

An illustration of properties and values  which are fundamental aspects of inheritance relationships
Properties and values are foundational aspects of inheritance relationships

A property is an object parameter that stores a value. The property definition should designate the specific type of value the property can store.

Examples of properties include:

  1. GameObject / Prefab: Position, rotation, camera component
  2. Material: Rendering mode, emission
  3. VisualElement: Text attributes, font family

Inheritance

An illustration of an inheritance relationship, with solid lines indicating the original object and values while dashed lines indicating the object instance and its inherited values
Inheritance is a relationship between an original object and its object instances

Inheritance is a relationship between a parent object and its child objects.

A parent object defines specific properties and values, from which child objects will derive their values; if the parent object’s values change, the child objects will reflect those changes.

Instance

An illustration of the instance’s role in inheritance relationships
 An instance of an object inherits properties and values from its parent

An instance of an object is a single occurrence of an original object and, in the context of inheritance, refers to child objects that inherit properties and values from its parent.

Instances are a reference to the parent object, and may be stored in, or “live" in, a different place than the parent objects. For example, while Prefab objects are stored in the Project, Prefab instances are stored in the Hierarchy of the Scene.

Examples

Prefabs

An illustration of the Prefabs example of inheritance relationships
Prefabs are reusable assets from which new Prefab instances can be created
An example of the original Prefab and a Prefab instance with overridden properties

Materials

An illustration of the materials example of inheritance relationships
A materials example of inheritance relationships
A side-by-side comparison of an original Material variant on the left and a Material variant with an overridden property on the right
Inheritance features in a Material example with an overridden property

Visual Elements (UI Builder Properties)

An illustration of the UI Builder example of inheritance relationships where a USS Selector has been applied to a VisualElement
A USS Selector applied to a VisualElement
A side-by-side comparison of a USS Selector applied to a VisualElement on the left and on the right, an illustration of how the color property is inherited from the USS Selector
Inheritance features in a UI Builder example

2D Sprite Library

An illustration of a 2D Sprite Library example of inheritance relationships
An example of a 2D Sprite Library Asset’s inheritance relationships
An illustration of inheritance features in a 2D Sprite Library
An example of inheritance features in a 2D Sprite Library

Inheritance features

Inheritance

Signifying inheritance

At the value level:

  • it is not always required to overtly signify that a value is inherited at first glance.

    consider whether it is useful to use additional visual signifiers to indicate to the user that a value is inherited; though additional visual signifiers can be useful, consider whether they add unnecessary visual clutter and whether they are useful to all users, or only a small subset of users
  • provide information that a value is inherited to users upon further interaction, for example in a tooltip on hover

At the object level:

  • signify the parent object that the instance is inheriting from
  • use an object field control to signify the parent object, as it enables the user to reference the parent object asset directly from the control
An illustration showing, on the left, inheritance info in tooltip on hover in UI Builder and, on the right, showing the object field control in Prefabs
On the left is an example showing inheritance info in tooltip on hover in UI Builder; on the right is an example of the object field control in Prefabs
Manipulating inheritance

Inheritance relationships are typically manipulated and managed at the object level.

Creating an inheritance relationship
Parent objects are usually stored as assets in the Unity project.

There are typically two ways that parent objects can be created:

  • A user may create a parent object asset in the Unity project, and create or link instances from that asset
  • A user may create a regular object in its primary context (eg. a GameObject in the scene), and choose to convert it to an original object (eg. Prefab)
  • If a regular object is converted to a parent object, a parent object asset will be created, and the regular object will be converted to an instance of that parent asset

Deleting an inheritance relationship is known as detaching:

  • When an instance is detached from its parent object, it retains the values it had at the time of detaching, and changes made in the original object from that point forward do not get reflected in the instance
  • If inherited values are overtly signified in the UI, then inheritance signifiers should disappear when the instance is detached; override signifiers should also disappear
Multiple inheritance levels

It is possible for multiple levels of inheritance to exist. One type of multi-level inheritance is variants.

  • For simplicity, only provide the user with the final resolved value at a glance
  • Provide more detailed information to users upon further interaction
  • For example, if a value can inherit from multiple sources, provide what those sources are, and in what order those sources will apply to the value

Overrides

Definition
An illustration of overrides role in inheritance relationships
An override is when a value set on a child object prevails over and replaces a value inherited from a parent

An override is when a value set on a child object prevails over and replaces a value inherited from a parent. Overrides are primarily an authoring-time feature.

When to use overrides

Overrides represent a specific inheritance concept in the Editor, and is expressed through a specific set of UI and UX features.

Don't recommendation illustrated by a red X icon

Do not use override UI patterns in features that do not make use of the conceptual model of overrides and inheritance as defined above.

What is not an override:

  • Overrides only exist when an inheritance relationship exists between an object and its instance
  • If an object’s instance does not preserve the relationship with its parent object (ie. in the example of a copy-pasted or cloned object), then overrides may not be set on the instance
Signifying overrides

In the Editor, an override is signified at the value level using the override bar.
-> see the Anatomy & UI section

It is important to preserve the meaning of the override bar, as users associate it with a specific concept in the Editor and are able to apply that concept in multiple areas, including areas new to them.

Don't recommendation illustrated by a red X icon

Do not use the override pattern just to indicate “this line is different”:

  • The visual design pattern that the override bar uses is a common design solution in the Editor
  • The override bar is often incorrectly used to denote that an inspector property field is different from the rest around it. However, if the use case does not truly reflect the conceptual mental model of an override, refrain from using the override bar UI. Explore other options to visually indicate that an element is different, taking fundamental design guidelines -> and accessibility -> into account.

    See overrides anatomy ->


At an object level, provide an aggregate view of all overrides on the object so that the user may work efficiently.

See the Overrides at an object level section ->

Manipulating overrides

At a value level:

  • allow the user to compare overridden values to inherited values
  • allow the user to revert overridden values to inherited values
  • allow the user to push overridden values back to the original parent object so that other child objects will inherit the overridden value
  • provide these options to the user in-context; for example, in a context menu on the value directly
An illustration of context menu options for overrides for a Material Variant
Context menu options for overrides

At an object level:

  • provide a consolidated view of all overrides on the object so that the user may work efficiently
  • allow the user to manipulate overrides using a consolidated view of all overrides on the object
  • allow the user to accomplish the same actions as at the value level; for example, in a Prefabs overrides dropdown
An illustration showing an overrides menu
An overrides menu
An illustration showing a side-by-side comparison of a Prefabs inspector header with a mini inspector
An example showing overrides in a Prefabs inspector header compared to a mini inspector

Optional features

Variants

Definition
Visual diagram that illustrates the variant’s role in inheritance relationships
Consider implementing variants in your feature if it will be heavily used by medium- to large-sized production teams

A variant

  • is a unique type of child object of a parent object
  • inherits properties and values from the parent object, but can also have overrides that its child objects inherit from
  • functions both as a parent object and as a child object
  • it is impossible to create a variant without first having a parent object
When to use variants

Consider implementing variants in your feature if it will be heavily used by medium- to large-sized production teams, where multiple users with different responsibilities access a single Unity project.

Signifying variants

Iconography
Variant assets in Unity are marked with an icon that is a variation of the parent object’s icon. Variants have a distinct, consistent visual language applied to the parent object’s icon.

Request variant icons (internal) ->

Side-by-side comparisons of icon variants for Prefabs, Materials, 2D Sprite Libraries
Variant assets in Unity are marked with an icon that is a variation of the parent object’s icon

Inheritance Tree View

  • Follow the same general principles for signifying multi-level inheritance relationships
  • For variants, consider using the inheritance tree view, which allows the user to see the inheritance tree of any variant, including all its parent objects and all its variant child objects
An illustration showing an inheritance tree dropdown
For variants, consider using the inheritance tree view, which allows the user to see the inheritance tree of any variant
Manipulating variants

Creating variants

Typically, variants are stored the same way as other parent objects: as assets in the Unity project.

There are typically two ways that variants can be created:

  • A user may create a variant of a parent object
  • A user may create an instance of a parent object, and choose to convert it to a variant
  • When the original instance is converted to a variant, a variant asset will be created, and the original instance will be converted to an instance of that variant asset
  • The original instance’s overrides will become regular values set on the variant that its instances inherit from
The creation of a material variant asset using the create menu
+++  Image of real UI, divided in two halves. 1. Real UI example of creating variant asset in create menu (materials); 2. Real UI example of creating variant asset by using inheritance tree dropdown (materials)
+++  Image of real UI, divided in two halves. 1. Real UI example of creating variant asset in create menu (materials); 2. Real UI example of creating variant asset by using inheritance tree dropdown (materials)

Deleting Variant Relationships (Detaching)

  • A variant may be detached from the parent object it inherits from
  • When the variant is detached from its parent object, this breaks the inheritance relationship between the variant and its parent object, but preserves the inheritance relationships between the variant and its child objects
  • When the variant is detached from its parent object, it becomes a parent object asset instead of becoming a variant asset

Override locking

Definition
An illustration of override locking in inheritance relationships
A user may want to lock certain properties of a parent object
  • A user may want to lock certain properties of a parent object
  • When a property is locked on a parent object, any instances of that object may not override that particular property
When to use override locking

You might consider implementing override locking in your feature if your feature will be heavily used by medium- to large-sized production teams, where multiple users with different responsibilities access a single Unity project.

Signifying override locking

Signifying on parent objects
Show the override locking feature upon hover next to the property that can be locked.

Signifying on instances

  • Show the lock icon next to a locked property, and disable the property UI.
  • Explain to the user where the override lock is coming from.
An illustration of a lock icon next to overridden property with an explanatory tooltip
Show the lock icon next to a locked property and disable the property UI

Anatomy and UI

Override bar

Side-by-side illustrations of an override bar in the Inspector on the left and an override bar in the Hierarchy on the right
The override bar is the visual signifier that denotes the presence of an override on the property.

The override bar is the visual signifier that denotes the presence of an override on the property.

Layout

An illustration of a Prefab override in the Inspector, annotated with its size and layout information
A Prefab override in the Inspector
  • It appears on the left side of the label of a property in an inspector
  • Its height is the same as the entirety of the property it is overriding
  • If the override exists for an entire inspector component, ensure that the override bar appears on the inspector component header, and the entire height of the inspector component with no line breaks.
  • For example, if a user adds a new inspector component to a Prefab instance that the original Prefab did not have, an override bar would appear on the entire inspector component. In essence, the user is overriding an inherited value of “null” for that inspector component by adding it on the instance.

Style

An illustration of override bars in light and dark themes
Override bars in light and dark themes
Override bar
The color of all other override bars (eg. Materials)
#090909
#C4C4C4
.unity-binding__prefab-override-bar-not-applicable
The color of the override bar for a Prefab override when disabled
rgba(50, 163, 225,0.35)
rgba(5, 147, 224,0.35)
.unity-binding__prefab-override-bar
The color of the override bar for a Prefab override
rgb(50, 163, 225)
rgb(5, 147, 224)
Icon of a red triangle to indicate a message of warning.
Use bold labels to highlight overrides
The label that the override appears next to should appear bolded; this provides a subtle reinforcement of the override bar signifier.

Interactable area

Illustration of a Prefab override in the Inspector, annotated with its interactable area
A Prefab override in the Inspector, annotated with its interactable area
  • When including features to manipulate an override, ensure that the interactable area is large enough by including the overridden property label