EntityQuery

struct in Unity.Entities

Leave feedback

Suggest a change

Description

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

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.

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, and must be enabled on matching entities. " Any = At least one of the component types in this array must exist in the archetype, and must be enabled on matching entities. " None = None of the component types in this array can exist in the archetype, or they must be present and disabled on matching entities. " Disabled = All component types in this array must exist in the archetype, and must be disabled on matching entities. " Absent = None of the component types in this array can exist in the archetype " Present = All of the component types in this array must exist in the archetype, whether or not they are enabled.

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

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 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)]

[Entities.ForEach]: xref:Unity.Entities.SystemBase.Entities [Entities.WithStoreEntityQueryInField]: xref:Unity.Entities.SystemBase.Entities [ComponentSystemBase.GetEntityQuery()]: xref:Unity.Entities.ComponentSystemBase.GetEntityQuery" [ComponentType.ReadOnly]: xref:Unity.Entities.ComponentType.ReadOnly@@1 [ComponentSystemBase.RequireForUpdate()]: xref:Unity.Entities.ComponentSystemBase.RequireForUpdate(Unity.Entities.EntityQuery) [ArchetypeChunk.Has()]: xref:Unity.Entities.ArchetypeChunk.Has1(Unity.Entities.ComponentTypeHandle{@@0}) [archetype]: xref:Unity.Entities.EntityArchetype [changed]: xref:Unity.Entities.EntityQuery.SetChangedVersionFilter" [shared component]: xref:Unity.Entities.EntityQuery.SetSharedComponentFilter" [reset]: xref:Unity.Entities.EntityQuery.ResetFilter" [native array]: https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeArray_1.html

Properties

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

Public Methods

Method	Description
AddChangedVersionFilter	Filters out entities in chunks for which the specified component has not changed. Additive with other filter functions.
AddDependency	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	Filters this EntityQuery so that it only selects entities with an unmanaged shared component of type SharedComponent equal to sharedComponent. Additive with other filter functions.
CalculateBaseEntityIndexArray	Generates an array containing the index of the first entity within each chunk, relative to the list of entities that match this query.
CalculateBaseEntityIndexArrayAsync	Asynchronously generates an array containing the index of the first entity within each chunk, relative to the list of entities that match this query.
CalculateChunkCount	Calculates the number of chunks that match this EntityQuery, taking into account all active query filters and enabled components.
CalculateChunkCountWithoutFiltering	Calculates the number of chunks that match this EntityQuery, ignoring any set filters.
CalculateEntityCount	Calculates the number of entities selected by this EntityQuery.
CalculateEntityCountWithoutFiltering	Calculates the number of entities selected by this EntityQuery, ignoring any set filters.
CalculateFilteredChunkIndexArray	Generates an array which gives the index of each chunk relative to the set of chunks that currently match the query, after taking all active filtering into account.
CalculateFilteredChunkIndexArrayAsync	Asynchronously generates an array which gives the index of each chunk relative to the set of chunks that currently match the query, after taking all active filtering into account.
CompareQuery	Compares a query description to the description defining this EntityQuery.
CompleteDependency	Ensures all jobs running on this EntityQuery complete.
CopyFromComponentDataArray	Copies the values of component type T in a NativeArray into the entities matched by this query.
CopyFromComponentDataListAsync	Asynchronously copies the values of component type T in a NativeList into the entities matched by this query.
Dispose	Disposes this EntityQuery instance.
Equals	Compare two queries for equality.
GetCombinedComponentOrderVersion	This method is obsolete. Use EntityManager.GetComponentOrderVersion instead.
GetDependency	Combines all dependencies in this EntityQuery into a single JobHandle.
GetEntityQueryDescs	Reconstructs the query descriptions used to create this EntityQuery. The query matches an archetype if it meets the criteria of at least one of these query descriptions. This method is mainly intended for reflection.
GetEntityQueryMask	Returns an EntityQueryMask, which can be used to quickly determine if an entity matches the query.
GetHashCode	Compute the hash code for this query
GetSingleton	Gets the value of a singleton component. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.
GetSingletonBuffer	Gets the value of a singleton buffer component. Note that if querying a singleton buffer component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.
GetSingletonEntity	Attempts to retrieve the single entity that this query matches.
GetSingletonRW	Gets a reference to a singleton component, for read/write access. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.
HasFilter	Reports whether this entity query has a filter applied to it.
HasSingleton	Checks whether a singleton component of the specified type exists. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.
Matches	Returns true if the entity matches the query, false if it does not.
MatchesIgnoreFilter	Returns true if the entity's archetype is matched by this query, ignoring all query filtering (including chunk filters and enableable components).
ResetFilter	Resets this EntityQuery's chunk filter settings to the default (all filtering disabled).
SetChangedVersionFilter	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	Filters this EntityQuery so that it only selects entities with shared component of type SharedComponent equal to sharedComponent.
SetSingleton	Sets the value of a singleton component. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.
ToArchetypeChunkArray	Synchronously creates an array of the chunks containing entities matching this EntityQuery.
ToArchetypeChunkList	Synchronously fills a list with the chunks containing entities matching this EntityQuery.
ToArchetypeChunkListAsync	Asynchronously creates a list of the chunks containing entities matching this EntityQuery.
ToComponentDataArray	Creates a NativeArray containing the components of type T for the selected entities.
ToComponentDataListAsync	Creates (and asynchronously populates) a NativeList containing the value of component T for the selected entities. Since the exact number of entities matching the query won't be known until the job runs, this method returns a NativeList<T0>.
ToEntityArray	Creates a NativeArray containing the selected entities.
ToEntityListAsync	Creates (and asynchronously populates) a NativeList containing the selected entities. Since the exact number of entities matching the query won't be known until the job runs, this method returns a NativeList<T0>.
TryGetSingleton	Gets the value of a singleton component, and returns whether or not a singleton component of the specified type matches inside the EntityQuery. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.
TryGetSingletonBuffer	Gets the value of a singleton buffer component, and returns whether or not a singleton buffer component of the specified type exists in the World. Note that if querying a singleton buffer component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.
TryGetSingletonEntity	Gets the singleton Entity, and returns whether or not a singleton Entity of the specified type exists in the World.
TryGetSingletonRW	Gets a reference to the value of a singleton component, and returns whether or not a singleton component of the specified type matches inside the EntityQuery. Note that if querying a singleton component from a system-associated entity, the query must include either EntityQueryOptions.IncludeSystems or the SystemInstance component.

Operators

Operator	Description
operator !=	Test two queries for inequality
operator ==	Test two queries for equality

Is something described here not working as you expect it to? It might be a Known Issue. Please check with the Issue Tracker at issuetracker.unity3d.com.

Scripting API

EntityQuery

Success!

Submission failed

Description

Properties

Public Methods

Operators