Add warning when a hierarchy component is missing

A common pitfall since 0.8 is the requirement on `ComputedVisibility`
being present on all ancestors of an entity that itself has
`ComputedVisibility`, without which, the entity becomes invisible.

I myself hit the issue and got very confused, and saw a few people hit
it as well, so it makes sense to provide a hint of what to do when such
a situation is encountered.

We now check that all entities with both a `Parent` and a
`ComputedVisibility` component have parents that themselves have a
`ComputedVisibility` component.

Note that the warning is only printed once.

We also add a similar warning to `GlobalTransform`.

This only emits a warning. Because sometimes it could be an intended
behavior.

Alternatives:
- Do nothing and keep repeating to newcomers how to avoid recurring
  pitfalls
- Make the transform and visibility propagations tolerant to missing
  components

Author: nicopap

crates/bevy_hierarchy/Cargo.toml

@@ -14,7 +14,9 @@ trace = []
 [dependencies]
 # bevy
 bevy_app = { path = "../bevy_app", version = "0.9.0-dev" }
+bevy_core = { path = "../bevy_core", version = "0.9.0-dev" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.9.0-dev", features = ["bevy_reflect"] }
+bevy_log = { path = "../bevy_log", version = "0.9.0-dev" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.9.0-dev", features = ["bevy"] }
 bevy_utils = { path = "../bevy_utils", version = "0.9.0-dev" }
 

crates/bevy_hierarchy/src/lib.rs

@@ -16,10 +16,15 @@ pub use child_builder::*;
 mod events;
 pub use events::*;
 
+mod valid_parent_check_plugin;
+pub use valid_parent_check_plugin::*;
+
 #[doc(hidden)]
 pub mod prelude {
     #[doc(hidden)]
-    pub use crate::{child_builder::*, components::*, hierarchy::*, HierarchyPlugin};
+    pub use crate::{
+        child_builder::*, components::*, hierarchy::*, HierarchyPlugin, ValidParentCheckPlugin,
+    };
 }
 
 use bevy_app::prelude::*;

crates/bevy_hierarchy/src/valid_parent_check_plugin.rs

@@ -0,0 +1,59 @@
+use std::marker::PhantomData;
+
+use bevy_app::{App, CoreStage, Plugin};
+use bevy_core::Name;
+use bevy_ecs::prelude::*;
+use bevy_log::warn;
+use bevy_utils::{get_short_name, HashSet};
+
+use crate::Parent;
+
+/// System to print a warning for each `Entity` with a `T` component
+/// which parent hasn't a `T` component.
+///
+/// Hierarchy propagations are top-down, and limited only to entities
+/// with a specific component (such as `ComputedVisibility` and `GlobalTransform`).
+/// This means that entities with one of those component
+/// and a parent without the same component is probably a programming error.
+/// (See B0004 explanation linked in warning message)
+pub fn check_hierarchy_component_has_valid_parent<T: Component>(
+    parent_query: Query<
+        (Entity, &Parent, Option<&Name>),
+        (With<T>, Or<(Changed<Parent>, Added<T>)>),
+    >,
+    component_query: Query<(), With<T>>,
+    mut already_diagnosed: Local<HashSet<Entity>>,
+) {
+    for (entity, parent, name) in &parent_query {
+        let parent = parent.get();
+        if !component_query.contains(parent) && !already_diagnosed.contains(&entity) {
+            already_diagnosed.insert(entity);
+            warn!(
+                "warning[B0004]: {name} with the {ty_name} component has a parent without {ty_name}.\n\
+                This will cause inconsistent behaviors! See https://bevyengine.org/learn/errors/#B0004",
+                ty_name = get_short_name(std::any::type_name::<T>()),
+                name = name.map_or("An entity".to_owned(), |s| format!("The {s} entity")),
+            );
+        }
+    }
+}
+
+/// Print a warning for each `Entity` with a `T` component
+/// which parent hasn't a `T` component.
+///
+/// See [`check_hierarchy_component_has_valid_parent`] for details.
+pub struct ValidParentCheckPlugin<T>(PhantomData<fn() -> T>);
+impl<T: Component> Default for ValidParentCheckPlugin<T> {
+    fn default() -> Self {
+        Self(PhantomData)
+    }
+}
+
+impl<T: Component> Plugin for ValidParentCheckPlugin<T> {
+    fn build(&self, app: &mut App) {
+        app.add_system_to_stage(
+            CoreStage::Last,
+            check_hierarchy_component_has_valid_parent::<T>,
+        );
+    }
+}

crates/bevy_internal/src/default_plugins.rs

@@ -35,6 +35,11 @@ impl PluginGroup for DefaultPlugins {
         group.add(bevy_input::InputPlugin::default());
         group.add(bevy_window::WindowPlugin::default());
 
+        #[cfg(debug_assertions)]
+        group.add(bevy_hierarchy::ValidParentCheckPlugin::<
+            crate::prelude::GlobalTransform,
+        >::default());
+
         #[cfg(feature = "bevy_asset")]
         group.add(bevy_asset::AssetPlugin::default());
 
@@ -50,6 +55,11 @@ impl PluginGroup for DefaultPlugins {
         #[cfg(feature = "bevy_render")]
         group.add(bevy_render::RenderPlugin::default());
 
+        #[cfg(all(feature = "bevy_render", debug_assertions))]
+        group.add(bevy_hierarchy::ValidParentCheckPlugin::<
+            crate::prelude::ComputedVisibility,
+        >::default());
+
         #[cfg(feature = "bevy_core_pipeline")]
         group.add(bevy_core_pipeline::CorePipelinePlugin::default());
 

errors/B0004.md

@@ -0,0 +1,112 @@
+# B0004
+
+A runtime warning.
+
+An [`Entity`] with a hierarchy-inherited component has a [`Parent`]
+without the hierarchy-inherited component in question.
+
+The hierarchy-inherited components are:
+
+- [`ComputedVisibility`]
+- [`GlobalTransform`]
+
+For example, the following code will cause a warning to be emitted:
+
+```rust,no_run
+use bevy::prelude::*;
+
+// WARNING: this code is buggy
+fn setup_cube(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) {
+    commands
+        .spawn_bundle(TransformBundle::default())
+        .with_children(|parent| {
+            // cube
+            parent.spawn_bundle(PbrBundle {
+                mesh: meshes.add(Mesh::from(shape::Cube { size: 1.0 })),
+                material: materials.add(Color::rgb(0.8, 0.7, 0.6).into()),
+                transform: Transform::from_xyz(0.0, 0.5, 0.0),
+                ..default()
+            });
+        });
+
+    // camera
+    commands.spawn_bundle(Camera3dBundle {
+        transform: Transform::from_xyz(-2.0, 2.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
+        ..default()
+    });
+}
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_startup_system(setup_cube)
+        .run();
+}
+```
+
+This code **will not** show a cube on screen.
+This is because the entity spawned with `commands.spawn_bundle(…)`
+doesn't have a [`ComputedVisibility`] component.
+Since the cube is spawned as a child of an entity without the
+[`ComputedVisibility`] component, it will not be visible at all.
+
+To fix this, you must use [`SpatialBundle`] over [`TransformBundle`],
+as follow:
+
+```rust,no_run
+use bevy::prelude::*;
+
+fn setup_cube(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) {
+    commands
+        // We use SpatialBundle instead of TransformBundle, it contains the
+        // ComputedVisibility component needed to display the cube,
+        // In addition to the Transform and GlobalTransform components.
+        .spawn_bundle(SpatialBundle::default())
+        .with_children(|parent| {
+            // cube
+            parent.spawn_bundle(PbrBundle {
+                mesh: meshes.add(Mesh::from(shape::Cube { size: 1.0 })),
+                material: materials.add(Color::rgb(0.8, 0.7, 0.6).into()),
+                transform: Transform::from_xyz(0.0, 0.5, 0.0),
+                ..default()
+            });
+        });
+
+    // camera
+    commands.spawn_bundle(Camera3dBundle {
+        transform: Transform::from_xyz(-2.0, 2.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
+        ..default()
+    });
+}
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_startup_system(setup_cube)
+        .run();
+}
+```
+
+A similar problem occurs when the [`GlobalTransform`] component is missing.
+However, when a parent [`GlobalTransform`] is missing,
+it will simply prevent all transform propagation,
+including when updating the [`Transform`] component of the child.
+
+You will most likely encouter this warning when loading a scene
+as a child of a pre-existing [`Entity`] that does not have the proper components.
+
+[`ComputedVisibility`]: https://docs.rs/bevy/*/bevy/render/view/struct.ComputedVisibility.html
+[`GlobalTransform`]: https://docs.rs/bevy/*/bevy/transform/components/struct.GlobalTransform.html
+[`Transform`]: https://docs.rs/bevy/*/bevy/transform/components/struct.Transform.html
+[`Parent`]: https://docs.rs/bevy/*/bevy/hierarchy/struct.Parent.html
+[`Entity`]: https://docs.rs/bevy/*/bevy/ecs/entity/struct.Entity.html
+[`SpatialBundle`]: https://docs.rs/bevy/*/bevy/render/prelude/struct.SpatialBundle.html
+[`TransformBundle`]: https://docs.rs/bevy/*/bevy/transform/struct.TransformBundle.html

errors/src/lib.rs

@@ -6,3 +6,6 @@ pub struct B0002;
 
 #[doc = include_str!("../B0003.md")]
 pub struct B0003;
+
+#[doc = include_str!("../B0004.md")]
+pub struct B0004;