add max delta

Author: maniwani

crates/bevy_time/src/clock.rs

@@ -29,15 +29,15 @@ pub struct Clock {
 impl Default for Clock {
     fn default() -> Self {
         Self {
+            startup: Instant::now(),
+            first_update: None,
+            last_update: None,
             delta: Duration::ZERO,
             delta_seconds: 0.0,
             delta_seconds_f64: 0.0,
             elapsed: Duration::ZERO,
             elapsed_seconds: 0.0,
             elapsed_seconds_f64: 0.0,
-            startup: Instant::now(),
-            first_update: None,
-            last_update: None,
             wrap_period: Duration::from_secs(3600), // 1 hour
             elapsed_wrapped: Duration::ZERO,
             elapsed_seconds_wrapped: 0.0,
@@ -55,7 +55,8 @@ impl Clock {
         }
     }
 
-    pub fn tick(&mut self, dt: Duration, instant: Instant) {
+    /// Advances the clock by `dt` and records it happening at `instant`.
+    pub fn update(&mut self, dt: Duration, instant: Instant) {
         self.delta = dt;
         self.delta_seconds = self.delta.as_secs_f32();
         self.delta_seconds_f64 = self.delta.as_secs_f64();

crates/bevy_time/src/fixed_timestep.rs

@@ -16,7 +16,7 @@ use bevy_utils::{default, Duration, Instant};
 
 use crate::{Time, TimeContext};
 
-/// The step size (and some metadata) for the `FixedUpdate` schedule .
+/// The step size (and some metadata) for the `FixedUpdate` schedule.
 #[derive(Resource, Debug, Clone, Copy)]
 pub struct FixedTimestep {
     size: Duration,

crates/bevy_time/src/lib.rs

@@ -67,17 +67,17 @@ impl Plugin for TimePlugin {
     }
 }
 
-/// Configuration resource used to determine how the time system should run.
+/// Determines how the duration of app updates are measured.
 ///
-/// For most cases, [`TimeUpdateStrategy::Automatic`] is fine. When writing tests, dealing with networking, or similar
-/// you may prefer to set the next [`Time`] value manually.
-#[derive(Resource, Default)]
+/// Most users should leave this as [`TimeUpdateStrategy::Automatic`]. The other variants are provided to
+/// make writing tests and similar logic easier.
+#[derive(Resource, Default, Clone, Copy)]
 pub enum TimeUpdateStrategy {
     #[default]
     Automatic,
-    // Update [`Time`] with an exact `Instant` value
+    /// The duration of the update will be the duration between its last update and the given [`Instant`].
     ManualInstant(Instant),
-    // Update [`Time`] with the last update time + a specified `Duration`
+    /// The duration of the update will be the given [`Duration`].
     ManualDuration(Duration),
 }
 
@@ -104,11 +104,12 @@ fn time_system(
     mut time: ResMut<Time>,
     mut real_time: ResMut<RealTime>,
     mut fixed_timestep: ResMut<FixedTimestep>,
-    update_strategy: Res<TimeUpdateStrategy>,
+    strategy: Res<TimeUpdateStrategy>,
     time_recv: Option<Res<TimeReceiver>>,
     mut has_received_time: Local<bool>,
 ) {
-    let real_frame_start = if let Some(time_recv) = time_recv {
+    assert!(matches!(time.context(), TimeContext::Update));
+    let frame_start = if let Some(time_recv) = time_recv {
         // TODO: Figure out how to handle this when using pipelined rendering.
         if let Ok(instant) = time_recv.0.try_recv() {
             *has_received_time = true;
@@ -123,22 +124,21 @@ fn time_system(
         Instant::now()
     };
 
-    // update real time clock
-    real_time.update_with_instant(real_frame_start);
-
-    let virtual_frame_start = match update_strategy.as_ref() {
-        TimeUpdateStrategy::Automatic => real_frame_start,
+    let frame_start = match strategy.as_ref() {
+        TimeUpdateStrategy::Automatic => frame_start,
         TimeUpdateStrategy::ManualInstant(instant) => *instant,
         TimeUpdateStrategy::ManualDuration(duration) => {
             let last_update = time.last_update().unwrap_or(time.startup());
             last_update.checked_add(*duration).unwrap()
         }
     };
 
+    // update real time clock
+    real_time.update_with_instant(frame_start);
+
     // update virtual time clock
-    // TODO: limit how much time can be advanced in a single frame (e.g. Unity's maximumDeltaTime)
-    time.update_with_instant(virtual_frame_start);
+    time.update_with_instant(frame_start);
 
-    // accumulate virtual time delta
+    // accumulate
     fixed_timestep.accumulate(time.delta());
 }

crates/bevy_time/src/time.rs

@@ -15,11 +15,11 @@ pub struct Time {
     context: TimeContext,
     update: Clock,
     fixed_update: Clock,
-    // settings
     paused: bool,
     next_paused: Option<bool>,
     relative_speed: f64, // using `f64` instead of `f32` to minimize drift from rounding errors
     next_relative_speed: Option<f64>,
+    max_delta: Duration,
 }
 
 /// [`Time`] stores two clocks that are synchronized but advance at different rates.
@@ -41,6 +41,7 @@ impl Default for Time {
             next_paused: None,
             relative_speed: 1.0,
             next_relative_speed: None,
+            max_delta: Duration::from_millis(500),
         }
     }
 }
@@ -156,8 +157,17 @@ impl Time {
                 self.apply_pending_changes();
 
                 // zero for first update
-                let dt = instant - self.current_clock().last_update().unwrap_or(instant);
-                let dt = if self.paused {
+                let mut dt = instant - self.update.last_update().unwrap_or(instant);
+
+                if dt > self.max_delta {
+                    warn!(
+                        "update delta time {:?} is larger than the maximum {:?}",
+                        dt, self.max_delta
+                    );
+                    dt = self.max_delta;
+                }
+
+                dt = if self.paused {
                     Duration::ZERO
                 } else if self.relative_speed != 1.0 {
                     dt.mul_f64(self.relative_speed)
@@ -166,7 +176,7 @@ impl Time {
                     dt
                 };
 
-                self.update.tick(dt, instant);
+                self.update.update(dt, instant);
             }
             TimeContext::FixedUpdate => {
                 warn!("In the `FixedUpdate` context, `Time` can only be advanced via `tick`.");
@@ -175,7 +185,7 @@ impl Time {
     }
 
     pub(crate) fn tick(&mut self, dt: Duration, instant: Instant) {
-        self.current_clock_mut().tick(dt, instant);
+        self.current_clock_mut().update(dt, instant);
     }
 
     /// Applies pending pause or relative speed changes.
@@ -376,6 +386,27 @@ impl Time {
     pub fn is_paused(&self) -> bool {
         self.paused
     }
+
+    /// Returns the maximum value of [`delta`](#method.delta) (*before* scaling) for any given update.
+    #[inline]
+    pub fn max_delta(&self) -> Duration {
+        self.max_delta
+    }
+
+    /// Sets the maximum value of [`delta`](#method.delta) (*before* scaling) for any given update.
+    ///
+    /// After an unusually long update, this value limits the value of [`delta`](#method.delta)
+    /// in the next update to avoid the app falling into a "death spiral" where each update has an
+    /// ever-increasing number of `FixedUpdate` steps to run.
+    ///
+    /// Without this setting, anything that results in an exceptionally long time passing between
+    /// app updates (e.g. the program was suspended) would cause time to jump forward a lot and
+    /// rack up a large simulation debt.
+    #[inline]
+    pub fn set_max_delta(&mut self, max_delta: Duration) {
+        assert!(!max_delta.is_zero());
+        self.max_delta = max_delta;
+    }
 }
 
 /// A clock that tracks how much actual time has elasped since the last update and since startup.
@@ -407,7 +438,7 @@ impl RealTime {
     pub fn update_with_instant(&mut self, instant: Instant) {
         // zero for first update
         let dt = instant - self.0.last_update().unwrap_or(instant);
-        self.0.tick(dt, instant);
+        self.0.update(dt, instant);
     }
 
     /// Returns the [`Instant`] the clock was created.
@@ -608,6 +639,9 @@ mod tests {
         let mut time = Time::new(startup);
         time.set_wrap_period(Duration::from_secs(3));
 
+        // disable maximum delta for this test
+        time.set_max_delta(Duration::MAX);
+
         assert_eq!(time.elapsed_seconds_wrapped(), 0.0);
 
         // time starts counting from first update
@@ -633,6 +667,9 @@ mod tests {
         let mut time = Time::new(startup);
         let mut real_time = RealTime::new(startup);
 
+        // disable maximum delta for this test
+        time.set_max_delta(Duration::MAX);
+
         let first_update = Instant::now();
         time.update_with_instant(first_update);
         real_time.update_with_instant(first_update);