Rename Timer::finished and Timer::paused to is_finished and is_paused (#19386)

# Objective
Renames `Timer::finished` and `Timer::paused` to `Timer::is_finished`
and `Timer::is_paused` to align the public APIs for `Time`, `Timer`, and
`Stopwatch`.

Fixes #19110

crates/bevy_diagnostic/src/log_diagnostics_plugin.rs

@@ -190,7 +190,7 @@ impl LogDiagnosticsPlugin {
         time: Res<Time<Real>>,
         diagnostics: Res<DiagnosticsStore>,
     ) {
-        if state.timer.tick(time.delta()).finished() {
+        if state.timer.tick(time.delta()).is_finished() {
             Self::log_diagnostics(&state, &diagnostics);
         }
     }
@@ -200,7 +200,7 @@ impl LogDiagnosticsPlugin {
         time: Res<Time<Real>>,
         diagnostics: Res<DiagnosticsStore>,
     ) {
-        if state.timer.tick(time.delta()).finished() {
+        if state.timer.tick(time.delta()).is_finished() {
             Self::for_each_diagnostic(&state, &diagnostics, |diagnostic| {
                 debug!("{:#?}\n", diagnostic);
             });

crates/bevy_time/src/common_conditions.rs

@@ -167,7 +167,7 @@ pub fn repeating_after_delay(duration: Duration) -> impl FnMut(Res<Time>) -> boo
     let mut timer = Timer::new(duration, TimerMode::Once);
     move |time: Res<Time>| {
         timer.tick(time.delta());
-        timer.finished()
+        timer.is_finished()
     }
 }
 
@@ -199,7 +199,7 @@ pub fn repeating_after_real_delay(
     let mut timer = Timer::new(duration, TimerMode::Once);
     move |time: Res<Time<Real>>| {
         timer.tick(time.delta());
-        timer.finished()
+        timer.is_finished()
     }
 }
 

crates/bevy_time/src/timer.rs

@@ -54,6 +54,34 @@ impl Timer {
         }
     }
 
+    /// Returns `true` if the timer has reached its duration.
+    ///
+    /// For repeating timers, this method behaves identically to [`Timer::just_finished`].
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_time::*;
+    /// use std::time::Duration;
+    ///
+    /// let mut timer_once = Timer::from_seconds(1.0, TimerMode::Once);
+    /// timer_once.tick(Duration::from_secs_f32(1.5));
+    /// assert!(timer_once.is_finished());
+    /// timer_once.tick(Duration::from_secs_f32(0.5));
+    /// assert!(timer_once.is_finished());
+    ///
+    /// let mut timer_repeating = Timer::from_seconds(1.0, TimerMode::Repeating);
+    /// timer_repeating.tick(Duration::from_secs_f32(1.1));
+    /// assert!(timer_repeating.is_finished());
+    /// timer_repeating.tick(Duration::from_secs_f32(0.8));
+    /// assert!(!timer_repeating.is_finished());
+    /// timer_repeating.tick(Duration::from_secs_f32(0.6));
+    /// assert!(timer_repeating.is_finished());
+    /// ```
+    #[inline]
+    pub fn is_finished(&self) -> bool {
+        self.finished
+    }
+
     /// Returns `true` if the timer has reached its duration.
     ///
     /// For repeating timers, this method behaves identically to [`Timer::just_finished`].
@@ -77,6 +105,7 @@ impl Timer {
     /// timer_repeating.tick(Duration::from_secs_f32(0.6));
     /// assert!(timer_repeating.finished());
     /// ```
+    #[deprecated(since = "0.17.0", note = "Use `is_finished` instead")]
     #[inline]
     pub fn finished(&self) -> bool {
         self.finished
@@ -143,7 +172,7 @@ impl Timer {
     /// timer.set_elapsed(Duration::from_secs(2));
     /// assert_eq!(timer.elapsed(), Duration::from_secs(2));
     /// // the timer is not finished even if the elapsed time is greater than the duration.
-    /// assert!(!timer.finished());
+    /// assert!(!timer.is_finished());
     /// ```
     #[inline]
     pub fn set_elapsed(&mut self, time: Duration) {
@@ -230,7 +259,7 @@ impl Timer {
     /// assert_eq!(repeating.elapsed_secs(), 0.5);
     /// ```
     pub fn tick(&mut self, delta: Duration) -> &Self {
-        if self.paused() {
+        if self.is_paused() {
             self.times_finished_this_tick = 0;
             if self.mode == TimerMode::Repeating {
                 self.finished = false;
@@ -238,7 +267,7 @@ impl Timer {
             return self;
         }
 
-        if self.mode != TimerMode::Repeating && self.finished() {
+        if self.mode != TimerMode::Repeating && self.is_finished() {
             self.times_finished_this_tick = 0;
             return self;
         }
@@ -246,7 +275,7 @@ impl Timer {
         self.stopwatch.tick(delta);
         self.finished = self.elapsed() >= self.duration();
 
-        if self.finished() {
+        if self.is_finished() {
             if self.mode == TimerMode::Repeating {
                 self.times_finished_this_tick = self
                     .elapsed()
@@ -308,6 +337,25 @@ impl Timer {
         self.stopwatch.unpause();
     }
 
+    /// Returns `true` if the timer is paused.
+    ///
+    /// See also [`Stopwatch::is_paused`](Stopwatch::is_paused).
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_time::*;
+    /// let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
+    /// assert!(!timer.is_paused());
+    /// timer.pause();
+    /// assert!(timer.is_paused());
+    /// timer.unpause();
+    /// assert!(!timer.is_paused());
+    /// ```
+    #[inline]
+    pub fn is_paused(&self) -> bool {
+        self.stopwatch.is_paused()
+    }
+
     /// Returns `true` if the timer is paused.
     ///
     /// See also [`Stopwatch::is_paused`](Stopwatch::is_paused).
@@ -322,6 +370,7 @@ impl Timer {
     /// timer.unpause();
     /// assert!(!timer.paused());
     /// ```
+    #[deprecated(since = "0.17.0", note = "Use `is_paused` instead")]
     #[inline]
     pub fn paused(&self) -> bool {
         self.stopwatch.is_paused()
@@ -338,7 +387,7 @@ impl Timer {
     /// let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
     /// timer.tick(Duration::from_secs_f32(1.5));
     /// timer.reset();
-    /// assert!(!timer.finished());
+    /// assert!(!timer.is_finished());
     /// assert!(!timer.just_finished());
     /// assert_eq!(timer.elapsed_secs(), 0.0);
     /// ```
@@ -466,7 +515,7 @@ mod tests {
         assert_eq!(t.elapsed_secs(), 0.25);
         assert_eq!(t.elapsed_secs_f64(), 0.25);
         assert_eq!(t.duration(), Duration::from_secs_f32(10.0));
-        assert!(!t.finished());
+        assert!(!t.is_finished());
         assert!(!t.just_finished());
         assert_eq!(t.times_finished_this_tick(), 0);
         assert_eq!(t.mode(), TimerMode::Once);
@@ -477,7 +526,7 @@ mod tests {
         t.tick(Duration::from_secs_f32(500.0));
         assert_eq!(t.elapsed_secs(), 0.25);
         assert_eq!(t.duration(), Duration::from_secs_f32(10.0));
-        assert!(!t.finished());
+        assert!(!t.is_finished());
         assert!(!t.just_finished());
         assert_eq!(t.times_finished_this_tick(), 0);
         assert_eq!(t.mode(), TimerMode::Once);
@@ -488,7 +537,7 @@ mod tests {
         t.tick(Duration::from_secs_f32(500.0));
         assert_eq!(t.elapsed_secs(), 10.0);
         assert_eq!(t.elapsed_secs_f64(), 10.0);
-        assert!(t.finished());
+        assert!(t.is_finished());
         assert!(t.just_finished());
         assert_eq!(t.times_finished_this_tick(), 1);
         assert_eq!(t.fraction(), 1.0);
@@ -497,7 +546,7 @@ mod tests {
         t.tick(Duration::from_secs_f32(1.0));
         assert_eq!(t.elapsed_secs(), 10.0);
         assert_eq!(t.elapsed_secs_f64(), 10.0);
-        assert!(t.finished());
+        assert!(t.is_finished());
         assert!(!t.just_finished());
         assert_eq!(t.times_finished_this_tick(), 0);
         assert_eq!(t.fraction(), 1.0);
@@ -512,7 +561,7 @@ mod tests {
         assert_eq!(t.elapsed_secs(), 0.75);
         assert_eq!(t.elapsed_secs_f64(), 0.75);
         assert_eq!(t.duration(), Duration::from_secs_f32(2.0));
-        assert!(!t.finished());
+        assert!(!t.is_finished());
         assert!(!t.just_finished());
         assert_eq!(t.times_finished_this_tick(), 0);
         assert_eq!(t.mode(), TimerMode::Repeating);
@@ -522,7 +571,7 @@ mod tests {
         t.tick(Duration::from_secs_f32(1.5));
         assert_eq!(t.elapsed_secs(), 0.25);
         assert_eq!(t.elapsed_secs_f64(), 0.25);
-        assert!(t.finished());
+        assert!(t.is_finished());
         assert!(t.just_finished());
         assert_eq!(t.times_finished_this_tick(), 1);
         assert_eq!(t.fraction(), 0.125);
@@ -531,7 +580,7 @@ mod tests {
         t.tick(Duration::from_secs_f32(1.0));
         assert_eq!(t.elapsed_secs(), 1.25);
         assert_eq!(t.elapsed_secs_f64(), 1.25);
-        assert!(!t.finished());
+        assert!(!t.is_finished());
         assert!(!t.just_finished());
         assert_eq!(t.times_finished_this_tick(), 0);
         assert_eq!(t.fraction(), 0.625);
@@ -546,7 +595,7 @@ mod tests {
         assert_eq!(t.times_finished_this_tick(), 3);
         assert_eq!(t.elapsed_secs(), 0.5);
         assert_eq!(t.elapsed_secs_f64(), 0.5);
-        assert!(t.finished());
+        assert!(t.is_finished());
         assert!(t.just_finished());
         t.tick(Duration::from_secs_f32(0.2));
         assert_eq!(t.times_finished_this_tick(), 0);
@@ -607,12 +656,12 @@ mod tests {
 
         t.tick(Duration::from_secs_f32(10.0));
         assert!(t.just_finished());
-        assert!(t.finished());
+        assert!(t.is_finished());
         // A paused timer should change just_finished to false after a tick
         t.pause();
         t.tick(Duration::from_secs_f32(5.0));
         assert!(!t.just_finished());
-        assert!(t.finished());
+        assert!(t.is_finished());
     }
 
     #[test]
@@ -621,11 +670,11 @@ mod tests {
 
         t.tick(Duration::from_secs_f32(10.0));
         assert!(t.just_finished());
-        assert!(t.finished());
+        assert!(t.is_finished());
         // A paused repeating timer should change finished and just_finished to false after a tick
         t.pause();
         t.tick(Duration::from_secs_f32(5.0));
         assert!(!t.just_finished());
-        assert!(!t.finished());
+        assert!(!t.is_finished());
     }
 }

examples/app/plugin.rs

@@ -46,7 +46,7 @@ struct PrintMessageState {
 }
 
 fn print_message_system(mut state: ResMut<PrintMessageState>, time: Res<Time>) {
-    if state.timer.tick(time.delta()).finished() {
+    if state.timer.tick(time.delta()).is_finished() {
         info!("{}", state.message);
     }
 }

examples/ecs/event.rs

@@ -42,7 +42,7 @@ fn deal_damage_over_time(
     mut state: ResMut<DamageTimer>,
     mut events: EventWriter<DealDamage>,
 ) {
-    if state.tick(time.delta()).finished() {
+    if state.tick(time.delta()).is_finished() {
         // Events can be sent with 'write' and constructed just like any other object.
         events.write(DealDamage { amount: 10 });
     }

examples/ecs/state_scoped.rs

@@ -116,7 +116,7 @@ fn toggle(
     state: Res<State<GameState>>,
     mut next_state: ResMut<NextState<GameState>>,
 ) {
-    if !timer.0.tick(time.delta()).finished() {
+    if !timer.0.tick(time.delta()).is_finished() {
         return;
     }
     *next_state = match state.get() {

examples/games/alien_cake_addict.rs

@@ -203,7 +203,7 @@ fn move_player(
     mut transforms: Query<&mut Transform>,
     time: Res<Time>,
 ) {
-    if game.player.move_cooldown.tick(time.delta()).finished() {
+    if game.player.move_cooldown.tick(time.delta()).is_finished() {
         let mut moved = false;
         let mut rotation = 0.0;
 
@@ -314,7 +314,7 @@ fn spawn_bonus(
     mut rng: ResMut<Random>,
 ) {
     // make sure we wait enough time before spawning the next cake
-    if !timer.0.tick(time.delta()).finished() {
+    if !timer.0.tick(time.delta()).is_finished() {
         return;
     }
 

examples/games/game_menu.rs

@@ -101,7 +101,7 @@ mod splash {
         time: Res<Time>,
         mut timer: ResMut<SplashTimer>,
     ) {
-        if timer.tick(time.delta()).finished() {
+        if timer.tick(time.delta()).is_finished() {
             game_state.set(GameState::Menu);
         }
     }
@@ -215,7 +215,7 @@ mod game {
         mut game_state: ResMut<NextState<GameState>>,
         mut timer: ResMut<GameTimer>,
     ) {
-        if timer.tick(time.delta()).finished() {
+        if timer.tick(time.delta()).is_finished() {
             game_state.set(GameState::Menu);
         }
     }

examples/time/timers.rs

@@ -59,10 +59,10 @@ fn countdown(time: Res<Time>, mut countdown: ResMut<Countdown>) {
     countdown.main_timer.tick(time.delta());
 
     // The API encourages this kind of timer state checking (if you're only checking for one value)
-    // Additionally, `finished()` would accomplish the same thing as `just_finished` due to the
+    // Additionally, `is_finished()` would accomplish the same thing as `just_finished` due to the
     // timer being repeating, however this makes more sense visually.
     if countdown.percent_trigger.tick(time.delta()).just_finished() {
-        if !countdown.main_timer.finished() {
+        if !countdown.main_timer.is_finished() {
             // Print the percent complete the main timer is.
             info!(
                 "Timer is {:0.0}% complete!",

examples/ui/ui_scaling.rs

@@ -115,7 +115,7 @@ impl TargetScale {
     }
 
     fn already_completed(&self) -> bool {
-        self.target_time.finished() && !self.target_time.just_finished()
+        self.target_time.is_finished() && !self.target_time.just_finished()
     }
 }
 

examples/window/custom_cursor_image.rs

@@ -117,7 +117,7 @@ fn execute_animation(time: Res<Time>, mut query: Query<(&mut AnimationConfig, &m
         if let CursorIcon::Custom(CustomCursor::Image(ref mut image)) = *cursor_icon {
             config.frame_timer.tick(time.delta());
 
-            if config.frame_timer.finished() {
+            if config.frame_timer.is_finished() {
                 if let Some(atlas) = image.texture_atlas.as_mut() {
                     atlas.index += config.increment;
 

release-content/migration-guides/rename_timer_paused_and_finished.md

@@ -0,0 +1,11 @@
+---
+title: Renamed `Timer::paused` to `Timer::is_paused` and `Timer::finished` to `Timer::is_finished`
+pull_requests: [19386]
+---
+
+The following changes were made:
+
+- `Timer::paused` is now `Timer::is_paused`
+- `Timer::finished` is now `Timer::is_finished`
+
+This change was made to align the `Timer` public API with that of `Time` and `Stopwatch`.