Improve debugging tools for change detection (bevyengine#4160)

# Objective

1. Previously, the `change_tick` and `last_change_tick` fields on `SystemChangeTick` [were `pub`](https://docs.rs/bevy/0.6.1/bevy/ecs/system/struct.SystemChangeTick.html).
   1.  This was actively misleading, as while this can be fetched as a `SystemParam`, a copy is returned instead
2. This information could be useful for debugging, but there was no way to investigate when data was changed.
3. There were no docs!

## Solution

1. Move these to a getter method.
2. Add `last_changed` method to the `DetectChanges` trait to enable inspection of when data was last changed.
3. Add docs.

# Changelog

 `SystemChangeTick` now provides getter methods for the current and previous change tick, rather than public fields.
 This can be combined with `DetectChanges::last_changed()` to debug the timing of changes.

# Migration guide

The `change_tick` and `last_change_tick` fields on `SystemChangeTick` are now private, use the corresponding getter method instead.

crates/bevy_ecs/src/change_detection.rs

@@ -42,6 +42,15 @@ pub trait DetectChanges {
  ///
  /// **Note**: This operation is irreversible.
  fn set_changed(&mut self);
+
+ /// Returns the change tick recording the previous time this component (or resource) 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`](crate::system::SystemChangeTick)
+ /// [`SystemParam`](crate::system::SystemParam).
+ fn last_changed(&self) -> u32;
 }
 
 macro_rules! change_detection_impl {
@@ -67,6 +76,11 @@ macro_rules! change_detection_impl {
  .component_ticks
  .set_changed(self.ticks.change_tick);
  }
+
+ #[inline]
+ fn last_changed(&self) -> u32 {
+ self.ticks.last_change_tick
+ }
  }
 
  impl<$($generics),* $(: $traits)?> Deref for $name<$($generics),*> {

crates/bevy_ecs/src/system/system_param.rs

@@ -1164,11 +1164,33 @@ impl<'w, 's> SystemParamFetch<'w, 's> for BundlesState {
  }
 }
 
-/// The [`SystemParamState`] of [`SystemChangeTick`].
+/// A [`SystemParam`] that reads the previous and current change ticks of the system.
+///
+/// A system's change ticks are updated each time it runs:
+/// - `last_change_tick` copies the previous value of `change_tick`
+/// - `change_tick` copies the current value of [`World::read_change_tick`]
+///
+/// Component change ticks that are more recent than `last_change_tick` will be detected by the system.
+/// Those can be read by calling [`last_changed`](crate::change_detection::DetectChanges::last_changed)
+/// on a [`Mut<T>`](crate::change_detection::Mut) or [`ResMut<T>`](crate::change_detection::ResMut).
 #[derive(Debug)]
 pub struct SystemChangeTick {
- pub last_change_tick: u32,
- pub change_tick: u32,
+ last_change_tick: u32,
+ change_tick: u32,
+}
+
+impl SystemChangeTick {
+ /// Returns the current [`World`] change tick seen by the system.
+ #[inline]
+ pub fn change_tick(&self) -> u32 {
+ self.change_tick
+ }
+
+ /// Returns the [`World`] change tick seen by the system the previous time it ran.
+ #[inline]
+ pub fn last_change_tick(&self) -> u32 {
+ self.last_change_tick
+ }
 }
 
 // SAFE: Only reads internal system state