Interface IComponentData

An interface for implementing general-purpose components.

Namespace: Unity.Entities

Syntax

public interface IComponentData

Remarks

An IComponentData implementation must be a struct and can only contain unmanaged, blittable types, including:

• C#-defined blittable types
• bool
• char
• BlobAssetReference<T> (a reference to a Blob data structure)
• FixedString (a fixed-sized character buffer)
• Unity.Collections.FixedList
• fixed arrays (in an unsafe context)
• structs containing these unmanaged, blittable fields

Note that you can also use a separate, IBufferElementData component in a DynamicBuffer<T> as an array-like data structure.

A single IComponentData implementation should only contain fields for data that is always, or almost always, accessed at the same time. In general, using a greater number of smaller component types is more efficient than using fewer, larger component types.

Add, set, and remove the components of an entity using the EntityManager or an EntityCommandBuffer. (You can also update the fields of an IComponentData struct normally when you have a reference to it.)

IComponentData objects are stored in chunks (ArchetypeChunk), indexed by Entity. You can implement systems (ComponentSystemBase) to select and iterate over a set of entities having specific components. Use EntityQueryBuilder with ComponentSystem for non-Job based systems. Use EntityQuery with JobComponentSystem for Unity.Entities.IJobForEach`1 and IJobChunk based systems. All the components of an entity must fit into a single chunk and thus cannot exceed 16 KB. (Some components, such as DynamicBuffer<T> and BlobArray<T> can store data outside the chunk, so may not fully count against that limit.)

While, most of the components that you add to entities implement IComponentData, ECS also provides several, specialized component types. These specialized types include:

• IBufferElementData -- for use in a DynamicBuffer<T>
• ISharedComponentData -- a component whose value is shared by all entities in the same chunk
• ISystemStateComponentData -- a component for storing internal system state associated with an entity.
• ISystemStateSharedComponentData -- the system state version of the shared component interface.
• ISystemStateBufferElementData -- the system state version of the buffer element interface.

Note: Chunk components, which you can use to store data associated with a chunk (see AddChunkComponentData<T>(Entity)) and singleton components, which are components for which only one instance of a type is allowed (see SetSingleton<T>(T)), use the IComponentData interface.

See General-purpose components for additional information.