Add a lot of documentation

Author: nakedible

crates/bevy_time/src/fixed.rs

@@ -6,40 +6,107 @@ use crate::FixedUpdate;
 use crate::time::Time;
 use crate::virt::Virtual;
 
+/// The fixed timestep game clock following virtual time.
+///
+/// Normally used as `Time<Fixed>`. It is automatically inserted as a resource
+/// by `TimePlugin` and updated based on `Time<Virtual>`. The fixed clock is
+/// automatically set as the generic `Time` resource during `FixedUpdate`
+/// schedule processing.
+/// 
+/// The fixed timestep game clock runs at a regular interval and is extremely
+/// useful for steady, frame-rate independent gameplay logic and physics. 
+/// 
+/// To run a system on a fixed timestep, add it to the `FixedUpdate` schedule.
+/// This schedule is run a number of times between `PreUpdate` and `Update`
+/// according to the accumulated `overstep()` time divided by the `timestep()`.
+/// This means the schedule may run 0, 1 or more times during a single update.
+/// 
+/// `Time<Fixed>` and the generic `Time` resource will report a `delta()` equal
+/// to `timestep()` and always grow `elapsed()` by one `timestep()` per
+/// iteration.
+/// 
+/// The fixed timestep clock follows the `Time<Virtual>` clock, which means it
+/// is affected by `paused()`, `relative_speed()` and `max_delta()` from virtual
+/// time. If the virtual clock is paused, the `FixedUpdate` schedule will not
+/// run. It is guaranteed that the `elapsed()` time in `Time<Fixed>` is always
+/// between the previous `elapsed()` and the next `elapsed()` value in
+/// `Time<Virtual>`, so the values are compatible.
+/// 
+/// Changing the timestep size while the game is running should not normally be
+/// done, as having a regular interval is the point of this schedule, but it may
+/// be necessary for effects like "bullet-time" if the normal granularity of the
+/// fixed timestep is too big for the slowed down time. In this case,
+/// `set_timestep()` and be called to set a new value. The new value will be
+/// used immediately for the next run of the `FixedUpdate` schedule, meaning
+/// that it will affect the `delta()` value for the very next `FixedUpdate`,
+/// even if it is still during the same frame. Any `overstep()` present in the
+/// accumulator will be processed according to the new `timestep()` value.
+
 #[derive(Debug, Copy, Clone, Reflect, FromReflect)]
 pub struct Fixed {
     timestep: Duration,
     overstep: Duration,
 }
 
 impl Time<Fixed> {
+    /// Returns the amount of virtual time that must pass before the fixed
+    /// timestep schedule is run again.
     pub fn timestep(&self) -> Duration {
         self.context().timestep
     }
 
+    /// Sets the amount of virtual time that must pass before the fixed timestep
+    /// schedule is run again, as [`Duration`].
+    /// 
+    /// Takes effect immediately on the next run of the schedule, respecting
+    /// what is currently in `overstep()`.
     pub fn set_timestep(&mut self, timestep: Duration) {
         assert_ne!(timestep, Duration::ZERO, "attempted to set fixed timestep to zero");
         self.context_mut().timestep = timestep;
     }
 
+    /// Sets the amount of virtual time that must pass before the fixed timestep
+    /// schedule is run again, as seconds.
+    /// 
+    /// Timestep is stored as a `Duration`, which has fixed nanosecond
+    /// resolution and will be converted from the floating point number.
+    /// 
+    /// Takes effect immediately on the next run of the schedule, respecting
+    /// what is currently in `overstep()`.
     pub fn set_timestep_seconds(&mut self, seconds: f64) {
+        assert!(seconds.is_sign_positive(), "seconds less than or equal to zero");
+        assert!(seconds.is_finite(), "seconds is infinite");
         self.set_timestep(Duration::from_secs_f64(seconds));
     }
 
+    /// Sets the amount of virtual time that must pass before the fixed timestep
+    /// schedule is run again, as frequency.
+    /// 
+    /// The timestep value is set to `1 / hz`, converted to a `Duration` which
+    /// has fixed nanosecond resolution.
+    /// 
+    /// Takes effect immediately on the next run of the schedule, respecting
+    /// what is currently in `overstep()`.
     pub fn set_timestep_hz(&mut self, hz: f64) {
         assert!(hz.is_sign_positive(), "Hz less than or equal to zero");
         assert!(hz.is_finite(), "Hz is infinite");
         self.set_timestep_seconds(1.0 / hz);
     }
 
+    /// Returns the amount of overstep time accumulated toward new steps, as
+    /// `Duration`.
     pub fn overstep(&self) -> Duration {
         self.context().overstep
     }
 
+    /// Returns the amount of overstep time accumulated toward new steps, as an
+    /// [`f32`] fraction of the timestep.
     pub fn overstep_percentage(&self) -> f32 {
         self.context().overstep.as_secs_f32() / self.context().timestep.as_secs_f32()
     }
 
+    /// Returns the amount of overstep time accumulated toward new steps, as an
+    /// [`f64`] fraction of the timestep.
     pub fn overstep_percentage_f64(&self) -> f64 {
         self.context().overstep.as_secs_f64() / self.context().timestep.as_secs_f64()
     }

crates/bevy_time/src/real.rs

@@ -3,6 +3,25 @@ use bevy_reflect::{FromReflect, Reflect};
 
 use crate::time::Time;
 
+/// Real time clock representing elapsed wall clock time.
+/// 
+/// Normally used as `Time<Real>`. It is automatically inserted as a resource by
+/// `TimePlugin` and updated with time instants based on `TimeUpdateStrategy`.
+/// 
+/// The `delta()` and `elapsed()` values of this clock should be used for
+/// anything which deals specifically with real time (wall clock time). It will
+/// not be affected by relative game speed adjustments, pausing or other
+/// adjustments.
+/// 
+/// The clock does not count time from `startup()` to `first_update()` into
+/// elapsed, but instead will start counting time from the first update call.
+/// `delta()` and `elapsed()` will report zero on the first update as there is
+/// no previous update instant. This means that a `delta()` of zero must be
+/// handled without errors in application logic, as it may theoretically also
+/// happen at other times.
+/// 
+/// `Instant`s for `startup()`, `first_update()` and `last_update()` are
+/// recorded and accessible.
 #[derive(Debug, Copy, Clone, Reflect, FromReflect)]
 pub struct Real {
     startup: Instant,
@@ -21,6 +40,7 @@ impl Default for Real {
 }
 
 impl Time<Real> {
+    /// Constructs a new `Time<Real>` instance with a specific startup `Instant`.
     pub fn new(startup: Instant) -> Self {
         Self::new_with(Real {
             startup,

crates/bevy_time/src/time.rs

@@ -2,8 +2,83 @@ use bevy_ecs::{reflect::ReflectResource, system::Resource};
 use bevy_reflect::{FromReflect, Reflect};
 use bevy_utils::Duration;
 
-/// A generic clock that tracks how much it has advanced its previous update and
-/// since its creation.
+/// A generic clock resource that tracks how much it has advanced its previous
+/// update and since its creation.
+/// 
+/// Multiple instances of this resource are inserted automatically by
+/// `TimePlugin`:
+/// 
+/// - `Time<Real>` tracks real wall-clock time.
+/// - `Time<Virtual>` tracks virtual game time that may be paused or scaled.
+/// - `Time<Fixed` tracks fixed timesteps based on virtual time.
+/// - `Time` is a generic clock that corresponds to "current" or "default" time
+///   for systems. It contains `Time<Virtual>` except inside the `FixedUpdate`
+///   schedule when it contains `Time<Fixed`.
+/// 
+/// A clock tracks the time elapsed since the previous time this clock was
+/// advanced as `delta()` and the total amount of time the clock has been
+/// advanced with as `elapsed()`. Both are represented as exact `Duration`
+/// values with fixed nanosecond precision. The clock does not support time
+/// moving backwards, but it can be updated with `Duration::ZERO` which will set
+/// `delta()` to zero.
+/// 
+/// These values are also available in seconds as `f32` via `delta_seconds()`
+/// and `elapsed_seconds()`, and also in seconds as `f64` via
+/// `delta_seconds_f64()` and `elapsed_seconds_f64()`.
+/// 
+/// Since `elapsed_seconds()` will grow constantly and is `f32`, it will exhibit
+/// gradual precision loss. For applications that require an `f32` value but
+/// suffer from gradual precision loss there is `wrapped_elapsed_seconds()`
+/// available. The same wrapped value is also available as `Duration` and `f64`
+/// for consistency. The wrap period is by default 1 hour, and can be set by
+/// `set_wrap_period()`.
+/// 
+/// # Accessing clocks
+/// 
+/// By default, any systems requiring current `delta()` or `elapsed()` should
+/// use `Res<Time>` to access the default time configured for the program. By
+/// default, this refers to `Time<Virtual>` except during `FixedUpdate` when it
+/// refers to `Time<Fixed>`. This makes your system compatible to be used either
+/// in `Update` or `FixedUpdate` schedule depending on what is needed.
+/// 
+/// If your system needs to react based on real time (wall clock time), like for
+/// user interfaces, it should use `Res<Time<Real>>`. The `delta()` and
+/// `elapsed()` values will always correspond to real time and will not be
+/// affected by pause, time scaling or other tweaks.
+/// 
+/// If your system specifically needs to access fixed timestep clock, even when
+/// placed in `Update` schedule, you should use `Res<Time<Fixed>>`. The
+/// `delta()` and `elapsed()` values will correspond to the latest fixed
+/// timestep that has been run.
+/// 
+/// Finally, if your system specifically needs to know the current virtual game
+/// time, even if placed inside `FixedUpdate`, for example to know if the game
+/// is `paused()` or to use `relative_speed()`, you can use
+/// `Res<Time<Virtual>>`. However, if the system is placed in `FixedUpdate`,
+/// extra care must be used because your system might be run multiple times with
+/// the same `delta()` and `elapsed()` values as the virtual game time has not
+/// changed between the iterations.
+/// 
+/// If you need to change the settings for any of the clocks, for example to
+/// `pause()` the game, you should use `ResMut<Time<Virtual>>`.
+/// 
+/// # Adding custom clocks
+/// 
+/// New custom clocks can be created by creating your own struct as a context
+/// and passing it to `new_from()`. These clocks can be inserted as resources as
+/// normal and then accessed by systems. You can use the `advance_by()` or
+/// `advance_to()` methods to move the clock forwards based on your own logic.
+/// 
+/// Your context struct will need to implement the `Default` trait because
+/// `Time` structures support reflection. It also makes initialization trivial
+/// by being able to call `app.init_resource::<Time<Custom>>()`.
+/// 
+/// You can also replace the "generic" `Time` clock resource if the "default"
+/// time for your game should not be the default virtual time provided. You can
+/// get a "generic" snapshot of your clock by calling `as_generic()` and then
+/// overwrite the `Time` resource with it. The default systems added by
+/// `TimePlugin` will overwrite the `Time` clock during `First` and
+/// `FixedUpdate` schedules.
 #[derive(Resource, Debug, Copy, Clone, Reflect, FromReflect)]
 #[reflect(Resource)]
 pub struct Time<T: Default = ()> {
@@ -23,7 +98,7 @@ pub struct Time<T: Default = ()> {
 impl<T: Default> Time<T> {
     const DEFAULT_WRAP_SECONDS: u64 = 3600; // 1 hour
 
-    /// Create a new clock with `delta` and `elapsed` starting from zero.
+    /// Create a new clock from context with `delta` and `elapsed` starting from zero.
     pub fn new_with(context: T) -> Self {
         Self {
             context,

crates/bevy_time/src/virt.rs

@@ -5,6 +5,60 @@ use bevy_reflect::{FromReflect, Reflect};
 use crate::time::Time;
 use crate::real::Real;
 
+/// The virtual game clock representing game time.
+/// 
+/// Normally used as `Time<Virtual>`. It is automatically inserted as a resource
+/// by `TimePlugin` and updated based on `Time<Real>`. The virtual clock is
+/// automatically set as the default generic `Time` resource for the update.
+/// 
+/// Virtual clock differs from real time clock in that it can be paused, sped up
+/// and slowed down. It also limits the amount it will move forward based on a
+/// single update, to prevent bugs and bad behaviour in game logic if the
+/// updates do not always come at regular intervals.
+/// 
+/// The virtual clock can be paused by calling `pause()` and unpaused by calling
+/// `unpause()`. When the game clock is paused `delta()` will be zero on each
+/// update, and `elapsed()` will not grow. `effective_relative_speed()` will
+/// return `0.0`. Calling `pause()` will not affect value the `delta()` value
+/// for the update currently being processed.
+/// 
+/// The speed of the virtual clock can be changed by calling
+/// `set_relative_speed()`. A value of `2.0` means that virtual clock should
+/// advance twice as fast as real time, meaning that `delta()` values will be
+/// double of what `Time<Real>::delta()` reports and `elapsed()` will go twice
+/// as fast as `Time<Real>::elapsed()`. Calling `set_relative_speed()` will not
+/// affect the `delta()` value for the update currently being processed.
+/// 
+/// The maximum amount of delta time that can be added by a single update can be
+/// set by `set_max_delta()`. This value serves a dual purpose in the virtual
+/// clock.
+/// 
+/// If the game temporarily freezes due to any reason, such as disk access, a
+/// blocking system call, or operating system level suspend, reporting the full
+/// elapsed delta time is likely to cause bugs in game logic. Usually if a
+/// laptop is suspended for an hour, it doesn't make sense to try to simulate
+/// the game logic for the elapsed hour when resuming. Instead it is better to
+/// lose the extra time and pretend a shorter duration of time passed. Setting
+/// `max_delta` to a relatively short time means that the impact on game logic
+/// will be minimal.
+/// 
+/// If the game lags for some reason, meaning that it will take a longer time to
+/// compute a frame than the real time that passes during the computation, then
+/// we would fall behind in processing virtual time. If this situation persists,
+/// and computing a frame takes longer depending on how much virtual time has
+/// passed, the game would enter a "death spiral" where computing each frame
+/// takes longer and longer and the game will appear to freeze. By limiting the
+/// maximum time that can be added at once, we also limit the amount of virtual
+/// time the game needs to compute for each frame. This means that the game will
+/// run slow, and it will run slower than real time, but it will not freeze and
+/// it will recover as soon as computation becomes fast again.
+/// 
+/// You should set `max_delta()` to a value that is approximately the minimum
+/// FPS your game should have even if heavily lagged for a moment. The actual
+/// FPS when lagged will be somewhat lower than this, depending on how much more
+/// time it takes to compute a frame compared to real time. You should also
+/// consider how stable your FPS is, as the limit will also dictate how big of
+/// an FPS drop you can accept without losing time and falling behind real time.
 #[derive(Debug, Copy, Clone, Reflect, FromReflect)]
 pub struct Virtual {
     max_delta: Duration,
@@ -13,26 +67,41 @@ pub struct Virtual {
 }
 
 impl Time<Virtual> {
-    /// Default max_delta value.
     const DEFAULT_MAX_DELTA: Duration = Duration::from_millis(333); // XXX: better value
 
-    /// Returns the maximum amount of time that can be added to the clock by a
+    /// Returns the maximum amount of time that can be added to this clock by a
     /// single update, as [`std::time::Duration`].
     /// 
     /// This is the maximum value [`Self::delta()`] will return and also to
-    /// maximum time [`Self::elapsed()`] will be increased by in a single update.
+    /// maximum time [`Self::elapsed()`] will be increased by in a single
+    /// update.
+    /// 
+    /// This ensures that even if there are no updates scheduled for an extended
+    /// amount of time, there won't be a huge update at once for the clock. This
+    /// also limits the number of fixed time ticks that will be evaluated at
+    /// maximum per a single update.
+    /// 
+    /// The default value is [`Self::DEFAULT_MAX_DELTA`].
     #[inline]
     pub fn max_delta(&self) -> Duration {
         self.context().max_delta
     }
 
-    /// Sets the maximum amount of time that can be added to the clock by a
+    /// Sets the maximum amount of time that can be added to this clock by a
     /// single update, as [`std::time::Duration`].
     /// 
-    /// This ensures that even if there are no updates scheduled for an extended
-    /// amount of time, there won't be a huge update at once for the clock. This
-    /// also limits the number of fixed time ticks that will be evaluated at
-    /// maximum per a single update.
+    /// This is the maximum value [`Self::delta()`] will return and also to
+    /// maximum time [`Self::elapsed()`] will be increased by in a single
+    /// update.
+    /// 
+    /// This is used to ensure that even if the game freezes for a few seconds,
+    /// or is suspended for hours or even days, the virtual clock doesn't
+    /// suddenly jump forward for that full amount, which would likely cause
+    /// gameplay bugs or having to suddenly simulate all the intervening time.
+    /// 
+    /// re are no updates scheduled for an extended amount of time, there won't
+    /// be a huge update at once for the clock. This also limits the number of
+    /// fixed time ticks that will be evaluated at maximum per a single update.
     /// 
     /// The default value is [`Self::DEFAULT_MAX_DELTA`]. If you want to disable
     /// this feature, set the value to [`std::time::Duration::MAX`]