Struct EntityQuery
Use an EntityQuery object to select entities with components that meet specific requirements.
Namespace: Unity.Entities
Syntax
[BurstCompatible]
public struct EntityQuery : IDisposableRemarks
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 archetypeAny= At least one of the component types in this array must exist in the archetypeNone= 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 Static component:
EntityQueryDesc description = new EntityQueryDesc
{
None = new ComponentType[]
{
typeof(Static)
},
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.
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
| Name | Description |
|---|---|
| IsEmpty | Reports whether this query would currently select zero entities. |
| IsEmptyIgnoreFilter | Reports whether this query would currently select zero entities. This will ignore any filters set on the EntityQuery. |
Methods
| Name | Description |
|---|---|
| AddChangedVersionFilter(ComponentType) | Filters out entities in chunks for which the specified component has not changed. Additive with other filter functions. |
| AddDependency(JobHandle) | Adds another job handle to this EntityQuery's dependencies. |
| AddOrderVersionFilter() | Filters out entities in chunks for which no structural changes have occurred. Additive with other filter functions. |
| AddSharedComponentFilter<SharedComponent>(SharedComponent) | Filters this EntityQuery so that it only selects entities with shared component values
matching the values specified by the |
| CalculateChunkCount() | Calculates the number of chunks that match this EntityQuery. |
| CalculateChunkCountWithoutFiltering() | Calculates the number of chunks that match this EntityQuery, ignoring any set filters. |
| CalculateEntityCount() | Calculates the number of entities selected by this EntityQuery. |
| CalculateEntityCount(NativeArray<Entity>) | Calculates the number of entities in the input entity list which match this EntityQuery. |
| CalculateEntityCountWithoutFiltering() | Calculates the number of entities selected by this EntityQuery, ignoring any set filters. |
| CalculateEntityCountWithoutFiltering(NativeArray<Entity>) | Calculates the number of entities in the input entity list which match this EntityQuery, ignoring any filters. |
| CompareComponents(NativeArray<ComponentType>) | Compares a list of component types to the types defining this EntityQuery. |
| CompareComponents(ComponentType[]) | Compares a list of component types to the types defining this EntityQuery. |
| CompareQuery(in EntityQueryDescBuilder) | Compares a query description to the description defining this EntityQuery. |
| CompleteDependency() | Ensures all jobs running on this EntityQuery complete. |
| CopyFromComponentDataArray<T>(NativeArray<T>) | Copies the component values in the provided NativeArray to the entities matching this query. |
| CopyFromComponentDataArrayAsync<T>(NativeArray<T>, out JobHandle) | Asynchronously copies the component values in the provided NativeArray to the entities matching this query. |
| CreateArchetypeChunkArray(Allocator) | Synchronously creates an array of the chunks containing entities matching this EntityQuery. |
| CreateArchetypeChunkArrayAsync(Allocator, out JobHandle) | Asynchronously creates an array of the chunks containing entities matching this EntityQuery. |
| Dispose() | Disposes this EntityQuery instance. |
| Equals(Object) | |
| Equals(EntityQuery) | |
| GetArchetypeChunkIterator() | Gets an ArchetypeChunkIterator which can be used to iterate over every chunk returned by this EntityQuery. |
| GetCombinedComponentOrderVersion() | |
| GetDependency() | Combines all dependencies in this EntityQuery into a single JobHandle. |
| GetEntityQueryDesc() | Returns an EntityQueryDesc, which can be used to re-create the EntityQuery. |
| GetEntityQueryMask() | Returns an EntityQueryMask, which can be used to quickly determine if an entity matches the query. |
| GetHashCode() | |
| GetSingleton<T>() | Gets the value of a singleton component. |
| GetSingletonEntity() | |
| HasFilter() | Reports whether this entity query has a filter applied to it. |
| Matches(Entity) | Returns true if the entity matches the query, false if it does not. Applies any filters |
| MatchesAny(NativeArray<Entity>) | Fast path to determine if any entities in the input entity list match this EntityQuery. |
| MatchesAnyIgnoreFilter(NativeArray<Entity>) | Fast path to determine if any entities in the input entity list match this EntityQuery, ignoring any filters. |
| MatchesNoFilter(Entity) | Returns true if the entity matches the query, false if it does not. Applies any filters |
| ResetFilter() | Resets this EntityQuery's filter. |
| SetChangedVersionFilter(ComponentType) | Filters out entities in chunks for which the specified component has not changed. |
| SetChangedVersionFilter(ComponentType[]) | Filters out entities in chunks for which the specified component has not changed. |
| SetOrderVersionFilter() | Filters out entities in chunks for which no structural changes have occurred. |
| SetSharedComponentFilter<SharedComponent1>(SharedComponent1) | Filters this EntityQuery so that it only selects entities with shared component values
matching the values specified by the |
| SetSharedComponentFilter<SharedComponent1, SharedComponent2>(SharedComponent1, SharedComponent2) | Filters this EntityQuery based on the values of two separate shared components. |
| SetSingleton<T>(T) | Sets the value of a singleton component. |
| ToComponentDataArray<T>() | |
| ToComponentDataArray<T>(Allocator) | Creates a NativeArray containing the components of type T for the selected entities. |
| ToComponentDataArray<T>(NativeArray<Entity>, Allocator) | Creates a NativeArray containing the components of type T for the selected entities, given an input entity list to limit the search. |
| ToComponentDataArrayAsync<T>(Allocator, out JobHandle) | Creates a NativeArray containing the components of type T for the selected entities. |
| ToEntityArray(Allocator) | Creates a NativeArray containing the selected entities. |
| ToEntityArray(NativeArray<Entity>, Allocator) | Creates a NativeArray containing the selected entities, given an input entity list to limit the search. |
| ToEntityArrayAsync(Allocator, out JobHandle) | Creates a NativeArray containing the selected entities. |
Operators
| Name | Description |
|---|---|
| Equality(EntityQuery, EntityQuery) | |
| Inequality(EntityQuery, EntityQuery) |