Struct ObservableTimer 

pub struct ObservableTimer {
    pub timer: Timer,
    pub finish_behavior: TimerFinishBehavior,
}

A timer component that triggers observable lifecycle events on its Entity.

When an ObservableTimer is first added to an Entity (either by adding a new one, or replacing the current one) a TimerStarted event will be triggered. Then, each time an interval completes, a TimerFinished event will be triggered. Finally, when the timer component is removed, a TimerStopped event will be triggered.

By default a TimerMode::Once timer will despawn its Entity when it finishes. This behavior can be changed to removing only the ObservableTimer component, or doing nothing. See Self::with_finish_behavior for setting behavior at creation, or Self::finish_behavior for changing it after creation. Note that this behavior will not be run if the timer is removed manually before finishing.

To cancel a currently running timer simply remove the component. This will cause a TimerStopped event to be triggered.

Fields

timer: Timer

The internal Timer.

finish_behavior: TimerFinishBehavior

The timer’s finish behavior.

Implementations

impl ObservableTimer

pub fn new(duration: Duration, mode: TimerMode) -> Self

Create a new timer.

pub fn from_seconds(duration: f32, mode: TimerMode) -> Self

Create a new timer from a duration in seconds.

pub fn with_finish_behavior(self, finish_behavior: TimerFinishBehavior) -> Self

Set the TimerFinishBehavior for this timer.

Methods from Deref<Target = Timer>

pub fn is_finished(&self) -> bool

Returns true if the timer has reached its duration.

For repeating timers, this method behaves identically to Timer::just_finished.

Examples

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());

pub fn finished(&self) -> bool

👎Deprecated since 0.17.0: Use is_finished instead

Returns true if the timer has reached its duration.

For repeating timers, this method behaves identically to Timer::just_finished.

Examples

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.finished());
timer_once.tick(Duration::from_secs_f32(0.5));
assert!(timer_once.finished());

let mut timer_repeating = Timer::from_seconds(1.0, TimerMode::Repeating);
timer_repeating.tick(Duration::from_secs_f32(1.1));
assert!(timer_repeating.finished());
timer_repeating.tick(Duration::from_secs_f32(0.8));
assert!(!timer_repeating.finished());
timer_repeating.tick(Duration::from_secs_f32(0.6));
assert!(timer_repeating.finished());

pub fn just_finished(&self) -> bool

Returns true only on the tick the timer reached its duration.

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
timer.tick(Duration::from_secs_f32(1.5));
assert!(timer.just_finished());
timer.tick(Duration::from_secs_f32(0.5));
assert!(!timer.just_finished());

pub fn elapsed(&self) -> Duration

Returns the time elapsed on the timer. Guaranteed to be between 0.0 and duration. Will only equal duration when the timer is finished and non repeating.

See also Stopwatch::elapsed.

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
timer.tick(Duration::from_secs_f32(0.5));
assert_eq!(timer.elapsed(), Duration::from_secs_f32(0.5));

pub fn elapsed_secs(&self) -> f32

Returns the time elapsed on the timer as an f32. See also Timer::elapsed.

pub fn elapsed_secs_f64(&self) -> f64

Returns the time elapsed on the timer as an f64. See also Timer::elapsed.

pub fn set_elapsed(&mut self, time: Duration)

Sets the elapsed time of the timer without any other considerations.

See also Stopwatch::set.

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
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.is_finished());

pub fn duration(&self) -> Duration

Returns the duration of the timer.

Examples

use std::time::Duration;
let timer = Timer::new(Duration::from_secs(1), TimerMode::Once);
assert_eq!(timer.duration(), Duration::from_secs(1));

pub fn set_duration(&mut self, duration: Duration)

Sets the duration of the timer.

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.5, TimerMode::Once);
timer.set_duration(Duration::from_secs(1));
assert_eq!(timer.duration(), Duration::from_secs(1));

pub fn finish(&mut self)

Finishes the timer.

Examples

let mut timer = Timer::from_seconds(1.5, TimerMode::Once);
timer.finish();
assert!(timer.finished());

pub fn mode(&self) -> TimerMode

Returns the mode of the timer.

Examples

let mut timer = Timer::from_seconds(1.0, TimerMode::Repeating);
assert_eq!(timer.mode(), TimerMode::Repeating);

pub fn set_mode(&mut self, mode: TimerMode)

Sets the mode of the timer.

Examples

let mut timer = Timer::from_seconds(1.0, TimerMode::Repeating);
timer.set_mode(TimerMode::Once);
assert_eq!(timer.mode(), TimerMode::Once);

pub fn tick(&mut self, delta: Duration) -> &Timer

Advance the timer by delta seconds. Non repeating timer will clamp at duration. Repeating timer will wrap around. Will not affect paused timers.

See also Stopwatch::tick.

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
let mut repeating = Timer::from_seconds(1.0, TimerMode::Repeating);
timer.tick(Duration::from_secs_f32(1.5));
repeating.tick(Duration::from_secs_f32(1.5));
assert_eq!(timer.elapsed_secs(), 1.0);
assert_eq!(repeating.elapsed_secs(), 0.5);

pub fn pause(&mut self)

Pauses the Timer. Disables the ticking of the timer.

See also Stopwatch::pause.

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
timer.pause();
timer.tick(Duration::from_secs_f32(0.5));
assert_eq!(timer.elapsed_secs(), 0.0);

pub fn unpause(&mut self)

Unpauses the Timer. Resumes the ticking of the timer.

See also Stopwatch::unpause().

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
timer.pause();
timer.tick(Duration::from_secs_f32(0.5));
timer.unpause();
timer.tick(Duration::from_secs_f32(0.5));
assert_eq!(timer.elapsed_secs(), 0.5);

pub fn is_paused(&self) -> bool

Returns true if the timer is paused.

See also Stopwatch::is_paused.

Examples

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());

pub fn paused(&self) -> bool

👎Deprecated since 0.17.0: Use is_paused instead

Returns true if the timer is paused.

See also Stopwatch::is_paused.

Examples

let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
assert!(!timer.paused());
timer.pause();
assert!(timer.paused());
timer.unpause();
assert!(!timer.paused());

pub fn reset(&mut self)

Resets the timer. The reset doesn’t affect the paused state of the timer.

See also Stopwatch::reset.

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Once);
timer.tick(Duration::from_secs_f32(1.5));
timer.reset();
assert!(!timer.is_finished());
assert!(!timer.just_finished());
assert_eq!(timer.elapsed_secs(), 0.0);

pub fn fraction(&self) -> f32

Returns the fraction of the timer elapsed time (goes from 0.0 to 1.0).

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(2.0, TimerMode::Once);
timer.tick(Duration::from_secs_f32(0.5));
assert_eq!(timer.fraction(), 0.25);

pub fn fraction_remaining(&self) -> f32

Returns the fraction of the timer remaining time (goes from 1.0 to 0.0).

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(2.0, TimerMode::Once);
timer.tick(Duration::from_secs_f32(0.5));
assert_eq!(timer.fraction_remaining(), 0.75);

pub fn remaining_secs(&self) -> f32

Returns the remaining time in seconds

Examples

use std::cmp::Ordering;
use std::time::Duration;
let mut timer = Timer::from_seconds(2.0, TimerMode::Once);
timer.tick(Duration::from_secs_f32(0.5));
let result = timer.remaining_secs().total_cmp(&1.5);
assert_eq!(Ordering::Equal, result);

pub fn remaining(&self) -> Duration

Returns the remaining time using Duration

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(2.0, TimerMode::Once);
timer.tick(Duration::from_secs_f32(0.5));
assert_eq!(timer.remaining(), Duration::from_secs_f32(1.5));

pub fn times_finished_this_tick(&self) -> u32

Returns the number of times a repeating timer finished during the last tick call.

For non repeating-timers, this method will only ever return 0 or 1.

Examples

use std::time::Duration;
let mut timer = Timer::from_seconds(1.0, TimerMode::Repeating);
timer.tick(Duration::from_secs_f32(6.0));
assert_eq!(timer.times_finished_this_tick(), 6);
timer.tick(Duration::from_secs_f32(2.0));
assert_eq!(timer.times_finished_this_tick(), 2);
timer.tick(Duration::from_secs_f32(0.5));
assert_eq!(timer.times_finished_this_tick(), 0);

Trait Implementations

impl Clone for ObservableTimer

fn clone(&self) -> ObservableTimer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Component for ObservableTimer

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = ::bevy::ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn on_remove() -> Option<ComponentHook>

Gets the on_remove ComponentHook for this Component if one is defined.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_replace ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl Debug for ObservableTimer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for ObservableTimer

type Target = Timer

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for ObservableTimer

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.