From be24106f600be6029e4c6f1ccf99ae975a8f0c2a Mon Sep 17 00:00:00 2001
From: Cameron <51241057+maniwani@users.noreply.github.com>
Date: Fri, 23 Jun 2023 19:05:14 -0700
Subject: [PATCH] split `Time` into two clocks, make it work in `FixedUpdate`
 too

---
 crates/bevy_time/src/clock.rs             | 182 ++++++
 crates/bevy_time/src/common_conditions.rs |  47 +-
 crates/bevy_time/src/fixed_timestep.rs    | 250 ++++----
 crates/bevy_time/src/lib.rs               |  57 +-
 crates/bevy_time/src/time.rs              | 734 ++++++++++++----------
 5 files changed, 763 insertions(+), 507 deletions(-)
 create mode 100644 crates/bevy_time/src/clock.rs

diff --git a/crates/bevy_time/src/clock.rs b/crates/bevy_time/src/clock.rs
new file mode 100644
index 0000000000000..c865be4c3fc0c
--- /dev/null
+++ b/crates/bevy_time/src/clock.rs
@@ -0,0 +1,182 @@
+use bevy_reflect::{FromReflect, Reflect};
+use bevy_utils::{default, Duration, Instant};
+
+fn duration_div_rem(dividend: Duration, divisor: Duration) -> (u32, Duration) {
+    // `Duration` does not have a built-in modulo operation
+    let quotient = (dividend.as_nanos() / divisor.as_nanos()) as u32;
+    let remainder = dividend - (quotient * divisor);
+    (quotient, remainder)
+}
+
+/// A stopwatch that tracks the time since last update and the time since creation.
+#[derive(Debug, Clone, Copy, Reflect, FromReflect, PartialEq)]
+pub struct Clock {
+    startup: Instant,
+    first_update: Option<Instant>,
+    last_update: Option<Instant>,
+    delta: Duration,
+    delta_seconds: f32,
+    delta_seconds_f64: f64,
+    elapsed: Duration,
+    elapsed_seconds: f32,
+    elapsed_seconds_f64: f64,
+    wrap_period: Duration,
+    elapsed_wrapped: Duration,
+    elapsed_seconds_wrapped: f32,
+    elapsed_seconds_wrapped_f64: f64,
+}
+
+impl Default for Clock {
+    fn default() -> Self {
+        Self {
+            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,
+            elapsed_seconds_wrapped_f64: 0.0,
+        }
+    }
+}
+
+impl Clock {
+    /// Constructs a new `Clock` instance with a specific startup `Instant`.
+    pub fn new(startup: Instant) -> Self {
+        Self {
+            startup,
+            ..default()
+        }
+    }
+
+    pub fn tick(&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();
+
+        self.elapsed += dt;
+        self.elapsed_seconds = self.elapsed.as_secs_f32();
+        self.elapsed_seconds_f64 = self.elapsed.as_secs_f64();
+
+        self.elapsed_wrapped = duration_div_rem(self.elapsed, self.wrap_period).1;
+        self.elapsed_seconds_wrapped = self.elapsed_wrapped.as_secs_f32();
+        self.elapsed_seconds_wrapped_f64 = self.elapsed_wrapped.as_secs_f64();
+
+        if self.last_update.is_none() {
+            self.first_update = Some(instant);
+        }
+
+        self.last_update = Some(instant);
+    }
+
+    /// Returns the [`Instant`] the clock was created.
+    #[inline]
+    pub fn startup(&self) -> Instant {
+        self.startup
+    }
+
+    /// Returns the [`Instant`] when [`update`](#method.update) was first called, if it exists.
+    #[inline]
+    pub fn first_update(&self) -> Option<Instant> {
+        self.first_update
+    }
+
+    /// Returns the [`Instant`] when [`update`](#method.update) was last called, if it exists.
+    #[inline]
+    pub fn last_update(&self) -> Option<Instant> {
+        self.last_update
+    }
+
+    /// Returns how much time has advanced since the last [`update`](#method.update), as a [`Duration`].
+    #[inline]
+    pub fn delta(&self) -> Duration {
+        self.delta
+    }
+
+    /// Returns how much time has advanced since the last [`update`](#method.update), as [`f32`] seconds.
+    #[inline]
+    pub fn delta_seconds(&self) -> f32 {
+        self.delta_seconds
+    }
+
+    /// Returns how much time has advanced since the last [`update`](#method.update), as [`f64`] seconds.
+    #[inline]
+    pub fn delta_seconds_f64(&self) -> f64 {
+        self.delta_seconds_f64
+    }
+
+    /// Returns how much time has advanced since [`startup`](#method.startup), as [`Duration`].
+    #[inline]
+    pub fn elapsed(&self) -> Duration {
+        self.elapsed
+    }
+
+    /// Returns how much time has advanced since [`startup`](#method.startup), as [`f32`] seconds.
+    ///
+    /// **Note:** This is a monotonically increasing value. It's precision will degrade over time.
+    /// If you need an `f32` but that precision loss is unacceptable,
+    /// use [`elapsed_seconds_wrapped`](#method.elapsed_seconds_wrapped).
+    #[inline]
+    pub fn elapsed_seconds(&self) -> f32 {
+        self.elapsed_seconds
+    }
+
+    /// Returns how much time has advanced since [`startup`](#method.startup), as [`f64`] seconds.
+    #[inline]
+    pub fn elapsed_seconds_f64(&self) -> f64 {
+        self.elapsed_seconds_f64
+    }
+
+    /// Returns how much time has advanced since [`startup`](#method.startup) modulo
+    /// the [`wrap_period`](#method.wrap_period), as [`Duration`].
+    #[inline]
+    pub fn elapsed_wrapped(&self) -> Duration {
+        self.elapsed_wrapped
+    }
+
+    /// Returns how much time has advanced since [`startup`](#method.startup) modulo
+    /// the [`wrap_period`](#method.wrap_period), as [`f32`] seconds.
+    ///
+    /// This method is intended for applications (e.g. shaders) that require an [`f32`] value but
+    /// suffer from the gradual precision loss of [`elapsed_seconds`](#method.elapsed_seconds).
+    #[inline]
+    pub fn elapsed_seconds_wrapped(&self) -> f32 {
+        self.elapsed_seconds_wrapped
+    }
+
+    /// Returns how much time has advanced since [`startup`](#method.startup) modulo
+    /// the [`wrap_period`](#method.wrap_period), as [`f64`] seconds.
+    #[inline]
+    pub fn elapsed_seconds_wrapped_f64(&self) -> f64 {
+        self.elapsed_seconds_wrapped_f64
+    }
+
+    /// Returns the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
+    /// [`elapsed_wrapped`](#method.elapsed_wrapped).
+    ///
+    /// **Note:** The default modulus is one hour.
+    #[inline]
+    pub fn wrap_period(&self) -> Duration {
+        self.wrap_period
+    }
+
+    /// Sets the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
+    /// [`elapsed_wrapped`](#method.elapsed_wrapped).
+    ///
+    /// **Note:** This will not take effect until the next update.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `wrap_period` is a zero-length duration.
+    #[inline]
+    pub fn set_wrap_period(&mut self, wrap_period: Duration) {
+        assert!(!wrap_period.is_zero(), "division by zero");
+        self.wrap_period = wrap_period;
+    }
+}
diff --git a/crates/bevy_time/src/common_conditions.rs b/crates/bevy_time/src/common_conditions.rs
index 974de24dfae2c..f17c25cee25e1 100644
--- a/crates/bevy_time/src/common_conditions.rs
+++ b/crates/bevy_time/src/common_conditions.rs
@@ -1,12 +1,10 @@
-use crate::{fixed_timestep::FixedTime, Time, Timer, TimerMode};
+use crate::{Time, Timer, TimerMode};
 use bevy_ecs::system::Res;
 use bevy_utils::Duration;
 
 /// Run condition that is active on a regular time interval, using [`Time`] to advance
 /// the timer.
 ///
-/// If used for a fixed timestep system, use [`on_fixed_timer`] instead.
-///
 /// ```rust,no_run
 /// # use bevy_app::{App, NoopPluginGroup as DefaultPlugins, PluginGroup, Update};
 /// # use bevy_ecs::schedule::IntoSystemConfigs;
@@ -29,9 +27,8 @@ use bevy_utils::Duration;
 /// times. This condition should only be used with large time durations (relative to
 /// delta time).
 ///
-/// For more accurate timers, use the [`Timer`] class directly (see
-/// [`Timer::times_finished_this_tick`] to address the problem mentioned above), or
-/// use fixed timesteps that allow systems to run multiple times per frame.
+/// To create a more precise timer, use the [`Timer`] class directly (see
+/// [`Timer::times_finished_this_tick`], which can address the issue described above).
 pub fn on_timer(duration: Duration) -> impl FnMut(Res<Time>) -> bool + Clone {
     let mut timer = Timer::new(duration, TimerMode::Repeating);
     move |time: Res<Time>| {
@@ -40,40 +37,6 @@ pub fn on_timer(duration: Duration) -> impl FnMut(Res<Time>) -> bool + Clone {
     }
 }
 
-/// Run condition that is active on a regular time interval, using [`FixedTime`] to
-/// advance the timer.
-///
-/// If used for a non-fixed timestep system, use [`on_timer`] instead.
-///
-/// ```rust,no_run
-/// # use bevy_app::{App, NoopPluginGroup as DefaultPlugins, PluginGroup, FixedUpdate};
-/// # use bevy_ecs::schedule::IntoSystemConfigs;
-/// # use bevy_utils::Duration;
-/// # use bevy_time::common_conditions::on_fixed_timer;
-/// fn main() {
-///     App::new()
-///         .add_plugins(DefaultPlugins)
-///         .add_systems(FixedUpdate,
-///             tick.run_if(on_fixed_timer(Duration::from_secs(1))),
-///         )
-///         .run();
-/// }
-/// fn tick() {
-///     // ran once a second
-/// }
-/// ```
-///
-/// Note that this run condition may not behave as expected if `duration` is smaller
-/// than the fixed timestep period, since the timer may complete multiple times in
-/// one fixed update.
-pub fn on_fixed_timer(duration: Duration) -> impl FnMut(Res<FixedTime>) -> bool + Clone {
-    let mut timer = Timer::new(duration, TimerMode::Repeating);
-    move |time: Res<FixedTime>| {
-        timer.tick(time.period);
-        timer.just_finished()
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -85,9 +48,7 @@ mod tests {
     #[test]
     fn distributive_run_if_compiles() {
         Schedule::default().add_systems(
-            (test_system, test_system)
-                .distributive_run_if(on_timer(Duration::new(1, 0)))
-                .distributive_run_if(on_fixed_timer(Duration::new(1, 0))),
+            (test_system, test_system).distributive_run_if(on_timer(Duration::new(1, 0))),
         );
     }
 }
diff --git a/crates/bevy_time/src/fixed_timestep.rs b/crates/bevy_time/src/fixed_timestep.rs
index 66be2f41ef2ff..449f8e8853794 100644
--- a/crates/bevy_time/src/fixed_timestep.rs
+++ b/crates/bevy_time/src/fixed_timestep.rs
@@ -1,116 +1,155 @@
-//! Tools to run systems at a regular interval.
-//! This can be extremely useful for steady, frame-rate independent gameplay logic and physics.
+//! A tool for implementing gameplay logic in way that results in consistent behaviour,
+//! independent of framerate.
 //!
-//! To run a system on a fixed timestep, add it to the [`FixedUpdate`] [`Schedule`](bevy_ecs::schedule::Schedule).
-//! This schedule is run in [`RunFixedUpdateLoop`](bevy_app::RunFixedUpdateLoop) near the start of each frame,
-//! via the [`run_fixed_update_schedule`] exclusive system.
+//! To run systems on a fixed timestep, add them to the [`FixedUpdate`] schedule.
+//! This schedule will be run during [`RunFixedUpdateLoop`](bevy_app::RunFixedUpdateLoop), by the
+//! exclusive system [`run_fixed_update_schedule`].
 //!
-//! This schedule will be run a number of times each frame,
-//! equal to the accumulated divided by the period resource, rounded down,
-//! as tracked in the [`FixedTime`] resource.
-//! Unused time will be carried over.
+//! [`FixedUpdate`] can run zero or more times each frame. Each [timestep](FixedTimestep::size)
+//! time that elapses in [`Time`] will queue another step to run.
 //!
-//! This does not guarantee that the time elapsed between executions is exact,
-//! and systems in this schedule can run 0, 1 or more times on any given frame.
-//!
-//! For example, a system with a fixed timestep run criteria of 120 times per second will run
-//! two times during a ~16.667ms frame, once during a ~8.333ms frame, and once every two frames
-//! with ~4.167ms frames. However, the same criteria may not result in exactly 8.333ms passing
-//! between each execution.
-//!
-//! When using fixed time steps, it is advised not to rely on [`Time::delta`] or any of it's
-//! variants for game simulation, but rather use the value of [`FixedTime`] instead.
+//! However, no guarantees about the real time that elapses between these runs can be made.
 
-use crate::Time;
 use bevy_app::FixedUpdate;
 use bevy_ecs::{system::Resource, world::World};
-use bevy_utils::Duration;
-use thiserror::Error;
-
-/// The amount of time that must pass before the fixed timestep schedule is run again.
-#[derive(Resource, Debug)]
-pub struct FixedTime {
-    accumulated: Duration,
-    /// Defaults to 1/60th of a second.
-    /// To configure this value, simply mutate or overwrite this resource.
-    pub period: Duration,
+use bevy_utils::{default, Duration, Instant};
+
+use crate::{Time, TimeContext};
+
+/// The step size (and some metadata) for the `FixedUpdate` schedule .
+#[derive(Resource, Debug, Clone, Copy)]
+pub struct FixedTimestep {
+    size: Duration,
+    steps: u32,
+    overstep: Duration,
+    max_steps_per_update: u32,
 }
 
-impl FixedTime {
-    /// Creates a new [`FixedTime`] struct
-    pub fn new(period: Duration) -> Self {
-        FixedTime {
-            accumulated: Duration::ZERO,
-            period,
+impl Default for FixedTimestep {
+    fn default() -> Self {
+        Self {
+            size: Duration::from_micros(15625),
+            steps: 0,
+            overstep: Duration::ZERO,
+            max_steps_per_update: u32::MAX,
         }
     }
+}
 
-    /// Creates a new [`FixedTime`] struct with a period specified in `f32` seconds
-    pub fn new_from_secs(period: f32) -> Self {
-        FixedTime {
-            accumulated: Duration::ZERO,
-            period: Duration::from_secs_f32(period),
-        }
+impl FixedTimestep {
+    /// Constructs a new `FixedTimestep` from a [`Duration`].
+    pub fn new(size: Duration) -> Self {
+        assert!(!size.is_zero(), "timestep is zero");
+        Self { size, ..default() }
+    }
+
+    /// Constructs a new `FixedTimestep` from an [`f64`] number of seconds.
+    pub fn from_secs(seconds: f64) -> Self {
+        Self::new(Duration::from_secs_f64(seconds))
     }
 
-    /// Adds the `delta_time` to the accumulated time so far.
-    pub fn tick(&mut self, delta_time: Duration) {
-        self.accumulated += delta_time;
+    /// Constructs a new `FixedTimestep` from a nominal [`f64`] number of steps per second.
+    pub fn from_hz(hz: f64) -> Self {
+        assert!(hz.is_sign_positive(), "Hz less than or equal to zero");
+        assert!(hz.is_finite(), "Hz is infinite");
+        Self::from_secs(1.0 / hz)
     }
 
-    /// Returns the current amount of accumulated time
-    pub fn accumulated(&self) -> Duration {
-        self.accumulated
+    /// Returns the step size as a [`Duration`].
+    #[inline]
+    pub fn size(&self) -> Duration {
+        self.size
     }
 
-    /// Expends one `period` of accumulated time.
+    /// Sets the step size, given as a [`Duration`].
     ///
-    /// [`Err(FixedUpdateError`)] will be returned if there is
-    /// not enough accumulated time to span an entire period.
-    pub fn expend(&mut self) -> Result<(), FixedUpdateError> {
-        if let Some(new_value) = self.accumulated.checked_sub(self.period) {
-            self.accumulated = new_value;
-            Ok(())
-        } else {
-            Err(FixedUpdateError::NotEnoughTime {
-                accumulated: self.accumulated,
-                period: self.period,
-            })
-        }
+    /// # Panics
+    ///
+    /// Panics if `step_size` is a zero-length duration.
+    pub fn set_size(&mut self, size: Duration) {
+        assert!(!size.is_zero(), "timestep is zero");
+        self.size = size;
     }
-}
 
-impl Default for FixedTime {
-    fn default() -> Self {
-        FixedTime {
-            accumulated: Duration::ZERO,
-            period: Duration::from_secs_f32(1. / 60.),
+    /// Returns the number of steps accumulated.
+    #[inline]
+    pub fn steps(&self) -> u32 {
+        self.steps
+    }
+
+    /// Returns the amount of time accumulated toward new steps, as a [`Duration`].
+    #[inline]
+    pub fn overstep(&self) -> Duration {
+        self.overstep
+    }
+
+    /// Returns the amount of time accumulated toward new steps,
+    /// as an [`f32`] fraction of the timestep.
+    #[inline]
+    pub fn overstep_percentage(&self) -> f32 {
+        self.overstep.as_secs_f32() / self.size.as_secs_f32()
+    }
+
+    /// Returns the amount of time accumulated toward new steps,
+    /// as an [`f64`] fraction of the timestep.
+    pub fn overstep_percentage_f64(&self) -> f64 {
+        self.overstep.as_secs_f64() / self.size.as_secs_f64()
+    }
+
+    /// Adds `time` to an internal accumulator.
+    pub fn accumulate(&mut self, time: Duration) {
+        self.overstep += time;
+        while self.overstep >= self.size {
+            self.overstep -= self.size;
+            self.steps += 1;
         }
     }
-}
 
-/// An error returned when working with [`FixedTime`].
-#[derive(Debug, Error)]
-pub enum FixedUpdateError {
-    #[error("At least one period worth of time must be accumulated.")]
-    NotEnoughTime {
-        accumulated: Duration,
-        period: Duration,
-    },
+    /// Consumes one step and returns the number remaining.
+    /// Returns `None` if there was no step that could be expended.
+    pub fn expend(&mut self) -> Option<u32> {
+        let remaining = self.steps.checked_sub(1);
+        self.steps = self.steps.saturating_sub(1);
+        remaining
+    }
+
+    /// Returns the maximum number of `FixedUpdate` steps that can be run in one update.
+    pub fn max_steps_per_update(&self) -> u32 {
+        self.max_steps_per_update
+    }
+
+    /// Sets the maximum number of `FixedUpdate` steps that can be run in one update.
+    pub fn set_max_steps_per_update(&mut self, steps: u32) {
+        self.max_steps_per_update = steps;
+    }
 }
 
-/// Ticks the [`FixedTime`] resource then runs the [`FixedUpdate`].
+/// Runs the [`FixedUpdate`] schedule zero or more times, advancing its clock each time.
 pub fn run_fixed_update_schedule(world: &mut World) {
-    // Tick the time
-    let delta_time = world.resource::<Time>().delta();
-    let mut fixed_time = world.resource_mut::<FixedTime>();
-    fixed_time.tick(delta_time);
-
-    // Run the schedule until we run out of accumulated time
     let _ = world.try_schedule_scope(FixedUpdate, |world, schedule| {
-        while world.resource_mut::<FixedTime>().expend().is_ok() {
+        // swap context
+        let mut time = world.resource_mut::<Time>();
+        time.set_context(TimeContext::FixedUpdate);
+
+        // solve for number of steps (done in advance on purpose)
+        let mut timestep = world.resource_mut::<FixedTimestep>();
+        let mut steps = 0;
+        while timestep.expend().is_some() && steps < timestep.max_steps_per_update {
+            steps += 1;
+        }
+
+        // run schedule however many times
+        let dt = timestep.size();
+        for _ in 0..steps {
+            let mut time = world.resource_mut::<Time>();
+            assert!(matches!(time.context(), TimeContext::FixedUpdate));
+            time.tick(dt, Instant::now());
             schedule.run(world);
         }
+
+        // swap context
+        let mut time = world.resource_mut::<Time>();
+        time.set_context(TimeContext::Update);
     });
 }
 
@@ -120,39 +159,40 @@ mod test {
 
     #[test]
     fn fixed_time_starts_at_zero() {
-        let new_time = FixedTime::new_from_secs(42.);
-        assert_eq!(new_time.accumulated(), Duration::ZERO);
+        let acc = FixedTimestep::from_secs(42.0);
+        assert_eq!(acc.overstep(), Duration::ZERO);
 
-        let default_time = FixedTime::default();
-        assert_eq!(default_time.accumulated(), Duration::ZERO);
+        let acc = FixedTimestep::default();
+        assert_eq!(acc.overstep(), Duration::ZERO);
     }
 
     #[test]
     fn fixed_time_ticks_up() {
-        let mut fixed_time = FixedTime::default();
-        fixed_time.tick(Duration::from_secs(1));
-        assert_eq!(fixed_time.accumulated(), Duration::from_secs(1));
+        let mut acc = FixedTimestep::new(Duration::from_secs(2));
+        acc.accumulate(Duration::from_secs(1));
+        assert_eq!(acc.overstep(), Duration::from_secs(1));
     }
 
     #[test]
     fn enough_accumulated_time_is_required() {
-        let mut fixed_time = FixedTime::new(Duration::from_secs(2));
-        fixed_time.tick(Duration::from_secs(1));
-        assert!(fixed_time.expend().is_err());
-        assert_eq!(fixed_time.accumulated(), Duration::from_secs(1));
-
-        fixed_time.tick(Duration::from_secs(1));
-        assert!(fixed_time.expend().is_ok());
-        assert_eq!(fixed_time.accumulated(), Duration::ZERO);
+        let mut acc = FixedTimestep::new(Duration::from_secs(2));
+        acc.accumulate(Duration::from_secs(1));
+        assert!(acc.expend().is_none());
+        assert_eq!(acc.overstep(), Duration::from_secs(1));
+
+        acc.accumulate(Duration::from_secs(1));
+        assert_eq!(acc.overstep(), Duration::ZERO);
+        assert_eq!(acc.steps(), 1);
+        assert!(acc.expend().is_some());
     }
 
     #[test]
     fn repeatedly_expending_time() {
-        let mut fixed_time = FixedTime::new(Duration::from_secs(1));
-        fixed_time.tick(Duration::from_secs_f32(3.2));
-        assert!(fixed_time.expend().is_ok());
-        assert!(fixed_time.expend().is_ok());
-        assert!(fixed_time.expend().is_ok());
-        assert!(fixed_time.expend().is_err());
+        let mut acc = FixedTimestep::new(Duration::from_secs(1));
+        acc.accumulate(Duration::from_secs_f32(3.2));
+        assert!(acc.expend().is_some());
+        assert!(acc.expend().is_some());
+        assert!(acc.expend().is_some());
+        assert!(acc.expend().is_none());
     }
 }
diff --git a/crates/bevy_time/src/lib.rs b/crates/bevy_time/src/lib.rs
index 704d54d860452..c793222805951 100644
--- a/crates/bevy_time/src/lib.rs
+++ b/crates/bevy_time/src/lib.rs
@@ -1,5 +1,6 @@
 #![allow(clippy::type_complexity)]
 
+mod clock;
 /// Common run conditions
 pub mod common_conditions;
 pub mod fixed_timestep;
@@ -8,7 +9,7 @@ mod stopwatch;
 mod time;
 mod timer;
 
-use fixed_timestep::FixedTime;
+use fixed_timestep::*;
 pub use stopwatch::*;
 pub use time::*;
 pub use timer::*;
@@ -20,7 +21,7 @@ use crossbeam_channel::{Receiver, Sender};
 pub mod prelude {
     //! The Bevy Time Prelude.
     #[doc(hidden)]
-    pub use crate::{fixed_timestep::FixedTime, Time, Timer, TimerMode};
+    pub use crate::{fixed_timestep::FixedTimestep, RealTime, Time, Timer, TimerMode};
 }
 
 use bevy_app::{prelude::*, RunFixedUpdateLoop};
@@ -33,18 +34,21 @@ use crate::fixed_timestep::run_fixed_update_schedule;
 pub struct TimePlugin;
 
 #[derive(Debug, PartialEq, Eq, Clone, Hash, SystemSet)]
-/// Updates the elapsed time. Any system that interacts with [Time] component should run after
-/// this.
+/// Updates [`Time`]. All systems that access [`Time`] should run after this.
 pub struct TimeSystem;
 
 impl Plugin for TimePlugin {
     fn build(&self, app: &mut App) {
-        app.init_resource::<Time>()
-            .init_resource::<TimeUpdateStrategy>()
-            .register_type::<Timer>()
+        app.register_type::<Timer>()
             .register_type::<Time>()
-            .register_type::<Stopwatch>()
-            .init_resource::<FixedTime>()
+            .register_type::<Stopwatch>();
+
+        // initialize clocks w/ same startup time
+        let startup = Instant::now();
+        app.insert_resource(Time::new(startup))
+            .insert_resource(RealTime::new(startup))
+            .init_resource::<FixedTimestep>()
+            .init_resource::<TimeUpdateStrategy>()
             .add_systems(First, time_system.in_set(TimeSystem))
             .add_systems(RunFixedUpdateLoop, run_fixed_update_schedule);
 
@@ -93,19 +97,22 @@ pub fn create_time_channels() -> (TimeSender, TimeReceiver) {
     (TimeSender(s), TimeReceiver(r))
 }
 
-/// The system used to update the [`Time`] used by app logic. If there is a render world the time is sent from
-/// there to this system through channels. Otherwise the time is updated in this system.
+/// The system used to update all clocks. If there is a render world, the previous frame duration
+/// is sent from there to this system through a channel. Otherwise, it's calculated in this system.
+#[allow(clippy::too_many_arguments)]
 fn time_system(
     mut time: ResMut<Time>,
+    mut real_time: ResMut<RealTime>,
+    mut fixed_timestep: ResMut<FixedTimestep>,
     update_strategy: Res<TimeUpdateStrategy>,
     time_recv: Option<Res<TimeReceiver>>,
     mut has_received_time: Local<bool>,
 ) {
-    let new_time = if let Some(time_recv) = time_recv {
+    let real_frame_start = if let Some(time_recv) = time_recv {
         // TODO: Figure out how to handle this when using pipelined rendering.
-        if let Ok(new_time) = time_recv.0.try_recv() {
+        if let Ok(instant) = time_recv.0.try_recv() {
             *has_received_time = true;
-            new_time
+            instant
         } else {
             if *has_received_time {
                 warn!("time_system did not receive the time from the render world! Calculations depending on the time may be incorrect.");
@@ -116,12 +123,22 @@ fn time_system(
         Instant::now()
     };
 
-    match update_strategy.as_ref() {
-        TimeUpdateStrategy::Automatic => time.update_with_instant(new_time),
-        TimeUpdateStrategy::ManualInstant(instant) => time.update_with_instant(*instant),
+    // 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,
+        TimeUpdateStrategy::ManualInstant(instant) => *instant,
         TimeUpdateStrategy::ManualDuration(duration) => {
-            let last_update = time.last_update().unwrap_or_else(|| time.startup());
-            time.update_with_instant(last_update + *duration);
+            let last_update = time.last_update().unwrap_or(time.startup());
+            last_update.checked_add(*duration).unwrap()
         }
-    }
+    };
+
+    // 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);
+
+    // accumulate virtual time delta
+    fixed_timestep.accumulate(time.delta());
 }
diff --git a/crates/bevy_time/src/time.rs b/crates/bevy_time/src/time.rs
index f462296ad6aef..de607de8a160a 100644
--- a/crates/bevy_time/src/time.rs
+++ b/crates/bevy_time/src/time.rs
@@ -1,68 +1,46 @@
 use bevy_ecs::{reflect::ReflectResource, system::Resource};
 use bevy_reflect::{FromReflect, Reflect};
-use bevy_utils::{Duration, Instant};
+use bevy_utils::tracing::warn;
+use bevy_utils::{default, Duration, Instant};
 
-/// A clock that tracks how much it has advanced (and how much real time has elapsed) since
-/// its previous update and since its creation.
+use crate::clock::Clock;
+
+/// A clock that tracks how much time has advanced since the last update and since startup.
+///
+/// **NOTE:** This clock can be set to advance faster or slower than real-time. It can also be paused.
+/// For a clock that tracks the actual time that elapses, see [`RealTime`].
 #[derive(Resource, Reflect, FromReflect, Debug, Clone)]
 #[reflect(Resource)]
 pub struct Time {
-    startup: Instant,
-    first_update: Option<Instant>,
-    last_update: Option<Instant>,
-    // pausing
+    context: TimeContext,
+    update: Clock,
+    fixed_update: Clock,
+    // settings
     paused: bool,
-    // scaling
+    next_paused: Option<bool>,
     relative_speed: f64, // using `f64` instead of `f32` to minimize drift from rounding errors
-    delta: Duration,
-    delta_seconds: f32,
-    delta_seconds_f64: f64,
-    elapsed: Duration,
-    elapsed_seconds: f32,
-    elapsed_seconds_f64: f64,
-    raw_delta: Duration,
-    raw_delta_seconds: f32,
-    raw_delta_seconds_f64: f64,
-    raw_elapsed: Duration,
-    raw_elapsed_seconds: f32,
-    raw_elapsed_seconds_f64: f64,
-    // wrapping
-    wrap_period: Duration,
-    elapsed_wrapped: Duration,
-    elapsed_seconds_wrapped: f32,
-    elapsed_seconds_wrapped_f64: f64,
-    raw_elapsed_wrapped: Duration,
-    raw_elapsed_seconds_wrapped: f32,
-    raw_elapsed_seconds_wrapped_f64: f64,
+    next_relative_speed: Option<f64>,
+}
+
+/// [`Time`] stores two clocks that are synchronized but advance at different rates.
+/// This value determines which one is shown.
+#[derive(Debug, Default, Clone, Copy, Reflect, FromReflect, PartialEq, Eq)]
+pub enum TimeContext {
+    #[default]
+    Update,
+    FixedUpdate,
 }
 
 impl Default for Time {
     fn default() -> Self {
         Self {
-            startup: Instant::now(),
-            first_update: None,
-            last_update: None,
+            context: TimeContext::Update,
+            update: default(),
+            fixed_update: default(),
             paused: false,
+            next_paused: None,
             relative_speed: 1.0,
-            delta: Duration::ZERO,
-            delta_seconds: 0.0,
-            delta_seconds_f64: 0.0,
-            elapsed: Duration::ZERO,
-            elapsed_seconds: 0.0,
-            elapsed_seconds_f64: 0.0,
-            raw_delta: Duration::ZERO,
-            raw_delta_seconds: 0.0,
-            raw_delta_seconds_f64: 0.0,
-            raw_elapsed: Duration::ZERO,
-            raw_elapsed_seconds: 0.0,
-            raw_elapsed_seconds_f64: 0.0,
-            wrap_period: Duration::from_secs(3600), // 1 hour
-            elapsed_wrapped: Duration::ZERO,
-            elapsed_seconds_wrapped: 0.0,
-            elapsed_seconds_wrapped_f64: 0.0,
-            raw_elapsed_wrapped: Duration::ZERO,
-            raw_elapsed_seconds_wrapped: 0.0,
-            raw_elapsed_seconds_wrapped_f64: 0.0,
+            next_relative_speed: None,
         }
     }
 }
@@ -70,12 +48,46 @@ impl Default for Time {
 impl Time {
     /// Constructs a new `Time` instance with a specific startup `Instant`.
     pub fn new(startup: Instant) -> Self {
+        let clock = Clock::new(startup);
         Self {
-            startup,
-            ..Default::default()
+            update: clock,
+            fixed_update: clock,
+            ..default()
         }
     }
 
+    pub fn clock(&self, context: TimeContext) -> &Clock {
+        match context {
+            TimeContext::Update => &self.update,
+            TimeContext::FixedUpdate => &self.fixed_update,
+        }
+    }
+
+    pub(crate) fn clock_mut(&mut self, context: TimeContext) -> &mut Clock {
+        match context {
+            TimeContext::Update => &mut self.update,
+            TimeContext::FixedUpdate => &mut self.fixed_update,
+        }
+    }
+
+    pub(crate) fn current_clock(&self) -> &Clock {
+        self.clock(self.context)
+    }
+
+    pub(crate) fn current_clock_mut(&mut self) -> &mut Clock {
+        self.clock_mut(self.context)
+    }
+
+    /// Returns the current [`TimeContext`].
+    pub fn context(&self) -> TimeContext {
+        self.context
+    }
+
+    /// Changes the current [`TimeContext`].
+    pub fn set_context(&mut self, context: TimeContext) {
+        self.context = context;
+    }
+
     /// Updates the internal time measurements.
     ///
     /// Calling this method as part of your app will most likely result in inaccurate timekeeping,
@@ -138,42 +150,47 @@ impl Time {
     /// }
     /// ```
     pub fn update_with_instant(&mut self, instant: Instant) {
-        let raw_delta = instant - self.last_update.unwrap_or(self.startup);
-        let delta = if self.paused {
-            Duration::ZERO
-        } else if self.relative_speed != 1.0 {
-            raw_delta.mul_f64(self.relative_speed)
-        } else {
-            // avoid rounding when at normal speed
-            raw_delta
-        };
-
-        if self.last_update.is_some() {
-            self.delta = delta;
-            self.delta_seconds = self.delta.as_secs_f32();
-            self.delta_seconds_f64 = self.delta.as_secs_f64();
-            self.raw_delta = raw_delta;
-            self.raw_delta_seconds = self.raw_delta.as_secs_f32();
-            self.raw_delta_seconds_f64 = self.raw_delta.as_secs_f64();
-        } else {
-            self.first_update = Some(instant);
+        match self.context {
+            TimeContext::Update => {
+                // apply pending pause and relative speed changes
+                self.apply_pending_changes();
+
+                // zero for first update
+                let dt = instant - self.current_clock().last_update().unwrap_or(instant);
+                let dt = if self.paused {
+                    Duration::ZERO
+                } else if self.relative_speed != 1.0 {
+                    dt.mul_f64(self.relative_speed)
+                } else {
+                    // avoid rounding when at normal speed
+                    dt
+                };
+
+                self.update.tick(dt, instant);
+            }
+            TimeContext::FixedUpdate => {
+                warn!("In the `FixedUpdate` context, `Time` can only be advanced via `tick`.");
+            }
         }
+    }
 
-        self.elapsed += delta;
-        self.elapsed_seconds = self.elapsed.as_secs_f32();
-        self.elapsed_seconds_f64 = self.elapsed.as_secs_f64();
-        self.raw_elapsed += raw_delta;
-        self.raw_elapsed_seconds = self.raw_elapsed.as_secs_f32();
-        self.raw_elapsed_seconds_f64 = self.raw_elapsed.as_secs_f64();
+    pub(crate) fn tick(&mut self, dt: Duration, instant: Instant) {
+        self.current_clock_mut().tick(dt, instant);
+    }
 
-        self.elapsed_wrapped = duration_div_rem(self.elapsed, self.wrap_period).1;
-        self.elapsed_seconds_wrapped = self.elapsed_wrapped.as_secs_f32();
-        self.elapsed_seconds_wrapped_f64 = self.elapsed_wrapped.as_secs_f64();
-        self.raw_elapsed_wrapped = duration_div_rem(self.raw_elapsed, self.wrap_period).1;
-        self.raw_elapsed_seconds_wrapped = self.raw_elapsed_wrapped.as_secs_f32();
-        self.raw_elapsed_seconds_wrapped_f64 = self.raw_elapsed_wrapped.as_secs_f64();
+    /// Applies pending pause or relative speed changes.
+    ///
+    /// This method is provided for use in tests. Calling this method as part of your app will most
+    /// likely result in inaccurate timekeeping, as the `Time` resource is ordinarily managed by the
+    /// [`TimePlugin`](crate::TimePlugin).
+    pub fn apply_pending_changes(&mut self) {
+        if let Some(value) = self.next_paused.take() {
+            self.paused = value;
+        }
 
-        self.last_update = Some(instant);
+        if let Some(value) = self.next_relative_speed.take() {
+            self.relative_speed = value;
+        }
     }
 
     /// Returns the [`Instant`] the clock was created.
@@ -181,7 +198,7 @@ impl Time {
     /// This usually represents when the app was started.
     #[inline]
     pub fn startup(&self) -> Instant {
-        self.startup
+        self.current_clock().startup()
     }
 
     /// Returns the [`Instant`] when [`update`](#method.update) was first called, if it exists.
@@ -189,7 +206,7 @@ impl Time {
     /// This usually represents when the first app update started.
     #[inline]
     pub fn first_update(&self) -> Option<Instant> {
-        self.first_update
+        self.current_clock().first_update()
     }
 
     /// Returns the [`Instant`] when [`update`](#method.update) was last called, if it exists.
@@ -197,148 +214,84 @@ impl Time {
     /// This usually represents when the current app update started.
     #[inline]
     pub fn last_update(&self) -> Option<Instant> {
-        self.last_update
+        self.current_clock().last_update()
     }
 
     /// Returns how much time has advanced since the last [`update`](#method.update), as a [`Duration`].
     #[inline]
     pub fn delta(&self) -> Duration {
-        self.delta
+        self.current_clock().delta()
     }
 
     /// Returns how much time has advanced since the last [`update`](#method.update), as [`f32`] seconds.
     #[inline]
     pub fn delta_seconds(&self) -> f32 {
-        self.delta_seconds
+        self.current_clock().delta_seconds()
     }
 
     /// Returns how much time has advanced since the last [`update`](#method.update), as [`f64`] seconds.
     #[inline]
     pub fn delta_seconds_f64(&self) -> f64 {
-        self.delta_seconds_f64
+        self.current_clock().delta_seconds_f64()
     }
 
-    /// Returns how much time has advanced since [`startup`](#method.startup), as [`Duration`].
+    /// Returns how much time has advanced since [`first_update`](#method.first_update), as [`Duration`].
     #[inline]
     pub fn elapsed(&self) -> Duration {
-        self.elapsed
+        self.current_clock().elapsed()
     }
 
-    /// Returns how much time has advanced since [`startup`](#method.startup), as [`f32`] seconds.
+    /// Returns how much time has advanced since [`first_update`](#method.first_update), as [`f32`] seconds.
     ///
     /// **Note:** This is a monotonically increasing value. It's precision will degrade over time.
     /// If you need an `f32` but that precision loss is unacceptable,
     /// use [`elapsed_seconds_wrapped`](#method.elapsed_seconds_wrapped).
     #[inline]
     pub fn elapsed_seconds(&self) -> f32 {
-        self.elapsed_seconds
+        self.current_clock().elapsed_seconds()
     }
 
-    /// Returns how much time has advanced since [`startup`](#method.startup), as [`f64`] seconds.
+    /// Returns how much time has advanced since [`first_update`](#method.first_update), as [`f64`] seconds.
     #[inline]
     pub fn elapsed_seconds_f64(&self) -> f64 {
-        self.elapsed_seconds_f64
+        self.current_clock().elapsed_seconds_f64()
     }
 
-    /// Returns how much time has advanced since [`startup`](#method.startup) modulo
+    /// Returns how much time has advanced since [`first_update`](#method.first_update) modulo
     /// the [`wrap_period`](#method.wrap_period), as [`Duration`].
     #[inline]
     pub fn elapsed_wrapped(&self) -> Duration {
-        self.elapsed_wrapped
+        self.current_clock().elapsed_wrapped()
     }
 
-    /// Returns how much time has advanced since [`startup`](#method.startup) modulo
+    /// Returns how much time has advanced since [`first_update`](#method.first_update) modulo
     /// the [`wrap_period`](#method.wrap_period), as [`f32`] seconds.
     ///
     /// This method is intended for applications (e.g. shaders) that require an [`f32`] value but
     /// suffer from the gradual precision loss of [`elapsed_seconds`](#method.elapsed_seconds).
     #[inline]
     pub fn elapsed_seconds_wrapped(&self) -> f32 {
-        self.elapsed_seconds_wrapped
+        self.current_clock().elapsed_seconds_wrapped()
     }
 
-    /// Returns how much time has advanced since [`startup`](#method.startup) modulo
+    /// Returns how much time has advanced since [`first_update`](#method.first_update) modulo
     /// the [`wrap_period`](#method.wrap_period), as [`f64`] seconds.
     #[inline]
     pub fn elapsed_seconds_wrapped_f64(&self) -> f64 {
-        self.elapsed_seconds_wrapped_f64
-    }
-
-    /// Returns how much real time has elapsed since the last [`update`](#method.update), as a [`Duration`].
-    #[inline]
-    pub fn raw_delta(&self) -> Duration {
-        self.raw_delta
-    }
-
-    /// Returns how much real time has elapsed since the last [`update`](#method.update), as [`f32`] seconds.
-    #[inline]
-    pub fn raw_delta_seconds(&self) -> f32 {
-        self.raw_delta_seconds
-    }
-
-    /// Returns how much real time has elapsed since the last [`update`](#method.update), as [`f64`] seconds.
-    #[inline]
-    pub fn raw_delta_seconds_f64(&self) -> f64 {
-        self.raw_delta_seconds_f64
-    }
-
-    /// Returns how much real time has elapsed since [`startup`](#method.startup), as [`Duration`].
-    #[inline]
-    pub fn raw_elapsed(&self) -> Duration {
-        self.raw_elapsed
-    }
-
-    /// Returns how much real time has elapsed since [`startup`](#method.startup), as [`f32`] seconds.
-    ///
-    /// **Note:** This is a monotonically increasing value. It's precision will degrade over time.
-    /// If you need an `f32` but that precision loss is unacceptable,
-    /// use [`raw_elapsed_seconds_wrapped`](#method.raw_elapsed_seconds_wrapped).
-    #[inline]
-    pub fn raw_elapsed_seconds(&self) -> f32 {
-        self.raw_elapsed_seconds
-    }
-
-    /// Returns how much real time has elapsed since [`startup`](#method.startup), as [`f64`] seconds.
-    #[inline]
-    pub fn raw_elapsed_seconds_f64(&self) -> f64 {
-        self.raw_elapsed_seconds_f64
-    }
-
-    /// Returns how much real time has elapsed since [`startup`](#method.startup) modulo
-    /// the [`wrap_period`](#method.wrap_period), as [`Duration`].
-    #[inline]
-    pub fn raw_elapsed_wrapped(&self) -> Duration {
-        self.raw_elapsed_wrapped
-    }
-
-    /// Returns how much real time has elapsed since [`startup`](#method.startup) modulo
-    /// the [`wrap_period`](#method.wrap_period), as [`f32`] seconds.
-    ///
-    /// This method is intended for applications (e.g. shaders) that require an [`f32`] value but
-    /// suffer from the gradual precision loss of [`raw_elapsed_seconds`](#method.raw_elapsed_seconds).
-    #[inline]
-    pub fn raw_elapsed_seconds_wrapped(&self) -> f32 {
-        self.raw_elapsed_seconds_wrapped
-    }
-
-    /// Returns how much real time has elapsed since [`startup`](#method.startup) modulo
-    /// the [`wrap_period`](#method.wrap_period), as [`f64`] seconds.
-    #[inline]
-    pub fn raw_elapsed_seconds_wrapped_f64(&self) -> f64 {
-        self.raw_elapsed_seconds_wrapped_f64
+        self.current_clock().elapsed_seconds_wrapped_f64()
     }
 
     /// Returns the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
-    /// [`raw_elapsed_wrapped`](#method.raw_elapsed_wrapped).
+    /// [`elapsed_wrapped`](#method.elapsed_wrapped).
     ///
     /// **Note:** The default modulus is one hour.
     #[inline]
     pub fn wrap_period(&self) -> Duration {
-        self.wrap_period
+        self.current_clock().wrap_period()
     }
 
     /// Sets the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
-    /// [`raw_elapsed_wrapped`](#method.raw_elapsed_wrapped).
+    /// [`elapsed_wrapped`](#method.elapsed_wrapped).
     ///
     /// **Note:** This will not take effect until the next update.
     ///
@@ -347,8 +300,7 @@ impl Time {
     /// Panics if `wrap_period` is a zero-length duration.
     #[inline]
     pub fn set_wrap_period(&mut self, wrap_period: Duration) {
-        assert!(!wrap_period.is_zero(), "division by zero");
-        self.wrap_period = wrap_period;
+        self.current_clock_mut().set_wrap_period(wrap_period);
     }
 
     /// Returns the speed the clock advances relative to your system clock, as [`f32`].
@@ -373,48 +325,50 @@ impl Time {
         }
     }
 
-    /// Sets the speed the clock advances relative to your system clock, given as an [`f32`].
+    /// Sets the speed the clock advances relative to its inputs, given as an [`f32`].
     ///
-    /// For example, setting this to `2.0` will make the clock advance twice as fast as your system clock.
+    /// For example, setting this to `2.0` will make the clock advance twice as fast as its inputs.
     ///
-    /// **Note:** This does not affect the `raw_*` measurements.
+    /// **Note:** This will not take effect until the next update.
     ///
     /// # Panics
     ///
-    /// Panics if `ratio` is negative or not finite.
+    /// Panics if `r` is negative or not finite.
     #[inline]
-    pub fn set_relative_speed(&mut self, ratio: f32) {
-        self.set_relative_speed_f64(ratio as f64);
+    pub fn set_relative_speed(&mut self, r: f32) {
+        self.set_relative_speed_f64(r as f64);
     }
 
-    /// Sets the speed the clock advances relative to your system clock, given as an [`f64`].
+    /// Sets the speed the clock advances relative to its inputs, given as an [`f64`].
     ///
-    /// For example, setting this to `2.0` will make the clock advance twice as fast as your system clock.
+    /// For example, setting this to `2.0` will make the clock advance twice as fast as its inputs.
     ///
-    /// **Note:** This does not affect the `raw_*` measurements.
+    /// **Note:** This will not take effect until the next update.
     ///
     /// # Panics
     ///
-    /// Panics if `ratio` is negative or not finite.
+    /// Panics if `r` is negative or not finite.
     #[inline]
-    pub fn set_relative_speed_f64(&mut self, ratio: f64) {
-        assert!(ratio.is_finite(), "tried to go infinitely fast");
-        assert!(ratio >= 0.0, "tried to go back in time");
-        self.relative_speed = ratio;
+    pub fn set_relative_speed_f64(&mut self, r: f64) {
+        assert!(r.is_finite(), "tried to go infinitely fast");
+        assert!(r >= 0.0, "tried to go back in time");
+        self.next_relative_speed = Some(r);
     }
 
     /// Stops the clock, preventing it from advancing until resumed.
     ///
-    /// **Note:** This does not affect the `raw_*` measurements.
+    /// **Note:** This will not take effect until the next update.
     #[inline]
     pub fn pause(&mut self) {
-        self.paused = true;
+        self.next_paused = Some(true);
     }
 
     /// Resumes the clock if paused.
+    ///
+    /// **Note:** This will not take effect until the next update.
     #[inline]
     pub fn unpause(&mut self) {
-        self.paused = false;
+        self.next_paused = Some(false);
     }
 
     /// Returns `true` if the clock is currently paused.
@@ -424,305 +378,407 @@ impl Time {
     }
 }
 
-fn duration_div_rem(dividend: Duration, divisor: Duration) -> (u32, Duration) {
-    // `Duration` does not have a built-in modulo operation
-    let quotient = (dividend.as_nanos() / divisor.as_nanos()) as u32;
-    let remainder = dividend - (quotient * divisor);
-    (quotient, remainder)
+/// A clock that tracks how much actual time has elasped since the last update and since startup.
+///
+/// This clock cannot be paused and will always advance at the same rate as [`Instant`].
+#[derive(Resource, Debug)]
+pub struct RealTime(Clock);
+
+impl RealTime {
+    /// Constructs a new `Time` instance with a specific startup `Instant`.
+    pub(crate) fn new(startup: Instant) -> Self {
+        Self(Clock::new(startup))
+    }
+
+    /// Updates the internal time measurements.
+    ///
+    /// Calling this method as part of your app will most likely result in inaccurate timekeeping,
+    /// as this resource is ordinarily managed by the [`TimePlugin`](crate::TimePlugin).
+    pub fn update(&mut self) {
+        let now = Instant::now();
+        self.update_with_instant(now);
+    }
+
+    /// Updates time with a specified [`Instant`].
+    ///
+    /// This method is provided for use in tests. Calling this method as part of your app will most
+    /// likely result in inaccurate timekeeping, as this resource is ordinarily managed by the
+    /// [`TimePlugin`](crate::TimePlugin).
+    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);
+    }
+
+    /// Returns the [`Instant`] the clock was created.
+    ///
+    /// This usually represents when the app was started.
+    #[inline]
+    pub fn startup(&self) -> Instant {
+        self.0.startup()
+    }
+
+    /// Returns the [`Instant`] when [`update`](#method.update) was first called, if it exists.
+    ///
+    /// This usually represents when the first app update started.
+    #[inline]
+    pub fn first_update(&self) -> Option<Instant> {
+        self.0.first_update()
+    }
+
+    /// Returns the [`Instant`] when [`update`](#method.update) was last called, if it exists.
+    ///
+    /// This usually represents when the current app update started.
+    #[inline]
+    pub fn last_update(&self) -> Option<Instant> {
+        self.0.last_update()
+    }
+
+    /// Returns how much real time has elapsed since the last [`update`](#method.update), as a [`Duration`].
+    #[inline]
+    pub fn delta(&self) -> Duration {
+        self.0.delta()
+    }
+
+    /// Returns how much real time has elapsed since the last [`update`](#method.update), as [`f32`] seconds.
+    #[inline]
+    pub fn delta_seconds(&self) -> f32 {
+        self.0.delta_seconds()
+    }
+
+    /// Returns how much real time has elapsed since the last [`update`](#method.update), as [`f64`] seconds.
+    #[inline]
+    pub fn delta_seconds_f64(&self) -> f64 {
+        self.0.delta_seconds_f64()
+    }
+
+    /// Returns how much real time has elapsed since [`first_update`](#method.first_update), as [`Duration`].
+    #[inline]
+    pub fn elapsed(&self) -> Duration {
+        self.0.elapsed()
+    }
+
+    /// Returns how much real time has elapsed since [`first_update`](#method.first_update), as [`f32`] seconds.
+    ///
+    /// **Note:** This is a monotonically increasing value. It's precision will degrade over time.
+    /// If you need an `f32` but that precision loss is unacceptable,
+    /// use [`elapsed_seconds_wrapped`](#method.elapsed_seconds_wrapped).
+    #[inline]
+    pub fn elapsed_seconds(&self) -> f32 {
+        self.0.elapsed_seconds()
+    }
+
+    /// Returns how much real time has elapsed since [`first_update`](#method.first_update), as [`f64`] seconds.
+    #[inline]
+    pub fn elapsed_seconds_f64(&self) -> f64 {
+        self.0.elapsed_seconds_f64()
+    }
+
+    /// Returns how much real time has elapsed since [`first_update`](#method.first_update) modulo
+    /// the [`wrap_period`](#method.wrap_period), as [`Duration`].
+    #[inline]
+    pub fn elapsed_wrapped(&self) -> Duration {
+        self.0.elapsed_wrapped()
+    }
+
+    /// Returns how much real time has elapsed since [`first_update`](#method.first_update) modulo
+    /// the [`wrap_period`](#method.wrap_period), as [`f32`] seconds.
+    ///
+    /// This method is intended for applications (e.g. shaders) that require an [`f32`] value but
+    /// suffer from the gradual precision loss of [`elapsed_seconds`](#method.elapsed_seconds).
+    #[inline]
+    pub fn elapsed_seconds_wrapped(&self) -> f32 {
+        self.0.elapsed_seconds_wrapped()
+    }
+
+    /// Returns how much real time has elapsed since [`first_update`](#method.first_update) modulo
+    /// the [`wrap_period`](#method.wrap_period), as [`f64`] seconds.
+    #[inline]
+    pub fn elapsed_seconds_wrapped_f64(&self) -> f64 {
+        self.0.elapsed_seconds_wrapped_f64()
+    }
+
+    /// Returns the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
+    /// [`elapsed_wrapped`](#method.elapsed_wrapped).
+    ///
+    /// **Note:** The default modulus is one hour.
+    #[inline]
+    pub fn wrap_period(&self) -> Duration {
+        self.0.wrap_period()
+    }
+
+    /// Sets the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
+    /// [`elapsed_wrapped`](#method.elapsed_wrapped).
+    ///
+    /// **Note:** This will not take effect until the next update.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `wrap_period` is a zero-length duration.
+    #[inline]
+    pub fn set_wrap_period(&mut self, wrap_period: Duration) {
+        self.0.set_wrap_period(wrap_period);
+    }
 }
 
 #[cfg(test)]
 #[allow(clippy::float_cmp)]
 mod tests {
-    use super::Time;
     use bevy_utils::{Duration, Instant};
 
+    use super::{RealTime, Time};
+
     fn assert_float_eq(a: f32, b: f32) {
         assert!((a - b).abs() <= f32::EPSILON, "{a} != {b}");
     }
 
     #[test]
     fn update_test() {
-        let start_instant = Instant::now();
-        let mut time = Time::new(start_instant);
+        let startup = Instant::now();
+        let mut time = Time::new(startup);
 
         // Ensure `time` was constructed correctly.
-        assert_eq!(time.startup(), start_instant);
+        assert_eq!(time.startup(), startup);
         assert_eq!(time.first_update(), None);
         assert_eq!(time.last_update(), None);
         assert_eq!(time.relative_speed(), 1.0);
         assert_eq!(time.delta(), Duration::ZERO);
         assert_eq!(time.delta_seconds(), 0.0);
         assert_eq!(time.delta_seconds_f64(), 0.0);
-        assert_eq!(time.raw_delta(), Duration::ZERO);
-        assert_eq!(time.raw_delta_seconds(), 0.0);
-        assert_eq!(time.raw_delta_seconds_f64(), 0.0);
         assert_eq!(time.elapsed(), Duration::ZERO);
         assert_eq!(time.elapsed_seconds(), 0.0);
         assert_eq!(time.elapsed_seconds_f64(), 0.0);
-        assert_eq!(time.raw_elapsed(), Duration::ZERO);
-        assert_eq!(time.raw_elapsed_seconds(), 0.0);
-        assert_eq!(time.raw_elapsed_seconds_f64(), 0.0);
 
         // Update `time` and check results.
         // The first update to `time` normally happens before other systems have run,
         // so the first delta doesn't appear until the second update.
-        let first_update_instant = Instant::now();
-        time.update_with_instant(first_update_instant);
+        let first_update = Instant::now();
+        time.update_with_instant(first_update);
 
-        assert_eq!(time.startup(), start_instant);
-        assert_eq!(time.first_update(), Some(first_update_instant));
-        assert_eq!(time.last_update(), Some(first_update_instant));
+        assert_eq!(time.startup(), startup);
+        assert_eq!(time.first_update(), Some(first_update));
+        assert_eq!(time.last_update(), Some(first_update));
         assert_eq!(time.relative_speed(), 1.0);
         assert_eq!(time.delta(), Duration::ZERO);
         assert_eq!(time.delta_seconds(), 0.0);
         assert_eq!(time.delta_seconds_f64(), 0.0);
-        assert_eq!(time.raw_delta(), Duration::ZERO);
-        assert_eq!(time.raw_delta_seconds(), 0.0);
-        assert_eq!(time.raw_delta_seconds_f64(), 0.0);
-        assert_eq!(time.elapsed(), first_update_instant - start_instant,);
+        assert_eq!(time.elapsed(), first_update - first_update);
         assert_eq!(
             time.elapsed_seconds(),
-            (first_update_instant - start_instant).as_secs_f32(),
+            (first_update - first_update).as_secs_f32(),
         );
         assert_eq!(
             time.elapsed_seconds_f64(),
-            (first_update_instant - start_instant).as_secs_f64(),
-        );
-        assert_eq!(time.raw_elapsed(), first_update_instant - start_instant,);
-        assert_eq!(
-            time.raw_elapsed_seconds(),
-            (first_update_instant - start_instant).as_secs_f32(),
-        );
-        assert_eq!(
-            time.raw_elapsed_seconds_f64(),
-            (first_update_instant - start_instant).as_secs_f64(),
+            (first_update - first_update).as_secs_f64(),
         );
 
         // Update `time` again and check results.
         // At this point its safe to use time.delta().
-        let second_update_instant = Instant::now();
-        time.update_with_instant(second_update_instant);
-        assert_eq!(time.startup(), start_instant);
-        assert_eq!(time.first_update(), Some(first_update_instant));
-        assert_eq!(time.last_update(), Some(second_update_instant));
+        let second_update = Instant::now();
+        time.update_with_instant(second_update);
+
+        assert_eq!(time.startup(), startup);
+        assert_eq!(time.first_update(), Some(first_update));
+        assert_eq!(time.last_update(), Some(second_update));
         assert_eq!(time.relative_speed(), 1.0);
-        assert_eq!(time.delta(), second_update_instant - first_update_instant);
+        assert_eq!(time.delta(), second_update - first_update);
         assert_eq!(
             time.delta_seconds(),
-            (second_update_instant - first_update_instant).as_secs_f32(),
+            (second_update - first_update).as_secs_f32(),
         );
         assert_eq!(
             time.delta_seconds_f64(),
-            (second_update_instant - first_update_instant).as_secs_f64(),
-        );
-        assert_eq!(
-            time.raw_delta(),
-            second_update_instant - first_update_instant,
-        );
-        assert_eq!(
-            time.raw_delta_seconds(),
-            (second_update_instant - first_update_instant).as_secs_f32(),
+            (second_update - first_update).as_secs_f64(),
         );
-        assert_eq!(
-            time.raw_delta_seconds_f64(),
-            (second_update_instant - first_update_instant).as_secs_f64(),
-        );
-        assert_eq!(time.elapsed(), second_update_instant - start_instant,);
+        assert_eq!(time.elapsed(), second_update - first_update);
         assert_eq!(
             time.elapsed_seconds(),
-            (second_update_instant - start_instant).as_secs_f32(),
+            (second_update - first_update).as_secs_f32(),
         );
         assert_eq!(
             time.elapsed_seconds_f64(),
-            (second_update_instant - start_instant).as_secs_f64(),
-        );
-        assert_eq!(time.raw_elapsed(), second_update_instant - start_instant,);
-        assert_eq!(
-            time.raw_elapsed_seconds(),
-            (second_update_instant - start_instant).as_secs_f32(),
-        );
-        assert_eq!(
-            time.raw_elapsed_seconds_f64(),
-            (second_update_instant - start_instant).as_secs_f64(),
+            (second_update - first_update).as_secs_f64(),
         );
     }
 
     #[test]
     fn wrapping_test() {
-        let start_instant = Instant::now();
+        let startup = Instant::now();
 
-        let mut time = Time {
-            startup: start_instant,
-            wrap_period: Duration::from_secs(3),
-            ..Default::default()
-        };
+        let mut time = Time::new(startup);
+        time.set_wrap_period(Duration::from_secs(3));
 
         assert_eq!(time.elapsed_seconds_wrapped(), 0.0);
 
-        time.update_with_instant(start_instant + Duration::from_secs(1));
+        // time starts counting from first update
+        let first_update = Instant::now();
+        time.update_with_instant(first_update);
+
+        time.update_with_instant(first_update + Duration::from_secs(1));
         assert_float_eq(time.elapsed_seconds_wrapped(), 1.0);
 
-        time.update_with_instant(start_instant + Duration::from_secs(2));
+        time.update_with_instant(first_update + Duration::from_secs(2));
         assert_float_eq(time.elapsed_seconds_wrapped(), 2.0);
 
-        time.update_with_instant(start_instant + Duration::from_secs(3));
+        time.update_with_instant(first_update + Duration::from_secs(3));
         assert_float_eq(time.elapsed_seconds_wrapped(), 0.0);
 
-        time.update_with_instant(start_instant + Duration::from_secs(4));
+        time.update_with_instant(first_update + Duration::from_secs(4));
         assert_float_eq(time.elapsed_seconds_wrapped(), 1.0);
     }
 
     #[test]
     fn relative_speed_test() {
-        let start_instant = Instant::now();
-        let mut time = Time::new(start_instant);
+        let startup = Instant::now();
+        let mut time = Time::new(startup);
+        let mut real_time = RealTime::new(startup);
 
-        let first_update_instant = Instant::now();
-        time.update_with_instant(first_update_instant);
+        let first_update = Instant::now();
+        time.update_with_instant(first_update);
+        real_time.update_with_instant(first_update);
 
         // Update `time` again and check results.
         // At this point its safe to use time.delta().
-        let second_update_instant = Instant::now();
-        time.update_with_instant(second_update_instant);
-        assert_eq!(time.startup(), start_instant);
-        assert_eq!(time.first_update(), Some(first_update_instant));
-        assert_eq!(time.last_update(), Some(second_update_instant));
+        let second_update = Instant::now();
+        time.update_with_instant(second_update);
+        real_time.update_with_instant(second_update);
+
+        assert_eq!(time.startup(), startup);
+        assert_eq!(time.first_update(), Some(first_update));
+        assert_eq!(time.last_update(), Some(second_update));
         assert_eq!(time.relative_speed(), 1.0);
-        assert_eq!(time.delta(), second_update_instant - first_update_instant);
+        assert_eq!(time.delta(), second_update - first_update);
         assert_eq!(
             time.delta_seconds(),
-            (second_update_instant - first_update_instant).as_secs_f32(),
+            (second_update - first_update).as_secs_f32(),
         );
         assert_eq!(
             time.delta_seconds_f64(),
-            (second_update_instant - first_update_instant).as_secs_f64(),
-        );
-        assert_eq!(
-            time.raw_delta(),
-            second_update_instant - first_update_instant,
+            (second_update - first_update).as_secs_f64(),
         );
+        assert_eq!(real_time.delta(), second_update - first_update);
         assert_eq!(
-            time.raw_delta_seconds(),
-            (second_update_instant - first_update_instant).as_secs_f32(),
+            real_time.delta_seconds(),
+            (second_update - first_update).as_secs_f32(),
         );
         assert_eq!(
-            time.raw_delta_seconds_f64(),
-            (second_update_instant - first_update_instant).as_secs_f64(),
+            real_time.delta_seconds_f64(),
+            (second_update - first_update).as_secs_f64(),
         );
-        assert_eq!(time.elapsed(), second_update_instant - start_instant,);
+        assert_eq!(time.elapsed(), second_update - first_update);
         assert_eq!(
             time.elapsed_seconds(),
-            (second_update_instant - start_instant).as_secs_f32(),
+            (second_update - first_update).as_secs_f32(),
         );
         assert_eq!(
             time.elapsed_seconds_f64(),
-            (second_update_instant - start_instant).as_secs_f64(),
+            (second_update - first_update).as_secs_f64(),
         );
-        assert_eq!(time.raw_elapsed(), second_update_instant - start_instant,);
+        assert_eq!(real_time.elapsed(), second_update - first_update);
         assert_eq!(
-            time.raw_elapsed_seconds(),
-            (second_update_instant - start_instant).as_secs_f32(),
+            real_time.elapsed_seconds(),
+            (second_update - first_update).as_secs_f32(),
         );
         assert_eq!(
-            time.raw_elapsed_seconds_f64(),
-            (second_update_instant - start_instant).as_secs_f64(),
+            real_time.elapsed_seconds_f64(),
+            (second_update - first_update).as_secs_f64(),
         );
 
         // Make app time advance at 2x the rate of your system clock.
         time.set_relative_speed(2.0);
+        time.apply_pending_changes();
 
         // Update `time` again 1 second later.
         let elapsed = Duration::from_secs(1);
-        let third_update_instant = second_update_instant + elapsed;
-        time.update_with_instant(third_update_instant);
+        let third_update = second_update + elapsed;
+        time.update_with_instant(third_update);
+        real_time.update_with_instant(third_update);
 
         // Since app is advancing 2x your system clock, expect time
         // to have advanced by twice the amount of real time elapsed.
-        assert_eq!(time.startup(), start_instant);
-        assert_eq!(time.first_update(), Some(first_update_instant));
-        assert_eq!(time.last_update(), Some(third_update_instant));
+        assert_eq!(time.startup(), startup);
+        assert_eq!(time.first_update(), Some(first_update));
+        assert_eq!(time.last_update(), Some(third_update));
         assert_eq!(time.relative_speed(), 2.0);
         assert_eq!(time.delta(), elapsed.mul_f32(2.0));
         assert_eq!(time.delta_seconds(), elapsed.mul_f32(2.0).as_secs_f32());
         assert_eq!(time.delta_seconds_f64(), elapsed.mul_f32(2.0).as_secs_f64());
-        assert_eq!(time.raw_delta(), elapsed);
-        assert_eq!(time.raw_delta_seconds(), elapsed.as_secs_f32());
-        assert_eq!(time.raw_delta_seconds_f64(), elapsed.as_secs_f64());
+        assert_eq!(real_time.delta(), elapsed);
+        assert_eq!(real_time.delta_seconds(), elapsed.as_secs_f32());
+        assert_eq!(real_time.delta_seconds_f64(), elapsed.as_secs_f64());
         assert_eq!(
             time.elapsed(),
-            second_update_instant - start_instant + elapsed.mul_f32(2.0),
+            second_update - first_update + elapsed.mul_f32(2.0),
         );
         assert_eq!(
             time.elapsed_seconds(),
-            (second_update_instant - start_instant + elapsed.mul_f32(2.0)).as_secs_f32(),
+            (second_update - first_update + elapsed.mul_f32(2.0)).as_secs_f32(),
         );
         assert_eq!(
             time.elapsed_seconds_f64(),
-            (second_update_instant - start_instant + elapsed.mul_f32(2.0)).as_secs_f64(),
-        );
-        assert_eq!(
-            time.raw_elapsed(),
-            second_update_instant - start_instant + elapsed,
+            (second_update - first_update + elapsed.mul_f32(2.0)).as_secs_f64(),
         );
+        assert_eq!(real_time.elapsed(), second_update - first_update + elapsed);
         assert_eq!(
-            time.raw_elapsed_seconds(),
-            (second_update_instant - start_instant + elapsed).as_secs_f32(),
+            real_time.elapsed_seconds(),
+            (second_update - first_update + elapsed).as_secs_f32(),
         );
         assert_eq!(
-            time.raw_elapsed_seconds_f64(),
-            (second_update_instant - start_instant + elapsed).as_secs_f64(),
+            real_time.elapsed_seconds_f64(),
+            (second_update - first_update + elapsed).as_secs_f64(),
         );
     }
 
     #[test]
     fn pause_test() {
-        let start_instant = Instant::now();
-        let mut time = Time::new(start_instant);
+        let startup = Instant::now();
+        let mut time = Time::new(startup);
+        let mut real_time = RealTime::new(startup);
 
-        let first_update_instant = Instant::now();
-        time.update_with_instant(first_update_instant);
+        let first_update = Instant::now();
+        time.update_with_instant(first_update);
+        real_time.update_with_instant(first_update);
 
         assert!(!time.is_paused());
         assert_eq!(time.relative_speed(), 1.0);
 
         time.pause();
+        time.apply_pending_changes();
 
         assert!(time.is_paused());
         assert_eq!(time.relative_speed(), 0.0);
 
-        let second_update_instant = Instant::now();
-        time.update_with_instant(second_update_instant);
-        assert_eq!(time.startup(), start_instant);
-        assert_eq!(time.first_update(), Some(first_update_instant));
-        assert_eq!(time.last_update(), Some(second_update_instant));
+        let second_update = Instant::now();
+        time.update_with_instant(second_update);
+        real_time.update_with_instant(second_update);
+
+        assert_eq!(time.startup(), startup);
+        assert_eq!(time.first_update(), Some(first_update));
+        assert_eq!(time.last_update(), Some(second_update));
         assert_eq!(time.delta(), Duration::ZERO);
-        assert_eq!(
-            time.raw_delta(),
-            second_update_instant - first_update_instant,
-        );
-        assert_eq!(time.elapsed(), first_update_instant - start_instant);
-        assert_eq!(time.raw_elapsed(), second_update_instant - start_instant);
+        assert_eq!(real_time.delta(), second_update - first_update);
+        assert_eq!(time.elapsed(), first_update - first_update);
+        assert_eq!(real_time.elapsed(), second_update - first_update);
 
         time.unpause();
+        time.apply_pending_changes();
 
         assert!(!time.is_paused());
         assert_eq!(time.relative_speed(), 1.0);
 
-        let third_update_instant = Instant::now();
-        time.update_with_instant(third_update_instant);
-        assert_eq!(time.startup(), start_instant);
-        assert_eq!(time.first_update(), Some(first_update_instant));
-        assert_eq!(time.last_update(), Some(third_update_instant));
-        assert_eq!(time.delta(), third_update_instant - second_update_instant);
-        assert_eq!(
-            time.raw_delta(),
-            third_update_instant - second_update_instant,
-        );
+        let third_update = Instant::now();
+        time.update_with_instant(third_update);
+        real_time.update_with_instant(third_update);
+
+        assert_eq!(time.startup(), startup);
+        assert_eq!(time.first_update(), Some(first_update));
+        assert_eq!(time.last_update(), Some(third_update));
+        assert_eq!(time.delta(), third_update - second_update);
+        assert_eq!(real_time.delta(), third_update - second_update);
         assert_eq!(
             time.elapsed(),
-            (third_update_instant - second_update_instant) + (first_update_instant - start_instant),
+            (third_update - second_update) + (first_update - first_update),
         );
-        assert_eq!(time.raw_elapsed(), third_update_instant - start_instant);
+        assert_eq!(real_time.elapsed(), third_update - first_update);
     }
 }