Entity command buffer overview

An entity command buffer (ECB) stores a queue of thread-safe commands which you can add to and later play back. You can use an ECB to schedule structural changes from jobs and perform changes on the main thread after the jobs complete. You can also use ECBs on the main thread to delay changes, or play back a set of changes multiple times.

The methods in EntityCommandBuffer record commands, which mirror methods available in EntityManager. For example:

  • CreateEntity(EntityArchetype): Registers a command that creates a new entity with the specified archetype.
  • DestroyEntity(Entity): Registers a command that destroys the entity.
  • SetComponent<T>(Entity, T): Registers a command that sets the value for a component of type T on the entity.
  • AddComponent<T>(Entity): Registers a command that adds a component of type T to the entity.
  • RemoveComponent<T>(EntityQuery): Registers a command that removes a component of type T from all entities that match the query.

Entities created by command buffers

The EntityCommandBuffer methods CreateEntity() and Instantiate() return real Entity references at record time. The entity is allocated immediately, but is not assigned a chunk until Playback() runs. This means:

  • You can use the returned entity in any subsequent command on the same buffer, for example ecb.AddComponent<T>(e).
  • You can store the entity reference or pass it to other code. The reference remains valid across Playback().
  • You can record Entity fields in component values (including IBufferElementData) that reference these entities, for example ecb.SetComponent(e2, new Parent{ Value = e }). The references are stored directly; no remap pass is needed at playback.
  • Accessing the entity via EntityManager or queries only works after Playback(), because the entity has no chunk before then.

For Instantiate(prefab), only the root entity is allocated at record time. If the prefab has a LinkedEntityGroup, the child entities are allocated during Playback() and can be read from the root's LinkedEntityGroup buffer after playback completes.

Passing an entity created by one command buffer into a different command buffer's commands is allowed (the reference is real), but the originating buffer must be played back before any EntityManager-style access succeeds. Use a single buffer per logical batch of work to keep ordering clear.

Entity command buffer safety

EntityCommandBuffer has a job safety handle, similar to a native container. This safety is only available in the Unity Editor, and not in player builds. The safety checks throw an exception if you try to do any of the following on an incomplete scheduled job that uses an ECB:

  • Access the EntityCommandBuffer through its AddComponent, Playback, Dispose, or other methods.
  • Schedule another job that accesses the same EntityCommandBuffer, unless the new job depends on the already scheduled job.
Note

It’s best practice to use a separate ECB for each distinct job. This is because if you reuse an ECB in consecutive jobs, the jobs might use an overlapping set of sort keys (such as if both use ChunkIndexInQuery), and the commands that the jobs record might be interleaved.

Additional resources