Question What is Unity.Hierarchy for?

Greetings!

Since you guys have found the built-in hierarchy core module, I guess it is worth bringing some information about the topic.

The goal behind this new module is to provide a high performance, highly scalable data container tailored for hierarchical data, that is also fully runtime compatible. Those APIs will then serve as a foundation for other projects that we are working on. Please note that the API is not final yet and will most likely change (hopefully not too much).

Let’s discuss the new APIs. The main point of entry is the Hierarchy class. This object can be used to create and manage hierarchical data. To achieve the highest level of performance, the implementation uses a data oriented approach, where the nodes of the hierarchy are lightweight handles; they do not carry actual data themselves. This is why you will notice the HierarchyNode struct only contains an ID and version.

When you need to add data per node, you do this using the property APIs on the Hierarchy. Properties have a name and storage strategy. Once you create or get a property, you can then get or set the value of that property for the specified node. The storage strategy allows to control whether or not you want to allocate memory for every node (sparse array strategy), or only allocate memory for nodes that actually have a value set (dense array strategy). Property data is allocated in native and fully aligned, so that we can filter values as fast as possible, which is necessary to support fast searches.

By default, nodes added to the hierarchy are typeless. That is, they do not have special functionalities. But in case you need to handle different types of nodes within the same hierarchy, you can register what we call a “hierarchy node type handler”. This node handler essentially defines the behavior of your node type. For example, node handlers will allow game objects, entities and other kinds of nodes to all happily live in the same hierarchy.

The next big class is the HierarchyFlattened, which depends on a Hierarchy instance to feed it data. This is essentially an acceleration structure that is used when you need to transform the hierarchical data into a flat array, which is usually required for displaying efficiently in UI. It is highly optimized to only update when the hierarchy topology changes, and it is able to copy results from a previous update if it detects an entire branch didn’t change. The HierarchyFlattened is an array of HierarchyFlattenedNode, which holds additional information about the structure of the hierarchical data, so you can quickly get offsets of parent, siblings, etc. within the array.

And finally, there is the HierarchyViewModel class. This one sits on top of a HierarchyFlattened instance, and its main purpose is to filter the flattened array for viewing. For example, it's used to filter out nodes that are collapsed, or to filter nodes based on advanced search queries. Essentially, this is the object from which one would read the data to display in the UI.

We are planning new features to be built on top of this technology and are using it to improve existing features. We are also considering making a public UI Toolkit control to take advantage of our accelerated container. All these new functionalities will be available at runtime, which means it will all be available to your games if you need to store, manage and display hierarchies. If you have questions about this new API, feel free to ask here. Cheers!