Merge pull request #845 from AmbientRun/derived-children

Derived `children` from `parent`

Author: FredrikNoren

CHANGELOG.md

@@ -145,6 +145,7 @@ These PRs are not directly user-facing, but improve the development experience.
 - **Elements**: All hooks are now free functions (i.e. `use_state(hooks, ..)` instead of `hooks.use_state(..)`)
 - **UI**: Focus is now global across different packages, and we've removed the FocusRoot component
 - **API**: CursorLockGuard removed and `hide_cursor` package introduced.
+- **Hierarchies**: The `children` component is now automatically derived from `parent` components (unless the user opts out of this). The `children` component is also not networked any longer, since it's calculated on the client side.
 
 #### Non-breaking
 

app/src/server/mod.rs

@@ -221,6 +221,7 @@ fn systems(_world: &mut World) -> SystemGroup {
             // Can happen *during* the physics step
             Box::new(ambient_core::async_ecs::async_ecs_systems()),
             Box::new(ambient_prefab::systems()),
+            Box::new(ambient_core::hierarchy::systems()),
             // Happens after the physics step
             ambient_physics::fetch_simulation_system(),
             Box::new(ambient_animation::animation_systems()),

campfire/src/package.rs

@@ -144,6 +144,7 @@ fn check_all() -> anyhow::Result<()> {
             if !features.is_empty() {
                 command.args(["--features", features]);
             }
+            command.args(["--", "-A", "clippy::collapsible-if"]);
 
             if !command.spawn()?.wait()?.success() {
                 anyhow::bail!(

crates/app/src/lib.rs

@@ -99,6 +99,7 @@ pub fn world_instance_systems(full: bool) -> SystemGroup {
             Box::new(async_ecs_systems()),
             remove_at_time_system(),
             refcount_system(),
+            Box::new(ambient_core::hierarchy::systems()),
             Box::new(WorldEventsSystem),
             Box::new(ambient_focus::systems()),
             if full {

crates/core/src/hierarchy.rs

@@ -1,13 +1,51 @@
 use std::collections::HashSet;
 
-use ambient_ecs::{query, Component, ComponentValue, ECSError, Entity, EntityId, World};
+use ambient_ecs::{
+    generated::hierarchy::components::unmanaged_children, query, Component, ComponentValue,
+    ECSError, Entity, EntityId, SystemGroup, World,
+};
 use itertools::Itertools;
 use yaml_rust::YamlEmitter;
 
 pub use ambient_ecs::generated::hierarchy::components::{children, parent};
 
 use crate::name;
 
+pub fn systems() -> SystemGroup {
+    SystemGroup::new(
+        "hierarchy",
+        vec![
+            query(parent().changed()).to_system_with_name("update_children", |q, world, qs, _| {
+                for (id, parent) in q.collect_cloned(world, qs) {
+                    if world.has_component(parent, unmanaged_children()) {
+                        continue;
+                    }
+                    if let Ok(children) = world.get_mut(parent, children()) {
+                        if !children.contains(&id) {
+                            children.push(id);
+                        }
+                    } else {
+                        world.add_component(parent, children(), vec![id]).unwrap();
+                    }
+                }
+            }),
+            query(parent()).despawned().to_system_with_name(
+                "remove_children",
+                |q, world, qs, _| {
+                    for (id, parent) in q.collect_cloned(world, qs) {
+                        if world.has_component(parent, unmanaged_children()) {
+                            continue;
+                        }
+                        if let Ok(children) = world.get_mut(parent, children()) {
+                            children.retain(|c| *c != id);
+                        }
+                    }
+                },
+            ),
+        ],
+    )
+}
+
 pub fn despawn_recursive(world: &mut World, entity: EntityId) -> Option<Entity> {
     despawn_children_recursive(world, entity);
     world.despawn(entity)

crates/ecs/src/generated.rs

@@ -240,7 +240,7 @@ mod raw {
                 };
                 use glam::{Mat4, Quat, UVec2, UVec3, UVec4, Vec2, Vec3, Vec4};
                 use std::time::Duration;
-                components ! ("hierarchy" , { # [doc = "**Parent**: The parent of this entity.\n\n*Attributes*: Debuggable, Networked, Store"] @ [Debuggable , Networked , Store , Name ["Parent"] , Description ["The parent of this entity."]] parent : EntityId , # [doc = "**Children**: The children of this entity.\n\n*Attributes*: Debuggable, Networked, Store, MaybeResource"] @ [Debuggable , Networked , Store , MaybeResource , Name ["Children"] , Description ["The children of this entity."]] children : Vec :: < EntityId > , });
+                components ! ("hierarchy" , { # [doc = "**Parent**: The parent of this entity.\n\n*Attributes*: Debuggable, Networked, Store"] @ [Debuggable , Networked , Store , Name ["Parent"] , Description ["The parent of this entity."]] parent : EntityId , # [doc = "**Children**: The children of this entity.\n\n*Attributes*: Debuggable, Store, MaybeResource"] @ [Debuggable , Store , MaybeResource , Name ["Children"] , Description ["The children of this entity."]] children : Vec :: < EntityId > , # [doc = "**Unmanaged children**: This children component is not updated automatically for this entity when this component is attached.\n\n*Attributes*: Debuggable, Networked, Store, MaybeResource"] @ [Debuggable , Networked , Store , MaybeResource , Name ["Unmanaged children"] , Description ["This children component is not updated automatically for this entity when this component is attached."]] unmanaged_children : () , });
             }
         }
         #[allow(unused)]

crates/model/src/model.rs

@@ -13,7 +13,8 @@ use ambient_core::{
     },
 };
 use ambient_ecs::{
-    generated::animation::components::bind_id, query, ComponentDesc, Entity, EntityId, World,
+    generated::{animation::components::bind_id, hierarchy::components::unmanaged_children},
+    query, ComponentDesc, Entity, EntityId, World,
 };
 use ambient_gpu::gpu::Gpu;
 use ambient_native_std::{
@@ -207,7 +208,8 @@ impl Model {
                         .with(children(), vec![])
                         .with(local_to_parent(), transform)
                         .with(local_to_world(), Default::default())
-                        .with(is_model_node(), ()),
+                        .with(is_model_node(), ())
+                        .with(unmanaged_children(), ()),
                     count,
                 );
                 for (transform, root) in transform_roots.iter().zip(roots.iter()) {
@@ -375,6 +377,9 @@ impl Model {
             }
         }
         if self.0.has_component(id, children()) {
+            for id in &entities {
+                world.add_component(*id, unmanaged_children(), ()).ok();
+            }
             for c in self.0.get_ref(id, children()).unwrap().iter() {
                 self.spawn_subtree(
                     gpu,

docs/src/reference/hierarchies.md

@@ -1,10 +1,10 @@
 # Hierarchies and transforms
 
-Ambient supports hierarchies of entities using the `parent` and `children` components. Both need to be present for a hierarchy to be valid - as an example, the following entities in the ECS
+Ambient supports hierarchies of entities using the `parent` and `children` components. The user only specifies the `parent` component, the `children` are automatically derived from the existing parents.
+As an example, the following entities in the ECS
 
 ```yml
 entity a:
-  - children: [b, c]
 entity b:
   - parent: a
 entity c:
@@ -19,8 +19,6 @@ entity a
     entity c
 ```
 
-If you are creating hierachies yourself, you need to make sure that both `parent` and `children` exists and are correct for the hierarchy to work.
-
 The `entity::add_child` and `entity::remove_child` functions can be used to add and remove children from a parent.
 
 When using the `model_from_url` or `prefab_from_url` components, the entire model sub-tree will be spawned in, with the root of the sub-tree being added as a child to the entity with the component. Each entity in the sub-tree will be part of the hierarchy using their own `parent` and `children` components.
@@ -32,7 +30,6 @@ To apply transforms to a hierarchy, `local_to_parent` must be used:
 
 ```yml
 entity a:
-  - children: [b]
   - local_to_world: Mat4(..)
 entity b:
   - parent: a
@@ -46,7 +43,6 @@ In this case, `b.local_to_world` will be calculated as `a.local_to_world * b.loc
 
 ```yml
 entity a:
-  - children: [b]
   - local_to_world: Mat4(..)
   - translation: vec3(5., 2., 9.)
   - rotation: quat(..)
@@ -88,3 +84,9 @@ mesh_to_world = local_to_world * mesh_to_local
 This also means that you can attach a mesh in the middle of a hierarchy, with an offset. For instance, if you have
 a bone hierarchy on a character, you can attach an mesh to the upper arm bone, but without `mesh_to_local/world` it
 would be rendered at the center of the arm (inside the arm), so by using `mesh_to_local/world` you can offset it.
+
+## Opting out of automatically derived children
+
+If you wish to manage the `children` component yourself, you can attach an `unmanaged_children` component to your
+entity. This stops `children` from being automatically created, and it's now up to you to populate the `children`
+component to create a valid hierarchy.

guest/rust/Cargo.lock

@@ -2,7 +2,7 @@ use crate::{
     core::{
         app::components::name,
         audio::components::*,
-        hierarchy::components::{children, parent},
+        hierarchy::components::{children, parent, unmanaged_children},
     },
     entity,
     prelude::{Entity, EntityId},
@@ -82,6 +82,7 @@ impl AudioPlayer {
             .with(is_audio_player(), ())
             .with(name(), "Audio player".to_string())
             .with(children(), vec![])
+            .with(unmanaged_children(), ())
             .spawn();
         Self { entity: player }
     }