EntityCommandBufferSystem

Description

A system that provides EntityCommandBuffer objects for other systems.

Each system that uses the EntityCommandBuffer provided by a command buffer system must 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 EntityCommandBufferSystem.OnUpdate function.

To create a command buffer, get the buffer system's Singleton component with SystemAPI.GetSingleton, and then call CreateCommandBuffer(WorldUnmanaged) on that singleton. If you write to a command buffer created this way from a Job, you don't need to register that Job with the buffer system: the buffer system completes all Jobs scheduled against its singleton component before it plays the command buffer back.

If you instead call EntityCommandBufferSystem.CreateCommandBuffer on the buffer system instance, and you write to that command buffer from a Job, you must add the JobHandle of that Job to the buffer system's dependency list with EntityCommandBufferSystem.AddJobHandleForProducer.

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

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.

Public Methods

Protected Methods

Inherited Members