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

    Class ComponentSystemBase

    A system provides behavior in an ECS architecture.

    Inheritance
    System.Object
    ComponentSystemBase
    ComponentSystem
    JobComponentSystem
    Namespace: Unity.Entities
    Syntax
    public abstract class ComponentSystemBase
    Remarks

    A typical system operates on a set of entities that have specific components. The system identifies the components of interest using an EntityQuery (JobComponentSystem) or EntityQueryBuilder (ComponentSystem). The system then finds the entities matching the query and iterates over them, reading and writing data, and performing other entity operations as appropriate. A ComponentSystem is designed to perform its work on the main thread; a JobComponentSystem is designed to work with ECS-specific Jobs, such as IJobForEach<T0> and IJobChunk or with general-purpose C# Jobs.

    You can implement a set of system lifecycle event functions when you implement a system. The ECS invokes these functions in the following order:

    • OnCreate() -- called when the system is created.
    • OnStartRunning() -- before the first OnUpdate and whenever the system resumes running.
    • OnUpdate -- every frame as long as the system has work to do (see ShouldRunSystem()) and the system is Enabled. Note that the OnUpdate function is defined in the subclasses of ComponentSystemBase; each system class can define its own update behavior.
    • OnStopRunning() -- whenever the system stops updating because it finds no entities matching its queries. Also called before OnDestroy.
    • OnDestroy() -- when the system is destroyed.

    All of these functions are executed on the main thread. Note that you can schedule Jobs from the OnUpdate(JobHandle) function of a JobComponentSystem to perform work on background threads.

    The runtime executes systems in the order determined by their ComponentSystemGroup. Place a system in a group using UpdateInGroupAttribute. Use UpdateBeforeAttribute and UpdateAfterAttribute to specify the execution order within a group.

    If you do not explicitly place a system in a specific group, the runtime places it in the Default World SimulationSystemGroup. By default, all systems are discovered, instantiated, and added to the default World. You can use the DisableAutoCreationAttribute to prevent a system from being created automatically.

    Properties

    Enabled

    Controls whether this system executes when its OnUpdate function is called.

    Declaration
    public bool Enabled { get; set; }
    Property Value
    Type Description
    System.Boolean

    True, if the system is enabled.

    Remarks

    The Enabled property is intended for debugging so that you can easily turn on and off systems from the Entity Debugger window. A system with Enabled set to false will not update, even if its ShouldRunSystem() function returns true.

    EntityManager

    The EntityManager object of the World in which this system exists.

    Declaration
    public EntityManager EntityManager { get; }
    Property Value
    Type Description
    EntityManager

    The EntityManager for this system.

    EntityQueries

    The query objects cached by this system.

    Declaration
    public EntityQuery[] EntityQueries { get; }
    Property Value
    Type Description
    EntityQuery[]

    A read-only array of the cached EntityQuery objects.

    Remarks

    A system caches any queries it implicitly creates through the IJob interfaces or EntityQueryBuilder, that you create explicitly by calling GetEntityQuery(ComponentType[]), or that you add to the system as a required query with RequireForUpdate(EntityQuery). Implicit queries may be created lazily and not exist before a system has run for the first time.

    GlobalSystemVersion

    The current change version number in this World.

    Declaration
    public uint GlobalSystemVersion { get; }
    Property Value
    Type Description
    System.UInt32
    Remarks

    The system updates the component version numbers inside any ArchetypeChunk instances that this system accesses with write permissions to this value.

    LastSystemVersion

    The current version of this system.

    Declaration
    public uint LastSystemVersion { get; }
    Property Value
    Type Description
    System.UInt32

    The GlobalSystemVersion the last time this system ran.

    Remarks

    LastSystemVersion is updated to match the GlobalSystemVersion whenever a system runs.

    When you use SetFilterChanged(ComponentType) or DidChange<T>(ArchetypeChunkComponentType<T>, UInt32), LastSystemVersion provides the basis for determining whether a component could have changed since the last time the system ran.

    When a system accesses a component and has write permission, it updates the change version of that component type to the current value of LastSystemVersion. The system updates the component type's version whether or not it actually modifies data in any instances of the component type -- this is one reason why you should specify read-only access to components whenever possible.

    For efficiency, ECS tracks the change version of component types by chunks, not by individual entities. If a system updates the component of a given type for any entity in a chunk, then ECS assumes that the components of all entities in that chunk could have been changed. Change filtering allows you to save processing time by skipping all entities in an unchanged chunk, but does not support skipping individual entities in a chunk that does contain changes.

    World

    The World in which this system exists.

    Declaration
    public World World { get; }
    Property Value
    Type Description
    World

    The World of this system.

    Methods

    GetArchetypeChunkBufferType<T>(Boolean)

    Gets the run-time type information required to access an array of buffer components in a chunk.

    Declaration
    public ArchetypeChunkBufferType<T> GetArchetypeChunkBufferType<T>(bool isReadOnly = false)
        where T : struct, IBufferElementData
    Parameters
    Type Name Description
    System.Boolean isReadOnly

    Whether the data is only read, not written. Access data as read-only whenever possible.

    Returns
    Type Description
    ArchetypeChunkBufferType<T>

    An object representing the type information required to safely access buffer components stored in a chunk.

    Type Parameters
    Name Description
    T

    A struct that implements IBufferElementData.

    Remarks

    Pass a GetArchetypeChunkBufferType instance to a job that has access to chunk data, such as an IJobChunk job, to access that type of buffer component inside the job.

    GetArchetypeChunkComponentType<T>(Boolean)

    Gets the run-time type information required to access an array of component data in a chunk.

    Declaration
    public ArchetypeChunkComponentType<T> GetArchetypeChunkComponentType<T>(bool isReadOnly = false)
    Parameters
    Type Name Description
    System.Boolean isReadOnly

    Whether the component data is only read, not written. Access components as read-only whenever possible.

    Returns
    Type Description
    ArchetypeChunkComponentType<T>

    An object representing the type information required to safely access component data stored in a chunk.

    Type Parameters
    Name Description
    T

    A struct that implements IComponentData.

    Remarks

    Pass an instance to a job that has access to chunk data, such as an IJobChunk job, to access that type of component inside the job.

    GetArchetypeChunkEntityType()

    Gets the run-time type information required to access the array of Entity objects in a chunk.

    Declaration
    public ArchetypeChunkEntityType GetArchetypeChunkEntityType()
    Returns
    Type Description
    ArchetypeChunkEntityType

    An object representing the type information required to safely access Entity instances stored in a chunk.

    GetArchetypeChunkSharedComponentType<T>()

    Gets the run-time type information required to access a shared component data in a chunk.

    Declaration
    public ArchetypeChunkSharedComponentType<T> GetArchetypeChunkSharedComponentType<T>()
        where T : struct, ISharedComponentData
    Returns
    Type Description
    ArchetypeChunkSharedComponentType<T>

    An object representing the type information required to safely access shared component data stored in a chunk.

    Type Parameters
    Name Description
    T

    A struct that implements ISharedComponentData.

    GetComponentDataFromEntity<T>(Boolean)

    Gets an array-like container containing all components of type T, indexed by Entity.

    Declaration
    public ComponentDataFromEntity<T> GetComponentDataFromEntity<T>(bool isReadOnly = false)
        where T : struct, IComponentData
    Parameters
    Type Name Description
    System.Boolean isReadOnly

    Whether the data is only read, not written. Access data as read-only whenever possible.

    Returns
    Type Description
    ComponentDataFromEntity<T>

    All component data of type T.

    Type Parameters
    Name Description
    T

    A struct that implements IComponentData.

    GetEntityQuery(NativeArray<ComponentType>)

    Gets the cached query for the specified component types, if one exists; otherwise, creates a new query instance and caches it.

    Declaration
    protected EntityQuery GetEntityQuery(NativeArray<ComponentType> componentTypes)
    Parameters
    Type Name Description
    NativeArray<ComponentType> componentTypes

    An array of component types.

    Returns
    Type Description
    EntityQuery

    The new or cached query.

    GetEntityQuery(ComponentType[])

    Gets the cached query for the specified component types, if one exists; otherwise, creates a new query instance and caches it.

    Declaration
    protected EntityQuery GetEntityQuery(params ComponentType[] componentTypes)
    Parameters
    Type Name Description
    ComponentType[] componentTypes

    An array or comma-separated list of component types.

    Returns
    Type Description
    EntityQuery

    The new or cached query.

    GetEntityQuery(EntityQueryDesc[])

    Combines an array of query description objects into a single query.

    Declaration
    protected EntityQuery GetEntityQuery(params EntityQueryDesc[] queryDesc)
    Parameters
    Type Name Description
    EntityQueryDesc[] queryDesc

    An array of query description objects to be combined to define the query.

    Returns
    Type Description
    EntityQuery

    The new or cached query.

    Remarks

    This function looks for a cached query matching the combined query descriptions, and returns it if one exists; otherwise, the function creates a new query instance and caches it.

    GetSingleton<T>()

    Gets the value of a singleton component.

    Declaration
    public T GetSingleton<T>()
        where T : struct, IComponentData
    Returns
    Type Description
    T

    The component.

    Type Parameters
    Name Description
    T

    The IComponentData subtype of the singleton component.

    See Also
    GetSingleton<T>()

    GetSingletonEntity<T>()

    Gets the Entity instance for a singleton.

    Declaration
    public Entity GetSingletonEntity<T>()
        where T : struct, IComponentData
    Returns
    Type Description
    Entity

    The entity associated with the specified singleton component.

    Type Parameters
    Name Description
    T

    The IComponentData subtype of the singleton component.

    See Also
    GetSingletonEntity()

    HasSingleton<T>()

    Checks whether a singelton component of the specified type exists.

    Declaration
    public bool HasSingleton<T>()
        where T : struct, IComponentData
    Returns
    Type Description
    System.Boolean

    True, if a singleton of the secified type exists in the current World.

    Type Parameters
    Name Description
    T

    The IComponentData subtype of the singleton component.

    OnCreate()

    Called when this system is created.

    Declaration
    protected virtual void OnCreate()
    Remarks

    Implement an OnCreate() function to set up system resources when it is created.

    OnCreate is invoked before the the first time OnStartRunning() and OnUpdate are invoked.

    OnCreateManager()

    Deprecated. Use OnCreate().

    Declaration
    protected virtual void OnCreateManager()

    OnDestroy()

    Called when this system is destroyed.

    Declaration
    protected virtual void OnDestroy()
    Remarks

    Systems are destroyed when the application shuts down, the World is destroyed, or you call DestroySystem(ComponentSystemBase). In the Unity Editor, system destruction occurs when you exit Play Mode and when scripts are reloaded.

    OnDestroyManager()

    Deprecated. Use OnDestroy().

    Declaration
    protected virtual void OnDestroyManager()

    OnStartRunning()

    Called before the first call to OnUpdate and when a system resumes updating after being stopped or disabled.

    Declaration
    protected virtual void OnStartRunning()
    Remarks

    If the EntityQuery objects defined for a system do not match any existing entities then the system skips updates until a successful match is found. Likewise, if you set Enabled to false, then the system stops running. In both cases, OnStopRunning() is called when a running system stops updating; OnStartRunning is called when it starts updating again.

    OnStopRunning()

    Called when this system stops running because no entities match the system's EntityQuery objects or because you change the system Enabled property to false.

    Declaration
    protected virtual void OnStopRunning()
    Remarks

    If the EntityQuery objects defined for a system do not match any existing entities then the system skips updating until a successful match is found. Likewise, if you set Enabled to false, then the system stops running. In both cases, OnStopRunning() is called when a running system stops updating; OnStartRunning is called when it starts updating again.

    RequireForUpdate(EntityQuery)

    Adds a query that must return entities for the system to run. You can add multiple required queries to a system; all of them must match at least one entity for the system to run.

    Declaration
    public void RequireForUpdate(EntityQuery query)
    Parameters
    Type Name Description
    EntityQuery query

    A query that must match entities this frame in order for this system to run.

    Remarks

    Any queries added through RequireforUpdate override all other queries cached by this system. In other words, if any required query does not find matching entities, the update is skipped even if another query created for the system (either explicitly or implicitly) does match entities and vice versa.

    RequireSingletonForUpdate<T>()

    Require that a specific singleton component exist for this system to run.

    Declaration
    public void RequireSingletonForUpdate<T>()
    Type Parameters
    Name Description
    T

    The IComponentData subtype of the singleton component.

    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

    A component containing the value to assign to the singleton.

    Type Parameters
    Name Description
    T

    The IComponentData subtype of the singleton component.

    See Also
    SetSingleton<T>(T)

    ShouldRunSystem()

    Reports whether any of this system's entity queries currently match any chunks. This function is used internally to determine whether the system's OnUpdate function can be skipped.

    Declaration
    public bool ShouldRunSystem()
    Returns
    Type Description
    System.Boolean

    True, if the queries in this system match existing entities or the system has the AlwaysUpdateSystemAttribute.

    Remarks

    A system without any queries also returns true. Note that even if this function returns true, other factors may prevent a system from updating. For example, a system will not be updated if its Enabled property is false.

    Update()

    Executes the system immediately.

    Declaration
    public void Update()
    Remarks

    The exact behavior is determined by this system's specific subclass.

    See Also
    ComponentSystem
    JobComponentSystem
    ComponentSystemGroup
    EntityCommandBufferSystem

    Extension Methods

    JobForEachExtensions.GetEntityQueryForIJobForEach(ComponentSystemBase, Type)
    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