entity-command-buffer

Entity Command Buffer

Intent

Record structural changes (AddComponent, RemoveComponent, Instantiate, DestroyEntity) during job execution or entity iteration, then play them back safely on the main thread after the frame boundary.

Use When

Any structural change needed inside a job or while iterating entities. Use BeginSimulationEntityCommandBufferSystem for standard playback timing. Use Allocator.Temp ECB only for immediate same-frame playback on the main thread.

Avoid When

The change is a component value mutation, not a structural change — write directly via RefRW. Avoid creating per-system manual ECBs when BeginSimulationEntityCommandBufferSystem covers the timing.

Senior Pattern

• Get ECB singleton from the appropriate ECB system: SystemAPI.GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>().CreateCommandBuffer(state.WorldUnmanaged).
• For parallel jobs: use ecb.AsParallelWriter() and pass [ChunkIndexInQuery] int chunkIndex as the sort key to Execute.
• For main-thread same-frame use: new EntityCommandBuffer(Allocator.Temp), call Playback, then Dispose.
• Commands are replayed in sort-key order — deterministic across parallel workers.

Code Template

// From a parallel job:
[BurstCompile]
partial struct SpawnJob : IJobEntity
{
    public EntityCommandBuffer.ParallelWriter Ecb;
    public Entity Prefab;

    void Execute([ChunkIndexInQuery] int chunkIndex, in SpawnRequest request)
    {
        var e = Ecb.Instantiate(chunkIndex, Prefab);
        Ecb.SetComponent(chunkIndex, e, new LocalTransform
        {
            Position = request.Position,
            Rotation = quaternion.identity,
            Scale = 1f
        });
    }
}

[BurstCompile]
public void OnUpdate(ref SystemState state)
{
    var ecbSingleton = SystemAPI.GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>();
    var ecb = ecbSingleton.CreateCommandBuffer(state.WorldUnmanaged);

    state.Dependency = new SpawnJob
    {
        Ecb = ecb.AsParallelWriter(),
        Prefab = SystemAPI.GetSingleton<SpawnConfig>().Prefab
    }.ScheduleParallel(state.Dependency);
}