ecb-system-timing

ECB System Timing — Begin vs End Simulation

Intent

Select the correct ECBSystem playback boundary (BeginSimulation vs EndSimulation) based on when the structural change result must be visible, and guard both with RequireForUpdate.

Use When

Any system that needs deferred structural changes and can tolerate a one-frame-boundary delay. The standard choice for all production ECB usage.

Avoid When

The structural change must be visible within the same system update — use a manual ECB (Allocator.Temp) with explicit Playback instead. Avoid when running in a custom World without standard ECBSystems — check with RequireForUpdate first.

Senior Pattern

• In OnCreate: state.RequireForUpdate<BeginSimulationEntityCommandBufferSystem.Singleton>() — both a safety guard and a dependency declaration.
• In OnUpdate: var ecbSingleton = SystemAPI.GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>(); var ecb = ecbSingleton.CreateCommandBuffer(state.WorldUnmanaged);
• BeginSimulation playback: runs before SimulationSystemGroup — structural changes are visible to all simulation systems in the current frame.
• EndSimulation playback: runs after SimulationSystemGroup — structural changes are visible from the next frame's simulation.
• Never cache the ECB reference across frames — the ECBSystem's internal buffer is reset after playback.

Code Template

[BurstCompile]
[UpdateInGroup(typeof(SimulationSystemGroup))]
public partial struct EnemyDestroySystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state)
    {
        state.RequireForUpdate<BeginSimulationEntityCommandBufferSystem.Singleton>();
        state.RequireForUpdate<EnemyTag>();
    }

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

        foreach (var (health, entity) in
            SystemAPI.Query<RefRO<Health>>().WithEntityAccess())
        {
            if (health.ValueRO.Current <= 0)
                ecb.DestroyEntity(entity);
        }
    }
}