Reliable change detection (#1471)

# Problem Definition

The current change tracking (via flags for both components and resources) fails to detect changes made by systems that are scheduled to run earlier in the frame than they are.

This issue is discussed at length in [#68](#68) and [#54](#54).

This is very much a draft PR, and contributions are welcome and needed.

# Criteria
1. Each change is detected at least once, no matter the ordering.
2. Each change is detected at most once, no matter the ordering.
3. Changes should be detected the same frame that they are made.
4. Competitive ergonomics. Ideally does not require opting-in.
5. Low CPU overhead of computation.
6. Memory efficient. This must not increase over time, except where the number of entities / resources does.
7. Changes should not be lost for systems that don't run.
8. A frame needs to act as a pure function. Given the same set of entities / components it needs to produce the same end state without side-effects.

**Exact** change-tracking proposals satisfy criteria 1 and 2.
**Conservative** change-tracking proposals satisfy criteria 1 but not 2.
**Flaky** change tracking proposals satisfy criteria 2 but not 1.

# Code Base Navigation

There are three types of flags: 
- `Added`: A piece of data was added to an entity / `Resources`.
- `Mutated`: A piece of data was able to be modified, because its `DerefMut` was accessed
- `Changed`: The bitwise OR of `Added` and `Changed`

The special behavior of `ChangedRes`, with respect to the scheduler is being removed in [#1313](#1313) and does not need to be reproduced.

`ChangedRes` and friends can be found in "bevy_ecs/core/resources/resource_query.rs".

The `Flags` trait for Components can be found in "bevy_ecs/core/query.rs".

`ComponentFlags` are stored in "bevy_ecs/core/archetypes.rs", defined on line 446.

# Proposals

**Proposal 5 was selected for implementation.**

## Proposal 0: No Change Detection

The baseline, where computations are performed on everything regardless of whether it changed.

**Type:** Conservative

**Pros:**
- already implemented
- will never miss events
- no overhead

**Cons:**
- tons of repeated work
- doesn't allow users to avoid repeating work (or monitoring for other changes)

## Proposal 1: Earlier-This-Tick Change Detection

The current approach as of Bevy 0.4. Flags are set, and then flushed at the end of each frame.

**Type:** Flaky

**Pros:**
- already implemented
- simple to understand
- low memory overhead (2 bits per component)
- low time overhead (clear every flag once per frame)

**Cons:**
- misses systems based on ordering
- systems that don't run every frame miss changes
- duplicates detection when looping
- can lead to unresolvable circular dependencies

## Proposal 2: Two-Tick Change Detection

Flags persist for two frames, using a double-buffer system identical to that used in events.

A change is observed if it is found in either the current frame's list of changes or the previous frame's.

**Type:** Conservative

**Pros:**
- easy to understand
- easy to implement
- low memory overhead (4 bits per component)
- low time overhead (bit mask and shift every flag once per frame)

**Cons:**
- can result in a great deal of duplicated work
- systems that don't run every frame miss changes
- duplicates detection when looping

## Proposal 3: Last-Tick Change Detection

Flags persist for two frames, using a double-buffer system identical to that used in events.

A change is observed if it is found in the previous frame's list of changes.

**Type:** Exact

**Pros:**
- exact
- easy to understand
- easy to implement
- low memory overhead (4 bits per component)
- low time overhead (bit mask and shift every flag once per frame)

**Cons:**
- change detection is always delayed, possibly causing painful chained delays
- systems that don't run every frame miss changes
- duplicates detection when looping

## Proposal 4: Flag-Doubling Change Detection

Combine Proposal 2 and Proposal 3. Differentiate between `JustChanged` (current behavior) and `Changed` (Proposal 3).

Pack this data into the flags according to [this implementation proposal](#68 (comment)).

**Type:** Flaky + Exact

**Pros:**
- allows users to acc
- easy to implement
- low memory overhead (4 bits per component)
- low time overhead (bit mask and shift every flag once per frame)

**Cons:**
- users must specify the type of change detection required
- still quite fragile to system ordering effects when using the flaky `JustChanged` form
- cannot get immediate + exact results
- systems that don't run every frame miss changes
- duplicates detection when looping

## [SELECTED] Proposal 5: Generation-Counter Change Detection

A global counter is increased after each system is run. Each component saves the time of last mutation, and each system saves the time of last execution. Mutation is detected when the component's counter is greater than the system's counter. Discussed [here](#68 (comment)). How to handle addition detection is unsolved; the current proposal is to use the highest bit of the counter as in proposal 1.

**Type:** Exact (for mutations), flaky (for additions)

**Pros:**
- low time overhead (set component counter on access, set system counter after execution)
- robust to systems that don't run every frame
- robust to systems that loop

**Cons:**
- moderately complex implementation
- must be modified as systems are inserted dynamically
- medium memory overhead (4 bytes per component + system)
- unsolved addition detection

## Proposal 6: System-Data Change Detection

For each system, track which system's changes it has seen. This approach is only worth fully designing and implementing if Proposal 5 fails in some way.  

**Type:** Exact

**Pros:**
- exact
- conceptually simple

**Cons:**
- requires storing data on each system
- implementation is complex
- must be modified as systems are inserted dynamically

## Proposal 7: Total-Order Change Detection

Discussed [here](#68 (comment)). This proposal is somewhat complicated by the new scheduler, but I believe it should still be conceptually feasible. This approach is only worth fully designing and implementing if Proposal 5 fails in some way.  

**Type:** Exact

**Pros:**
- exact
- efficient data storage relative to other exact proposals

**Cons:**
- requires access to the scheduler
- complex implementation and difficulty grokking
- must be modified as systems are inserted dynamically

# Tests

- We will need to verify properties 1, 2, 3, 7 and 8. Priority: 1 > 2 = 3 > 8 > 7
- Ideally we can use identical user-facing syntax for all proposals, allowing us to re-use the same syntax for each.
- When writing tests, we need to carefully specify order using explicit dependencies.
- These tests will need to be duplicated for both components and resources.
- We need to be sure to handle cases where ambiguous system orders exist.

`changing_system` is always the system that makes the changes, and `detecting_system` always detects the changes.

The component / resource changed will be simple boolean wrapper structs.

## Basic Added / Mutated / Changed

2 x 3 design:
- Resources vs. Components
- Added vs. Changed vs. Mutated
- `changing_system` runs before `detecting_system`
- verify at the end of tick 2

## At Least Once

2 x 3 design:
- Resources vs. Components
- Added vs. Changed vs. Mutated
- `changing_system` runs after `detecting_system`
- verify at the end of tick 2

## At Most Once

2 x 3 design:
- Resources vs. Components
- Added vs. Changed vs. Mutated
- `changing_system` runs once before `detecting_system`
- increment a counter based on the number of changes detected
- verify at the end of tick 2

## Fast Detection
2 x 3 design:
- Resources vs. Components
- Added vs. Changed vs. Mutated
- `changing_system` runs before `detecting_system`
- verify at the end of tick 1

## Ambiguous System Ordering Robustness
2 x 3 x 2 design:
- Resources vs. Components
- Added vs. Changed vs. Mutated
- `changing_system` runs [before/after] `detecting_system` in tick 1
- `changing_system` runs [after/before] `detecting_system` in tick 2

## System Pausing
2 x 3 design:
- Resources vs. Components
- Added vs. Changed vs. Mutated
- `changing_system` runs in tick 1, then is disabled by run criteria
- `detecting_system` is disabled by run criteria until it is run once during tick 3
- verify at the end of tick 3

## Addition Causes Mutation

2 design:
- Resources vs. Components
- `adding_system_1` adds a component / resource
- `adding system_2` adds the same component / resource
- verify the `Mutated` flag at the end of the tick
- verify the `Added` flag at the end of the tick

First check tests for: #333
Second check tests for: #1443

## Changes Made By Commands

- `adding_system` runs in Update in tick 1, and sends a command to add a component 
- `detecting_system` runs in Update in tick 1 and 2, after `adding_system`
- We can't detect the changes in tick 1, since they haven't been processed yet
- If we were to track these changes as being emitted by `adding_system`, we can't detect the changes in tick 2 either, since `detecting_system` has already run once after `adding_system` :( 

# Benchmarks

See: [general advice](https://github.com/bevyengine/bevy/blob/master/docs/profiling.md), [Criterion crate](https://github.com/bheisler/criterion.rs)

There are several critical parameters to vary: 
1. entity count (1 to 10^9)
2. fraction of entities that are changed (0% to 100%)
3. cost to perform work on changed entities, i.e. workload (1 ns to 1s)

1 and 2 should be varied between benchmark runs. 3 can be added on computationally.

We want to measure:
- memory cost
- run time

We should collect these measurements across several frames (100?) to reduce bootup effects and accurately measure the mean, variance and drift.

Entity-component change detection is much more important to benchmark than resource change detection, due to the orders of magnitude higher number of pieces of data.

No change detection at all should be included in benchmarks as a second control for cases where missing changes is unacceptable.

## Graphs
1. y: performance, x: log_10(entity count), color: proposal, facet: performance metric. Set cost to perform work to 0. 
2. y: run time, x: cost to perform work, color: proposal, facet: fraction changed. Set number of entities to 10^6
3. y: memory, x: frames, color: proposal

# Conclusions
1. Is the theoretical categorization of the proposals correct according to our tests?
2. How does the performance of the proposals compare without any load?
3. How does the performance of the proposals compare with realistic loads?
4. At what workload does more exact change tracking become worth the (presumably) higher overhead?
5. When does adding change-detection to save on work become worthwhile?
6. Is there enough divergence in performance between the best solutions in each class to ship more than one change-tracking solution?

# Implementation Plan

1. Write a test suite.
2. Verify that tests fail for existing approach.
3. Write a benchmark suite.
4. Get performance numbers for existing approach.
5. Implement, test and benchmark various solutions using a Git branch per proposal.
6. Create a draft PR with all solutions and present results to team.
7. Select a solution and replace existing change detection.

Co-authored-by: Brice DAVIER <[email protected]>
Co-authored-by: Carter Anderson <[email protected]>

Author: 3 people

crates/bevy_core/src/time/fixed_timestep.rs

@@ -196,4 +196,8 @@ impl System for FixedTimestep {
             );
         }
     }
+
+    fn check_change_tick(&mut self, change_tick: u32) {
+        self.internal_system.check_change_tick(change_tick);
+    }
 }

crates/bevy_ecs/macros/src/lib.rs

@@ -270,11 +270,12 @@ pub fn impl_query_set(_input: TokenStream) -> TokenStream {
                 #[inline]
                 unsafe fn get_param(
                     state: &'a mut Self,
-                    _system_state: &'a SystemState,
+                    system_state: &'a SystemState,
                     world: &'a World,
+                    change_tick: u32,
                 ) -> Self::Item {
                     let (#(#query,)*) = &state.0;
-                    QuerySet((#(Query::new(world, #query),)*))
+                    QuerySet((#(Query::new(world, #query, system_state.last_change_tick, change_tick),)*))
                 }
             }
 
@@ -402,9 +403,10 @@ pub fn derive_system_param(input: TokenStream) -> TokenStream {
                 state: &'a mut Self,
                 system_state: &'a #path::system::SystemState,
                 world: &'a #path::world::World,
+                change_tick: u32,
             ) -> Self::Item {
                 #struct_name {
-                    #(#fields: <<#field_types as SystemParam>::Fetch as #path::system::SystemParamFetch>::get_param(&mut state.state.#field_indices, system_state, world),)*
+                    #(#fields: <<#field_types as SystemParam>::Fetch as #path::system::SystemParamFetch>::get_param(&mut state.state.#field_indices, system_state, world, change_tick),)*
                     #(#ignored_fields: <#ignored_field_types>::default(),)*
                 }
             }

crates/bevy_ecs/src/archetype.rs

@@ -1,6 +1,6 @@
 use crate::{
     bundle::BundleId,
-    component::{ComponentFlags, ComponentId, StorageType},
+    component::{ComponentId, StorageType},
     entity::{Entity, EntityLocation},
     storage::{Column, SparseArray, SparseSet, SparseSetIndex, TableId},
 };
@@ -36,9 +36,14 @@ impl ArchetypeId {
     }
 }
 
+pub enum ComponentStatus {
+    Added,
+    Mutated,
+}
+
 pub struct FromBundle {
     pub archetype_id: ArchetypeId,
-    pub bundle_flags: Vec<ComponentFlags>,
+    pub bundle_status: Vec<ComponentStatus>,
 }
 
 #[derive(Default)]
@@ -70,13 +75,13 @@ impl Edges {
         &mut self,
         bundle_id: BundleId,
         archetype_id: ArchetypeId,
-        bundle_flags: Vec<ComponentFlags>,
+        bundle_status: Vec<ComponentStatus>,
     ) {
         self.from_bundle.insert(
             bundle_id,
             FromBundle {
                 archetype_id,
-                bundle_flags,
+                bundle_status,
             },
         );
     }

crates/bevy_ecs/src/bundle.rs

@@ -1,7 +1,8 @@
 pub use bevy_ecs_macros::Bundle;
 
 use crate::{
-    component::{Component, ComponentFlags, ComponentId, Components, StorageType, TypeInfo},
+    archetype::ComponentStatus,
+    component::{Component, ComponentId, ComponentTicks, Components, StorageType, TypeInfo},
     entity::Entity,
     storage::{SparseSetIndex, SparseSets, Table},
 };
@@ -123,32 +124,56 @@ pub struct BundleInfo {
 impl BundleInfo {
     /// # Safety
     /// table row must exist, entity must be valid
+    #[allow(clippy::clippy::too_many_arguments)]
     #[inline]
     pub(crate) unsafe fn write_components<T: Bundle>(
         &self,
         sparse_sets: &mut SparseSets,
         entity: Entity,
         table: &Table,
         table_row: usize,
-        bundle_flags: &[ComponentFlags],
+        bundle_status: &[ComponentStatus],
         bundle: T,
+        change_tick: u32,
     ) {
         // NOTE: get_components calls this closure on each component in "bundle order".
         // bundle_info.component_ids are also in "bundle order"
         let mut bundle_component = 0;
         bundle.get_components(|component_ptr| {
             // SAFE: component_id was initialized by get_dynamic_bundle_info
             let component_id = *self.component_ids.get_unchecked(bundle_component);
-            let flags = *bundle_flags.get_unchecked(bundle_component);
+            let component_status = bundle_status.get_unchecked(bundle_component);
             match self.storage_types[bundle_component] {
                 StorageType::Table => {
                     let column = table.get_column(component_id).unwrap();
                     column.set_unchecked(table_row, component_ptr);
-                    column.get_flags_unchecked_mut(table_row).insert(flags);
+                    let column_status = column.get_ticks_unchecked_mut(table_row);
+                    match component_status {
+                        ComponentStatus::Added => {
+                            *column_status = ComponentTicks::new(change_tick);
+                        }
+                        ComponentStatus::Mutated => {
+                            column_status.set_changed(change_tick);
+                        }
+                    }
                 }
                 StorageType::SparseSet => {
                     let sparse_set = sparse_sets.get_mut(component_id).unwrap();
-                    sparse_set.insert(entity, component_ptr, flags);
+                    match component_status {
+                        ComponentStatus::Added => {
+                            sparse_set.insert(
+                                entity,
+                                component_ptr,
+                                ComponentTicks::new(change_tick),
+                            );
+                        }
+                        ComponentStatus::Mutated => {
+                            sparse_set
+                                .get_ticks(entity)
+                                .unwrap()
+                                .set_changed(change_tick);
+                        }
+                    }
                 }
             }
             bundle_component += 1;

crates/bevy_ecs/src/component/mod.rs

@@ -3,7 +3,6 @@ mod type_info;
 pub use type_info::*;
 
 use crate::storage::SparseSetIndex;
-use bitflags::bitflags;
 use std::{
     alloc::Layout,
     any::{Any, TypeId},
@@ -303,9 +302,55 @@ impl Components {
     }
 }
 
-bitflags! {
-    pub struct ComponentFlags: u8 {
-        const ADDED = 1;
-        const MUTATED = 2;
+#[derive(Copy, Clone, Debug)]
+pub struct ComponentTicks {
+    pub(crate) added: u32,
+    pub(crate) changed: u32,
+}
+
+impl ComponentTicks {
+    #[inline]
+    pub fn is_added(&self, last_change_tick: u32, change_tick: u32) -> bool {
+        // The comparison is relative to `change_tick` so that we can detect changes over the whole
+        // `u32` range. Comparing directly the ticks would limit to half that due to overflow
+        // handling.
+        let component_delta = change_tick.wrapping_sub(self.added);
+        let system_delta = change_tick.wrapping_sub(last_change_tick);
+
+        component_delta < system_delta
+    }
+
+    #[inline]
+    pub fn is_changed(&self, last_change_tick: u32, change_tick: u32) -> bool {
+        let component_delta = change_tick.wrapping_sub(self.changed);
+        let system_delta = change_tick.wrapping_sub(last_change_tick);
+
+        component_delta < system_delta
+    }
+
+    pub(crate) fn new(change_tick: u32) -> Self {
+        Self {
+            added: change_tick,
+            changed: change_tick,
+        }
+    }
+
+    pub(crate) fn check_ticks(&mut self, change_tick: u32) {
+        check_tick(&mut self.added, change_tick);
+        check_tick(&mut self.changed, change_tick);
+    }
+
+    #[inline]
+    pub(crate) fn set_changed(&mut self, change_tick: u32) {
+        self.changed = change_tick;
+    }
+}
+
+fn check_tick(last_change_tick: &mut u32, change_tick: u32) {
+    let tick_delta = change_tick.wrapping_sub(*last_change_tick);
+    const MAX_DELTA: u32 = (u32::MAX / 4) * 3;
+    // Clamp to max delta
+    if tick_delta > MAX_DELTA {
+        *last_change_tick = change_tick.wrapping_sub(MAX_DELTA);
     }
 }