Introducing shared components
Shared components group entities in chunks based on the values of their shared component, which helps with the de-duplication of data. To do this, Unity stores all entities of an archetype that have the same shared component values together. This removes repeated values across entities.
You can create both managed and unmanaged shared components. Managed shared components have the same advantages and restrictions as regular managed components.
Shared component value storage
For each world, Unity stores shared component values in arrays separate from ECS chunks, and chunks in that world store handles to locate the appropriate shared component values for their archetype. Entities in the same chunk share the same shared component value. Multiple chunks can store the same shared component handle which means there is no limit to the number of entities that can use the same shared component value.
If you change the shared component value for an entity, Unity moves the entity to a chunk that uses the new shared component value. This means that changing a shared component value for an entity is a structural change. If an equal value already exists in the shared component value array, Unity moves the entity to a chunk that stores the index of the existing value. Otherwise, Unity adds the new value to the shared component value array and moves the entity to a new chunk that stores the index of this new value. For information on how to change how ECS compares shared component values, see Override the default comparison behavior.
Unity stores unmanaged and managed shared components separate from one another and makes unmanaged shared components available to Burst compiled code via the unmanaged shared component APIs (such as SetUnmanagedSharedComponentData
). For more information, see Optimize shared components.
Override the default comparison behavior
To change how ECS compares instances of a shared component, implement IEquatable<YourSharedComponent>
for the shared component. If you do this, ECS uses your implementation to check if instances of the shared component are equal. If the shared component is unmanaged, you can add the [BurstCompile]
attribute to the shared component struct, the Equals
method, and the GetHashCode
method to improve performance.
Share shared components between worlds
For managed objects that are resource intensive to create and keep, such as a blob asset, you can use shared components to only store one copy of that object across all worlds. To do this, implement the IRefCounted interface with Retain
and Release
. Implement Retain
and Release
so that these methods properly manage the lifetime of the underlying resource. If the shared component is unmanaged, you can add the [BurstCompile]
attribute to the shared component struct, the Retain
method, and the Release
method to improve performance.
Don't modify objects referenced by a shared component
To work correctly, shared components rely on you using the Entities API to change their values. This includes referenced objects. If a shared component contains a reference type or pointer, be careful not to modify the referenced object without using the Entities API.