Struct EntityQueryBuilder

Describes a query to find archetypes in terms of required, optional, and excluded components.

Namespace: Unity.Entities
Assembly: Unity.Entities.dll
Syntax
[GenerateTestsForBurstCompatibility]
public ref struct EntityQueryBuilder
Remarks

EntityQueryBuilder is unmanaged and compatible with the Burst compiler. It is the recommended way to create an EntityQuery, and can be used for both SystemBase and ISystem.

Use an EntityQueryBuilder object to describe complex queries.

A query description combines the component types you specify (using methods like WithAll, WithAny, and WithNone) sets according to the following rules:

  • All - Includes archetypes that have every component in this set, but only includes entities where the component is enabled.
  • Any - Includes archetypes that have at least one component in this set
  • None - Excludes archetypes that have any component in this set, but includes entities which have the component disabled.
  • Disabled - Includes archetypes that have every component in this set, but only matches entities where the component is disabled.
  • Absent - Excludes archetypes that have any component in this set.
  • Present - Includes archetypes that have every component in this set, whether or not the components are enabled.

For example, given entities with the following components:

  • Player has components: ObjectPosition, ObjectRotation, Player
  • Enemy1 has components: ObjectPosition, ObjectRotation, Melee
  • Enemy2 has components: ObjectPosition, ObjectRotation, Ranger

The query description below matches all of the archetypes that: have any of [Melee or Ranger], AND have none of [Player], AND have all of [ObjectPosition and ObjectRotation]

var query = new EntityQueryBuilder(Allocator.Temp)
    .WithAll<ObjectPosition, ObjectRotation>()
    .WithAny<Melee, Ranger>()
    .WithNone<Player>()
    .Build(this);

In other words, the query created from this description selects the Enemy1 and Enemy2 entities, but not the Player entity.

Constructors

Name Description
EntityQueryBuilder(AllocatorHandle)

Create an entity query description builder.

Methods

Name Description
AddAdditionalQuery()

Add an additional query description to a single EntityQuery.
AddAll(ComponentType)

Obsolete. Use WithAll(ComponentType*, int) instead.
AddAny(ComponentType)

Obsolete. Use WithAny(ComponentType*, int) instead.
AddNone(ComponentType)

Obsolete. Use WithNone(ComponentType*, int) instead.
Build(EntityManager)

Create an EntityQuery owned by an EntityManager.
Build(SystemBase)

Create an EntityQuery owned by an SystemBase.
Build(ref SystemState)

Create an EntityQuery owned by an ISystem's SystemState.
Dispose()

Dispose the builder and release the memory.
FinalizeQuery()

Obsolete. Calling this method has no effect; it is temporarily provided for backwards compatibility.
Reset()

Reset the builder for reuse.
WithAbsentChunkComponent<T>()

Add an absent Chunk Component type to the query.
WithAbsent<T1>()

Add absent component types to the query.
WithAbsent<T>(ref T)

Add absent component types to the query.
WithAbsent<T1, T2>()

Add absent component types to the query.
WithAbsent<T1, T2, T3>()

Add absent component types to the query.
WithAbsent<T1, T2, T3, T4>()

Add absent component types to the query.
WithAbsent<T1, T2, T3, T4, T5>()

Add absent component types to the query.
WithAbsent<T1, T2, T3, T4, T5, T6>()

Add absent component types to the query.
WithAbsent<T1, T2, T3, T4, T5, T6, T7>()

Add absent component types to the query.
WithAllChunkComponentRW<T>()

Add a required chunk component type to the query.
WithAllChunkComponent<T>()

Add a read-only required chunk component type to the query.
WithAllRW<T1>()

Add required component types to the query with ReadWrite mode.
WithAllRW<T1, T2>()

Add required component types to the query with ReadWrite mode.
WithAll<T1>()

Add required component types to the query.
WithAll<T>(ref T)

Add a list of required component types to the query.
WithAll<T1, T2>()

Add required component types to the query.
WithAll<T1, T2, T3>()

Add required component types to the query.
WithAll<T1, T2, T3, T4>()

Add required component types to the query.
WithAll<T1, T2, T3, T4, T5>()

Add required component types to the query.
WithAll<T1, T2, T3, T4, T5, T6>()

Add required component types to the query.
WithAll<T1, T2, T3, T4, T5, T6, T7>()

Add required component types to the query.
WithAnyChunkComponentRW<T>()

Add an optional chunk component type to the query.
WithAnyChunkComponent<T>()

Add an optional read-only chunk component type to the query.
WithAnyRW<T1>()

Add optional component types to the query with ReadWrite mode.
WithAnyRW<T1, T2>()

Add optional component types to the query with ReadWrite mode.
WithAny<T1>()

Add optional component types to the query.
WithAny<T>(ref T)

Add optional component types to the query.
WithAny<T1, T2>()

Add optional component types to the query.
WithAny<T1, T2, T3>()

Add optional component types to the query.
WithAny<T1, T2, T3, T4>()

Add optional component types to the query.
WithAny<T1, T2, T3, T4, T5>()

Add optional component types to the query.
WithAny<T1, T2, T3, T4, T5, T6>()

Add optional component types to the query.
WithAny<T1, T2, T3, T4, T5, T6, T7>()

Add optional component types to the query.
WithAspect<TAspect>()

Add component type requirement for a given aspect.
WithDisabledRW<T1>()

Add required disabled component types to the query with ReadWrite mode.
WithDisabledRW<T1, T2>()

Add required disabled component types to the query with ReadWrite mode.
WithDisabled<T1>()

Add required disabled component types to the query.
WithDisabled<T>(ref T)

Add a list of required disabled component types to the query.
WithDisabled<T1, T2>()

Add required disabled component types to the query.
WithDisabled<T1, T2, T3>()

Add required disabled component types to the query.
WithDisabled<T1, T2, T3, T4>()

Add required disabled component types to the query.
WithDisabled<T1, T2, T3, T4, T5>()

Add required disabled component types to the query.
WithDisabled<T1, T2, T3, T4, T5, T6>()

Add required component types to the query.
WithDisabled<T1, T2, T3, T4, T5, T6, T7>()

Add required component types to the query.
WithNoneChunkComponent<T>()

Add an excluded Chunk Component type to the query.
WithNone<T1>()

Add excluded component types to the query.
WithNone<T>(ref T)

Add excluded component types to the query.
WithNone<T1, T2>()

Add excluded component types to the query.
WithNone<T1, T2, T3>()

Add excluded component types to the query.
WithNone<T1, T2, T3, T4>()

Add excluded component types to the query.
WithNone<T1, T2, T3, T4, T5>()

Add excluded component types to the query.
WithNone<T1, T2, T3, T4, T5, T6>()

Add excluded component types to the query.
WithNone<T1, T2, T3, T4, T5, T6, T7>()

Add excluded component types to the query.
WithOptions(EntityQueryOptions)

Set options for the current query.
WithPresentChunkComponentRW<T>()

Add a required chunk component type to the query, whether it is enabled or disabled.
WithPresentChunkComponent<T>()

Add a required read-only chunk component type to the query, whether it is enabled or disabled.
WithPresentRW<T1>()

Add required component types to the query with ReadWrite mode, whether they are enabled or disabled.
WithPresentRW<T1, T2>()

Add required component types to the query with ReadWrite mode, whether they are enabled or disabled.
WithPresent<T1>()

Add required component types to the query, whether the type is enabled or not.
WithPresent<T>(ref T)

Add a list of required component types to the query, whether they are enabled or disabled.
WithPresent<T1, T2>()

Add required component types to the query, whether the type is enabled or not.
WithPresent<T1, T2, T3>()

Add required component types to the query, whether the type is enabled or not.
WithPresent<T1, T2, T3, T4>()

Add required component types to the query, whether the type is enabled or not.
WithPresent<T1, T2, T3, T4, T5>()

Add required component types to the query, whether the type is enabled or not.
WithPresent<T1, T2, T3, T4, T5, T6>()

Add required component types to the query, whether the type is enabled or not.
WithPresent<T1, T2, T3, T4, T5, T6, T7>()

Add required component types to the query, whether the type is enabled or not.

Did you find this page useful? Please give it a rating: