Trait DetectChanges

pub trait DetectChanges {
    type Inner: ?Sized;

    // Required methods
    fn is_added(&self) -> bool;
    fn is_changed(&self) -> bool;
    fn set_changed(&mut self);
    fn last_changed(&self) -> u32;
    fn set_last_changed(&mut self, last_change_tick: u32);
    fn bypass_change_detection(&mut self) -> &mut Self::Inner;
}

Types that implement reliable change detection.

Example

Using types that implement DetectChanges, such as ResMut, provide a way to query if a value has been mutated in another system. Normally change detecting is triggered by either DerefMut or AsMut, however it can be manually triggered via DetectChanges::set_changed.

use bevy_ecs::prelude::*;

#[derive(Resource)]
struct MyResource(u32);

fn my_system(mut resource: ResMut<MyResource>) {
    if resource.is_changed() {
        println!("My resource was mutated!");
    }

   resource.0 = 42; // triggers change detection via [`DerefMut`]
}

Required Associated Types

type Inner: ?Sized

The type contained within this smart pointer

For example, for Res<T> this would be T.

Required Methods

fn is_added(&self) -> bool

Returns true if this value was added after the system last ran.

fn is_changed(&self) -> bool

Returns true if this value was added or mutably dereferenced after the system last ran.

fn set_changed(&mut self)

Flags this value as having been changed.

Mutably accessing this smart pointer will automatically flag this value as having been changed. However, mutation through interior mutability requires manual reporting.

Note: This operation cannot be undone.

fn last_changed(&self) -> u32

Returns the change tick recording the previous time this data was changed.

Note that components and resources are also marked as changed upon insertion.

For comparison, the previous change tick of a system can be read using the SystemChangeTick SystemParam.

fn set_last_changed(&mut self, last_change_tick: u32)

Manually sets the change tick recording the previous time this data was mutated.

Warning

This is a complex and error-prone operation, primarily intended for use with rollback networking strategies. If you merely want to flag this data as changed, use set_changed instead. If you want to avoid triggering change detection, use bypass_change_detection instead.

fn bypass_change_detection(&mut self) -> &mut Self::Inner

Manually bypasses change detection, allowing you to mutate the underlying value without updating the change tick.

Warning

This is a risky operation, that can have unexpected consequences on any system relying on this code. However, it can be an essential escape hatch when, for example, you are trying to synchronize representations using change detection and need to avoid infinite recursion.

Implementors

impl<'a> DetectChanges for MutUntyped<'a>

type Inner = PtrMut<'a>

impl<'a, T> DetectChanges for Mut<'a, T>

where T: ?Sized,

type Inner = T

impl<'a, T> DetectChanges for NonSendMut<'a, T>

where T: ?Sized,

type Inner = T

impl<'a, T> DetectChanges for ResMut<'a, T>

where T: Resource + ?Sized,

type Inner = T