wave8-wrong-system-group-fixed-timestep

Wrong System Group — Fixed Timestep Failure Mode

Intent

Identify and fix the failure mode of placing fixed-timestep physics or simulation logic in the wrong system group, causing frame-rate-dependent execution instead of fixed-rate execution.

Use When

• Diagnosing why physics behavior is frame-rate dependent or non-deterministic
• Code review of any system that writes PhysicsVelocity, applies forces, or handles collision response

Avoid When

• The system intentionally runs every rendered frame — SimulationSystemGroup or PresentationSystemGroup are correct for those cases

Senior Pattern

// WRONG — runs every rendered frame, not at fixed timestep:
[UpdateInGroup(typeof(SimulationSystemGroup))]
public partial struct PhysicsResponseSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // Applies forces — frame-rate dependent, non-deterministic physics
    }
}

// CORRECT — runs at fixed timestep (default 50Hz):
[UpdateInGroup(typeof(FixedStepSimulationSystemGroup))]
[UpdateBefore(typeof(PhysicsSystemGroup))]
[BurstCompile]
public partial struct PhysicsResponseSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        // Applies forces — deterministic, fixed-rate
    }
}

// CORRECT — set custom fixed rate once at initialization:
[UpdateInGroup(typeof(InitializationSystemGroup))]
public partial class FixedRateBootstrapSystem : SystemBase
{
    protected override void OnCreate()
    {
        World.GetExistingSystemManaged<FixedStepSimulationSystemGroup>().Timestep = 1f / 30f;
        Enabled = false;  // run once
    }
    protected override void OnUpdate() { }
}

Diagnosis Checklist

• System writes PhysicsVelocity or PhysicsMass → must be in FixedStepSimulationSystemGroup
• System reads PhysicsWorldSingleton for queries → can be in SimulationSystemGroup (after physics completes)
• System handles collision/trigger events → must be in FixedStepSimulationSystemGroup [UpdateAfter(PhysicsSimulationGroup)]
• System interpolates for rendering → must be in PresentationSystemGroup