Class ComponentSystemBase

A system provides behavior in an ECS architecture.

Inheritance

Object

ComponentSystemBase

ComponentSystem

JobComponentSystem

SystemBase

Namespace: Unity.Entities

Syntax

public abstract class ComponentSystemBase

Remarks

System implementations should inherit SystemBase, which is a subclass of ComponentSystemBase.

Properties

Enabled

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

Declaration

public bool Enabled { get; set; }

Property Value

Type	Description
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
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
UInt32	The GlobalSystemVersion the last time this system ran.

Remarks

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

When you use or DidChange(ArchetypeChunkComponentTypeDynamic, 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.

Time

The current Time data for this system's world.

Declaration

public TimeData Time { get; }

Property Value

Type	Description
TimeData

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
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)
    where T : struct, IComponentData

Parameters

Type	Name	Description
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.

GetArchetypeChunkComponentTypeDynamic(ComponentType)

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

Declaration

public ArchetypeChunkComponentTypeDynamic GetArchetypeChunkComponentTypeDynamic(ComponentType componentType)

Parameters

Type	Name	Description
ComponentType	componentType	Type of the component

Returns

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

Remarks

Pass an ArchetypeChunkComponentTypeDynamic 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.

GetBufferFromEntity<T>(Boolean)

Gets a BufferFromEntity<T> object that can access a DynamicBuffer<T>.

Declaration

public BufferFromEntity<T> GetBufferFromEntity<T>(bool isReadOnly = false)
    where T : struct, IBufferElementData

Parameters

Type	Name	Description
Boolean	isReadOnly	Whether the buffer data is only read or is also written. Access data in a read-only fashion whenever possible.

Returns

Type	Description
BufferFromEntity<T>	An array-like object that provides access to buffers, indexed by Entity.

Type Parameters

Name	Description
T	The type of IBufferElementData stored in the buffer.

Remarks

Assign the returned object to a field of your Job struct so that you can access the contents of the buffer in a Job.

See Also

ComponentDataFromEntity<T>

GetComponentDataFromEntity<T>(Boolean)

Gets an dictionary-like container containing all components of type T, keyed by Entity.

Declaration

public ComponentDataFromEntity<T> GetComponentDataFromEntity<T>(bool isReadOnly = false)
    where T : struct, IComponentData

Parameters

Type	Name	Description
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>()

Returns

Type	Description
Entity	The entity associated with the specified singleton component.

Type Parameters

Name	Description
T	The Type 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
Boolean	True, if a singleton of the specified 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.

OnCreateForCompiler()

Declaration

protected virtual void OnCreateForCompiler()

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.

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
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 abstract void Update()

Remarks

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

See Also

SystemBase

ComponentSystemGroup

EntityCommandBufferSystem

Extension Methods

ComponentSystemBaseManagedComponentExtensions.HasSingleton<T>(ComponentSystemBase)

ComponentSystemBaseManagedComponentExtensions.GetSingleton<T>(ComponentSystemBase)

ComponentSystemBaseManagedComponentExtensions.SetSingleton<T>(ComponentSystemBase, T)

JobForEachExtensions.GetEntityQueryForIJobForEach(ComponentSystemBase, Type)