From 471dc7586d9ae616db4e064ba1ea86246a4e8232 Mon Sep 17 00:00:00 2001
From: Joy <51241057+maniwani@users.noreply.github.com>
Date: Sat, 20 Aug 2022 12:45:24 -0700
Subject: [PATCH 1/5] add global time scaling and global time pausing

Co-Authored-By: ira <JustTheCoolDude@gmail.com>
---
 .../src/frame_time_diagnostics_plugin.rs      |   7 +-
 .../src/log_diagnostics_plugin.rs             |   4 +-
 crates/bevy_time/src/time.rs                  | 648 +++++++++++++++---
 examples/2d/text2d.rs                         |   8 +-
 examples/3d/load_gltf.rs                      |   6 +-
 examples/3d/skybox.rs                         |   6 +-
 examples/3d/spotlight.rs                      |   8 +-
 examples/3d/transparency_3d.rs                |   2 +-
 examples/3d/update_gltf_scene.rs              |   4 +-
 examples/animation/custom_skinned_mesh.rs     |   5 +-
 examples/animation/gltf_skinned_mesh.rs       |   4 +-
 examples/audio/audio_control.rs               |   2 +-
 examples/ecs/component_change_detection.rs    |   4 +-
 examples/ecs/fixed_timestep.rs                |  30 +-
 examples/ecs/hierarchy.rs                     |   6 +-
 examples/ecs/removal_detection.rs             |   2 +-
 examples/ecs/state.rs                         |   2 +-
 examples/ecs/system_sets.rs                   |   2 +-
 examples/games/alien_cake_addict.rs           |   5 +-
 examples/scene/scene.rs                       |   2 +-
 examples/tools/scene_viewer.rs                |   6 +-
 examples/ui/text.rs                           |   2 +-
 examples/window/window_settings.rs            |   2 +-
 23 files changed, 602 insertions(+), 165 deletions(-)

diff --git a/crates/bevy_diagnostic/src/frame_time_diagnostics_plugin.rs b/crates/bevy_diagnostic/src/frame_time_diagnostics_plugin.rs
index ec9ea2d9469c1..c651e53a973bc 100644
--- a/crates/bevy_diagnostic/src/frame_time_diagnostics_plugin.rs
+++ b/crates/bevy_diagnostic/src/frame_time_diagnostics_plugin.rs
@@ -35,12 +35,13 @@ impl FrameTimeDiagnosticsPlugin {
     ) {
         diagnostics.add_measurement(Self::FRAME_COUNT, || frame_count.0 as f64);
 
-        if time.delta_seconds_f64() == 0.0 {
+        let delta_seconds = time.raw_delta_seconds_f64();
+        if delta_seconds == 0.0 {
             return;
         }
 
-        diagnostics.add_measurement(Self::FRAME_TIME, || time.delta_seconds_f64() * 1000.);
+        diagnostics.add_measurement(Self::FRAME_TIME, || delta_seconds * 1000.0);
 
-        diagnostics.add_measurement(Self::FPS, || 1.0 / time.delta_seconds_f64());
+        diagnostics.add_measurement(Self::FPS, || 1.0 / delta_seconds);
     }
 }
diff --git a/crates/bevy_diagnostic/src/log_diagnostics_plugin.rs b/crates/bevy_diagnostic/src/log_diagnostics_plugin.rs
index 9966157cb0cf5..588d05013e0e1 100644
--- a/crates/bevy_diagnostic/src/log_diagnostics_plugin.rs
+++ b/crates/bevy_diagnostic/src/log_diagnostics_plugin.rs
@@ -85,7 +85,7 @@ impl LogDiagnosticsPlugin {
         time: Res<Time>,
         diagnostics: Res<Diagnostics>,
     ) {
-        if state.timer.tick(time.delta()).finished() {
+        if state.timer.tick(time.raw_delta()).finished() {
             if let Some(ref filter) = state.filter {
                 for diagnostic in filter.iter().flat_map(|id| {
                     diagnostics
@@ -110,7 +110,7 @@ impl LogDiagnosticsPlugin {
         time: Res<Time>,
         diagnostics: Res<Diagnostics>,
     ) {
-        if state.timer.tick(time.delta()).finished() {
+        if state.timer.tick(time.raw_delta()).finished() {
             if let Some(ref filter) = state.filter {
                 for diagnostic in filter.iter().flat_map(|id| {
                     diagnostics
diff --git a/crates/bevy_time/src/time.rs b/crates/bevy_time/src/time.rs
index 58e4fa1c78353..a7fa93f7da832 100644
--- a/crates/bevy_time/src/time.rs
+++ b/crates/bevy_time/src/time.rs
@@ -2,55 +2,92 @@ use bevy_ecs::{reflect::ReflectResource, system::Resource};
 use bevy_reflect::{FromReflect, Reflect};
 use bevy_utils::{Duration, Instant};
 
-const SECONDS_PER_HOUR: u64 = 60 * 60;
-
-/// Tracks elapsed time since the last update and since the App has started
+/// Tracks how much time has advanced (and also how much real time has elapsed) since
+/// the previous app update and since the app was started.
 #[derive(Resource, Reflect, FromReflect, Debug, Clone)]
 #[reflect(Resource)]
 pub struct Time {
-    delta: Duration,
+    startup: Instant,
+    first_update: Option<Instant>,
     last_update: Option<Instant>,
-    delta_seconds_f64: f64,
+    relative_speed: f64, // using `f64` instead of `f32` to minimize drift from rounding errors
+    paused: bool,
+    delta: Duration,
     delta_seconds: f32,
-    seconds_since_startup: f64,
-    time_since_startup: Duration,
-    startup: Instant,
-    /// The maximum period before [`Time::seconds_since_startup_wrapped_f32`] wraps to 0
-    ///
-    /// Defaults to 1 hour
-    pub wrap_period: Duration,
+    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,
 }
 
 impl Default for Time {
-    fn default() -> Time {
-        Time {
-            delta: Duration::from_secs(0),
-            last_update: None,
+    fn default() -> Self {
+        Self {
             startup: Instant::now(),
-            delta_seconds_f64: 0.0,
-            seconds_since_startup: 0.0,
-            time_since_startup: Duration::from_secs(0),
+            first_update: None,
+            last_update: None,
+            relative_speed: 1.0,
+            paused: false,
+            delta: Duration::ZERO,
             delta_seconds: 0.0,
-            wrap_period: Duration::from_secs(SECONDS_PER_HOUR),
+            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,
         }
     }
 }
 
 impl Time {
+    /// Constructs a new `Time` instance with a specific startup `Instant`.
+    pub fn new(startup: Instant) -> Self {
+        Self {
+            startup,
+            ..Default::default()
+        }
+    }
+
     /// Updates the internal time measurements.
     ///
-    /// Calling this method on the [`Time`] resource as part of your app will most likely result in
-    /// inaccurate timekeeping, as the resource is ordinarily managed by the
-    /// [`TimePlugin`](crate::TimePlugin).
+    /// 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 update(&mut self) {
-        self.update_with_instant(Instant::now());
+        let now = Instant::now();
+        self.update_with_instant(now);
     }
 
-    /// Update time with a specified [`Instant`]
+    /// Updates time with a specified [`Instant`].
     ///
-    /// This method is provided for use in tests. Calling this method on the [`Time`] resource as
-    /// part of your app will most likely result in inaccurate timekeeping, as the resource is
-    /// ordinarily managed by the [`TimePlugin`](crate::TimePlugin).
+    /// 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).
     ///
     /// # Examples
     ///
@@ -99,154 +136,398 @@ impl Time {
     /// }
     /// ```
     pub fn update_with_instant(&mut self, instant: Instant) {
-        if let Some(last_update) = self.last_update {
-            self.delta = instant - last_update;
-            self.delta_seconds_f64 = self.delta.as_secs_f64();
+        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 errors 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);
         }
 
-        self.time_since_startup = instant - self.startup;
-        self.seconds_since_startup = self.time_since_startup.as_secs_f64();
+        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();
+
+        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();
+
         self.last_update = Some(instant);
     }
 
-    /// The delta between the current tick and last tick as a [`Duration`]
+    /// Returns the [`Instant`] the app was started.
+    #[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
     }
 
-    /// The delta between the current and last tick as [`f32`] seconds
+    /// 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
     }
 
-    /// The delta between the current and last tick as [`f64`] 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
     }
 
-    /// The time from startup to the last update in seconds
+    /// 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 exact clock time elapsed since the last [`update`](#method.update), as a [`Duration`].
+    #[inline]
+    pub fn raw_delta(&self) -> Duration {
+        self.raw_delta
+    }
+
+    /// Returns the exact clock time elapsed since the last [`update`](#method.update), as [`f32`] seconds.
+    #[inline]
+    pub fn raw_delta_seconds(&self) -> f32 {
+        self.raw_delta_seconds
+    }
+
+    /// Returns the exact clock time 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 the exact clock time elapsed since [`startup`](#method.startup), as [`Duration`].
+    #[inline]
+    pub fn raw_elapsed(&self) -> Duration {
+        self.raw_elapsed
+    }
+
+    /// Returns the exact clock time elapsed since [`startup`](#method.startup), as [`f32`] seconds.
+    #[inline]
+    pub fn raw_elapsed_seconds(&self) -> f32 {
+        self.raw_elapsed_seconds
+    }
+
+    /// Returns the exact clock time elapsed since [`startup`](#method.startup), as [`f64`] seconds.
+    #[inline]
+    pub fn raw_elapsed_seconds_f64(&self) -> f64 {
+        self.raw_elapsed_seconds_f64
+    }
+
+    /// Returns the exact clock time 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 the exact clock time elapsed since [`startup`](#method.startup) modulo
+    /// the [`wrap_period`](#method.wrap_period), as [`f32`] seconds.
+    #[inline]
+    pub fn raw_elapsed_seconds_wrapped(&self) -> f32 {
+        self.raw_elapsed_seconds_wrapped
+    }
+
+    /// Returns the exact clock time 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
+    }
+
+    /// Returns the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
+    /// [`raw_elapsed_wrapped`](#method.raw_elapsed_wrapped).
     ///
-    /// If you intend to cast this to an `f32` value, note that this value is monotonically increasing,
-    /// and that its precision as an `f32` will noticeably degrade over time (in a matter of hours).
-    /// If that precision loss is unacceptable, you should use [`Time::seconds_since_startup_wrapped_f32`],
-    /// which will return the time from startup modulo a wrapping period.
+    /// **Note:** The default modulus is one hour.
     #[inline]
-    pub fn seconds_since_startup(&self) -> f64 {
-        self.seconds_since_startup
+    pub fn wrap_period(&self) -> Duration {
+        self.wrap_period
     }
 
-    /// The time from startup to the last update, modulo the [`Time::wrap_period`], in seconds.
+    /// Sets the modulus used to calculate [`elapsed_wrapped`](#method.elapsed_wrapped) and
+    /// [`raw_elapsed_wrapped`](#method.raw_elapsed_wrapped).
     ///
-    /// Time from startup is a monotonically increasing value and so its precision when read as an `f32`
-    /// will noticeably degrade over time, which causes issues for some uses, e.g. shaders.
-    /// This method avoids noticeable degradation by limiting the values to a much smaller range.
+    /// # Panics
     ///
-    /// The default wrapping period is one hour.
+    /// Panics if `wrap_period` is zero.
     #[inline]
-    pub fn seconds_since_startup_wrapped_f32(&self) -> f32 {
-        (self.seconds_since_startup % self.wrap_period.as_secs_f64()) as f32
+    pub fn set_wrap_period(&mut self, wrap_period: Duration) {
+        assert!(wrap_period != Duration::ZERO, "division by zero");
+        self.wrap_period = wrap_period;
     }
 
-    /// The [`Instant`] the app was started
+    /// Returns the rate that time advances relative to real time, as [`f32`].
+    /// You might recognize this as "time scaling" or "time dilation" in other engines.
+    ///
+    /// **Note:** This function will return zero when time is paused.
     #[inline]
-    pub fn startup(&self) -> Instant {
-        self.startup
+    pub fn relative_speed(&self) -> f32 {
+        self.relative_speed_f64() as f32
     }
 
-    /// The [`Instant`] when [`Time::update`] was last called, if it exists
+    /// Returns the rate that time advances relative to real time, as [`f64`].
+    /// You might recognize this as "time scaling" or "time dilation" in other engines.
+    ///
+    /// **Note:** This function will return zero when time is paused.
     #[inline]
-    pub fn last_update(&self) -> Option<Instant> {
-        self.last_update
+    pub fn relative_speed_f64(&self) -> f64 {
+        if self.paused {
+            0.0
+        } else {
+            self.relative_speed
+        }
+    }
+
+    /// Sets the rate that time advances relative to real time, given as an [`f32`].
+    ///
+    /// For example, if set to `2.0`, time will advance twice as fast as your system clock.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `ratio` is negative or not finite.
+    #[inline]
+    pub fn set_relative_speed(&mut self, ratio: f32) {
+        self.set_relative_speed_f64(ratio as f64);
+    }
+
+    /// Sets the rate that time advances relative to real time, given as an [`f64`].
+    ///
+    /// For example, if set to `2.0`, time will advance twice as fast as your system clock.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `ratio` 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.is_sign_positive(), "tried to go back in time");
+        self.relative_speed = ratio;
+    }
+
+    /// Stops time, preventing it from advancing until resumed. Does not affect raw measurements.
+    #[inline]
+    pub fn pause(&mut self) {
+        self.paused = true;
+    }
+
+    /// Resumes time if paused.
+    #[inline]
+    pub fn unpause(&mut self) {
+        self.paused = false;
     }
 
-    /// The [`Duration`] from startup to the last update
+    /// Returns `true` if time has been paused.
     #[inline]
-    pub fn time_since_startup(&self) -> Duration {
-        self.time_since_startup
+    pub fn paused(&self) -> bool {
+        self.paused
     }
 }
 
+fn duration_div_rem(dividend: Duration, divisor: Duration) -> (Duration, Duration) {
+    // `Duration` does not have a built-in modulo operation
+    let n = (dividend.as_nanos() / divisor.as_nanos()) as u32;
+    let quotient = n * divisor;
+    let remainder = dividend - quotient;
+    (quotient, remainder)
+}
+
 #[cfg(test)]
 #[allow(clippy::float_cmp)]
 mod tests {
     use super::Time;
     use bevy_utils::{Duration, Instant};
 
+    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);
 
-        // Create a `Time` for testing
-        let mut time = Time {
-            startup: start_instant,
-            ..Default::default()
-        };
-
-        // Ensure `time` was constructed correctly
-        assert_eq!(time.delta(), Duration::from_secs(0));
-        assert_eq!(time.last_update(), None);
+        // Ensure `time` was constructed correctly.
         assert_eq!(time.startup(), start_instant);
-        assert_eq!(time.delta_seconds_f64(), 0.0);
-        assert_eq!(time.seconds_since_startup(), 0.0);
-        assert_eq!(time.time_since_startup(), Duration::from_secs(0));
+        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.seconds_since_startup_wrapped_f32(), 0.0);
-
-        // Update `time` and check results
+        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);
 
-        assert_eq!(time.delta(), Duration::from_secs(0));
-        assert_eq!(time.last_update(), Some(first_update_instant));
         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.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.seconds_since_startup(),
-            (first_update_instant - start_instant).as_secs_f64()
+            time.elapsed_seconds(),
+            (first_update_instant - start_instant).as_secs_f32(),
         );
         assert_eq!(
-            time.time_since_startup(),
-            (first_update_instant - start_instant)
+            time.elapsed_seconds_f64(),
+            (first_update_instant - start_instant).as_secs_f64(),
         );
-        assert_eq!(time.delta_seconds(), 0.0);
-        assert_float_eq(
-            time.seconds_since_startup_wrapped_f32(),
-            time.seconds_since_startup() as f32,
+        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(),
         );
 
-        // Update `time` again and check results
+        // 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.delta(), second_update_instant - first_update_instant);
-        assert_eq!(time.last_update(), Some(second_update_instant));
         assert_eq!(time.startup(), start_instant);
-        // At this point its safe to use time.delta as a valid value
-        // because it's been previously verified to be correct
-        assert_eq!(time.delta_seconds_f64(), time.delta().as_secs_f64());
+        assert_eq!(time.first_update(), Some(first_update_instant));
+        assert_eq!(time.last_update(), Some(second_update_instant));
+        assert_eq!(time.relative_speed(), 1.0);
+        assert_eq!(time.delta(), second_update_instant - first_update_instant);
+        assert_eq!(
+            time.delta_seconds(),
+            (second_update_instant - first_update_instant).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(),
+        );
         assert_eq!(
-            time.seconds_since_startup(),
-            (second_update_instant - start_instant).as_secs_f64()
+            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.time_since_startup(),
-            (second_update_instant - start_instant)
+            time.elapsed_seconds(),
+            (second_update_instant - start_instant).as_secs_f32(),
         );
-        assert_eq!(time.delta_seconds(), time.delta().as_secs_f32());
-        assert_float_eq(
-            time.seconds_since_startup_wrapped_f32(),
-            time.seconds_since_startup() as 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(),
         );
     }
 
     #[test]
-    fn update_wrapping() {
+    fn wrapping_test() {
         let start_instant = Instant::now();
 
         let mut time = Time {
@@ -255,22 +536,171 @@ mod tests {
             ..Default::default()
         };
 
-        assert_eq!(time.seconds_since_startup_wrapped_f32(), 0.0);
+        assert_eq!(time.elapsed_seconds_wrapped(), 0.0);
 
         time.update_with_instant(start_instant + Duration::from_secs(1));
-        assert_float_eq(time.seconds_since_startup_wrapped_f32(), 1.0);
+        assert_float_eq(time.elapsed_seconds_wrapped(), 1.0);
 
         time.update_with_instant(start_instant + Duration::from_secs(2));
-        assert_float_eq(time.seconds_since_startup_wrapped_f32(), 2.0);
+        assert_float_eq(time.elapsed_seconds_wrapped(), 2.0);
 
         time.update_with_instant(start_instant + Duration::from_secs(3));
-        assert_float_eq(time.seconds_since_startup_wrapped_f32(), 0.0);
+        assert_float_eq(time.elapsed_seconds_wrapped(), 0.0);
 
         time.update_with_instant(start_instant + Duration::from_secs(4));
-        assert_float_eq(time.seconds_since_startup_wrapped_f32(), 1.0);
+        assert_float_eq(time.elapsed_seconds_wrapped(), 1.0);
     }
 
-    fn assert_float_eq(a: f32, b: f32) {
-        assert!((a - b).abs() <= f32::EPSILON, "{a} != {b}");
+    #[test]
+    fn relative_speed_test() {
+        let start_instant = Instant::now();
+        let mut time = Time::new(start_instant);
+
+        let first_update_instant = Instant::now();
+        time.update_with_instant(first_update_instant);
+
+        // 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));
+        assert_eq!(time.relative_speed(), 1.0);
+        assert_eq!(time.delta(), second_update_instant - first_update_instant);
+        assert_eq!(
+            time.delta_seconds(),
+            (second_update_instant - first_update_instant).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(),
+        );
+        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_seconds(),
+            (second_update_instant - start_instant).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(),
+        );
+
+        // Make app time advance at 2x the rate of your system clock.
+        time.set_relative_speed(2.0);
+
+        // 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);
+
+        // 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.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!(
+            time.elapsed(),
+            second_update_instant - start_instant + elapsed.mul_f32(2.0),
+        );
+        assert_eq!(
+            time.elapsed_seconds(),
+            (second_update_instant - start_instant + 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,
+        );
+        assert_eq!(
+            time.raw_elapsed_seconds(),
+            (second_update_instant - start_instant + elapsed).as_secs_f32(),
+        );
+        assert_eq!(
+            time.raw_elapsed_seconds_f64(),
+            (second_update_instant - start_instant + elapsed).as_secs_f64(),
+        );
+    }
+
+    #[test]
+    fn pause_test() {
+        let start_instant = Instant::now();
+        let mut time = Time::new(start_instant);
+
+        let first_update_instant = Instant::now();
+        time.update_with_instant(first_update_instant);
+
+        assert!(!time.paused());
+        assert_eq!(time.relative_speed(), 1.0);
+
+        time.pause();
+
+        assert!(time.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));
+        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);
+
+        time.unpause();
+
+        assert!(!time.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,
+        );
+        assert_eq!(
+            time.elapsed(),
+            (third_update_instant - second_update_instant) + (first_update_instant - start_instant),
+        );
+        assert_eq!(time.raw_elapsed(), third_update_instant - start_instant);
     }
 }
diff --git a/examples/2d/text2d.rs b/examples/2d/text2d.rs
index e0093aae5dd9a..176c89b91e0f7 100644
--- a/examples/2d/text2d.rs
+++ b/examples/2d/text2d.rs
@@ -96,8 +96,8 @@ fn animate_translation(
     mut query: Query<&mut Transform, (With<Text>, With<AnimateTranslation>)>,
 ) {
     for mut transform in &mut query {
-        transform.translation.x = 100.0 * time.seconds_since_startup().sin() as f32 - 400.0;
-        transform.translation.y = 100.0 * time.seconds_since_startup().cos() as f32;
+        transform.translation.x = 100.0 * time.elapsed_seconds().sin() - 400.0;
+        transform.translation.y = 100.0 * time.elapsed_seconds().cos();
     }
 }
 
@@ -106,7 +106,7 @@ fn animate_rotation(
     mut query: Query<&mut Transform, (With<Text>, With<AnimateRotation>)>,
 ) {
     for mut transform in &mut query {
-        transform.rotation = Quat::from_rotation_z(time.seconds_since_startup().cos() as f32);
+        transform.rotation = Quat::from_rotation_z(time.elapsed_seconds().cos());
     }
 }
 
@@ -118,6 +118,6 @@ fn animate_scale(
     // rendered quad, resulting in a pixellated look.
     for mut transform in &mut query {
         transform.translation = Vec3::new(400.0, 0.0, 0.0);
-        transform.scale = Vec3::splat((time.seconds_since_startup().sin() as f32 + 1.1) * 2.0);
+        transform.scale = Vec3::splat((time.elapsed_seconds().sin() + 1.1) * 2.0);
     }
 }
diff --git a/examples/3d/load_gltf.rs b/examples/3d/load_gltf.rs
index 06e1de662e082..1a075e70b0ec9 100644
--- a/examples/3d/load_gltf.rs
+++ b/examples/3d/load_gltf.rs
@@ -1,6 +1,6 @@
 //! Loads and renders a glTF file as a scene.
 
-use std::f32::consts::PI;
+use std::f32::consts::*;
 
 use bevy::prelude::*;
 
@@ -52,8 +52,8 @@ fn animate_light_direction(
         transform.rotation = Quat::from_euler(
             EulerRot::ZYX,
             0.0,
-            time.seconds_since_startup() as f32 * PI / 5.0,
-            -PI / 4.,
+            time.elapsed_seconds() * PI / 5.0,
+            -FRAC_PI_4,
         );
     }
 }
diff --git a/examples/3d/skybox.rs b/examples/3d/skybox.rs
index 03dbfa0aacbc5..460c79d1d1191 100644
--- a/examples/3d/skybox.rs
+++ b/examples/3d/skybox.rs
@@ -98,16 +98,16 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     });
 }
 
-const CUBEMAP_SWAP_DELAY: f64 = 3.0;
+const CUBEMAP_SWAP_DELAY: f32 = 3.0;
 
 fn cycle_cubemap_asset(
     time: Res<Time>,
-    mut next_swap: Local<f64>,
+    mut next_swap: Local<f32>,
     mut cubemap: ResMut<Cubemap>,
     asset_server: Res<AssetServer>,
     render_device: Res<RenderDevice>,
 ) {
-    let now = time.seconds_since_startup();
+    let now = time.elapsed_seconds();
     if *next_swap == 0.0 {
         *next_swap = now + CUBEMAP_SWAP_DELAY;
         return;
diff --git a/examples/3d/spotlight.rs b/examples/3d/spotlight.rs
index acf27f0d09cc1..61b01b61ce824 100644
--- a/examples/3d/spotlight.rs
+++ b/examples/3d/spotlight.rs
@@ -1,4 +1,4 @@
-use std::f32::consts::PI;
+use std::f32::consts::*;
 
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
@@ -127,11 +127,11 @@ fn light_sway(time: Res<Time>, mut query: Query<(&mut Transform, &mut SpotLight)
     for (mut transform, mut angles) in query.iter_mut() {
         transform.rotation = Quat::from_euler(
             EulerRot::XYZ,
-            -PI / 2. + (time.seconds_since_startup() * 0.67 * 3.0).sin() as f32 * 0.5,
-            (time.seconds_since_startup() * 3.0).sin() as f32 * 0.5,
+            -FRAC_PI_2 + (time.elapsed_seconds() * 0.67 * 3.0).sin() * 0.5,
+            (time.elapsed_seconds() * 3.0).sin() * 0.5,
             0.0,
         );
-        let angle = ((time.seconds_since_startup() * 1.2).sin() as f32 + 1.0) * (PI / 4. - 0.1);
+        let angle = ((time.elapsed_seconds() * 1.2).sin() + 1.0) * (FRAC_PI_4 - 0.1);
         angles.inner_angle = angle * 0.8;
         angles.outer_angle = angle;
     }
diff --git a/examples/3d/transparency_3d.rs b/examples/3d/transparency_3d.rs
index 4f02259276517..f257eb8c11e7d 100644
--- a/examples/3d/transparency_3d.rs
+++ b/examples/3d/transparency_3d.rs
@@ -103,7 +103,7 @@ fn setup(
 ///                when the alpha value goes back below the threshold.
 /// - `Blend`: Object fades in and out smoothly.
 pub fn fade_transparency(time: Res<Time>, mut materials: ResMut<Assets<StandardMaterial>>) {
-    let alpha = (time.time_since_startup().as_secs_f32().sin() / 2.0) + 0.5;
+    let alpha = (time.elapsed_seconds().sin() / 2.0) + 0.5;
     for (_, material) in materials.iter_mut() {
         material.base_color.set_a(alpha);
     }
diff --git a/examples/3d/update_gltf_scene.rs b/examples/3d/update_gltf_scene.rs
index 265cf09f375b9..deecd3d69f5e5 100644
--- a/examples/3d/update_gltf_scene.rs
+++ b/examples/3d/update_gltf_scene.rs
@@ -54,9 +54,9 @@ fn move_scene_entities(
         iter_hierarchy(moved_scene_entity, &children, &mut |entity| {
             if let Ok(mut transform) = transforms.get_mut(entity) {
                 transform.translation = Vec3::new(
-                    offset * time.seconds_since_startup().sin() as f32 / 20.,
+                    offset * time.elapsed_seconds().sin() / 20.,
                     0.,
-                    time.seconds_since_startup().cos() as f32 / 20.,
+                    time.elapsed_seconds().cos() / 20.,
                 );
                 offset += 1.0;
             }
diff --git a/examples/animation/custom_skinned_mesh.rs b/examples/animation/custom_skinned_mesh.rs
index bc122453d6878..689c3a2e91917 100644
--- a/examples/animation/custom_skinned_mesh.rs
+++ b/examples/animation/custom_skinned_mesh.rs
@@ -1,7 +1,7 @@
 //! Skinned mesh example with mesh and joints data defined in code.
 //! Example taken from <https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_019_SimpleSkin.md>
 
-use std::f32::consts::PI;
+use std::f32::consts::*;
 
 use bevy::{
     pbr::AmbientLight,
@@ -162,7 +162,6 @@ fn setup(
 /// Animate the joint marked with [`AnimatedJoint`] component.
 fn joint_animation(time: Res<Time>, mut query: Query<&mut Transform, With<AnimatedJoint>>) {
     for mut transform in &mut query {
-        transform.rotation =
-            Quat::from_rotation_z(PI / 2. * time.time_since_startup().as_secs_f32().sin());
+        transform.rotation = Quat::from_rotation_z(FRAC_PI_2 * time.elapsed_seconds().sin());
     }
 }
diff --git a/examples/animation/gltf_skinned_mesh.rs b/examples/animation/gltf_skinned_mesh.rs
index a0f29384d0904..80c0df7aa6b29 100644
--- a/examples/animation/gltf_skinned_mesh.rs
+++ b/examples/animation/gltf_skinned_mesh.rs
@@ -1,7 +1,7 @@
 //! Skinned mesh example with mesh and joints data loaded from a glTF file.
 //! Example taken from <https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_019_SimpleSkin.md>
 
-use std::f32::consts::PI;
+use std::f32::consts::*;
 
 use bevy::{pbr::AmbientLight, prelude::*, render::mesh::skinning::SkinnedMesh};
 
@@ -67,6 +67,6 @@ fn joint_animation(
         let mut second_joint_transform = transform_query.get_mut(second_joint_entity).unwrap();
 
         second_joint_transform.rotation =
-            Quat::from_rotation_z(PI / 2. * time.time_since_startup().as_secs_f32().sin());
+            Quat::from_rotation_z(FRAC_PI_2 * time.elapsed_seconds().sin());
     }
 }
diff --git a/examples/audio/audio_control.rs b/examples/audio/audio_control.rs
index 2c5da2c919936..d5344e68ead8b 100644
--- a/examples/audio/audio_control.rs
+++ b/examples/audio/audio_control.rs
@@ -32,7 +32,7 @@ fn update_speed(
     time: Res<Time>,
 ) {
     if let Some(sink) = audio_sinks.get(&music_controller.0) {
-        sink.set_speed(((time.seconds_since_startup() / 5.0).sin() as f32 + 1.0).max(0.1));
+        sink.set_speed(((time.elapsed_seconds() / 5.0).sin() + 1.0).max(0.1));
     }
 }
 
diff --git a/examples/ecs/component_change_detection.rs b/examples/ecs/component_change_detection.rs
index 75938c6d3ce23..56823144d945f 100644
--- a/examples/ecs/component_change_detection.rs
+++ b/examples/ecs/component_change_detection.rs
@@ -14,7 +14,7 @@ fn main() {
 }
 
 #[derive(Component, Debug)]
-struct MyComponent(f64);
+struct MyComponent(f32);
 
 fn setup(mut commands: Commands) {
     commands.spawn(MyComponent(0.));
@@ -25,7 +25,7 @@ fn change_component(time: Res<Time>, mut query: Query<(Entity, &mut MyComponent)
     for (entity, mut component) in &mut query {
         if rand::thread_rng().gen_bool(0.1) {
             info!("changing component {:?}", entity);
-            component.0 = time.seconds_since_startup();
+            component.0 = time.elapsed_seconds();
         }
     }
 }
diff --git a/examples/ecs/fixed_timestep.rs b/examples/ecs/fixed_timestep.rs
index 0f58e7d531ee8..77755dc42a58e 100644
--- a/examples/ecs/fixed_timestep.rs
+++ b/examples/ecs/fixed_timestep.rs
@@ -31,22 +31,30 @@ fn main() {
         .run();
 }
 
-fn frame_update(mut last_time: Local<f64>, time: Res<Time>) {
-    info!("update: {}", time.seconds_since_startup() - *last_time);
-    *last_time = time.seconds_since_startup();
+fn frame_update(mut last_time: Local<f32>, time: Res<Time>) {
+    info!(
+        "time since last frame_update: {}",
+        time.raw_elapsed_seconds() - *last_time
+    );
+    *last_time = time.raw_elapsed_seconds();
 }
 
-fn fixed_update(mut last_time: Local<f64>, time: Res<Time>, fixed_timesteps: Res<FixedTimesteps>) {
+fn fixed_update(mut last_time: Local<f32>, time: Res<Time>, fixed_timesteps: Res<FixedTimesteps>) {
     info!(
-        "fixed_update: {}",
-        time.seconds_since_startup() - *last_time,
+        "time since last fixed_update: {}\n",
+        time.raw_elapsed_seconds() - *last_time
     );
 
-    let fixed_timestep = fixed_timesteps.get(LABEL).unwrap();
+    let state = fixed_timesteps.get(LABEL).unwrap();
+
+    info!("fixed timestep: {}\n", 0.5);
     info!(
-        "  overstep_percentage: {}",
-        fixed_timestep.overstep_percentage()
+        "time accrued toward next fixed_update: {}\n",
+        state.accumulator()
     );
-
-    *last_time = time.seconds_since_startup();
+    info!(
+        "time accrued toward next fixed_update (% of timestep): {}",
+        state.overstep_percentage()
+    );
+    *last_time = time.raw_elapsed_seconds();
 }
diff --git a/examples/ecs/hierarchy.rs b/examples/ecs/hierarchy.rs
index b4b35b7b39aad..fc1aa353244b3 100644
--- a/examples/ecs/hierarchy.rs
+++ b/examples/ecs/hierarchy.rs
@@ -1,6 +1,6 @@
 //! Creates a hierarchy of parents and children entities.
 
-use std::f32::consts::PI;
+use std::f32::consts::*;
 
 use bevy::prelude::*;
 
@@ -78,12 +78,12 @@ fn rotate(
         }
 
         // To demonstrate removing children, we'll remove a child after a couple of seconds.
-        if time.seconds_since_startup() >= 2.0 && children.len() == 2 {
+        if time.elapsed_seconds() >= 2.0 && children.len() == 2 {
             let child = children.last().unwrap();
             commands.entity(*child).despawn_recursive();
         }
 
-        if time.seconds_since_startup() >= 4.0 {
+        if time.elapsed_seconds() >= 4.0 {
             // This will remove the entity from its parent's list of children, as well as despawn
             // any children the entity has.
             commands.entity(parent).despawn_recursive();
diff --git a/examples/ecs/removal_detection.rs b/examples/ecs/removal_detection.rs
index 66c929390393a..f931066a4a4ec 100644
--- a/examples/ecs/removal_detection.rs
+++ b/examples/ecs/removal_detection.rs
@@ -44,7 +44,7 @@ fn remove_component(
     query: Query<Entity, With<MyComponent>>,
 ) {
     // After two seconds have passed the `Component` is removed.
-    if time.seconds_since_startup() > 2.0 {
+    if time.elapsed_seconds() > 2.0 {
         if let Some(entity) = query.iter().next() {
             commands.entity(entity).remove::<MyComponent>();
         }
diff --git a/examples/ecs/state.rs b/examples/ecs/state.rs
index 4025c40d10247..37cfcece63150 100644
--- a/examples/ecs/state.rs
+++ b/examples/ecs/state.rs
@@ -134,6 +134,6 @@ fn change_color(time: Res<Time>, mut query: Query<&mut Sprite>) {
     for mut sprite in &mut query {
         sprite
             .color
-            .set_b((time.seconds_since_startup() * 0.5).sin() as f32 + 2.0);
+            .set_b((time.elapsed_seconds() * 0.5).sin() as f32 + 2.0);
     }
 }
diff --git a/examples/ecs/system_sets.rs b/examples/ecs/system_sets.rs
index 0e591e59c0d2e..3461786768c09 100644
--- a/examples/ecs/system_sets.rs
+++ b/examples/ecs/system_sets.rs
@@ -90,7 +90,7 @@ fn main() {
 /// Example of a run criteria.
 /// Here we only want to run for a second, then stop.
 fn run_for_a_second(time: Res<Time>, mut done: ResMut<Done>) -> ShouldRun {
-    let elapsed = time.seconds_since_startup();
+    let elapsed = time.elapsed_seconds();
     if elapsed < 1.0 {
         info!(
             "We should run again. Elapsed/remaining: {:.2}s/{:.2}s",
diff --git a/examples/games/alien_cake_addict.rs b/examples/games/alien_cake_addict.rs
index 98c5af8694569..2330370d49069 100644
--- a/examples/games/alien_cake_addict.rs
+++ b/examples/games/alien_cake_addict.rs
@@ -356,9 +356,8 @@ fn rotate_bonus(game: Res<Game>, time: Res<Time>, mut transforms: Query<&mut Tra
     if let Some(entity) = game.bonus.entity {
         if let Ok(mut cake_transform) = transforms.get_mut(entity) {
             cake_transform.rotate_y(time.delta_seconds());
-            cake_transform.scale = Vec3::splat(
-                1.0 + (game.score as f32 / 10.0 * time.seconds_since_startup().sin() as f32).abs(),
-            );
+            cake_transform.scale =
+                Vec3::splat(1.0 + (game.score as f32 / 10.0 * time.elapsed_seconds().sin()).abs());
         }
     }
 }
diff --git a/examples/scene/scene.rs b/examples/scene/scene.rs
index 581cdd934d64e..e8e0271af28a1 100644
--- a/examples/scene/scene.rs
+++ b/examples/scene/scene.rs
@@ -52,7 +52,7 @@ impl FromWorld for ComponentB {
     fn from_world(world: &mut World) -> Self {
         let time = world.resource::<Time>();
         ComponentB {
-            _time_since_startup: time.time_since_startup(),
+            _time_since_startup: time.elapsed(),
             value: "Default Value".to_string(),
         }
     }
diff --git a/examples/tools/scene_viewer.rs b/examples/tools/scene_viewer.rs
index 9f216e42fe6d5..fac2833773c05 100644
--- a/examples/tools/scene_viewer.rs
+++ b/examples/tools/scene_viewer.rs
@@ -14,7 +14,7 @@ use bevy::{
     scene::InstanceId,
 };
 
-use std::f32::consts::PI;
+use std::f32::consts::*;
 
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemLabel)]
 struct CameraControllerCheckSystem;
@@ -331,8 +331,8 @@ fn update_lights(
             transform.rotation = Quat::from_euler(
                 EulerRot::ZYX,
                 0.0,
-                time.seconds_since_startup() as f32 * PI / 15.0,
-                -PI / 4.,
+                time.elapsed_seconds() * PI / 15.0,
+                -FRAC_PI_4,
             );
         }
     }
diff --git a/examples/ui/text.rs b/examples/ui/text.rs
index ddfaf940fb0b6..97dae334bec4e 100644
--- a/examples/ui/text.rs
+++ b/examples/ui/text.rs
@@ -78,7 +78,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
 
 fn text_color_system(time: Res<Time>, mut query: Query<&mut Text, With<ColorText>>) {
     for mut text in &mut query {
-        let seconds = time.seconds_since_startup() as f32;
+        let seconds = time.elapsed_seconds();
 
         // Update the color of the first and only section.
         text.sections[0].style.color = Color::Rgba {
diff --git a/examples/window/window_settings.rs b/examples/window/window_settings.rs
index a56f20ee49ca1..9fa9b6c9f8e65 100644
--- a/examples/window/window_settings.rs
+++ b/examples/window/window_settings.rs
@@ -46,7 +46,7 @@ fn change_title(time: Res<Time>, mut windows: ResMut<Windows>) {
     let window = windows.primary_mut();
     window.set_title(format!(
         "Seconds since startup: {}",
-        time.seconds_since_startup().round()
+        time.elapsed_seconds().round()
     ));
 }
 

From d20c3c0786d4a7df86f7a9f8b50935575eefd9c9 Mon Sep 17 00:00:00 2001
From: Joy <51241057+maniwani@users.noreply.github.com>
Date: Wed, 19 Oct 2022 18:44:10 -0700
Subject: [PATCH 2/5] fix

---
 crates/bevy_render/src/globals.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_render/src/globals.rs b/crates/bevy_render/src/globals.rs
index bba154d5a5c79..c910e13768d85 100644
--- a/crates/bevy_render/src/globals.rs
+++ b/crates/bevy_render/src/globals.rs
@@ -57,7 +57,7 @@ fn prepare_globals_buffer(
     frame_count: Res<FrameCount>,
 ) {
     let buffer = globals_buffer.buffer.get_mut();
-    buffer.time = time.seconds_since_startup_wrapped_f32();
+    buffer.time = time.elapsed_seconds_wrapped();
     buffer.delta_time = time.delta_seconds();
     buffer.frame_count = frame_count.0;
 

From 5eeea40b7a8fc2b40d4b2de0aef56743206191c2 Mon Sep 17 00:00:00 2001
From: Joy <51241057+maniwani@users.noreply.github.com>
Date: Wed, 19 Oct 2022 18:53:14 -0700
Subject: [PATCH 3/5] is_

---
 crates/bevy_time/src/time.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_time/src/time.rs b/crates/bevy_time/src/time.rs
index a7fa93f7da832..c700f08b6fa64 100644
--- a/crates/bevy_time/src/time.rs
+++ b/crates/bevy_time/src/time.rs
@@ -396,7 +396,7 @@ impl Time {
 
     /// Returns `true` if time has been paused.
     #[inline]
-    pub fn paused(&self) -> bool {
+    pub fn is_paused(&self) -> bool {
         self.paused
     }
 }
@@ -661,12 +661,12 @@ mod tests {
         let first_update_instant = Instant::now();
         time.update_with_instant(first_update_instant);
 
-        assert!(!time.paused());
+        assert!(!time.is_paused());
         assert_eq!(time.relative_speed(), 1.0);
 
         time.pause();
 
-        assert!(time.paused());
+        assert!(time.is_paused());
         assert_eq!(time.relative_speed(), 0.0);
 
         let second_update_instant = Instant::now();
@@ -684,7 +684,7 @@ mod tests {
 
         time.unpause();
 
-        assert!(!time.paused());
+        assert!(!time.is_paused());
         assert_eq!(time.relative_speed(), 1.0);
 
         let third_update_instant = Instant::now();

From 362c27da6c63380203e0ca311a8d6db4e649d9fc Mon Sep 17 00:00:00 2001
From: Joy <51241057+maniwani@users.noreply.github.com>
Date: Wed, 19 Oct 2022 18:56:09 -0700
Subject: [PATCH 4/5] doc symmetry

---
 crates/bevy_time/src/time.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/crates/bevy_time/src/time.rs b/crates/bevy_time/src/time.rs
index c700f08b6fa64..657960e440289 100644
--- a/crates/bevy_time/src/time.rs
+++ b/crates/bevy_time/src/time.rs
@@ -281,6 +281,10 @@ impl Time {
     }
 
     /// Returns the exact clock time 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
@@ -301,6 +305,9 @@ impl Time {
 
     /// Returns the exact clock time 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

From 82dde580535cf18991cd9562711238b44eafd8ff Mon Sep 17 00:00:00 2001
From: Joy <51241057+maniwani@users.noreply.github.com>
Date: Wed, 19 Oct 2022 19:03:56 -0700
Subject: [PATCH 5/5] Update time.rs

---
 crates/bevy_time/src/time.rs | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_time/src/time.rs b/crates/bevy_time/src/time.rs
index 657960e440289..e6d2d70c9af82 100644
--- a/crates/bevy_time/src/time.rs
+++ b/crates/bevy_time/src/time.rs
@@ -408,11 +408,10 @@ impl Time {
     }
 }
 
-fn duration_div_rem(dividend: Duration, divisor: Duration) -> (Duration, Duration) {
+fn duration_div_rem(dividend: Duration, divisor: Duration) -> (u32, Duration) {
     // `Duration` does not have a built-in modulo operation
-    let n = (dividend.as_nanos() / divisor.as_nanos()) as u32;
-    let quotient = n * divisor;
-    let remainder = dividend - quotient;
+    let quotient = (dividend.as_nanos() / divisor.as_nanos()) as u32;
+    let remainder = dividend - (quotient * divisor);
     (quotient, remainder)
 }