Improve bevy_ecs inspectability and add debugging methods.

[AlephCubed]

My attempt at adopting #7758.

Solution

• Add len, is_empty, and iter methods to Bundle.
• Add diagnostic methods to World, Schedules, Dag, and ComponentId.
  • Schedules and World also include a diagnose_with_flattened method that includes a flattened version of the dependancy graph. This was moved to a separate method as getting the flattened graph requires mutable access.

Example output:

This is an example output for World::diagnose_with_flattened:

world:
  summary:
    component: 4
    bundle: 9
    archetype: 5
    entity: 1
    resource: 2
    resource(non send): 0
    table: 4
    sparse set: 1
  detail:
    components:
      ComponentId(0)(bevy_ecs::event::base::EventWrapperComponent<bevy_ecs::world::component_constants::OnAdd>) Table send_sync
      ComponentId(1)(bevy_ecs::event::base::EventWrapperComponent<bevy_ecs::world::component_constants::OnInsert>) Table send_sync
      ComponentId(2)(bevy_ecs::event::base::EventWrapperComponent<bevy_ecs::world::component_constants::OnReplace>) Table send_sync
      ComponentId(3)(bevy_ecs::event::base::EventWrapperComponent<bevy_ecs::world::component_constants::OnRemove>) Table send_sync
      ComponentId(4)(bevy_ecs::schedule::schedule::Schedules) Table send_sync
      ComponentId(5)(world_diagnostic::GameState) Table send_sync
      ComponentId(6)(world_diagnostic::Counter) Table send_sync
      ComponentId(7)(world_diagnostic::Player) Table send_sync
      ComponentId(8)(world_diagnostic::HighlightFlag) SparseSet send_sync
    bundles:
      BundleId(0): ["ComponentId(7)(world_diagnostic::Player)"]
      BundleId(1): ["ComponentId(6)(world_diagnostic::Counter)", "ComponentId(8)(world_diagnostic::HighlightFlag)"]
      BundleId(2): ["ComponentId(6)(world_diagnostic::Counter)"]
      BundleId(3): ["ComponentId(8)(world_diagnostic::HighlightFlag)"]
    archetypes:
      ArchetypeId(0): components:[] table:TableId(0) entity:0
      ArchetypeId(1): components:["ComponentId(7)(world_diagnostic::Player)"] table:TableId(1) entity:0
      ArchetypeId(2): components:["ComponentId(6)(world_diagnostic::Counter)", "ComponentId(8)(world_diagnostic::HighlightFlag)"] table:TableId(2) entity:1
      ArchetypeId(3): components:["ComponentId(6)(world_diagnostic::Counter)", "ComponentId(7)(world_diagnostic::Player)"] table:TableId(3) entity:0
      ArchetypeId(4): components:["ComponentId(6)(world_diagnostic::Counter)", "ComponentId(7)(world_diagnostic::Player)", "ComponentId(8)(world_diagnostic::HighlightFlag)"] table:TableId(3) entity:0
    resources:
      ComponentId(4)(bevy_ecs::schedule::schedule::Schedules)
      ComponentId(5)(world_diagnostic::GameState)
    tables:
      [0] entities: 0
      [1] entities: 0
      [2] entities: 1
      [3] entities: 0
    sparse_set:
      ComponentId(8)(world_diagnostic::HighlightFlag) entity: 1
Schedule:
  schedules: 1
    label: Bar kind:SingleThreaded
  hierarchy:
    nodes:
      Set(6)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::second_system>()))
      Set(5)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::first_system>()))
      Set(4)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::Res<world_diagnostic::GameState>, bevy_ecs::system::query::Query<&mut world_diagnostic::Counter>), world_diagnostic::sync_counter>()))
      System(2)(world_diagnostic::sync_counter)
      Set(3)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::ResMut<world_diagnostic::GameState>), world_diagnostic::increase_game_state_count>()))
      Set(2)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::empty_system>()))
      Set(1)(Set2)
      System(4)(world_diagnostic::second_system)
      System(3)(world_diagnostic::first_system)
      Set(0)(Set1)
      System(1)(world_diagnostic::increase_game_state_count)
      System(0)(world_diagnostic::empty_system)
    edges:
      Set(3)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::ResMut<world_diagnostic::GameState>), world_diagnostic::increase_game_state_count>())) -> System(1)(world_diagnostic::increase_game_state_count)
      Set(1)(Set2) -> System(4)(world_diagnostic::second_system)
      Set(5)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::first_system>())) -> System(3)(world_diagnostic::first_system)
      Set(6)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::second_system>())) -> System(4)(world_diagnostic::second_system)
      Set(1)(Set2) -> System(3)(world_diagnostic::first_system)
      Set(0)(Set1) -> System(1)(world_diagnostic::increase_game_state_count)
      Set(4)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::Res<world_diagnostic::GameState>, bevy_ecs::system::query::Query<&mut world_diagnostic::Counter>), world_diagnostic::sync_counter>())) -> System(2)(world_diagnostic::sync_counter)
      Set(2)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::empty_system>())) -> System(0)(world_diagnostic::empty_system)
      Set(0)(Set1) -> System(0)(world_diagnostic::empty_system)
    topsorted:
      Set(6)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::second_system>()))
      Set(5)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::first_system>()))
      Set(4)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::Res<world_diagnostic::GameState>, bevy_ecs::system::query::Query<&mut world_diagnostic::Counter>), world_diagnostic::sync_counter>()))
      System(2)(world_diagnostic::sync_counter)
      Set(3)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::ResMut<world_diagnostic::GameState>), world_diagnostic::increase_game_state_count>()))
      Set(2)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::empty_system>()))
      Set(1)(Set2)
      System(4)(world_diagnostic::second_system)
      System(3)(world_diagnostic::first_system)
      Set(0)(Set1)
      System(1)(world_diagnostic::increase_game_state_count)
      System(0)(world_diagnostic::empty_system)
  dependency:
    nodes:
      Set(0)(Set1)
      Set(1)(Set2)
      System(0)(world_diagnostic::empty_system)
      Set(2)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::empty_system>()))
      System(1)(world_diagnostic::increase_game_state_count)
      Set(3)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::ResMut<world_diagnostic::GameState>), world_diagnostic::increase_game_state_count>()))
      Set(4)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::Res<world_diagnostic::GameState>, bevy_ecs::system::query::Query<&mut world_diagnostic::Counter>), world_diagnostic::sync_counter>()))
      System(2)(world_diagnostic::sync_counter)
      System(3)(world_diagnostic::first_system)
      Set(5)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::first_system>()))
      Set(6)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::second_system>()))
      System(4)(world_diagnostic::second_system)
    edges:
      System(1)(world_diagnostic::increase_game_state_count) -> Set(4)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::Res<world_diagnostic::GameState>, bevy_ecs::system::query::Query<&mut world_diagnostic::Counter>), world_diagnostic::sync_counter>()))
      System(3)(world_diagnostic::first_system) -> Set(6)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::second_system>()))
    topsorted:
      System(4)(world_diagnostic::second_system)
      Set(5)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::first_system>()))
      System(3)(world_diagnostic::first_system)
      Set(6)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::second_system>()))
      System(2)(world_diagnostic::sync_counter)
      Set(3)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::ResMut<world_diagnostic::GameState>), world_diagnostic::increase_game_state_count>()))
      System(1)(world_diagnostic::increase_game_state_count)
      Set(4)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(bevy_ecs::change_detection::Res<world_diagnostic::GameState>, bevy_ecs::system::query::Query<&mut world_diagnostic::Counter>), world_diagnostic::sync_counter>()))
      Set(2)(SystemTypeSet(fn bevy_ecs::system::function_system::FunctionSystem<fn(), world_diagnostic::empty_system>()))
      System(0)(world_diagnostic::empty_system)
      Set(1)(Set2)
      Set(0)(Set1)
  dependency flatten:
    nodes:
      System(4)(world_diagnostic::second_system)
      System(3)(world_diagnostic::first_system)
      System(0)(world_diagnostic::empty_system)
      System(2)(world_diagnostic::sync_counter)
      System(1)(world_diagnostic::increase_game_state_count)
    edges:
      System(1)(world_diagnostic::increase_game_state_count) -> System(2)(world_diagnostic::sync_counter)
      System(3)(world_diagnostic::first_system) -> System(4)(world_diagnostic::second_system)
    topsorted:
      System(1)(world_diagnostic::increase_game_state_count)
      System(2)(world_diagnostic::sync_counter)
      System(0)(world_diagnostic::empty_system)
      System(3)(world_diagnostic::first_system)
      System(4)(world_diagnostic::second_system)

[Carter0]

It might be good to elaborate more on this. For example, what diagnostic info do we get and why is this useful to see?

[Carter0]

I mostly get the functionality. I think the docs could use some work. But maybe that can be done in a different PR? Ill approve.

[Carter0]

You might want to add some PR tags like ‘needs review’ and then request some people like Alice to see it if you can.

That way other people can find it easier

[AlephCubed]

You might want to add some PR tags like ‘needs review’ and then request some people like Alice to see it if you can.

I don't think I have permission to do either of those, unless I am missing something.

[alice-i-cecile]

So, there's three parts to this:

1. The Bundles helper method. Great, love these. Please split them out into their own PR and we can merge them.
2. The example. This is... kind of meandering and poorly written, and has a hard time communicating how the user might use these APIs and others to investigate the state of the world. The name is not great, and it should not live in the bevy_ecs examples.
3. The methods themselves. I think the diagnose terminology is really unclear, and the "turn something into a string for the users" is an anti-pattern. We should return useful structured objects, which the users can then turn into a string on their own.

I really want better tools for investigating the state of the world and schedules holistically, but this needs to be better executed.

[AlephCubed]

Yeah the strings did feel a little weird to work with. I'll look into adding a more structured way to view the world state.