Class EntityQuery

A EntityQuery provides a queryDesc-based view of your component data.

Inheritance

EntityQuery

Namespace: Unity.Entities

Syntax

public class EntityQuery : IDisposable

Remarks

A EntityQuery defines a view of your data based on a queryDesc for the set of component types that an archetype must contain in order for its chunks and entities to be included in the view. You can also exclude archetypes that contain specific types of components. For simple queriesDesc, you can create a EntityQuery based on an array of component types. The following example defines a EntityQuery that finds all entities with both RotationQuaternion and RotationSpeed components.

//In a JobComponentSystem or ComponentSystem
EntityQuery m_Query = GetEntityQuery(typeof(RotationQuaternion),
                                           ComponentType.ReadOnly{RotationSpeed}());

The queryDesc uses ComponentType.ReadOnly instead of the simpler typeof expression to designate that the system does not write to RotationSpeed. Always specify read only when possible, since there are fewer constraints on read access to data, which can help the Job scheduler execute your Jobs more efficiently.

For more complex queriesDesc, you can use an EntityQueryDesc instead of a simple list of component types.

Use the EntityManager CreateEntityQuery(ComponentType[]) or the ComponentSystemBase GetEntityQuery(ComponentType[]) functions to get a EntityQuery instance.

Properties

IsEmptyIgnoreFilter

Ignore this EntityQuery if it has no entities in any of its archetypes.

Declaration

public bool IsEmptyIgnoreFilter { get; }

Property Value

Type	Description
Boolean	True if this EntityQuery has no entities. False if it has 1 or more entities.

Methods

AddChangedVersionFilter(ComponentType)

Declaration

public void AddChangedVersionFilter(ComponentType componentType)

Parameters

Type	Name	Description
ComponentType	componentType

AddDependency(JobHandle)

Adds another job handle to this EntityQuery's dependencies.

Declaration

public JobHandle AddDependency(JobHandle job)

Parameters

Type	Name	Description
JobHandle	job

Returns

Type	Description
JobHandle

Remarks

An entity query uses jobs internally when required to create arrays of entities and chunks. This junction adds an external job as a dependency for those internal jobs.

AddSharedComponentFilter<SharedComponent>(SharedComponent)

Declaration

public void AddSharedComponentFilter<SharedComponent>(SharedComponent sharedComponent)
    where SharedComponent : struct, ISharedComponentData

Parameters

Type	Name	Description
SharedComponent	sharedComponent

Type Parameters

Name	Description
SharedComponent

CalculateChunkCount()

Calculates the number of chunks that match this EntityQuery.

Declaration

public int CalculateChunkCount()

Returns

Type	Description
Int32	The number of chunks based on the current EntityQuery properties.

Remarks

The EntityQuery must run the queryDesc and apply any filters to calculate the chunk count.

CalculateChunkCountWithoutFiltering()

Calculates the number of chunks that match this EntityQuery, ignoring any set filters.

Declaration

public int CalculateChunkCountWithoutFiltering()

Returns

Type	Description
Int32	The number of chunks based on the current EntityQuery properties.

Remarks

The EntityQuery must run the queryDesc to calculate the chunk count.

CalculateEntityCount()

Calculates the number of entities selected by this EntityQuery.

Declaration

public int CalculateEntityCount()

Returns

Type	Description
Int32	The number of entities based on the current EntityQuery properties.

Remarks

The EntityQuery must run the queryDesc and apply any filters to calculate the entity count.

CalculateEntityCountWithoutFiltering()

Calculates the number of entities selected by this EntityQuery, ignoring any set filters.

Declaration

public int CalculateEntityCountWithoutFiltering()

Returns

Type	Description
Int32	The number of entities based on the current EntityQuery properties.

Remarks

The EntityQuery must run the queryDesc to calculate the entity count.

CompareComponents(NativeArray<ComponentType>)

Compares a list of component types to the types defining this EntityQuery.

Declaration

public bool CompareComponents(NativeArray<ComponentType> componentTypes)

Parameters

Type	Name	Description
NativeArray<ComponentType>	componentTypes	An array of ComponentType objects.

Returns

Type	Description
Boolean	True, if the list of types, including any read/write access specifiers, matches the list of required component types of this EntityQuery.

Remarks

Only required types in the query are used as the basis for the comparison. If you include types that the query excludes or only includes as optional, the comparison returns false. Do not include the Entity type, which is included implicitly.

CompareComponents(ComponentType[])

Compares a list of component types to the types defining this EntityQuery.

Declaration

public bool CompareComponents(ComponentType[] componentTypes)

Parameters

Type	Name	Description
ComponentType[]	componentTypes	An array of ComponentType objects.

Returns

Type	Description
Boolean	True, if the list of types, including any read/write access specifiers, matches the list of required component types of this EntityQuery.

Remarks

Only required types in the query are used as the basis for the comparison. If you include types that the query excludes or only includes as optional, the comparison returns false.

CompareQuery(EntityQueryDesc[])

Compares a query description to the description defining this EntityQuery.

Declaration

public bool CompareQuery(EntityQueryDesc[] queryDesc)

Parameters

Type	Name	Description
EntityQueryDesc[]	queryDesc	The query description to compare.

Returns

Type	Description
Boolean	True, if the query description contains the same components with the same read/write access modifiers as this EntityQuery.

Remarks

The All, Any, and None components in the query description are compared to the corresponding list in this EntityQuery.

CompleteDependency()

Ensures all jobs running on this EntityQuery complete.

Declaration

public void CompleteDependency()

Remarks

An entity query uses jobs internally when required to create arrays of entities and chunks. This function completes those jobs and returns when they are finished.

CopyFromComponentDataArray<T>(NativeArray<T>)

Declaration

public void CopyFromComponentDataArray<T>(NativeArray<T> componentDataArray)
    where T : struct, IComponentData

Parameters

Type	Name	Description
NativeArray<T>	componentDataArray

Type Parameters

Name	Description
T

CopyFromComponentDataArray<T>(NativeArray<T>, out JobHandle)

Declaration

public void CopyFromComponentDataArray<T>(NativeArray<T> componentDataArray, out JobHandle jobhandle)
    where T : struct, IComponentData

Parameters

Type	Name	Description
NativeArray<T>	componentDataArray
JobHandle	jobhandle

Type Parameters

Name	Description
T

CreateArchetypeChunkArray(Allocator)

Synchronously creates an array of the chunks containing entities matching this EntityQuery.

Declaration

public NativeArray<ArchetypeChunk> CreateArchetypeChunkArray(Allocator allocator)

Parameters

Type	Name	Description
Allocator	allocator	Allocator to use for the array.

Returns

Type	Description
NativeArray<ArchetypeChunk>	NativeArray of all the chunks in this ComponentChunkIterator.

Remarks

This method blocks until the internal job that performs the query completes. CreateArchetypeChunkArray(Allocator, out JobHandle)

CreateArchetypeChunkArray(Allocator, out JobHandle)

Asynchronously creates an array of the chunks containing entities matching this EntityQuery.

Declaration

public NativeArray<ArchetypeChunk> CreateArchetypeChunkArray(Allocator allocator, out JobHandle jobhandle)

Parameters

Type	Name	Description
Allocator	allocator	Allocator to use for the array.
JobHandle	jobhandle	An `out` parameter assigned the handle to the internal job that gathers the chunks matching this EntityQuery.

Returns

Type	Description
NativeArray<ArchetypeChunk>	NativeArray of all the chunks containing entities matching this query.

Remarks

Use jobhandle as a dependency for jobs that use the returned chunk array. CreateArchetypeChunkArray(Allocator).

Dispose()

Disposes this EntityQuery instance.

Declaration

public void Dispose()

Remarks

Do not dispose EntityQuery instance created by a ComponentSystem or JobComponentSystem. The system automatically disposes of its own entity queries.

Exceptions

Type	Condition
InvalidOperationException	Thrown if you attempt to dispose an EntityQuery belonging to a ComponentSystem or JobComponentSystem.

GetArchetypeChunkIterator()

Gets an ArchetypeChunkIterator which can be used to iterate over every chunk returned by this EntityQuery.

Declaration

public ArchetypeChunkIterator GetArchetypeChunkIterator()

Returns

Type	Description
ArchetypeChunkIterator	ArchetypeChunkIterator for this EntityQuery

GetCombinedComponentOrderVersion()

Declaration

public int GetCombinedComponentOrderVersion()

Returns

Type	Description
Int32

GetDependency()

Combines all dependencies in this EntityQuery into a single JobHandle.

Declaration

public JobHandle GetDependency()

Returns

Type	Description
JobHandle	JobHandle that represents the combined dependencies of this EntityQuery

Remarks

An entity query uses jobs internally when required to create arrays of entities and chunks.

GetSingleton<T>()

Gets the value of a singleton component.

Declaration

public T GetSingleton<T>()
    where T : struct, IComponentData

Returns

Type	Description
T	A copy of the singleton component.

Type Parameters

Name	Description
T	The component type.

Remarks

A singleton component is a component of which only one instance exists in the world and which has been set with SetSingleton<T>(T).

Exceptions

Type	Condition
InvalidOperationException

GetSingletonEntity()

Declaration

public Entity GetSingletonEntity()

Returns

Type	Description
Entity

HasFilter()

Returns if the entity query has a filter applied to it.

Declaration

public bool HasFilter()

Returns

Type	Description
Boolean	Returns true if the query has a filter, returns false if the query does not have a filter.

ResetFilter()

Resets this EntityQuery's filter.

Declaration

public void ResetFilter()

Remarks

Removes references to shared component data, if applicable, then resets the filter type to None.

SetChangedVersionFilter(ComponentType)

Filters out entities in chunks for which the specified component has not changed.

Declaration

public void SetChangedVersionFilter(ComponentType componentType)

Parameters

Type	Name	Description
ComponentType	componentType	ComponentType to mark as changed on this EntityQuery's filter.

Remarks

Saves a given ComponentType's index in RequiredComponents in this group's Changed filter.

SetChangedVersionFilter(ComponentType[])

Declaration

public void SetChangedVersionFilter(ComponentType[] componentType)

Parameters

Type	Name	Description
ComponentType[]	componentType

SetSharedComponentFilter<SharedComponent1>(SharedComponent1)

Filters this EntityQuery so that it only selects entities with shared component values matching the values specified by the sharedComponent1 parameter.

Declaration

public void SetSharedComponentFilter<SharedComponent1>(SharedComponent1 sharedComponent1)
    where SharedComponent1 : struct, ISharedComponentData

Parameters

Type	Name	Description
SharedComponent1	sharedComponent1	The shared component values on which to filter.

Type Parameters

Name	Description
SharedComponent1	The type of shared component. (The type must also be one of the types used to create the EntityQuery.

SetSharedComponentFilter<SharedComponent1, SharedComponent2>(SharedComponent1, SharedComponent2)

Filters this EntityQuery based on the values of two separate shared components.

Declaration

public void SetSharedComponentFilter<SharedComponent1, SharedComponent2>(SharedComponent1 sharedComponent1, SharedComponent2 sharedComponent2)
    where SharedComponent1 : struct, ISharedComponentData where SharedComponent2 : struct, ISharedComponentData

Parameters

Type	Name	Description
SharedComponent1	sharedComponent1	Shared component values on which to filter.
SharedComponent2	sharedComponent2	Shared component values on which to filter.

Type Parameters

Name	Description
SharedComponent1	The type of shared component. (The type must also be one of the types used to create the EntityQuery.
SharedComponent2	The type of shared component. (The type must also be one of the types used to create the EntityQuery.

Remarks

The filter only selects entities for which both shared component values specified by the sharedComponent1 and sharedComponent2 parameters match.

SetSingleton<T>(T)

Sets the value of a singleton component.

Declaration

public void SetSingleton<T>(T value)
    where T : struct, IComponentData

Parameters

Type	Name	Description
T	value	An instance of type T containing the values to set.

Type Parameters

Name	Description
T	The component type.

Remarks

For a component to be a singleton, there can be only one instance of that component in a World. The component must be the only component in its archetype and you cannot use the same type of component as a normal component.

To create a singleton, create an entity with the singleton component as its only component, and then use SetSingleton() to assign a value.

For example, if you had a component defined as:

public struct Singlet: IComponentData{ public int Value; }

You could create a singleton as follows:

var singletonEntity = entityManager.CreateEntity(typeof(Singlet));
var singletonGroup = entityManager.CreateEntityQuery(typeof(Singlet));
singletonGroup.SetSingleton<Singlet>(new Singlet {Value = 1});

You can set and get the singleton value from a EntityQuery or a ComponentSystem.

Exceptions

Type	Condition
InvalidOperationException	Thrown if more than one instance of this component type exists in the world or the component type appears in more than one archetype.

ToComponentDataArray<T>()

Declaration

public T[] ToComponentDataArray<T>()
    where T : class, IComponentData

Returns

Type	Description
T[]

Type Parameters

Name	Description
T

ToComponentDataArray<T>(Allocator)

Creates a NativeArray containing the components of type T for the selected entities.

Declaration

public NativeArray<T> ToComponentDataArray<T>(Allocator allocator)
    where T : struct, IComponentData

Parameters

Type	Name	Description
Allocator	allocator	The type of memory to allocate.

Returns

Type	Description
NativeArray<T>	An array containing the specified component for all the entities selected by the EntityQuery.

Type Parameters

Name	Description
T	The component type.

Exceptions

Type	Condition
InvalidOperationException	Thrown if you ask for a component that is not part of the group.

ToComponentDataArray<T>(Allocator, out JobHandle)

Creates a NativeArray containing the components of type T for the selected entities.

Declaration

public NativeArray<T> ToComponentDataArray<T>(Allocator allocator, out JobHandle jobhandle)
    where T : struct, IComponentData

Parameters

Type	Name	Description
Allocator	allocator	The type of memory to allocate.
JobHandle	jobhandle	An `out` parameter assigned a handle that you can use as a dependency for a Job that uses the NativeArray.

Returns

Type	Description
NativeArray<T>	An array containing the specified component for all the entities selected by the EntityQuery.

Type Parameters

Name	Description
T	The component type.

ToEntityArray(Allocator)

Creates a NativeArray containing the selected entities.

Declaration

public NativeArray<Entity> ToEntityArray(Allocator allocator)

Parameters

Type	Name	Description
Allocator	allocator	The type of memory to allocate.

Returns

Type	Description
NativeArray<Entity>	An array containing all the entities selected by the EntityQuery.

Remarks

This version of the function blocks until the Job used to fill the array is complete.

ToEntityArray(Allocator, out JobHandle)

Creates a NativeArray containing the selected entities.

Declaration

public NativeArray<Entity> ToEntityArray(Allocator allocator, out JobHandle jobhandle)

Parameters

Type	Name	Description
Allocator	allocator	The type of memory to allocate.
JobHandle	jobhandle	An `out` parameter assigned a handle that you can use as a dependency for a Job that uses the NativeArray.

Returns

Type	Description
NativeArray<Entity>	An array containing all the entities selected by the EntityQuery.

Extension Methods

EntityQueryExtensionsForComponentArray.ToComponentArray<T>(EntityQuery)

EntityQueryExtensionsForTransformAccessArray.GetTransformAccessArray(EntityQuery)