Change ColliderParent to a ColliderOf relationship and rework ColliderHierarchyPlugin (#671)

# Objective

`ColliderParent` should be a relationship for robustness and semantics, and to take advantage of automatic source tracking for rigid bodies.

The `ColliderHierarchyPlugin` also currently deals with both attaching colliders to rigid bodies and managing transforms. This would be good to split into separate plugins.

## Solution

Rename `ColliderParent` to `ColliderOf`, make it a `Relationship`, and add a `RigidBodyColliders` component for the `RelationshipTarget`. Collider hierarchies are now managed via observers and hooks instead of systems.

Note that `ColliderOf` requires a custom `Relationship` implementation, because Bevy's default implementation does not allow relationships to point to themselves.

I also split the `ColliderHierarchyPlugin` into a `ColliderHierarchyPlugin` (manages `ColliderOf` relationships) and `ColliderTransformPlugin` (manages and propagates collider transforms).

---

## Migration Guide

`ColliderParent` has been renamed to `ColliderOf`, and it is now a `Relationship`.

The transform management in `ColliderHierarchyPlugin` has been extracted into a new `ColliderTransformPlugin`. The `ColliderHierarchyPlugin` no longer takes a schedule.

Author: Jondolf

crates/avian2d/examples/kinematic_character_2d/plugin.rs

@@ -267,7 +267,7 @@ fn apply_movement_damping(mut query: Query<(&MovementDampingFactor, &mut LinearV
 fn kinematic_controller_collisions(
     collisions: Res<Collisions>,
     bodies: Query<&RigidBody>,
-    collider_parents: Query<&ColliderParent, Without<Sensor>>,
+    collider_rbs: Query<&ColliderOf, Without<Sensor>>,
     mut character_controllers: Query<
         (&mut Position, &mut LinearVelocity, Option<&MaxSlopeAngle>),
         (With<RigidBody>, With<CharacterController>),
@@ -277,8 +277,8 @@ fn kinematic_controller_collisions(
     // Iterate through collisions and move the kinematic body to resolve penetration
     for contacts in collisions.iter() {
         // Get the rigid body entities of the colliders (colliders could be children)
-        let Ok([collider_parent1, collider_parent2]) =
-            collider_parents.get_many([contacts.entity1, contacts.entity2])
+        let Ok([&ColliderOf { rigid_body: rb1 }, &ColliderOf { rigid_body: rb2 }]) =
+            collider_rbs.get_many([contacts.entity1, contacts.entity2])
         else {
             continue;
         };
@@ -291,19 +291,15 @@ fn kinematic_controller_collisions(
         let is_other_dynamic: bool;
 
         let (mut position, mut linear_velocity, max_slope_angle) =
-            if let Ok(character) = character_controllers.get_mut(collider_parent1.get()) {
+            if let Ok(character) = character_controllers.get_mut(rb1) {
                 is_first = true;
-                character_rb = *bodies.get(collider_parent1.get()).unwrap();
-                is_other_dynamic = bodies
-                    .get(collider_parent2.get())
-                    .is_ok_and(|rb| rb.is_dynamic());
+                character_rb = *bodies.get(rb1).unwrap();
+                is_other_dynamic = bodies.get(rb2).is_ok_and(|rb| rb.is_dynamic());
                 character
-            } else if let Ok(character) = character_controllers.get_mut(collider_parent2.get()) {
+            } else if let Ok(character) = character_controllers.get_mut(rb2) {
                 is_first = false;
-                character_rb = *bodies.get(collider_parent2.get()).unwrap();
-                is_other_dynamic = bodies
-                    .get(collider_parent1.get())
-                    .is_ok_and(|rb| rb.is_dynamic());
+                character_rb = *bodies.get(rb2).unwrap();
+                is_other_dynamic = bodies.get(rb1).is_ok_and(|rb| rb.is_dynamic());
                 character
             } else {
                 continue;

crates/avian3d/examples/kinematic_character_3d/plugin.rs

@@ -283,7 +283,7 @@ fn apply_movement_damping(mut query: Query<(&MovementDampingFactor, &mut LinearV
 fn kinematic_controller_collisions(
     collisions: Res<Collisions>,
     bodies: Query<&RigidBody>,
-    collider_parents: Query<&ColliderParent, Without<Sensor>>,
+    collider_rbs: Query<&ColliderOf, Without<Sensor>>,
     mut character_controllers: Query<
         (&mut Position, &mut LinearVelocity, Option<&MaxSlopeAngle>),
         (With<RigidBody>, With<CharacterController>),
@@ -293,8 +293,8 @@ fn kinematic_controller_collisions(
     // Iterate through collisions and move the kinematic body to resolve penetration
     for contacts in collisions.iter() {
         // Get the rigid body entities of the colliders (colliders could be children)
-        let Ok([collider_parent1, collider_parent2]) =
-            collider_parents.get_many([contacts.entity1, contacts.entity2])
+        let Ok([&ColliderOf { rigid_body: rb1 }, &ColliderOf { rigid_body: rb2 }]) =
+            collider_rbs.get_many([contacts.entity1, contacts.entity2])
         else {
             continue;
         };
@@ -307,19 +307,15 @@ fn kinematic_controller_collisions(
         let is_other_dynamic: bool;
 
         let (mut position, mut linear_velocity, max_slope_angle) =
-            if let Ok(character) = character_controllers.get_mut(collider_parent1.get()) {
+            if let Ok(character) = character_controllers.get_mut(rb1) {
                 is_first = true;
-                character_rb = *bodies.get(collider_parent1.get()).unwrap();
-                is_other_dynamic = bodies
-                    .get(collider_parent2.get())
-                    .is_ok_and(|rb| rb.is_dynamic());
+                character_rb = *bodies.get(rb1).unwrap();
+                is_other_dynamic = bodies.get(rb2).is_ok_and(|rb| rb.is_dynamic());
                 character
-            } else if let Ok(character) = character_controllers.get_mut(collider_parent2.get()) {
+            } else if let Ok(character) = character_controllers.get_mut(rb2) {
                 is_first = false;
-                character_rb = *bodies.get(collider_parent2.get()).unwrap();
-                is_other_dynamic = bodies
-                    .get(collider_parent1.get())
-                    .is_ok_and(|rb| rb.is_dynamic());
+                character_rb = *bodies.get(rb2).unwrap();
+                is_other_dynamic = bodies.get(rb1).is_ok_and(|rb| rb.is_dynamic());
                 character
             } else {
                 continue;

src/collision/broad_phase.rs

@@ -105,7 +105,7 @@ pub struct AabbIntersections(pub Vec<Entity>);
 struct AabbIntervals(
     Vec<(
         Entity,
-        ColliderParent,
+        ColliderOf,
         ColliderAabb,
         CollisionLayers,
         AabbIntervalFlags,
@@ -139,7 +139,7 @@ fn update_aabb_intervals(
     aabbs: Query<
         (
             &ColliderAabb,
-            Option<&ColliderParent>,
+            Option<&ColliderOf>,
             Option<&CollisionLayers>,
             Option<&ActiveCollisionHooks>,
             Has<AabbIntersections>,
@@ -152,10 +152,10 @@ fn update_aabb_intervals(
 ) {
     intervals
         .0
-        .retain_mut(|(collider_entity, collider_parent, aabb, layers, flags)| {
+        .retain_mut(|(collider_entity, collider_of, aabb, layers, flags)| {
             if let Ok((
                 new_aabb,
-                new_parent,
+                new_collider_of,
                 new_layers,
                 hooks,
                 new_store_intersections,
@@ -167,11 +167,18 @@ fn update_aabb_intervals(
                 }
 
                 *aabb = *new_aabb;
-                *collider_parent = new_parent.map_or(ColliderParent(*collider_entity), |p| *p);
+                *collider_of = new_collider_of.map_or(
+                    ColliderOf {
+                        rigid_body: *collider_entity,
+                    },
+                    |p| *p,
+                );
                 *layers = new_layers.map_or(CollisionLayers::default(), |layers| *layers);
 
-                let is_static =
-                    new_parent.is_some_and(|p| rbs.get(p.get()).is_ok_and(RigidBody::is_static));
+                let is_static = new_collider_of.is_some_and(|collider_of| {
+                    rbs.get(collider_of.rigid_body)
+                        .is_ok_and(RigidBody::is_static)
+                });
 
                 flags.set(AabbIntervalFlags::IS_INACTIVE, is_static || is_sleeping);
                 flags.set(
@@ -192,7 +199,7 @@ fn update_aabb_intervals(
 
 type AabbIntervalQueryData = (
     Entity,
-    Option<Read<ColliderParent>>,
+    Option<Read<ColliderOf>>,
     Read<ColliderAabb>,
     Option<Read<RigidBody>>,
     Option<Read<CollisionLayers>>,
@@ -210,7 +217,7 @@ fn add_new_aabb_intervals(
 ) {
     let re_enabled_aabbs = aabbs.iter_many(re_enabled_colliders.read());
     let aabbs = added_aabbs.iter().chain(re_enabled_aabbs).map(
-        |(entity, parent, aabb, rb, layers, hooks, store_intersections)| {
+        |(entity, collider_of, aabb, rb, layers, hooks, store_intersections)| {
             let mut flags = AabbIntervalFlags::empty();
             flags.set(AabbIntervalFlags::STORE_INTERSECTIONS, store_intersections);
             flags.set(
@@ -223,7 +230,7 @@ fn add_new_aabb_intervals(
             );
             (
                 entity,
-                parent.map_or(ColliderParent(entity), |p| *p),
+                collider_of.map_or(ColliderOf { rigid_body: entity }, |p| *p),
                 *aabb,
                 layers.map_or(CollisionLayers::default(), |layers| *layers),
                 flags,
@@ -280,20 +287,20 @@ fn sweep_and_prune<H: CollisionHooks>(
     broad_collision_pairs.clear();
 
     // Find potential collisions by checking for AABB intersections along all axes.
-    for (i, (entity1, parent1, aabb1, layers1, flags1)) in intervals.0.iter().enumerate() {
-        for (entity2, parent2, aabb2, layers2, flags2) in intervals.0.iter().skip(i + 1) {
+    for (i, (entity1, collider_of1, aabb1, layers1, flags1)) in intervals.0.iter().enumerate() {
+        for (entity2, collider_of2, aabb2, layers2, flags2) in intervals.0.iter().skip(i + 1) {
             // x doesn't intersect; check this first so we can discard as soon as possible.
             if aabb2.min.x > aabb1.max.x {
                 break;
             }
 
             // No collisions between bodies that haven't moved or colliders with incompatible layers
-            // or colliders with the same parent.
+            // or colliders attached to the same rigid body.
             if flags1
                 .intersection(*flags2)
                 .contains(AabbIntervalFlags::IS_INACTIVE)
                 || !layers1.interacts_with(*layers2)
-                || parent1 == parent2
+                || collider_of1 == collider_of2
             {
                 continue;
             }

src/collision/collider/backend.rs

@@ -188,7 +188,7 @@ impl<C: ScalableCollider> Plugin for ColliderBackendPlugin<C> {
                 let entity_ref = world.entity_mut(ctx.entity);
 
                 // Get the rigid body entity that the collider is attached to.
-                let Some(parent) = entity_ref.get::<ColliderParent>().copied() else {
+                let Some(collider_of) = entity_ref.get::<ColliderOf>().copied() else {
                     return;
                 };
 
@@ -197,22 +197,24 @@ impl<C: ScalableCollider> Plugin for ColliderBackendPlugin<C> {
                     *world.resource::<ColliderRemovalSystem>().to_owned();
 
                 // Handle collider removal.
-                world.commands().run_system_with(system_id, parent);
+                world.commands().run_system_with(system_id, collider_of);
             });
 
         // When the `Sensor` component is added to a collider, queue its rigid body for a mass property update.
         app.add_observer(
             |trigger: Trigger<OnAdd, Sensor>,
              mut commands: Commands,
-             query: Query<(&ColliderMassProperties, &ColliderParent)>| {
-                if let Ok((collider_mass_properties, parent)) = query.get(trigger.target()) {
+             query: Query<(&ColliderMassProperties, &ColliderOf)>| {
+                if let Ok((collider_mass_properties, &ColliderOf { rigid_body })) =
+                    query.get(trigger.target())
+                {
                     // If the collider mass properties are zero, there is nothing to subtract.
                     if *collider_mass_properties == ColliderMassProperties::ZERO {
                         return;
                     }
 
-                    // Queue the parent rigid body for a mass property update.
-                    if let Ok(mut entity_commands) = commands.get_entity(parent.get()) {
+                    // Queue the rigid body for a mass property update.
+                    if let Ok(mut entity_commands) = commands.get_entity(rigid_body) {
                         entity_commands.insert(RecomputeMassProperties);
                     }
                 }
@@ -252,12 +254,6 @@ impl<C: ScalableCollider> Plugin for ColliderBackendPlugin<C> {
             ),
         );
 
-        // Update collider parents for colliders that are on the same entity as the rigid body.
-        app.add_systems(
-            self.schedule,
-            update_root_collider_parents::<C>.before(PrepareSet::Finalize),
-        );
-
         let physics_schedule = app
             .get_schedule_mut(PhysicsSchedule)
             .expect("add PhysicsSchedule first");
@@ -290,29 +286,6 @@ impl<C: ScalableCollider> Plugin for ColliderBackendPlugin<C> {
 #[reflect(Component, Debug, Default)]
 pub struct ColliderMarker;
 
-/// Updates [`ColliderParent`] for colliders that are on the same entity as the [`RigidBody`].
-///
-/// The [`ColliderHierarchyPlugin`] should be used to handle hierarchies.
-fn update_root_collider_parents<C: AnyCollider>(
-    mut commands: Commands,
-    mut bodies: Query<
-        (Entity, Option<&mut ColliderParent>),
-        (With<RigidBody>, With<C>, Or<(Added<RigidBody>, Added<C>)>),
-    >,
-) {
-    for (entity, collider_parent) in &mut bodies {
-        if let Some(mut collider_parent) = collider_parent {
-            collider_parent.0 = entity;
-        } else {
-            commands.entity(entity).try_insert((
-                ColliderParent(entity),
-                // TODO: This probably causes a one frame delay. Compute real value?
-                ColliderTransform::default(),
-            ));
-        }
-    }
-}
-
 /// Generates [`Collider`]s based on [`ColliderConstructor`]s.
 ///
 /// If a [`ColliderConstructor`] requires a mesh, the system keeps running
@@ -505,7 +478,7 @@ fn update_aabb<C: AnyCollider>(
             &mut ColliderAabb,
             &Position,
             &Rotation,
-            Option<&ColliderParent>,
+            Option<&ColliderOf>,
             Option<&CollisionMargin>,
             Option<&SpeculativeMargin>,
             Has<SweptCcd>,
@@ -520,7 +493,7 @@ fn update_aabb<C: AnyCollider>(
             Changed<C>,
         )>,
     >,
-    parent_velocity: Query<
+    rb_velocities: Query<
         (
             &Position,
             &ComputedCenterOfMass,
@@ -544,7 +517,7 @@ fn update_aabb<C: AnyCollider>(
         mut aabb,
         pos,
         rot,
-        collider_parent,
+        collider_of,
         collision_margin,
         speculative_margin,
         has_swept_ccd,
@@ -571,16 +544,16 @@ fn update_aabb<C: AnyCollider>(
         // Expand the AABB based on the body's velocity and CCD speculative margin.
         let (lin_vel, ang_vel) = if let (Some(lin_vel), Some(ang_vel)) = (lin_vel, ang_vel) {
             (*lin_vel, *ang_vel)
-        } else if let Some(Ok((parent_pos, center_of_mass, Some(lin_vel), Some(ang_vel)))) =
-            collider_parent.map(|p| parent_velocity.get(p.get()))
+        } else if let Some(Ok((rb_pos, center_of_mass, Some(lin_vel), Some(ang_vel)))) =
+            collider_of.map(|&ColliderOf { rigid_body }| rb_velocities.get(rigid_body))
         {
             // If the rigid body is rotating, off-center colliders will orbit around it,
             // which affects their linear velocities. We need to compute the linear velocity
             // at the offset position.
             // TODO: This assumes that the colliders would continue moving in the same direction,
             //       but because they are orbiting, the direction will change. We should take
             //       into account the uniform circular motion.
-            let offset = pos.0 - parent_pos.0 - center_of_mass.0;
+            let offset = pos.0 - rb_pos.0 - center_of_mass.0;
             #[cfg(feature = "2d")]
             let vel_at_offset =
                 lin_vel.0 + Vector::new(-ang_vel.0 * offset.y, ang_vel.0 * offset.x) * 1.0;
@@ -661,26 +634,24 @@ pub fn update_collider_scale<C: ScalableCollider>(
 
 /// A resource that stores the system ID for the system that reacts to collider removals.
 #[derive(Resource)]
-struct ColliderRemovalSystem(SystemId<In<ColliderParent>>);
+struct ColliderRemovalSystem(SystemId<In<ColliderOf>>);
 
 /// Updates the mass properties of bodies and wakes bodies up when an attached collider is removed.
 ///
-/// Takes the removed collider's entity, parent, mass properties, and transform as input.
+/// Takes the removed collider's entity, rigid body entity, mass properties, and transform as input.
 fn collider_removed(
-    In(parent): In<ColliderParent>,
+    In(ColliderOf { rigid_body }): In<ColliderOf>,
     mut commands: Commands,
     mut sleep_query: Query<&mut TimeSleeping>,
 ) {
-    let parent = parent.get();
-
-    let Ok(mut entity_commands) = commands.get_entity(parent) else {
+    let Ok(mut entity_commands) = commands.get_entity(rigid_body) else {
         return;
     };
 
-    // Queue the parent entity for mass property recomputation.
+    // Queue the rigid body for mass property recomputation.
     entity_commands.insert(RecomputeMassProperties);
 
-    if let Ok(mut time_sleeping) = sleep_query.get_mut(parent) {
+    if let Ok(mut time_sleeping) = sleep_query.get_mut(rigid_body) {
         // Wake up the rigid body since removing the collider could also remove active contacts.
         entity_commands.remove::<Sleeping>();
         time_sleeping.0 = 0.0;
@@ -720,8 +691,9 @@ mod tests {
         app.add_plugins((
             PreparePlugin::new(FixedPostUpdate),
             MassPropertyPlugin::new(FixedPostUpdate),
+            ColliderHierarchyPlugin,
+            ColliderTransformPlugin::default(),
             ColliderBackendPlugin::<Collider>::new(FixedPostUpdate),
-            ColliderHierarchyPlugin::new(FixedPostUpdate),
         ));
 
         let collider = Collider::capsule(0.5, 2.0);