Class EntityQuery
A EntityQuery provides a queryDesc-based view of your component data.
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)
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 |
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.
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 |
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 |
Returns
Type | Description |
---|---|
NativeArray<Entity> | An array containing all the entities selected by the EntityQuery. |