bevy_hierarchy/components/
children.rs

1#[cfg(feature = "reflect")]
2use bevy_ecs::reflect::{
3    ReflectComponent, ReflectFromWorld, ReflectMapEntities, ReflectVisitEntities,
4    ReflectVisitEntitiesMut,
5};
6use bevy_ecs::{
7    component::Component,
8    entity::{Entity, VisitEntitiesMut},
9    prelude::FromWorld,
10    world::World,
11};
12use core::{ops::Deref, slice};
13use smallvec::SmallVec;
14
15/// Contains references to the child entities of this entity.
16///
17/// Each child must contain a [`Parent`] component that points back to this entity.
18/// This component rarely needs to be created manually,
19/// consider using higher level utilities like [`BuildChildren::with_children`]
20/// which are safer and easier to use.
21///
22/// See [`HierarchyQueryExt`] for hierarchy related methods on [`Query`].
23///
24/// [`HierarchyQueryExt`]: crate::query_extension::HierarchyQueryExt
25/// [`Query`]: bevy_ecs::system::Query
26/// [`Parent`]: crate::components::parent::Parent
27/// [`BuildChildren::with_children`]: crate::child_builder::BuildChildren::with_children
28#[derive(Component, Debug, VisitEntitiesMut)]
29#[cfg_attr(feature = "reflect", derive(bevy_reflect::Reflect))]
30#[cfg_attr(
31    feature = "reflect",
32    reflect(
33        Component,
34        MapEntities,
35        VisitEntities,
36        VisitEntitiesMut,
37        Debug,
38        FromWorld
39    )
40)]
41pub struct Children(pub(crate) SmallVec<[Entity; 8]>);
42
43// TODO: We need to impl either FromWorld or Default so Children can be registered as Reflect.
44// This is because Reflect deserialize by creating an instance and apply a patch on top.
45// However Children should only ever be set with a real user-defined entities. Its worth looking
46// into better ways to handle cases like this.
47impl FromWorld for Children {
48    #[inline]
49    fn from_world(_world: &mut World) -> Self {
50        Children(SmallVec::new())
51    }
52}
53
54impl Children {
55    /// Constructs a [`Children`] component with the given entities.
56    #[inline]
57    pub(crate) fn from_entities(entities: &[Entity]) -> Self {
58        Self(SmallVec::from_slice(entities))
59    }
60
61    /// Swaps the child at `a_index` with the child at `b_index`.
62    #[inline]
63    pub fn swap(&mut self, a_index: usize, b_index: usize) {
64        self.0.swap(a_index, b_index);
65    }
66
67    /// Sorts children [stably](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability)
68    /// in place using the provided comparator function.
69    ///
70    /// For the underlying implementation, see [`slice::sort_by`].
71    ///
72    /// For the unstable version, see [`sort_unstable_by`](Children::sort_unstable_by).
73    ///
74    /// See also [`sort_by_key`](Children::sort_by_key), [`sort_by_cached_key`](Children::sort_by_cached_key).
75    #[inline]
76    pub fn sort_by<F>(&mut self, compare: F)
77    where
78        F: FnMut(&Entity, &Entity) -> core::cmp::Ordering,
79    {
80        self.0.sort_by(compare);
81    }
82
83    /// Sorts children [stably](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability)
84    /// in place using the provided key extraction function.
85    ///
86    /// For the underlying implementation, see [`slice::sort_by_key`].
87    ///
88    /// For the unstable version, see [`sort_unstable_by_key`](Children::sort_unstable_by_key).
89    ///
90    /// See also [`sort_by`](Children::sort_by), [`sort_by_cached_key`](Children::sort_by_cached_key).
91    #[inline]
92    pub fn sort_by_key<K, F>(&mut self, compare: F)
93    where
94        F: FnMut(&Entity) -> K,
95        K: Ord,
96    {
97        self.0.sort_by_key(compare);
98    }
99
100    /// Sorts children [stably](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability)
101    /// in place using the provided key extraction function. Only evaluates each key at most
102    /// once per sort, caching the intermediate results in memory.
103    ///
104    /// For the underlying implementation, see [`slice::sort_by_cached_key`].
105    ///
106    /// See also [`sort_by`](Children::sort_by), [`sort_by_key`](Children::sort_by_key).
107    #[inline]
108    pub fn sort_by_cached_key<K, F>(&mut self, compare: F)
109    where
110        F: FnMut(&Entity) -> K,
111        K: Ord,
112    {
113        self.0.sort_by_cached_key(compare);
114    }
115
116    /// Sorts children [unstably](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability)
117    /// in place using the provided comparator function.
118    ///
119    /// For the underlying implementation, see [`slice::sort_unstable_by`].
120    ///
121    /// For the stable version, see [`sort_by`](Children::sort_by).
122    ///
123    /// See also [`sort_unstable_by_key`](Children::sort_unstable_by_key).
124    #[inline]
125    pub fn sort_unstable_by<F>(&mut self, compare: F)
126    where
127        F: FnMut(&Entity, &Entity) -> core::cmp::Ordering,
128    {
129        self.0.sort_unstable_by(compare);
130    }
131
132    /// Sorts children [unstably](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability)
133    /// in place using the provided key extraction function.
134    ///
135    /// For the underlying implementation, see [`slice::sort_unstable_by_key`].
136    ///
137    /// For the stable version, see [`sort_by_key`](Children::sort_by_key).
138    ///
139    /// See also [`sort_unstable_by`](Children::sort_unstable_by).
140    #[inline]
141    pub fn sort_unstable_by_key<K, F>(&mut self, compare: F)
142    where
143        F: FnMut(&Entity) -> K,
144        K: Ord,
145    {
146        self.0.sort_unstable_by_key(compare);
147    }
148}
149
150impl Deref for Children {
151    type Target = [Entity];
152
153    #[inline(always)]
154    fn deref(&self) -> &Self::Target {
155        &self.0[..]
156    }
157}
158
159impl<'a> IntoIterator for &'a Children {
160    type Item = <Self::IntoIter as Iterator>::Item;
161
162    type IntoIter = slice::Iter<'a, Entity>;
163
164    #[inline(always)]
165    fn into_iter(self) -> Self::IntoIter {
166        self.0.iter()
167    }
168}
bevy_hierarchy/components/children.rs

bevy_hierarchy/components/
children.rs
