bevy_ecs/
lifecycle.rs

1//! This module contains various tools to allow you to react to component insertion or removal,
2//! as well as entity spawning and despawning.
3//!
4//! There are four main ways to react to these lifecycle events:
5//!
6//! 1. Using component hooks, which act as inherent constructors and destructors for components.
7//! 2. Using [observers], which are a user-extensible way to respond to events, including component lifecycle events.
8//! 3. Using the [`RemovedComponents`] system parameter, which offers an event-style interface.
9//! 4. Using the [`Added`] query filter, which checks each component to see if it has been added since the last time a system ran.
10//!
11//! [observers]: crate::observer
12//! [`Added`]: crate::query::Added
13//!
14//! # Types of lifecycle events
15//!
16//! There are five types of lifecycle events, split into two categories. First, we have lifecycle events that are triggered
17//! when a component is added to an entity:
18//!
19//! - [`Add`]: Triggered when a component is added to an entity that did not already have it.
20//! - [`Insert`]: Triggered when a component is added to an entity, regardless of whether it already had it.
21//!
22//! When both events occur, [`Add`] hooks are evaluated before [`Insert`].
23//!
24//! Next, we have lifecycle events that are triggered when a component is removed from an entity:
25//!
26//! - [`Discard`]: Triggered when a component is removed from an entity, regardless if it is then replaced with a new value.
27//! - [`Remove`]: Triggered when a component is removed from an entity and not replaced, before the component is removed.
28//! - [`Despawn`]: Triggered for each component on an entity when it is despawned.
29//!
30//! [`Discard`] hooks are evaluated before [`Remove`], then finally [`Despawn`] hooks are evaluated.
31//!
32//! [`Add`] and [`Remove`] are counterparts: they are only triggered when a component is added or removed
33//! from an entity in such a way as to cause a change in the component's presence on that entity.
34//! Similarly, [`Insert`] and [`Discard`] are counterparts: they are triggered when a component is added or overwritten
35//! on an entity, regardless of whether this results in a change in the component's presence on that entity.
36//!
37//! To reliably synchronize data structures using with component lifecycle events,
38//! you can combine [`Insert`] and [`Discard`] to fully capture any changes to the data.
39//! This is particularly useful in combination with immutable components,
40//! to avoid any lifecycle-bypassing mutations.
41//!
42//! ## Lifecycle events and component types
43//!
44//! Despite the absence of generics, each lifecycle event is associated with a specific component.
45//! When defining a component hook for a [`Component`] type, that component is used.
46//! When observers watch lifecycle events, the `B: Bundle` generic is used.
47//!
48//! Each of these lifecycle events also corresponds to a fixed [`ComponentId`],
49//! which are assigned during [`World`] initialization.
50//! For example, [`Add`] corresponds to [`ADD`].
51//! This is used to skip [`TypeId`](core::any::TypeId) lookups in hot paths.
52use crate::{
53    change_detection::{MaybeLocation, Tick},
54    component::{Component, ComponentId, ComponentIdFor},
55    entity::Entity,
56    event::{EntityComponentsTrigger, EntityEvent, EventKey},
57    message::{
58        Message, MessageCursor, MessageId, MessageIterator, MessageIteratorWithId, Messages,
59    },
60    query::FilteredAccessSet,
61    relationship::RelationshipHookMode,
62    storage::SparseSet,
63    system::{Local, ReadOnlySystemParam, SystemMeta, SystemParam, SystemParamValidationError},
64    world::{unsafe_world_cell::UnsafeWorldCell, DeferredWorld, World},
65};
66
67use derive_more::derive::Into;
68
69#[cfg(feature = "bevy_reflect")]
70use bevy_reflect::Reflect;
71use core::{
72    fmt::Debug,
73    iter,
74    marker::PhantomData,
75    ops::{Deref, DerefMut},
76    option,
77};
78
79/// The type used for [`Component`] lifecycle hooks such as `on_add`, `on_insert` or `on_remove`.
80pub type ComponentHook = for<'w> fn(DeferredWorld<'w>, HookContext);
81
82/// Context provided to a [`ComponentHook`].
83#[derive(Clone, Copy, Debug)]
84pub struct HookContext {
85    /// The [`Entity`] this hook was invoked for.
86    pub entity: Entity,
87    /// The [`ComponentId`] this hook was invoked for.
88    pub component_id: ComponentId,
89    /// The caller location is `Some` if the `track_caller` feature is enabled.
90    pub caller: MaybeLocation,
91    /// Configures how relationship hooks will run
92    pub relationship_hook_mode: RelationshipHookMode,
93}
94
95/// [`World`]-mutating functions that run as part of lifecycle events of a [`Component`].
96///
97/// Hooks are functions that run when a component is added, overwritten, or removed from an entity.
98/// These are intended to be used for structural side effects that need to happen when a component is added or removed,
99/// and are not intended for general-purpose logic.
100///
101/// For example, you might use a hook to update a cached index when a component is added,
102/// to clean up resources when a component is removed,
103/// or to keep hierarchical data structures across entities in sync.
104///
105/// This information is stored in the [`ComponentInfo`](crate::component::ComponentInfo) of the associated component.
106///
107/// There are two ways of configuring hooks for a component:
108/// 1. Defining the relevant hooks on the [`Component`] implementation
109/// 2. Using the [`World::register_component_hooks`] method
110///
111/// # Example
112///
113/// ```
114/// use bevy_ecs::prelude::*;
115/// use bevy_ecs::entity::EntityHashSet;
116///
117/// #[derive(Component)]
118/// struct MyTrackedComponent;
119///
120/// #[derive(Resource, Default)]
121/// struct TrackedEntities(EntityHashSet);
122///
123/// let mut world = World::new();
124/// world.init_resource::<TrackedEntities>();
125///
126/// // No entities with `MyTrackedComponent` have been added yet, so we can safely add component hooks
127/// let mut tracked_component_query = world.query::<&MyTrackedComponent>();
128/// assert!(tracked_component_query.iter(&world).next().is_none());
129///
130/// world.register_component_hooks::<MyTrackedComponent>().on_add(|mut world, context| {
131///    let mut tracked_entities = world.resource_mut::<TrackedEntities>();
132///   tracked_entities.0.insert(context.entity);
133/// });
134///
135/// world.register_component_hooks::<MyTrackedComponent>().on_remove(|mut world, context| {
136///   let mut tracked_entities = world.resource_mut::<TrackedEntities>();
137///   tracked_entities.0.remove(&context.entity);
138/// });
139///
140/// let entity = world.spawn(MyTrackedComponent).id();
141/// let tracked_entities = world.resource::<TrackedEntities>();
142/// assert!(tracked_entities.0.contains(&entity));
143///
144/// world.despawn(entity);
145/// let tracked_entities = world.resource::<TrackedEntities>();
146/// assert!(!tracked_entities.0.contains(&entity));
147/// ```
148#[derive(Debug, Clone, Default)]
149pub struct ComponentHooks {
150    pub(crate) on_add: Option<ComponentHook>,
151    pub(crate) on_insert: Option<ComponentHook>,
152    pub(crate) on_discard: Option<ComponentHook>,
153    pub(crate) on_remove: Option<ComponentHook>,
154    pub(crate) on_despawn: Option<ComponentHook>,
155}
156
157impl ComponentHooks {
158    pub(crate) fn update_from_component<C: Component + ?Sized>(&mut self) -> &mut Self {
159        if let Some(hook) = C::on_add() {
160            self.on_add(hook);
161        }
162        if let Some(hook) = C::on_insert() {
163            self.on_insert(hook);
164        }
165        if let Some(hook) = C::on_discard() {
166            self.on_discard(hook);
167        }
168        if let Some(hook) = C::on_remove() {
169            self.on_remove(hook);
170        }
171        if let Some(hook) = C::on_despawn() {
172            self.on_despawn(hook);
173        }
174
175        self
176    }
177
178    /// Register a [`ComponentHook`] that will be run when this component is added to an entity.
179    /// An `on_add` hook will always run before `on_insert` hooks. Spawning an entity counts as
180    /// adding all of its components.
181    ///
182    /// # Panics
183    ///
184    /// Will panic if the component already has an `on_add` hook
185    pub fn on_add(&mut self, hook: ComponentHook) -> &mut Self {
186        self.try_on_add(hook)
187            .expect("Component already has an on_add hook")
188    }
189
190    /// Register a [`ComponentHook`] that will be run when this component is added (with `.insert`)
191    /// or replaced.
192    ///
193    /// An `on_insert` hook always runs after any `on_add` hooks (if the entity didn't already have the component).
194    ///
195    /// # Warning
196    ///
197    /// The hook won't run if the component is already present and is only mutated, such as in a system via a query.
198    /// As a result, this needs to be combined with immutable components to serve as a mechanism for reliably updating indexes and other caches.
199    ///
200    /// # Panics
201    ///
202    /// Will panic if the component already has an `on_insert` hook
203    pub fn on_insert(&mut self, hook: ComponentHook) -> &mut Self {
204        self.try_on_insert(hook)
205            .expect("Component already has an on_insert hook")
206    }
207
208    /// Register a [`ComponentHook`] that will be run when this component is about to be dropped,
209    /// such as being replaced (with `.insert`) or removed.
210    ///
211    /// If this component is inserted onto an entity that already has it, this hook will run before the value is replaced,
212    /// allowing access to the previous data just before it is dropped.
213    /// This hook does *not* run if the entity did not already have this component.
214    ///
215    /// An `on_discard` hook always runs before any `on_remove` hooks (if the component is being removed from the entity).
216    ///
217    /// # Warning
218    ///
219    /// The hook won't run if the component is already present and is only mutated, such as in a system via a query.
220    /// As a result, this needs to be combined with immutable components to serve as a mechanism for reliably updating indexes and other caches.
221    ///
222    /// # Panics
223    ///
224    /// Will panic if the component already has an `on_discard` hook
225    pub fn on_discard(&mut self, hook: ComponentHook) -> &mut Self {
226        self.try_on_discard(hook)
227            .expect("Component already has an on_discard hook")
228    }
229
230    /// Register a [`ComponentHook`] that will be run when this component is removed from an entity.
231    /// Despawning an entity counts as removing all of its components.
232    ///
233    /// # Panics
234    ///
235    /// Will panic if the component already has an `on_remove` hook
236    pub fn on_remove(&mut self, hook: ComponentHook) -> &mut Self {
237        self.try_on_remove(hook)
238            .expect("Component already has an on_remove hook")
239    }
240
241    /// Register a [`ComponentHook`] that will be run for each component on an entity when it is despawned.
242    ///
243    /// # Panics
244    ///
245    /// Will panic if the component already has an `on_despawn` hook
246    pub fn on_despawn(&mut self, hook: ComponentHook) -> &mut Self {
247        self.try_on_despawn(hook)
248            .expect("Component already has an on_despawn hook")
249    }
250
251    /// Attempt to register a [`ComponentHook`] that will be run when this component is added to an entity.
252    ///
253    /// This is a fallible version of [`Self::on_add`].
254    ///
255    /// Returns `None` if the component already has an `on_add` hook.
256    pub fn try_on_add(&mut self, hook: ComponentHook) -> Option<&mut Self> {
257        if self.on_add.is_some() {
258            return None;
259        }
260        self.on_add = Some(hook);
261        Some(self)
262    }
263
264    /// Attempt to register a [`ComponentHook`] that will be run when this component is added (with `.insert`)
265    ///
266    /// This is a fallible version of [`Self::on_insert`].
267    ///
268    /// Returns `None` if the component already has an `on_insert` hook.
269    pub fn try_on_insert(&mut self, hook: ComponentHook) -> Option<&mut Self> {
270        if self.on_insert.is_some() {
271            return None;
272        }
273        self.on_insert = Some(hook);
274        Some(self)
275    }
276
277    /// Attempt to register a [`ComponentHook`] that will be run when this component is replaced (with `.insert`) or removed
278    ///
279    /// This is a fallible version of [`Self::on_discard`].
280    ///
281    /// Returns `None` if the component already has an `on_discard` hook.
282    pub fn try_on_discard(&mut self, hook: ComponentHook) -> Option<&mut Self> {
283        if self.on_discard.is_some() {
284            return None;
285        }
286        self.on_discard = Some(hook);
287        Some(self)
288    }
289
290    /// Attempt to register a [`ComponentHook`] that will be run when this component is removed from an entity.
291    ///
292    /// This is a fallible version of [`Self::on_remove`].
293    ///
294    /// Returns `None` if the component already has an `on_remove` hook.
295    pub fn try_on_remove(&mut self, hook: ComponentHook) -> Option<&mut Self> {
296        if self.on_remove.is_some() {
297            return None;
298        }
299        self.on_remove = Some(hook);
300        Some(self)
301    }
302
303    /// Attempt to register a [`ComponentHook`] that will be run for each component on an entity when it is despawned.
304    ///
305    /// This is a fallible version of [`Self::on_despawn`].
306    ///
307    /// Returns `None` if the component already has an `on_despawn` hook.
308    pub fn try_on_despawn(&mut self, hook: ComponentHook) -> Option<&mut Self> {
309        if self.on_despawn.is_some() {
310            return None;
311        }
312        self.on_despawn = Some(hook);
313        Some(self)
314    }
315}
316
317/// [`EventKey`] for [`Add`]
318pub const ADD: EventKey = EventKey(ComponentId::new(crate::component::ADD));
319/// [`EventKey`] for [`Insert`]
320pub const INSERT: EventKey = EventKey(ComponentId::new(crate::component::INSERT));
321/// [`EventKey`] for [`Discard`]
322pub const DISCARD: EventKey = EventKey(ComponentId::new(crate::component::DISCARD));
323/// [`EventKey`] for [`Remove`]
324pub const REMOVE: EventKey = EventKey(ComponentId::new(crate::component::REMOVE));
325/// [`EventKey`] for [`Despawn`]
326pub const DESPAWN: EventKey = EventKey(ComponentId::new(crate::component::DESPAWN));
327
328/// Trigger emitted when a component is inserted onto an entity that does not already have that
329/// component. Runs before `Insert`.
330/// See [`ComponentHooks::on_add`](`crate::lifecycle::ComponentHooks::on_add`) for more information.
331#[derive(Debug, Clone, EntityEvent)]
332#[entity_event(trigger = EntityComponentsTrigger<'a>)]
333#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
334#[cfg_attr(feature = "bevy_reflect", reflect(Debug))]
335#[doc(alias = "OnAdd")]
336pub struct Add {
337    /// The entity this component was added to.
338    pub entity: Entity,
339}
340
341/// Trigger emitted when a component is inserted, regardless of whether or not the entity already
342/// had that component. Runs after `Add`, if it ran.
343/// See [`ComponentHooks::on_insert`](`crate::lifecycle::ComponentHooks::on_insert`) for more information.
344#[derive(Debug, Clone, EntityEvent)]
345#[entity_event(trigger = EntityComponentsTrigger<'a>)]
346#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
347#[cfg_attr(feature = "bevy_reflect", reflect(Debug))]
348#[doc(alias = "OnInsert")]
349pub struct Insert {
350    /// The entity this component was inserted into.
351    pub entity: Entity,
352}
353
354/// Trigger emitted when a component is removed from an entity, regardless
355/// of whether or not it is later replaced.
356///
357/// Runs before the value is replaced, so you can still access the original component data.
358/// See [`ComponentHooks::on_discard`](`crate::lifecycle::ComponentHooks::on_discard`) for more information.
359#[derive(Debug, Clone, EntityEvent)]
360#[entity_event(trigger = EntityComponentsTrigger<'a>)]
361#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
362#[cfg_attr(feature = "bevy_reflect", reflect(Debug))]
363#[doc(alias = "OnDiscard")]
364#[doc(alias = "OnReplace")]
365#[doc(alias = "Replace")]
366pub struct Discard {
367    /// The entity that held this component before it was discarded.
368    pub entity: Entity,
369}
370
371/// Trigger emitted when a component is removed from an entity, and runs before the component is
372/// removed, so you can still access the component data.
373/// See [`ComponentHooks::on_remove`](`crate::lifecycle::ComponentHooks::on_remove`) for more information.
374#[derive(Debug, Clone, EntityEvent)]
375#[entity_event(trigger = EntityComponentsTrigger<'a>)]
376#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
377#[cfg_attr(feature = "bevy_reflect", reflect(Debug))]
378#[doc(alias = "OnRemove")]
379pub struct Remove {
380    /// The entity this component was removed from.
381    pub entity: Entity,
382}
383
384/// [`EntityEvent`] emitted for each component on an entity when it is despawned.
385/// See [`ComponentHooks::on_despawn`](`crate::lifecycle::ComponentHooks::on_despawn`) for more information.
386#[derive(Debug, Clone, EntityEvent)]
387#[entity_event(trigger = EntityComponentsTrigger<'a>)]
388#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
389#[cfg_attr(feature = "bevy_reflect", reflect(Debug))]
390#[doc(alias = "OnDespawn")]
391pub struct Despawn {
392    /// The entity that held this component before it was despawned.
393    pub entity: Entity,
394}
395
396/// Wrapper around [`Entity`] for [`RemovedComponents`].
397/// Internally, `RemovedComponents` uses these as an [`Messages<RemovedComponentEntity>`].
398#[derive(Message, Debug, Clone, Into)]
399#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
400#[cfg_attr(feature = "bevy_reflect", reflect(Debug, Clone))]
401pub struct RemovedComponentEntity(Entity);
402
403/// Wrapper around a [`MessageCursor<RemovedComponentEntity>`] so that we
404/// can differentiate messages between components.
405#[derive(Debug)]
406pub struct RemovedComponentReader<T>
407where
408    T: Component,
409{
410    reader: MessageCursor<RemovedComponentEntity>,
411    marker: PhantomData<T>,
412}
413
414impl<T: Component> Default for RemovedComponentReader<T> {
415    fn default() -> Self {
416        Self {
417            reader: Default::default(),
418            marker: PhantomData,
419        }
420    }
421}
422
423impl<T: Component> Deref for RemovedComponentReader<T> {
424    type Target = MessageCursor<RemovedComponentEntity>;
425    fn deref(&self) -> &Self::Target {
426        &self.reader
427    }
428}
429
430impl<T: Component> DerefMut for RemovedComponentReader<T> {
431    fn deref_mut(&mut self) -> &mut Self::Target {
432        &mut self.reader
433    }
434}
435
436/// Stores the [`RemovedComponents`] event buffers for all types of component in a given [`World`].
437#[derive(Default, Debug)]
438pub struct RemovedComponentMessages {
439    event_sets: SparseSet<ComponentId, Messages<RemovedComponentEntity>>,
440}
441
442impl RemovedComponentMessages {
443    /// Creates an empty storage buffer for component removal messages.
444    pub fn new() -> Self {
445        Self::default()
446    }
447
448    /// For each type of component, swaps the event buffers and clears the oldest event buffer.
449    /// In general, this should be called once per frame/update.
450    pub fn update(&mut self) {
451        for (_component_id, messages) in self.event_sets.iter_mut() {
452            messages.update();
453        }
454    }
455
456    /// Returns an iterator over components and their entity messages.
457    pub fn iter(&self) -> impl Iterator<Item = (&ComponentId, &Messages<RemovedComponentEntity>)> {
458        self.event_sets.iter()
459    }
460
461    /// Gets the event storage for a given component.
462    pub fn get(
463        &self,
464        component_id: impl Into<ComponentId>,
465    ) -> Option<&Messages<RemovedComponentEntity>> {
466        self.event_sets.get(component_id.into())
467    }
468
469    /// Writes a removal message for the specified component.
470    pub fn write(&mut self, component_id: impl Into<ComponentId>, entity: Entity) {
471        self.event_sets
472            .get_or_insert_with(component_id.into(), Default::default)
473            .write(RemovedComponentEntity(entity));
474    }
475}
476
477/// A [`SystemParam`] that yields entities that had their `T` [`Component`]
478/// removed or have been despawned with it.
479///
480/// This acts effectively the same as a [`MessageReader`](crate::message::MessageReader).
481///
482/// Unlike hooks or observers (see the [lifecycle](crate) module docs),
483/// this does not allow you to see which data existed before removal.
484///
485/// If you are using `bevy_ecs` as a standalone crate,
486/// note that the [`RemovedComponents`] list will not be automatically cleared for you,
487/// and will need to be manually flushed using [`World::clear_trackers`](World::clear_trackers).
488///
489/// For users of `bevy` and `bevy_app`, [`World::clear_trackers`](World::clear_trackers) is
490/// automatically called by `bevy_app::App::update` and `bevy_app::SubApp::update`.
491/// For the main world, this is delayed until after all `SubApp`s have run.
492///
493/// # Examples
494///
495/// Basic usage:
496///
497/// ```
498/// # use bevy_ecs::component::Component;
499/// # use bevy_ecs::system::IntoSystem;
500/// # use bevy_ecs::lifecycle::RemovedComponents;
501/// #
502/// # #[derive(Component)]
503/// # struct MyComponent;
504/// fn react_on_removal(mut removed: RemovedComponents<MyComponent>) {
505///     removed.read().for_each(|removed_entity| println!("{}", removed_entity));
506/// }
507/// # bevy_ecs::system::assert_is_system(react_on_removal);
508/// ```
509#[derive(SystemParam)]
510pub struct RemovedComponents<'w, 's, T: Component> {
511    component_id: ComponentIdFor<'s, T>,
512    reader: Local<'s, RemovedComponentReader<T>>,
513    message_sets: &'w RemovedComponentMessages,
514}
515
516/// Iterator over entities that had a specific component removed.
517///
518/// See [`RemovedComponents`].
519pub type RemovedIter<'a> = iter::Map<
520    iter::Flatten<option::IntoIter<iter::Cloned<MessageIterator<'a, RemovedComponentEntity>>>>,
521    fn(RemovedComponentEntity) -> Entity,
522>;
523
524/// Iterator over entities that had a specific component removed.
525///
526/// See [`RemovedComponents`].
527pub type RemovedIterWithId<'a> = iter::Map<
528    iter::Flatten<option::IntoIter<MessageIteratorWithId<'a, RemovedComponentEntity>>>,
529    fn(
530        (&RemovedComponentEntity, MessageId<RemovedComponentEntity>),
531    ) -> (Entity, MessageId<RemovedComponentEntity>),
532>;
533
534fn map_id_messages(
535    (entity, id): (&RemovedComponentEntity, MessageId<RemovedComponentEntity>),
536) -> (Entity, MessageId<RemovedComponentEntity>) {
537    (entity.clone().into(), id)
538}
539
540// For all practical purposes, the api surface of `RemovedComponents<T>`
541// should be similar to `MessageReader<T>` to reduce confusion.
542impl<'w, 's, T: Component> RemovedComponents<'w, 's, T> {
543    /// Fetch underlying [`MessageCursor`].
544    pub fn reader(&self) -> &MessageCursor<RemovedComponentEntity> {
545        &self.reader
546    }
547
548    /// Fetch underlying [`MessageCursor`] mutably.
549    pub fn reader_mut(&mut self) -> &mut MessageCursor<RemovedComponentEntity> {
550        &mut self.reader
551    }
552
553    /// Fetch underlying [`Messages`].
554    pub fn messages(&self) -> Option<&Messages<RemovedComponentEntity>> {
555        self.message_sets.get(self.component_id.get())
556    }
557
558    /// Destructures to get a mutable reference to the `MessageCursor`
559    /// and a reference to `Messages`.
560    ///
561    /// This is necessary since Rust can't detect destructuring through methods and most
562    /// usecases of the reader uses the `Messages` as well.
563    pub fn reader_mut_with_messages(
564        &mut self,
565    ) -> Option<(
566        &mut RemovedComponentReader<T>,
567        &Messages<RemovedComponentEntity>,
568    )> {
569        self.message_sets
570            .get(self.component_id.get())
571            .map(|messages| (&mut *self.reader, messages))
572    }
573
574    /// Iterates over the messages this [`RemovedComponents`] has not seen yet. This updates the
575    /// [`RemovedComponents`]'s message counter, which means subsequent message reads will not include messages
576    /// that happened before now.
577    pub fn read(&mut self) -> RemovedIter<'_> {
578        self.reader_mut_with_messages()
579            .map(|(reader, messages)| reader.read(messages).cloned())
580            .into_iter()
581            .flatten()
582            .map(RemovedComponentEntity::into)
583    }
584
585    /// Like [`read`](Self::read), except also returning the [`MessageId`] of the messages.
586    pub fn read_with_id(&mut self) -> RemovedIterWithId<'_> {
587        self.reader_mut_with_messages()
588            .map(|(reader, messages)| reader.read_with_id(messages))
589            .into_iter()
590            .flatten()
591            .map(map_id_messages)
592    }
593
594    /// Determines the number of removal messages available to be read from this [`RemovedComponents`] without consuming any.
595    pub fn len(&self) -> usize {
596        self.messages()
597            .map(|messages| self.reader.len(messages))
598            .unwrap_or(0)
599    }
600
601    /// Returns `true` if there are no messages available to read.
602    pub fn is_empty(&self) -> bool {
603        self.messages()
604            .is_none_or(|messages| self.reader.is_empty(messages))
605    }
606
607    /// Consumes all available messages.
608    ///
609    /// This means these messages will not appear in calls to [`RemovedComponents::read()`] or
610    /// [`RemovedComponents::read_with_id()`] and [`RemovedComponents::is_empty()`] will return `true`.
611    pub fn clear(&mut self) {
612        if let Some((reader, messages)) = self.reader_mut_with_messages() {
613            reader.clear(messages);
614        }
615    }
616}
617
618// SAFETY: Only reads World removed component messages
619unsafe impl<'a> ReadOnlySystemParam for &'a RemovedComponentMessages {}
620
621// SAFETY: no component value access.
622unsafe impl<'a> SystemParam for &'a RemovedComponentMessages {
623    type State = ();
624    type Item<'w, 's> = &'w RemovedComponentMessages;
625
626    fn init_state(_world: &mut World) -> Self::State {}
627
628    fn init_access(
629        _state: &Self::State,
630        _system_meta: &mut SystemMeta,
631        _component_access_set: &mut FilteredAccessSet,
632        _world: &mut World,
633    ) {
634    }
635
636    #[inline]
637    unsafe fn get_param<'w, 's>(
638        _state: &'s mut Self::State,
639        _system_meta: &SystemMeta,
640        world: UnsafeWorldCell<'w>,
641        _change_tick: Tick,
642    ) -> Result<Self::Item<'w, 's>, SystemParamValidationError> {
643        Ok(world.removed_components())
644    }
645}
bevy_ecs/lifecycle.rs

bevy_ecs/
lifecycle.rs
