Class EntityQuery | Package Manager UI website
docs.unity3d.com
    Show / Hide Table of Contents

    Class EntityQuery

    A EntityQuery provides a queryDesc-based view of your component data.

    Inheritance
    System.Object
    EntityQuery
    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.

    EntityQuery m_Group = 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 CreateEntityQuery(ComponentType[]) or 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
    System.Boolean

    True if this EntityQuery has no entities. False if it has 1 or more entities.

    Methods

    AddDependency(JobHandle)

    Adds another job handle to this EntityQuery's dependencies.

    Declaration
    public void AddDependency(JobHandle job)
    Parameters
    Type Name Description
    JobHandle job

    CalculateLength()

    Calculates the number of entities selected by this EntityQuery.

    Declaration
    public int CalculateLength()
    Returns
    Type Description
    System.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.

    CompareComponents(NativeArray<ComponentType>)

    Declaration
    public bool CompareComponents(NativeArray<ComponentType> componentTypes)
    Parameters
    Type Name Description
    NativeArray<ComponentType> componentTypes
    Returns
    Type Description
    System.Boolean

    CompareComponents(ComponentType[])

    Declaration
    public bool CompareComponents(ComponentType[] componentTypes)
    Parameters
    Type Name Description
    ComponentType[] componentTypes
    Returns
    Type Description
    System.Boolean

    CompareQuery(EntityQueryDesc[])

    Declaration
    public bool CompareQuery(EntityQueryDesc[] queryDesc)
    Parameters
    Type Name Description
    EntityQueryDesc[] queryDesc
    Returns
    Type Description
    System.Boolean

    CompleteDependency()

    Ensures all jobs running on this EntityQuery complete.

    Declaration
    public void CompleteDependency()

    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)

    Creates an array with all the chunks in this EntityQuery. Waits for the GatherChunks job to complete here.

    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.

    CreateArchetypeChunkArray(Allocator, out JobHandle)

    Creates an array with all the chunks in this EntityQuery. Gives the caller a job handle so it can wait for GatherChunks to finish.

    Declaration
    public NativeArray<ArchetypeChunk> CreateArchetypeChunkArray(Allocator allocator, out JobHandle jobhandle)
    Parameters
    Type Name Description
    Allocator allocator

    Allocator to use for the array.

    JobHandle jobhandle

    Handle to the GatherChunks job used to fill the output array.

    Returns
    Type Description
    NativeArray<ArchetypeChunk>

    NativeArray of all the chunks in this ComponentChunkIterator.

    Dispose()

    Declaration
    public void Dispose()

    GetCombinedComponentOrderVersion()

    Declaration
    public int GetCombinedComponentOrderVersion()
    Returns
    Type Description
    System.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

    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
    System.InvalidOperationException

    GetSingletonEntity()

    Declaration
    public Entity GetSingletonEntity()
    Returns
    Type Description
    Entity

    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.

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

    SetFilter<SharedComponent1, SharedComponent2>(SharedComponent1, SharedComponent2)

    Filters this EntityQuery based on the values of two separate shared components.

    Declaration
    public void SetFilter<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.

    SetFilterChanged(ComponentType)

    Filters out entities in chunks for which the specified component has not changed.

    Declaration
    public void SetFilterChanged(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.

    SetFilterChanged(ComponentType[])

    Filters out entities in chunks for which the specified components have not changed.

    Declaration
    public void SetFilterChanged(ComponentType[] componentType)
    Parameters
    Type Name Description
    ComponentType[] componentType

    Array of up to two ComponentTypes to mark as changed on this EntityQuery's filter.

    Remarks

    Saves given ComponentTypes' indices in RequiredComponents in this group's Changed filter.

    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 entityManager = World.Active.EntityManager;
    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
    System.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>(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
    System.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

    A handle that you can use as a dependency for a Job that uses the NativeArray.

    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

    A handle that you can use as a dependency for a Job that uses the NativeArray.

    Returns
    Type Description
    NativeArray<Entity>

    An array containing all the entities selected by the EntityQuery.

    Extension Methods

    EntityQueryExtensionsForComponentArray.ToComponentArray<T>(EntityQuery)
    EntityQueryExtensionsForTransformAccessArray.GetTransformAccessArray(EntityQuery)
    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023