EntityQuery filters

To further sort entities, you can use a filter to exclude entities based on the following:

The filters you set remain in effect until you call ResetFilter on the query object.

To ignore the query's active chunk filters, use the EntityQuery methods that have names ending in IgnoreFilter. These methods are generally more efficient than the filtering equivalents. For example, see IsEmpty vs. IsEmptyIgnoreFilter.

Use a shared component filter

To use a shared component filter, include the shared component in the EntityQuery along with any other needed components and call the SetSharedComponentFilter method. Then pass in a struct of the same ISharedComponent type that contains the values to select. All values must match. You can add up to two different shared components to the filter.

You can change the filter at any time, but if you change the filter, it doesn't change any existing arrays of entities or components that you received from the group ToComponentDataArray<T> or ToEntityArray methods. You must recreate these arrays.

The following example defines a shared component named SharedGrouping and a system that only processes entities that have the group field set to 1.


struct SharedGrouping : ISharedComponentData
{
    public int Group;
}

[RequireMatchingQueriesForUpdate]
partial class ImpulseSystem : SystemBase
{
    EntityQuery query;

    protected override void OnCreate()
    {
        query = new EntityQueryBuilder(Allocator.Temp)
            .WithAllRW<ObjectPosition>()
            .WithAll<Displacement, SharedGrouping>()
            .Build(this);
    }

    protected override void OnUpdate()
    {
        // By default (without a filter), count all entities that have the required components.
        query.ResetFilter();
        int unfilteredCount = query.CalculateEntityCount();
        // With a filter, only entities in chunks that have SharedGrouping=1 will be counted.
        query.SetSharedComponentFilter(new SharedGrouping { Group = 1 });
        int filteredCount = query.CalculateEntityCount();
        // Many query methods include a variant that ignores any active filters. These variants are generally
        // more efficient, and should be used when conservative upper-bound results are acceptable.
        int ignoreFilterCount = query.CalculateEntityCountWithoutFiltering();
    }
}

Use a change filter

If you only need to update entities when a component value has changed, use the SetChangedVersionFilter method to add that component to the EntityQuery filter. For example, the following EntityQuery only includes entities from chunks that another system has already written to the Translation component:


EntityQuery query;

protected override void OnCreate()
{
    query = new EntityQueryBuilder(Allocator.Temp)
        .WithAllRW<LocalToWorld>()
        .WithAll<ObjectPosition>()
        .Build(this);
    query.SetChangedVersionFilter(typeof(ObjectPosition));

}

For efficiency, the change filter applies to whole archetype chunks, and not individual entities. The change filter also only checks whether a system that declared write access to the component has run, and not whether it changed any data. For example, if another job that can write to that component type accesses the chunk, then the change filter includes all entities in that chunk. This is why you should always declare read-only access to components that you don't need to modify.

Filtering by enableable components

Enableable components allow components on individual entities to be enabled and disabled at runtime. Disabling components on an entity doesn't move that entity into a new archetype, but for the purposes of EntityQuery matching, the entity is treated as if it doesn't have the component. Specifically:

  • If an entity has component T disabled, it will not match queries that require component T (using WithAll<T>()).
  • If an entity has component T disabled, it will match queries that exclude component T (using WithNone<T>()).

Most EntityQuery operations, such as ToEntityArray and CalculateEntityCount, automatically filter out entities whose enableable components would cause them not to match the query. To disable this filtering, use the IgnoreFilter variants of these operations, or pass the EntityQueryOptions.IgnoreComponentEnabledState at query creation time.

See the enableable components documentation for more details.

Further resources