dots-ecb-orchestration

ECB Orchestration — Senior Patterns

Structural changes inside a scheduled job are forbidden. The EntityCommandBuffer (ECB) records the intent in a job and plays it back on the main thread at a specific phase. Choosing the wrong phase silently delays your change by one frame, deadlocks dependency chains, or splits an atomic state transition.

Intent

Defer structural mutations (and Enabled flips done from jobs) into a recorder, then let a known ECB system play them back at a deterministic point in the frame.

The mental model: pick by playback phase, not by name

Decision rule: Identify the reader of the post-change state. Pick the ECB that plays back before that reader.

Senior pattern (single-writer, parallel job)

public partial struct DestroyFallenSystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        // Declare the dependency. Don't search for the ECB system every OnUpdate.
        state.RequireForUpdate<BeginSimulationEntityCommandBufferSystem.Singleton>();
    }

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

        // For parallel-scheduled jobs:
        var ecbParallel = ecb.AsParallelWriter();

        new DestroyFallenJob
        {
            EcbParallel = ecbParallel,
        }.ScheduleParallel();
    }
}

[BurstCompile]
partial struct DestroyFallenJob : IJobEntity
{
    public EntityCommandBuffer.ParallelWriter EcbParallel;

    void Execute([ChunkIndexInQuery] int chunkIndex, Entity entity, in LocalTransform t)
    {
        if (t.Position.y < 0f)
            EcbParallel.DestroyEntity(chunkIndex, entity);
    }
}