Class EntityQuery

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

Inheritance
System.Object
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.

EntityQuery m_Group = 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 CreateEntityQuery(ComponentType[]) or 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
System.Boolean

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

Methods

AddDependency(JobHandle)

Adds another job handle to this EntityQuery's dependencies.

Declaration
public void AddDependency(JobHandle job)
Parameters
Type Name Description
JobHandle job

CalculateLength()

Calculates the number of entities selected by this EntityQuery.

Declaration
public int CalculateLength()
Returns
Type Description
System.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.

CompareComponents(NativeArray<ComponentType>)

Declaration
public bool CompareComponents(NativeArray<ComponentType> componentTypes)
Parameters
Type Name Description
NativeArray<ComponentType> componentTypes
Returns
Type Description
System.Boolean

CompareComponents(ComponentType[])

Declaration
public bool CompareComponents(ComponentType[] componentTypes)
Parameters
Type Name Description
ComponentType[] componentTypes
Returns
Type Description
System.Boolean

CompareQuery(EntityQueryDesc[])

Declaration
public bool CompareQuery(EntityQueryDesc[] queryDesc)
Parameters
Type Name Description
EntityQueryDesc[] queryDesc
Returns
Type Description
System.Boolean

CompleteDependency()

Ensures all jobs running on this EntityQuery complete.

Declaration
public void CompleteDependency()

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)

Creates an array with all the chunks in this EntityQuery. Waits for the GatherChunks job to complete here.

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.

CreateArchetypeChunkArray(Allocator, out JobHandle)

Creates an array with all the chunks in this EntityQuery. Gives the caller a job handle so it can wait for GatherChunks to finish.

Declaration
public NativeArray<ArchetypeChunk> CreateArchetypeChunkArray(Allocator allocator, out JobHandle jobhandle)
Parameters
Type Name Description
Allocator allocator

Allocator to use for the array.
JobHandle jobhandle

Handle to the GatherChunks job used to fill the output array.
Returns
Type Description
NativeArray<ArchetypeChunk>

NativeArray of all the chunks in this ComponentChunkIterator.

Dispose()

Declaration
public void Dispose()

GetCombinedComponentOrderVersion()

Declaration
public int GetCombinedComponentOrderVersion()
Returns
Type Description
System.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

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
System.InvalidOperationException

GetSingletonEntity()

Declaration
public Entity GetSingletonEntity()
Returns
Type Description
Entity

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.

SetFilter<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 SetFilter<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.

SetFilter<SharedComponent1, SharedComponent2>(SharedComponent1, SharedComponent2)

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

Declaration
public void SetFilter<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.

SetFilterChanged(ComponentType)

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

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

SetFilterChanged(ComponentType[])

Filters out entities in chunks for which the specified components have not changed.

Declaration
public void SetFilterChanged(ComponentType[] componentType)
Parameters
Type Name Description
ComponentType[] componentType

Array of up to two ComponentTypes to mark as changed on this EntityQuery's filter.
Remarks

Saves given ComponentTypes' indices in RequiredComponents in this group's Changed filter.

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 entityManager = World.Active.EntityManager;
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
System.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>(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
System.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

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

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