bevy_time/
real.rs

1#[cfg(feature = "bevy_reflect")]
2use bevy_reflect::Reflect;
3use bevy_utils::{Duration, Instant};
4
5use crate::time::Time;
6
7/// Real time clock representing elapsed wall clock time.
8///
9/// A specialization of the [`Time`] structure. **For method documentation, see
10/// [`Time<Real>#impl-Time<Real>`].**
11///
12/// It is automatically inserted as a resource by
13/// [`TimePlugin`](crate::TimePlugin) and updated with time instants according
14/// to [`TimeUpdateStrategy`](crate::TimeUpdateStrategy).[^disclaimer]
15///
16/// Note:
17/// Using [`TimeUpdateStrategy::ManualDuration`](crate::TimeUpdateStrategy::ManualDuration)
18/// allows for mocking the wall clock for testing purposes.
19/// Besides this use case, it is not recommended to do this, as it will no longer
20/// represent "wall clock" time as intended.
21///
22/// The [`delta()`](Time::delta) and [`elapsed()`](Time::elapsed) values of this
23/// clock should be used for anything which deals specifically with real time
24/// (wall clock time). It will not be affected by relative game speed
25/// adjustments, pausing or other adjustments.[^disclaimer]
26///
27/// The clock does not count time from [`startup()`](Time::startup) to
28/// [`first_update()`](Time::first_update()) into elapsed, but instead will
29/// start counting time from the first update call. [`delta()`](Time::delta) and
30/// [`elapsed()`](Time::elapsed) will report zero on the first update as there
31/// is no previous update instant. This means that a [`delta()`](Time::delta) of
32/// zero must be handled without errors in application logic, as it may
33/// theoretically also happen at other times.
34///
35/// [`Instant`]s for [`startup()`](Time::startup),
36/// [`first_update()`](Time::first_update) and
37/// [`last_update()`](Time::last_update) are recorded and accessible.
38///
39/// [^disclaimer]: When using [`TimeUpdateStrategy::ManualDuration`](crate::TimeUpdateStrategy::ManualDuration),
40///     [`Time<Real>#impl-Time<Real>`] is only a *mock* of wall clock time.
41///
42#[derive(Debug, Copy, Clone)]
43#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
44pub struct Real {
45    startup: Instant,
46    first_update: Option<Instant>,
47    last_update: Option<Instant>,
48}
49
50impl Default for Real {
51    fn default() -> Self {
52        Self {
53            startup: Instant::now(),
54            first_update: None,
55            last_update: None,
56        }
57    }
58}
59
60impl Time<Real> {
61    /// Constructs a new `Time<Real>` instance with a specific startup
62    /// [`Instant`].
63    pub fn new(startup: Instant) -> Self {
64        Self::new_with(Real {
65            startup,
66            ..Default::default()
67        })
68    }
69
70    /// Updates the internal time measurements.
71    ///
72    /// Calling this method as part of your app will most likely result in
73    /// inaccurate timekeeping, as the [`Time`] resource is ordinarily managed
74    /// by the [`TimePlugin`](crate::TimePlugin).
75    pub fn update(&mut self) {
76        let instant = Instant::now();
77        self.update_with_instant(instant);
78    }
79
80    /// Updates time with a specified [`Duration`].
81    ///
82    /// This method is provided for use in tests.
83    ///
84    /// Calling this method as part of your app will most likely result in
85    /// inaccurate timekeeping, as the [`Time`] resource is ordinarily managed
86    /// by the [`TimePlugin`](crate::TimePlugin).
87    pub fn update_with_duration(&mut self, duration: Duration) {
88        let last_update = self.context().last_update.unwrap_or(self.context().startup);
89        self.update_with_instant(last_update + duration);
90    }
91
92    /// Updates time with a specified [`Instant`].
93    ///
94    /// This method is provided for use in tests.
95    ///
96    /// Calling this method as part of your app will most likely result in inaccurate timekeeping,
97    /// as the [`Time`] resource is ordinarily managed by the [`TimePlugin`](crate::TimePlugin).
98    pub fn update_with_instant(&mut self, instant: Instant) {
99        let Some(last_update) = self.context().last_update else {
100            let context = self.context_mut();
101            context.first_update = Some(instant);
102            context.last_update = Some(instant);
103            return;
104        };
105        let delta = instant - last_update;
106        self.advance_by(delta);
107        self.context_mut().last_update = Some(instant);
108    }
109
110    /// Returns the [`Instant`] the clock was created.
111    ///
112    /// This usually represents when the app was started.
113    #[inline]
114    pub fn startup(&self) -> Instant {
115        self.context().startup
116    }
117
118    /// Returns the [`Instant`] when [`Self::update`] was first called, if it
119    /// exists.
120    ///
121    /// This usually represents when the first app update started.
122    #[inline]
123    pub fn first_update(&self) -> Option<Instant> {
124        self.context().first_update
125    }
126
127    /// Returns the [`Instant`] when [`Self::update`] was last called, if it
128    /// exists.
129    ///
130    /// This usually represents when the current app update started.
131    #[inline]
132    pub fn last_update(&self) -> Option<Instant> {
133        self.context().last_update
134    }
135}
136
137#[cfg(test)]
138mod test {
139    use super::*;
140
141    #[test]
142    fn test_update() {
143        let startup = Instant::now();
144        let mut time = Time::<Real>::new(startup);
145
146        assert_eq!(time.startup(), startup);
147        assert_eq!(time.first_update(), None);
148        assert_eq!(time.last_update(), None);
149        assert_eq!(time.delta(), Duration::ZERO);
150        assert_eq!(time.elapsed(), Duration::ZERO);
151
152        time.update();
153
154        assert_ne!(time.first_update(), None);
155        assert_ne!(time.last_update(), None);
156        assert_eq!(time.delta(), Duration::ZERO);
157        assert_eq!(time.elapsed(), Duration::ZERO);
158
159        time.update();
160
161        assert_ne!(time.first_update(), None);
162        assert_ne!(time.last_update(), None);
163        assert_ne!(time.last_update(), time.first_update());
164        assert_ne!(time.delta(), Duration::ZERO);
165        assert_eq!(time.elapsed(), time.delta());
166
167        let prev_elapsed = time.elapsed();
168        time.update();
169
170        assert_ne!(time.delta(), Duration::ZERO);
171        assert_eq!(time.elapsed(), prev_elapsed + time.delta());
172    }
173
174    #[test]
175    fn test_update_with_instant() {
176        let startup = Instant::now();
177        let mut time = Time::<Real>::new(startup);
178
179        let first_update = Instant::now();
180        time.update_with_instant(first_update);
181
182        assert_eq!(time.startup(), startup);
183        assert_eq!(time.first_update(), Some(first_update));
184        assert_eq!(time.last_update(), Some(first_update));
185        assert_eq!(time.delta(), Duration::ZERO);
186        assert_eq!(time.elapsed(), Duration::ZERO);
187
188        let second_update = Instant::now();
189        time.update_with_instant(second_update);
190
191        assert_eq!(time.first_update(), Some(first_update));
192        assert_eq!(time.last_update(), Some(second_update));
193        assert_eq!(time.delta(), second_update - first_update);
194        assert_eq!(time.elapsed(), second_update - first_update);
195
196        let third_update = Instant::now();
197        time.update_with_instant(third_update);
198
199        assert_eq!(time.first_update(), Some(first_update));
200        assert_eq!(time.last_update(), Some(third_update));
201        assert_eq!(time.delta(), third_update - second_update);
202        assert_eq!(time.elapsed(), third_update - first_update);
203    }
204
205    #[test]
206    fn test_update_with_duration() {
207        let startup = Instant::now();
208        let mut time = Time::<Real>::new(startup);
209
210        time.update_with_duration(Duration::from_secs(1));
211
212        assert_eq!(time.startup(), startup);
213        assert_eq!(time.first_update(), Some(startup + Duration::from_secs(1)));
214        assert_eq!(time.last_update(), Some(startup + Duration::from_secs(1)));
215        assert_eq!(time.delta(), Duration::ZERO);
216        assert_eq!(time.elapsed(), Duration::ZERO);
217
218        time.update_with_duration(Duration::from_secs(1));
219
220        assert_eq!(time.first_update(), Some(startup + Duration::from_secs(1)));
221        assert_eq!(time.last_update(), Some(startup + Duration::from_secs(2)));
222        assert_eq!(time.delta(), Duration::from_secs(1));
223        assert_eq!(time.elapsed(), Duration::from_secs(1));
224
225        time.update_with_duration(Duration::from_secs(1));
226
227        assert_eq!(time.first_update(), Some(startup + Duration::from_secs(1)));
228        assert_eq!(time.last_update(), Some(startup + Duration::from_secs(3)));
229        assert_eq!(time.delta(), Duration::from_secs(1));
230        assert_eq!(time.elapsed(), Duration::from_secs(2));
231    }
232}
bevy_time/real.rs

bevy_time/
real.rs
