Split bevy_hierarchy out from bevy_transform (#4168)

# Objective

- Hierarchy tools are not just used for `Transform`: they are also used for scenes.
- In the future there's interest in using them for other features, such as visiibility inheritance.
- The fact that these tools are found in `bevy_transform` causes a great deal of user and developer confusion
- Fixes #2758.

## Solution

- Split `bevy_transform` into two!
- Make everything work again.

Note that this is a very tightly scoped PR: I *know* there are code quality and docs issues that existed in bevy_transform that I've just moved around. We should fix those in a seperate PR and try to merge this ASAP to reduce the bitrot involved in splitting an entire crate.

## Frustrations

The API around `GlobalTransform` is a mess: we have massive code and docs duplication, no link between the two types and no clear way to extend this to other forms of inheritance.

In the medium-term, I feel pretty strongly that `GlobalTransform` should be replaced by something like `Inherited<Transform>`, which lives in `bevy_hierarchy`:

- avoids code duplication
- makes the inheritance pattern extensible
- links the types at the type-level
- allows us to remove all references to inheritance from `bevy_transform`, making it more useful as a standalone crate and cleaning up its docs

## Additional context

- double-blessed by @cart in #4141 (comment) and #2758 (comment)
- preparation for more advanced / cleaner hierarchy tools: go read bevyengine/rfcs#53 !
- originally attempted by @finegeometer in #2789. It was a great idea, just needed more discussion!

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

Author: alice-i-cecile

crates/bevy_gltf/Cargo.toml

@@ -14,6 +14,7 @@ bevy_app = { path = "../bevy_app", version = "0.6.0" }
 bevy_asset = { path = "../bevy_asset", version = "0.6.0" }
 bevy_core = { path = "../bevy_core", version = "0.6.0" }
 bevy_ecs = { path = "../bevy_ecs", version = "0.6.0" }
+bevy_hierarchy = { path = "../bevy_hierarchy", version = "0.6.0" }
 bevy_pbr = { path = "../bevy_pbr", version = "0.6.0" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.6.0", features = ["bevy"] }
 bevy_render = { path = "../bevy_render", version = "0.6.0" }

crates/bevy_gltf/src/loader.rs

@@ -4,6 +4,7 @@ use bevy_asset::{
 };
 use bevy_core::Name;
 use bevy_ecs::world::World;
+use bevy_hierarchy::{BuildWorldChildren, WorldChildBuilder};
 use bevy_log::warn;
 use bevy_math::{Mat4, Vec3};
 use bevy_pbr::{
@@ -24,11 +25,8 @@ use bevy_render::{
     view::VisibleEntities,
 };
 use bevy_scene::Scene;
-use bevy_transform::{
-    hierarchy::{BuildWorldChildren, WorldChildBuilder},
-    prelude::Transform,
-    TransformBundle,
-};
+use bevy_transform::{components::Transform, TransformBundle};
+
 use bevy_utils::{HashMap, HashSet};
 use gltf::{
     mesh::Mode,

crates/bevy_hierarchy/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "bevy_hierarchy"
+version = "0.6.0"
+edition = "2021"
+description = "Provides hierarchy functionality for Bevy Engine"
+homepage = "https://bevyengine.org"
+repository = "https://github.com/bevyengine/bevy"
+license = "MIT OR Apache-2.0"
+keywords = ["bevy"]
+
+[dependencies]
+# bevy
+bevy_app = { path = "../bevy_app", version = "0.6.0" }
+bevy_ecs = { path = "../bevy_ecs", version = "0.6.0", features = ["bevy_reflect"] }
+bevy_reflect = { path = "../bevy_reflect", version = "0.6.0", features = ["bevy"] }
+bevy_utils = { path = "../bevy_utils", version = "0.6.0" }
+
+# other
+smallvec = { version = "1.6", features = ["serde", "union", "const_generics"] }

crates/bevy_transform/src/hierarchy/child_builder.rs renamed to crates/bevy_hierarchy/src/child_builder.rs

@@ -0,0 +1,5 @@
+mod children;
+mod parent;
+
+pub use children::Children;
+pub use parent::{Parent, PreviousParent};

crates/bevy_transform/src/components/children.rs renamed to crates/bevy_hierarchy/src/components/children.rs

@@ -116,7 +116,7 @@ mod tests {
     };
 
     use super::DespawnRecursiveExt;
-    use crate::{components::Children, hierarchy::BuildChildren};
+    use crate::{child_builder::BuildChildren, components::Children};
 
     #[derive(Component, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Debug)]
     struct Idx(u32);

crates/bevy_hierarchy/src/components/mod.rs

@@ -0,0 +1,53 @@
+#![warn(missing_docs)]
+//! `bevy_hierarchy` can be used to define hierarchies of entities.
+//!
+//! Most commonly, these hierarchies are used for inheriting `Transform` values
+//! from the [`Parent`] to its [`Children`].
+
+mod components;
+pub use components::*;
+
+mod hierarchy;
+pub use hierarchy::*;
+
+mod child_builder;
+pub use child_builder::*;
+
+mod systems;
+pub use systems::*;
+
+#[doc(hidden)]
+pub mod prelude {
+    #[doc(hidden)]
+    pub use crate::{child_builder::*, components::*, hierarchy::*, HierarchyPlugin};
+}
+
+use bevy_app::prelude::*;
+use bevy_ecs::prelude::*;
+
+/// The base plugin for handling [`Parent`] and [`Children`] components
+#[derive(Default)]
+pub struct HierarchyPlugin;
+
+/// Label enum for the systems relating to hierarchy upkeep
+#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemLabel)]
+pub enum HierarchySystem {
+    /// Updates [`Parent`] when changes in the hierarchy occur
+    ParentUpdate,
+}
+
+impl Plugin for HierarchyPlugin {
+    fn build(&self, app: &mut App) {
+        app.register_type::<Children>()
+            .register_type::<Parent>()
+            .register_type::<PreviousParent>()
+            .add_startup_system_to_stage(
+                StartupStage::PostStartup,
+                parent_update_system.label(HierarchySystem::ParentUpdate),
+            )
+            .add_system_to_stage(
+                CoreStage::PostUpdate,
+                parent_update_system.label(HierarchySystem::ParentUpdate),
+            );
+    }
+}

crates/bevy_transform/src/components/parent.rs renamed to crates/bevy_hierarchy/src/components/parent.rs

@@ -70,101 +70,3 @@ pub fn parent_update_system(
         commands.entity(*e).insert(Children::with(v));
     });
 }
-#[cfg(test)]
-mod test {
-    use bevy_ecs::{
-        schedule::{Schedule, Stage, SystemStage},
-        system::CommandQueue,
-        world::World,
-    };
-
-    use super::*;
-    use crate::{hierarchy::BuildChildren, transform_propagate_system::transform_propagate_system};
-
-    #[test]
-    fn correct_children() {
-        let mut world = World::default();
-
-        let mut update_stage = SystemStage::parallel();
-        update_stage.add_system(parent_update_system);
-        update_stage.add_system(transform_propagate_system);
-
-        let mut schedule = Schedule::default();
-        schedule.add_stage("update", update_stage);
-
-        // Add parent entities
-        let mut command_queue = CommandQueue::default();
-        let mut commands = Commands::new(&mut command_queue, &world);
-        let mut children = Vec::new();
-        let parent = commands
-            .spawn()
-            .insert(Transform::from_xyz(1.0, 0.0, 0.0))
-            .id();
-        commands.entity(parent).with_children(|parent| {
-            children.push(
-                parent
-                    .spawn()
-                    .insert(Transform::from_xyz(0.0, 2.0, 0.0))
-                    .id(),
-            );
-            children.push(
-                parent
-                    .spawn()
-                    .insert(Transform::from_xyz(0.0, 3.0, 0.0))
-                    .id(),
-            );
-        });
-        command_queue.apply(&mut world);
-        schedule.run(&mut world);
-
-        assert_eq!(
-            world
-                .get::<Children>(parent)
-                .unwrap()
-                .0
-                .iter()
-                .cloned()
-                .collect::<Vec<_>>(),
-            children,
-        );
-
-        // Parent `e1` to `e2`.
-        (*world.get_mut::<Parent>(children[0]).unwrap()).0 = children[1];
-
-        schedule.run(&mut world);
-
-        assert_eq!(
-            world
-                .get::<Children>(parent)
-                .unwrap()
-                .iter()
-                .cloned()
-                .collect::<Vec<_>>(),
-            vec![children[1]]
-        );
-
-        assert_eq!(
-            world
-                .get::<Children>(children[1])
-                .unwrap()
-                .iter()
-                .cloned()
-                .collect::<Vec<_>>(),
-            vec![children[0]]
-        );
-
-        assert!(world.despawn(children[0]));
-
-        schedule.run(&mut world);
-
-        assert_eq!(
-            world
-                .get::<Children>(parent)
-                .unwrap()
-                .iter()
-                .cloned()
-                .collect::<Vec<_>>(),
-            vec![children[1]]
-        );
-    }
-}