Struct EntityQuery

Use an EntityQuery object to select entities with components that meet specific requirements.

Namespace: Unity.Entities

Syntax

public struct EntityQuery : IDisposable

Remarks

An entity query defines the set of component types that an archetype must contain in order for its chunks and entities to be selected and specifies whether the components accessed through the query are read-only or read-write.

For simple queries, you can create an EntityQuery based on an array of component types. The following example defines a EntityQuery that finds all entities with both Rotation and RotationSpeed components.

            EntityQuery query = GetEntityQuery(typeof(Rotation),
           ComponentType.ReadOnly<RotationSpeed>());

The query 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-only access to data, which can help the Job scheduler execute your Jobs more efficiently.

For more complex queries, you can use an EntityQueryDesc object to create the entity query. A query description provides a flexible query mechanism to specify which archetypes to select based on the following sets of components:

All = All component types in this array must exist in the archetype
Any = At least one of the component types in this array must exist in the archetype
None = None of the component types in this array can exist in the archetype

For example, the following query includes archetypes containing Rotation and RotationSpeed components, but excludes any archetypes containing a Frozen component:

            EntityQueryDesc description = new EntityQueryDesc
       {
           None = new ComponentType[]
           {
               typeof(Frozen)
           },
           All = new ComponentType[]
           {
               typeof(Rotation),
               ComponentType.ReadOnly<RotationSpeed>()
           }
       };
       EntityQuery query = GetEntityQuery(description);

Note: Do not include completely optional components in the query description. To handle optional components, use IJobChunk and the ArchetypeChunk.Has() method to determine whether a chunk contains the optional component or not. Since all entities within the same chunk have the same components, you only need to check whether an optional component exists once per chunk -- not once per entity.

Within a system class, use the ComponentSystemBase.GetEntityQuery() function to get a EntityQuery instance. Outside a system, use the EntityManager.CreateEntityQuery() function.

You can filter entities based on whether they have changed or whether they have a specific value for a shared component. Once you have created an EntityQuery object, you can reset and change the filter settings, but you cannot modify the base query.

Use an EntityQuery for the following purposes:

To get a native array of a the values for a specific IComponentData type for all entities matching the query
To get an native array of the ArchetypeChunk objects matching the query
To schedule an IJobChunk job
To control whether a system updates using [ComponentSystemBase.RequireForUpdate(query)]

Note that Entities.ForEach defines an entity query implicitly based on the methods you call. You can access this implicit EntityQuery object using Entities.WithStoreEntityQueryInField. However, you cannot create an Entities.ForEach construction based on an existing EntityQuery object.

Properties

IsEmpty

Reports whether this query would currently select zero entities.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
Boolean	True, if this EntityQuery matches zero existing entities. False, if it matches one or more entities.

IsEmptyIgnoreFilter

Reports whether this query would currently select zero entities. This will ignore any filters set on the EntityQuery.

Declaration

public bool IsEmptyIgnoreFilter { get; }

Property Value

Type	Description
Boolean	True, if this EntityQuery matches zero existing entities. False, if it matches one or more entities.

Methods

AddChangedVersionFilter(ComponentType)

Filters out entities in chunks for which the specified component has not changed. Additive with other filter functions.

Declaration

public void AddChangedVersionFilter(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.

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.

AddOrderVersionFilter()

Filters out entities in chunks for which no structural changes have occurred. Additive with other filter functions.

Declaration

public void AddOrderVersionFilter()

AddSharedComponentFilter<SharedComponent>(SharedComponent)

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

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 execute 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 execute 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 execute and apply any filters to calculate the entity count. If you are checking for whether the entity count equals zero, consider the more efficient IsEmpty property.

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 execute to calculate the entity count. If you are checking for whether the entity count equals zero, consider the more efficient IsEmptyIgnoreFilter property.

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

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

Declaration

public void CopyFromComponentDataArrayAsync<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. CreateArchetypeChunkArrayAsync(Allocator, out JobHandle)

CreateArchetypeChunkArrayAsync(Allocator, out JobHandle)

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

Declaration

public NativeArray<ArchetypeChunk> CreateArchetypeChunkArrayAsync(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 instances accessed using GetEntityQuery(ComponentType[]). Systems automatically dispose of their own entity queries.

Exceptions

Type	Condition
InvalidOperationException	Thrown if you attempt to dispose an EntityQuery belonging to a system.

Equals(Object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj

Returns

Type	Description
Boolean

Overrides

ValueType.Equals(Object)

Equals(EntityQuery)

Declaration

public bool Equals(EntityQuery other)

Parameters

Type	Name	Description
EntityQuery	other

Returns

Type	Description
Boolean

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.

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32

Overrides

ValueType.GetHashCode()

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 that satisfies this query.

Exceptions

Type	Condition
InvalidOperationException

GetSingletonEntity()

Declaration

public Entity GetSingletonEntity()

Returns

Type	Description
Entity

HasFilter()

Reports whether this 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[])

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	ComponentTypes to mark as changed on this EntityQuery's filter.

Remarks

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

SetOrderVersionFilter()

Filters out entities in chunks for which no structural changes have occurred.

Declaration

public void SetOrderVersionFilter()

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 that satisfies this query.

Note: singletons are otherwise normal entities. The EntityQuery and ComponentSystemBase singleton functions add checks that you have not created two instances of a type that can be accessed by this singleton query, but other APIs do not prevent such accidental creation.

To create a singleton, create an entity with the singleton component.

For example, if you had a component defined as:

    public struct Singlet : IComponentData
{
   public int Value;
}

You could create a singleton as follows:

       Entity singletonEntity = entityManager.CreateEntity(typeof(Singlet));
       entityManager.SetComponentData(singletonEntity, new Singlet { Value = 1 });

To update the singleton component after creation, you can use an EntityQuery object that selects the singleton entity and call this SetSingleton() function:

            queryForSingleton.SetSingleton<Singlet>(new Singlet {Value = 1});

You can set and get the singleton value from a system: see SetSingleton<T>(T) and GetSingleton<T>().

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.

ToComponentDataArrayAsync<T>(Allocator, out JobHandle)

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

Declaration

public NativeArray<T> ToComponentDataArrayAsync<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.

ToEntityArrayAsync(Allocator, out JobHandle)

Creates a NativeArray containing the selected entities.

Declaration

public NativeArray<Entity> ToEntityArrayAsync(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.

Operators

Equality(EntityQuery, EntityQuery)

Declaration

public static bool operator ==(EntityQuery lhs, EntityQuery rhs)

Parameters

Type	Name	Description
EntityQuery	lhs
EntityQuery	rhs

Returns

Type	Description
Boolean

Inequality(EntityQuery, EntityQuery)

Declaration

public static bool operator !=(EntityQuery lhs, EntityQuery rhs)

Parameters

Type	Name	Description
EntityQuery	lhs
EntityQuery	rhs

Returns

Type	Description
Boolean

Extension Methods

EntityQueryManagedComponentExtensions.GetSingleton<T>(EntityQuery)

EntityQueryManagedComponentExtensions.SetSingleton<T>(EntityQuery, T)

EntityQueryExtensionsForComponentArray.ToComponentArray<T>(EntityQuery)

EntityQueryExtensionsForTransformAccessArray.GetTransformAccessArray(EntityQuery)