bevy_hierarchy/components/
children.rs

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

bevy_hierarchy/components/
children.rs
