Class EntityCommandBufferSystem

A system that provides EntityCommandBuffer objects for other systems.

Inheritance
System.Object
ComponentSystemBase
ComponentSystem
EntityCommandBufferSystem
BeginInitializationEntityCommandBufferSystem
BeginPresentationEntityCommandBufferSystem
BeginSimulationEntityCommandBufferSystem
EndInitializationEntityCommandBufferSystem
EndSimulationEntityCommandBufferSystem
Inherited Members
Namespace: Unity.Entities
Syntax
public abstract class EntityCommandBufferSystem : ComponentSystem
Remarks

Each system that uses the EntityCommandBuffer provided by a command buffer system must call CreateCommandBuffer() to create its own command buffer instance. This buffer system executes each of these separate command buffers in the order that you created them. The commands are executed during this system's OnUpdate() function.

When you write to a command buffer from a Job, you must add the of that Job to the buffer system's dependency list with AddJobHandleForProducer(JobHandle).

If you write to a command buffer from a Job that runs in parallel (and this includes both IJobForEach<T0> and IJobChunk), you must use the concurrent version of the command buffer (ToConcurrent()).

Executing the commands in an EntityCommandBuffer invokes the corresponding functions of the EntityManager. Any structural change, such as adding or removing entities, adding or removing components from entities, or changing shared component values, creates a sync-point in your application. At a sync point, all Jobs accessing entity components must complete before new Jobs can start. Such sync points make it difficult for the Job scheduler to fully utilize available computing power. To avoid sync points, you should use as few entity command buffer systems as possible.

The default ECS World code creates a ComponentSystemGroup setup with three main groups, InitializationSystemGroup, SimulationSystemGroup, and PresentationSystemGroup. Each of these main groups provides an existing EntityCommandBufferSystem executed at the start and the end of other, child systems.

Note that unused command buffers systems do not create sync points because there are no commands to execute and thus no structural changes created.

The EntityCommandBufferSystem class is abstract, so you must implement a subclass to create your own entity command buffer system. However, none of its methods are abstract, so you do not need to implement your own logic. Typically, you create an EntityCommandBufferSystem subclass to create a named buffer system for other systems to use and update it at an appropriate place in a custom ComponentSystemGroup setup.

Methods

AddJobHandleForProducer(JobHandle)

Adds the specified JobHandle to this system's list of dependencies.

Declaration
public void AddJobHandleForProducer(JobHandle producerJob)
Parameters
Type Name Description
JobHandle producerJob

The JobHandle of a Job which this buffer system should wait for before playing back its pending command buffers.
Remarks

When you write to a command buffer from a Job, you must add the of that Job to this buffer system's dependency list by calling this function. Otherwise, the buffer system could execute the commands currently in the command buffer while the writing Job is still in progress.

Examples

The following example illustrates how to use one of the default EntityCommandBuffer systems. The code selects all entities that have one custom component, in this case, AsyncProcessInfo, and processes each entity in the Execute() function of an IJobForEachWithEntity<T0> Job (the actual process is not shown since that part of the example is hypothetical). After processing, the Job uses an EntityCommandBuffer to remove the ProcessInfo component and add an ProcessCompleteTag component. Another system could use the ProcessCompleteTag to find entities that represent the end results of the process.

public struct ProcessInfo: IComponentData{ public float Value; }
public struct ProcessCompleteTag : IComponentData{}

public class AsyncProcessJobSystem : JobComponentSystem
{
    [BurstCompile]
    public struct ProcessInBackgroundJob : IJobForEachWithEntity<ProcessInfo>
    {
        [ReadOnly]
        public EntityCommandBuffer.Concurrent ConcurrentCommands;

        public void Execute(Entity entity, int index, [ReadOnly] ref ProcessInfo info)
        {
            // Process based on the ProcessInfo component,
            // then remove ProcessInfo and add a ProcessCompleteTag...

            ConcurrentCommands.RemoveComponent<ProcessInfo>(index, entity);
            ConcurrentCommands.AddComponent(index, entity, new ProcessCompleteTag());
        }
    }

    protected override JobHandle OnUpdate(JobHandle inputDeps)
    {
        var job = new ProcessInBackgroundJob();

        var ecbSystem =
            World.GetOrCreateSystem<EndSimulationEntityCommandBufferSystem>();
        job.ConcurrentCommands = ecbSystem.CreateCommandBuffer().ToConcurrent();

        var handle = job.Schedule(this, inputDeps);
        ecbSystem.AddJobHandleForProducer(handle);

        return handle;
    }
}

CreateCommandBuffer()

Creates an EntityCommandBuffer and adds it to this system's list of command buffers.

Declaration
public EntityCommandBuffer CreateCommandBuffer()
Returns
Type Description
EntityCommandBuffer

A command buffer that will be executed by this system.
Remarks

This buffer system executes its list of command buffers during its OnUpdate() function in the order you created the command buffers.

If you write to a command buffer in a Job, you must add the Job as a dependency of this system by calling AddJobHandleForProducer(JobHandle). The dependency ensures that the buffer system waits for the Job to complete before executing the command buffer.

If you write to a command buffer from a parallel Job, such as IJobForEach<T0> or IJobChunk, you must use the concurrent version of the command buffer, provided by EntityCommandBuffer.Concurrent.

OnCreate()

Initializes this command buffer system.

Declaration
protected override void OnCreate()
Overrides
Remarks

If you override this method, you should call base.OnCreate() to retain the default initialization logic.

OnDestroy()

Destroys this system, executing any pending command buffers first.

Declaration
protected override void OnDestroy()
Overrides
Remarks

If you override this method, you should call base.OnDestroy() to retain the default destruction logic.

OnUpdate()

Executes the command buffers in this system in the order they were created.

Declaration
protected override void OnUpdate()
Overrides
Remarks

If you override this method, you should call base.OnUpdate() to retain the default update logic.

Extension Methods