Bevy ECS: Parallelization Limits When Systems Share Mutable Component Access

1. Querying the Scheduler’s Conflict Graph

Bevy builds a conflict graph at app startup based solely on component type access (read/write). The current public API does not expose this graph, nor is there a diagnostic endpoint that reports how many systems were serialized because of inferred conflicts. In practice, you can infer serialization indirectly by:

• Adding explicit .before() or .after() constraints and measuring the change in frame time.
• Enabling bevy::diagnostic::FrameTimeDiagnosticsPlugin and looking for scheduler warnings in the debug log (e.g., "System X conflicts with Y, running sequentially").

So, answer to Q1: No, there is currently no supported method to query the conflict graph directly.

2. Filters Do Not Resolve Mutable Conflicts

When two systems request mutable access to the same component type, the scheduler considers them conflicting regardless of any With or Without filters. The type‑level conflict check ignores the specific archetypes a system will hit. Therefore, Query<&mut T, With> and Query<&mut T, With> will be serialized unless you add an explicit ordering constraint.

In a high‑entity scenario (10 000+ entities) this can quickly become a bottleneck: each conflicting pair introduces a serialization point that the scheduler can’t hide behind parallelism. The practical threshold is roughly the number of conflicting systems that exceeds the available CPU cores. When conflict density grows beyond the core count, the scheduler’s conservative policy will serialise enough systems to keep the core count saturated, and you’ll see a linear increase in the serialized portion of the frame time.

3. Recovering Parallelism by Splitting Mutable Components

The recommended pattern is to decompose a monolithic mutable component into smaller, orthogonal sub‑components. Each system then mutates only the sub‑component it cares about. Because the scheduler’s conflict graph is built per component type, this eliminates the type‑level conflict without needing .before/.after sync points.

#[derive(Component)]
struct Position { x: f32, y: f32 }

#[derive(Component)]
struct Velocity { vx: f32, vy: f32 }

fn move_system(mut query: Query<(&mut Position, &Velocity)>) {
    for (mut pos, vel) in query.iter_mut() {
        pos.x += vel.vx;
        pos.y += vel.vy;
    }
}

fn update_velocity_system(mut query: Query<&mut Velocity>) {
    for mut vel in query.iter_mut() {
        // modify velocity independently
    }
}

With this split, move_system mutates Position while update_velocity_system mutates Velocity. The scheduler sees no conflict and runs them in parallel. Keep an eye on cache locality: over‑splitting can hurt performance if the data is frequently accessed together.

Practical Steps to Verify Parallelism

1. Build a minimal Bevy app with two systems that mutate the same component but filter on disjoint With tags.
2. Run with default scheduler; enable FrameTimeDiagnosticsPlugin and set log level to DEBUG.
3. Observe whether the log reports a conflict and whether frame time shows a serialized spike.
4. Add .before() between the systems and confirm that the conflict warning disappears and frame time drops.
5. Apply the component‑splitting pattern and re‑profile; you should see the original frame time restored without ordering constraints.

By following these steps you can determine the practical threshold for serialization in your specific workload and apply the split‑component pattern to recover parallelism.

Missing Diagnostic Detail

To refine the recommendation, could you share the number of CPU cores you expect to use for the target hardware?