Interface ISharedComponentData

An interface for a component type whose value is shared by all entities in the same chunk.

Namespace: Unity.Entities

Syntax

public interface ISharedComponentData

Remarks

ISharedComponentData implementations are subject to the same constraints as IComponentData.

ISharedComponent implementations must implement IEquatable<T> and GetHashCode().

Note: Currently, the ISharedComponentData interface allows fields having reference types. However, we plan to restrict ISharedComponentData to unmanaged, blittable types only in a future version of the Entities package.

When you add a shared component to an EntityArchetype, ECS stores entities assigned the same values of that shared component in the same chunks. Thus, shared components further categorize entities within the same archetype. Use shared components when many entities share the same data values and it is more efficient to process all the entities of a given value together. For example, the RenderMesh shared component (in the Hybrid.Rendering package) defines a set of fields whose values can be shared by many 3D objects. Since all the entities with the same values for the RenderMesh fields are stored in the same chunks, the renderer can efficiently batch the draw calls for those entities based on the shared values.

You must set the value of a shared component on the main thread using either the EntityManager or an EntityCommandBuffer. When you change a shared component value, the affected entity is moved to a different chunk. If a chunk already exists with the same values, and has enough room, the entity is moved to that chunk. Otherwise, a new chunk is allocated. Changing a shared component value is a structural change that potentially creates a sync-point in your application.

You can find entities with a particular type of shared component using either EntityQuery or EntityQueryBuilder in the same way you select entities with specific types of IComponentData. You can also filter an entity query to select only entities with a specific shared component value using SetSharedComponentFilter<SharedComponent1>(SharedComponent1). You can filter based on two different shared components. (EntityQueryBuilder does not support filtering queries by shared component value.)

Avoid too many shared components and values on the same archetype. Since each combination of values, whether in the same component type or in different shared components, is stored in different chunks, too many combinations can lead to poor chunk utilization. Use the Entity Debugger window in the Unity Editor (menu: Window > Analysis > Entity Debugger) to monitor chunk utilization.

See Shared Component Data for additional information.