wave8-ecb-system-group-mismatch

ECB System Group Mismatch — Wrong Playback Timing

Intent

Identify and fix bugs caused by using an ECB from the wrong system group, resulting in structural change commands executing at the wrong frame boundary.

Use When

• Diagnosing one-frame-late structural changes, components appearing/disappearing unexpectedly, or ECB playback order bugs
• Code review of any system that records ECB commands to an ECBSystem singleton

Avoid When

• Using a manually created ECB with explicit Playback — group mismatch only affects ECBSystem-owned buffers, not manual ECBs

Senior Pattern

// WRONG — EndSimulationECBSystem from within FixedStepSimulationSystemGroup:
// Commands play back after SimulationSystemGroup ends (variable rate), not after FixedStep ends
[UpdateInGroup(typeof(FixedStepSimulationSystemGroup))]
public partial struct FixedPhysicsReactionSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // Wrong ECB system — playback happens at wrong frame boundary:
        var ecbSystem = SystemAPI.GetSingleton<EndSimulationEntityCommandBufferSystem.Singleton>();
        var ecb = ecbSystem.CreateCommandBuffer(state.WorldUnmanaged);
    }
}

// CORRECT — use the ECB system matching the enclosing group:
[UpdateInGroup(typeof(FixedStepSimulationSystemGroup))]
public partial struct FixedPhysicsReactionSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var ecbSystem = SystemAPI.GetSingleton<EndFixedStepSimulationEntityCommandBufferSystem.Singleton>();
        var ecb = ecbSystem.CreateCommandBuffer(state.WorldUnmanaged);
        // Commands play back at end of FixedStepSimulationSystemGroup — correct timing
    }
}

ECB System Selection Guide

Enclosing System Group	Correct ECB System
InitializationSystemGroup	BeginInitializationEntityCommandBufferSystem or EndInitializationEntityCommandBufferSystem
SimulationSystemGroup	BeginSimulationEntityCommandBufferSystem or EndSimulationEntityCommandBufferSystem
FixedStepSimulationSystemGroup	EndFixedStepSimulationEntityCommandBufferSystem
PresentationSystemGroup	EndPresentationEntityCommandBufferSystem