Table of Contents

Entity Command Buffer

EntityCommandBuffer (ECB) records structural operations and replays them later.

Use it when you cannot safely mutate structure immediately (for example, while iterating query results or inside parallel jobs).

Why Use ECB

  • Avoid structural modifications during active iteration.
  • Batch operations into one playback phase.
  • Use thread-local command buffers in multithreaded jobs.

Recorded Operations

The ECB supports recording:

  • create entity,
  • create entity with component set,
  • destroy entity,
  • add component,
  • remove component,
  • set component.

Basic Usage

var world = World.Create();
var ecb = world.EntityCommandBuffer;

ecb.CreateEntity(count: 100);

var entity = world.EntityManager.CreateEntity();
ecb.AddComponent(entity, new Velocity { X = 1, Y = 0, Z = 0 });
ecb.SetComponent(entity, new Velocity { X = 2, Y = 0, Z = 0 });

Thread-Local ECB

When a world has a JobScheduler, obtain per-thread buffers:

var threadLocal = world.GetThreadLocalEntityCommandBuffer(threadIndex);
threadLocal.DestroyEntity(entity);

Then playback all buffers at a sync point:

Playback is performed by the world/runtime update flow at synchronization points.

Notes

  • Playback executes in recording order per buffer.
  • Playback clears internal command data (Reset) after execution.
  • ECB does not replace dependency handling; you still need proper job synchronization before playback.