Improve bevy_ecs inspectability and add debugging methods.

crates/bevy_ecs/Cargo.toml

@@ -153,6 +153,10 @@ path = "examples/resources.rs"
 name = "change_detection"
 path = "examples/change_detection.rs"
 
+[[example]]
+name = "world_diagnostic"
+path = "examples/world_diagnostic.rs"
+
 [lints]
 workspace = true
 

crates/bevy_ecs/examples/world_diagnostic.rs

@@ -0,0 +1,123 @@
+//! In this example, we use a system to print diagnostic information about the world.
+//!
+//! This includes information about which components, bundles, and systems are registered,
+//! as well as the order that systems will run in.
+
+#![expect(
+    missing_docs,
+    reason = "Trivial example types do not require documentation."
+)]
+
+use bevy_ecs::prelude::*;
+use bevy_ecs_macros::{ScheduleLabel, SystemSet};
+
+fn empty_system() {}
+
+fn first_system() {}
+
+fn second_system() {}
+
+fn increase_game_state_count(mut state: ResMut<GameState>) {
+    state.counter += 1;
+}
+
+fn sync_counter(state: Res<GameState>, mut query: Query<&mut Counter>) {
+    for mut counter in query.iter_mut() {
+        counter.0 = state.counter;
+    }
+}
+
+#[derive(Resource, Default)]
+struct GameState {
+    counter: usize,
+}
+
+#[derive(SystemSet, Hash, Clone, Copy, PartialEq, Eq, Debug)]
+enum MySet {
+    Set1,
+    Set2,
+}
+
+#[derive(Component)]
+struct Counter(usize);
+
+#[derive(Component)]
+struct Player;
+
+#[derive(Component)]
+#[component(storage = "SparseSet")]
+struct HighlightFlag;
+
+#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+pub enum ScheduleLabel {
+    Foo,
+    Bar,
+}
+
+/// A special label for diagnostic.
+/// If a system has a commonly used label, like [`bevy_app::CoreSchedule`] it is not able to get
+/// the corresponding [`Schedule`] instance and can't be inspected.
+#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct DiagnosticLabel;
+
+/// World diagnostic example.
+fn diagnostic_world_system(world: &mut World) {
+    println!("{}", world.diagnose_with_flattened().unwrap());
+}
+
+// If you do not have mutable access, you can also use [`World::diagnose`].
+// This version will not include a flattened representation.
+//
+// fn diagnostic_world_system(world: &World) {
+//     println!("{}", world.diagnose().unwrap());
+// }
+
+// In this example, we add a counter resource and increase its value in one system,
+// while a different system prints debug information about the world.
+fn main() {
+    let mut world = World::new();
+    world.init_resource::<Schedules>();
+
+    {
+        let mut diagnostic_schedule = Schedule::new(DiagnosticLabel);
+        diagnostic_schedule.add_systems(diagnostic_world_system);
+        world.add_schedule(diagnostic_schedule);
+    }
+
+    let mut schedule = Schedule::new(ScheduleLabel::Bar);
+    schedule.configure_sets((MySet::Set1, MySet::Set2));
+
+    schedule.add_systems(empty_system.in_set(MySet::Set1));
+    schedule.add_systems(
+        increase_game_state_count
+            .in_set(MySet::Set1)
+            .before(sync_counter),
+    );
+    schedule.add_systems(sync_counter);
+    schedule.add_systems(first_system.before(second_system).in_set(MySet::Set2));
+    schedule.add_systems(second_system.in_set(MySet::Set2));
+    world.add_schedule(schedule);
+
+    world.init_resource::<GameState>();
+
+    world.run_schedule(ScheduleLabel::Bar);
+    world.run_schedule(DiagnosticLabel);
+
+    let player = world.spawn(Player).id();
+    // Create an archetype with one table component and one sparse set.
+    world.spawn((Counter(1), HighlightFlag));
+    world.run_schedule(ScheduleLabel::Bar);
+    world.run_schedule(DiagnosticLabel);
+
+    world.entity_mut(player).insert(Counter(100));
+    world.run_schedule(ScheduleLabel::Bar);
+    world.run_schedule(DiagnosticLabel);
+
+    world.entity_mut(player).insert(HighlightFlag);
+    world.run_schedule(ScheduleLabel::Bar);
+    world.run_schedule(DiagnosticLabel);
+
+    world.entity_mut(player).despawn();
+    world.run_schedule(ScheduleLabel::Bar);
+    world.run_schedule(DiagnosticLabel);
+}

crates/bevy_ecs/src/bundle.rs

@@ -1473,6 +1473,21 @@ pub struct Bundles {
 }
 
 impl Bundles {
+    /// The total number of [`Bundle`] registered in [`Storages`].
+    pub fn len(&self) -> usize {
+        self.bundle_infos.len()
+    }
+
+    /// Returns true if no [`Bundle`] registered in [`Storages`].
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// Iterate over [`BundleInfo`].
+    pub fn iter(&self) -> impl Iterator<Item = &BundleInfo> {
+        self.bundle_infos.iter()
+    }
+
     /// Gets the metadata associated with a specific type of bundle.
     /// Returns `None` if the bundle is not registered with the world.
     #[inline]

crates/bevy_ecs/src/component.rs

@@ -13,7 +13,7 @@ use crate::{
 };
 #[cfg(feature = "bevy_reflect")]
 use alloc::boxed::Box;
-use alloc::{borrow::Cow, format, vec::Vec};
+use alloc::{borrow::Cow, format, string::String, vec::Vec};
 pub use bevy_ecs_macros::Component;
 use bevy_platform_support::sync::Arc;
 use bevy_ptr::{OwningPtr, UnsafeCellDeref};
@@ -855,6 +855,12 @@ impl ComponentId {
     pub fn index(self) -> usize {
         self.0
     }
+
+    /// Returns a string containing information about the component in the context of the given [World].
+    pub fn diagnose(self, world: &World) -> String {
+        let component = world.components().get_info(self).unwrap();
+        format!("{:?}({})", self, component.name())
+    }
 }
 
 impl SparseSetIndex for ComponentId {

crates/bevy_ecs/src/schedule/schedule.rs

@@ -3,6 +3,7 @@
     reason = "This instance of module inception is being discussed; see #17344."
 )]
 use alloc::{
+    borrow::Cow,
     boxed::Box,
     collections::BTreeSet,
     format,
@@ -211,6 +212,83 @@ impl Schedules {
 
         self
     }
+
+    /// Returns a string containing information about the systems.
+    pub fn diagnose(&self) -> Result<String, core::fmt::Error> {
+        let mut result = "Schedule:\n".to_string();
+
+        let label_with_schedules = self.iter().collect::<Vec<_>>();
+        writeln!(result, "  schedules: {}", label_with_schedules.len())?;
+
+        for (label, schedule) in label_with_schedules {
+            let mut id_to_names = HashMap::<NodeId, Cow<'static, str>>::default();
+            schedule.systems_for_each(|node_id, system| {
+                id_to_names.insert(node_id, system.name());
+            });
+            for (node_id, set, _) in schedule.graph().system_sets() {
+                id_to_names.insert(node_id, format!("{:?}", set).into());
+            }
+
+            writeln!(
+                result,
+                "    label: {:?} kind:{:?}",
+                label,
+                schedule.get_executor_kind(),
+            )?;
+
+            let schedule_graph = schedule.graph();
+
+            writeln!(
+                result,
+                "{}",
+                schedule_graph
+                    .hierarchy()
+                    .diagnose("  ", "hierarchy", &id_to_names)?
+                    .trim_end()
+            )?;
+
+            writeln!(
+                result,
+                "{}",
+                schedule_graph
+                    .dependency()
+                    .diagnose("  ", "dependency", &id_to_names)?
+                    .trim_end()
+            )?;
+        }
+
+        Ok(result)
+    }
+
+    /// Returns a string containing information about the systems, including flattened representation.
+    pub fn diagnose_flattened(&mut self) -> Result<String, core::fmt::Error> {
+        let mut result = self.diagnose()?;
+
+        let label_with_schedules = self.iter_mut().collect::<Vec<_>>();
+
+        for (_, schedule) in label_with_schedules {
+            let mut id_to_names = HashMap::<NodeId, Cow<'static, str>>::default();
+            schedule.systems_for_each(|node_id, system| {
+                id_to_names.insert(node_id, system.name());
+            });
+            for (node_id, set, _) in schedule.graph().system_sets() {
+                id_to_names.insert(node_id, format!("{:?}", set).into());
+            }
+
+            let schedule_graph = &mut schedule.graph;
+
+            writeln!(
+                result,
+                "{}",
+                schedule_graph
+                    .dependency_flatten()
+                    .diagnose("  ", "dependency flatten", &id_to_names,)?
+                    .trim_end()
+            )?;
+        }
+
+        Ok(result)
+    }
 }
 
 fn make_executor(kind: ExecutorKind) -> Box<dyn SystemExecutor> {
@@ -346,6 +424,27 @@ impl Schedule {
         self
     }
 
+    /// Call function `f` on each pair of ([`NodeId`], [`ScheduleSystem`]).
+    fn systems_for_each(&self, mut f: impl FnMut(NodeId, &ScheduleSystem)) {
+        match self.executor_initialized {
+            true => {
+                for (id, system) in self
+                    .executable
+                    .system_ids
+                    .iter()
+                    .zip(self.executable.systems.iter())
+                {
+                    f(*id, system);
+                }
+            }
+            false => {
+                for (node_id, system, _) in self.graph.systems() {
+                    f(node_id, system);
+                }
+            }
+        }
+    }
+
     /// Configures a collection of system sets in this schedule, adding them if they does not exist.
     #[track_caller]
     pub fn configure_sets(&mut self, sets: impl IntoSystemSetConfigs) -> &mut Self {
@@ -552,6 +651,41 @@ impl Dag {
     pub fn cached_topsort(&self) -> &[NodeId] {
         &self.topsort
     }
+
+    /// Returns a string containing node and edge information about the [`Dag`].
+    pub fn diagnose(
+        &self,
+        prefix: &str,
+        name: &str,
+        id_to_names: &HashMap<NodeId, Cow<'static, str>>,
+    ) -> Result<String, core::fmt::Error> {
+        let mut result = String::new();
+        writeln!(result, "{prefix}{name}:")?;
+
+        writeln!(result, "{prefix}  nodes:")?;
+        for node_id in self.graph().nodes() {
+            let name = id_to_names.get(&node_id).unwrap();
+            writeln!(result, "{prefix}    {node_id:?}({name})")?;
+        }
+
+        writeln!(result, "{prefix}  edges:")?;
+        for (l, r) in self.graph().all_edges() {
+            let l_name = id_to_names.get(&l).unwrap();
+            let r_name = id_to_names.get(&r).unwrap();
+            writeln!(result, "{prefix}    {l:?}({l_name}) -> {r:?}({r_name})")?;
+        }
+
+        writeln!(result, "{prefix}  topsorted:")?;
+        for (node_id, node_name) in self
+            .cached_topsort()
+            .iter()
+            .map(|node_id| (node_id, id_to_names.get(node_id).unwrap()))
+        {
+            writeln!(result, "{prefix}    {node_id:?}({node_name})")?;
+        }
+
+        Ok(result)
+    }
 }
 
 /// A [`SystemSet`] with metadata, stored in a [`ScheduleGraph`].
@@ -737,6 +871,22 @@ impl ScheduleGraph {
         &self.dependency
     }
 
+    /// Returns the [`Dag`] of the flattened dependencies in the schedule.
+    ///
+    /// Nodes in this graph are systems and sets, and edges denote that
+    /// a system or set has to run before another system or set.
+    pub fn dependency_flatten(&mut self) -> Dag {
+        let (set_systems, _) =
+            self.map_sets_to_systems(&self.hierarchy.topsort, &self.hierarchy.graph);
+        let dependency_flattened = self.get_dependency_flattened(&set_systems);
+        Dag {
+            topsort: self
+                .topsort_graph(&dependency_flattened, ReportCycles::Dependency)
+                .unwrap(),
+            graph: dependency_flattened,
+        }
+    }
+
     /// Returns the list of systems that conflict with each other, i.e. have ambiguities in their access.
     ///
     /// If the `Vec<ComponentId>` is empty, the systems conflict on [`World`] access.