Improve `bevy_ecs` inspectability and add debugging methods. #17331

AlephCubed · 2025-01-12T19:28:30Z

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)

…or diagnostic

Example still doesn't work, but it's a start.

…adopted-conflict

…tened

…adopted-conflict

crates/bevy_ecs/examples/world_diagnostic.rs

Carter0 · 2025-01-19T21:53:19Z

crates/bevy_ecs/examples/world_diagnostic.rs

@@ -0,0 +1,115 @@
+//! In this example, we use a system to print diagnostic information about the world.


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

crates/bevy_ecs/src/schedule/schedule.rs

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.

Co-authored-by: Carter Weinberg <[email protected]>

Carter0 · 2025-01-19T23:43:07Z

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 · 2025-01-20T00:33:38Z

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.

shuoli84 and others added 26 commits February 20, 2023 12:13

Add len, iter on Bundles, add an example to show how to inspect a world

eca5de6

Add schedule diagnostic example

cb8f377

fix clippy, remove unused code

47f0860

add a note explain why need a special label

f951e57

clippy

4505730

fix index mismatch between graph and executor. return a string repr f…

a16f720

…or diagnostic

fix clippy. add more details in diagnostic

81802d7

fix clippy

81d22ed

Merge branch 'main' into ecs-inspectability-adopted-conflict

bddb539

Fixed CI not passing.

54b046c

Example still doesn't work, but it's a start.

Updated schedule label code in example.

14578c1

Merge branch 'bevyengine:main' into ecs-inspectability-adopted-conflict

dc34cd4

Fix spelling mistakes + format.

8619f8b

Replaced component_display with ComponentId::diagnose.

d14d70a

Replaced diagnose_dag with Dag::diagnose.

5a9b6a7

Replaced diagnostic_schedules with Schedules::diagnose.

9d5bb88

Replaced diagnostic_world with World::diagnose.

51b3098

Added Systems::diagnose_flattened.

159e607

Added World::diagnose_with_flattened.

a852d28

Replaced "".to_string() with String::new().

d891ef5

Merge remote-tracking branch 'upstream/main' into ecs-inspectability-…

84e29f1

…adopted-conflict

Merge branch 'ecs-inspectability-adopted-conflict' into diagnose-flat…

80e5e11

…tened

Fix CI not passing due to new requirements.

4f70216

Merge branch 'ecs-inspectability-adopted-conflict' into diagnose-flat…

3ae2ae7

…tened

Final Cleanup.

9177b0f

Merge remote-tracking branch 'upstream/main' into ecs-inspectability-…

fa75f6f

…adopted-conflict

AlephCubed marked this pull request as ready for review January 18, 2025 19:34

Carter0 reviewed Jan 19, 2025

View reviewed changes

crates/bevy_ecs/examples/world_diagnostic.rs Outdated Show resolved Hide resolved

Carter0 reviewed Jan 19, 2025

View reviewed changes

crates/bevy_ecs/examples/world_diagnostic.rs Outdated Show resolved Hide resolved

Carter0 reviewed Jan 19, 2025

View reviewed changes

crates/bevy_ecs/src/schedule/schedule.rs Outdated Show resolved Hide resolved

Carter0 reviewed Jan 19, 2025

View reviewed changes

crates/bevy_ecs/src/schedule/schedule.rs Outdated Show resolved Hide resolved

Carter0 approved these changes Jan 19, 2025

View reviewed changes

AlephCubed and others added 3 commits January 19, 2025 14:24

Added more documentation and comments to example.

cb6611b

Update doc comment for Dag::diagnose.

644ab19

Co-authored-by: Carter Weinberg <[email protected]>

Made Schedule::systems_for_each private.

03e0276

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve `bevy_ecs` inspectability and add debugging methods. #17331

Improve `bevy_ecs` inspectability and add debugging methods. #17331

AlephCubed commented Jan 12, 2025 •

edited

Loading

Carter0 Jan 19, 2025

Carter0 left a comment

Carter0 commented Jan 19, 2025

AlephCubed commented Jan 20, 2025

		@@ -0,0 +1,115 @@
		//! In this example, we use a system to print diagnostic information about the world.

Improve bevy_ecs inspectability and add debugging methods. #17331

Are you sure you want to change the base?

Improve bevy_ecs inspectability and add debugging methods. #17331

Conversation

AlephCubed commented Jan 12, 2025 • edited Loading

Solution

Example output:

Carter0 Jan 19, 2025

Choose a reason for hiding this comment

Carter0 left a comment

Choose a reason for hiding this comment

Carter0 commented Jan 19, 2025

AlephCubed commented Jan 20, 2025

Improve `bevy_ecs` inspectability and add debugging methods. #17331

Improve `bevy_ecs` inspectability and add debugging methods. #17331

AlephCubed commented Jan 12, 2025 •

edited

Loading