Struct Time

Source

pub struct Time<T = ()>where
    T: Default,
{ /* private fields */ }

Expand description

A generic clock resource that tracks how much it has advanced since its previous update and since its creation.

Multiple instances of this resource are inserted automatically by TimePlugin:

Time<Real> tracks real wall-clock time elapsed.
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 FixedMain schedule when it contains Time<Fixed>.

The time elapsed since the previous time this clock was advanced is saved as delta() and the total amount of time the clock has advanced is saved 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_secs() and elapsed_secs(), and also in seconds as f64 via delta_secs_f64() and elapsed_secs_f64().

Since elapsed_secs() 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 elapsed_secs_wrapped() 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 the FixedMain schedule when it refers to Time<Fixed>. This ensures your system can be used either in Update or FixedUpdate schedule depending on what is needed.

fn ambivalent_system(time: Res<Time>) {
    println!("this how I see time: delta {:?}, elapsed {:?}", time.delta(), time.elapsed());
}

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.

fn real_time_system(time: Res<Time<Real>>) {
    println!("this will always be real time: delta {:?}, elapsed {:?}", time.delta(), time.elapsed());
}

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.

fn fixed_time_system(time: Res<Time<Fixed>>) {
    println!("this will always be the last executed fixed timestep: delta {:?}, elapsed {:?}", time.delta(), time.elapsed());
}

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 was_paused() or to use effective_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.

fn fixed_time_system(time: Res<Time<Virtual>>) {
    println!("this will be virtual time for this update: delta {:?}, elapsed {:?}", time.delta(), time.elapsed());
    println!("also the relative speed of the game is now {}", time.effective_speed());
}

If you need to change the settings for any of the clocks, for example to pause() the game, you should use ResMut<Time<Virtual>>.

#[derive(Event)]
struct PauseEvent(bool);

fn pause_system(mut time: ResMut<Time<Virtual>>, mut events: EventReader<PauseEvent>) {
    for ev in events.read() {
        if ev.0 {
            time.pause();
        } else {
            time.unpause();
        }
    }
}

§Adding custom clocks

New custom clocks can be created by creating your own struct as a context and passing it to new_with(). 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.

If you want to add methods for your time instance and they require access to both your context and the generic time part, it’s probably simplest to add a custom trait for them and implement it for Time<Custom>.

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(Debug)]
struct Custom {
    last_external_time: Instant,
}

impl Default for Custom {
    fn default() -> Self {
        Self {
            last_external_time: Instant::now(),
        }
    }
}

trait CustomTime {
    fn update_from_external(&mut self, instant: Instant);
}

impl CustomTime for Time<Custom> {
    fn update_from_external(&mut self, instant: Instant) {
         let delta = instant - self.context().last_external_time;
         self.advance_by(delta);
         self.context_mut().last_external_time = instant;
    }
}

Struct TimeCopy item path

§Accessing clocks

§Adding custom clocks

Implementations§

impl Time<Fixed>

pub fn from_duration(timestep: Duration) -> Time<Fixed>

§Panics

pub fn from_seconds(seconds: f64) -> Time<Fixed>

§Panics

pub fn from_hz(hz: f64) -> Time<Fixed>

§Panics

pub fn timestep(&self) -> Duration

pub fn set_timestep(&mut self, timestep: Duration)

§Panics

pub fn set_timestep_seconds(&mut self, seconds: f64)

§Panics

pub fn set_timestep_hz(&mut self, hz: f64)

§Panics

pub fn overstep(&self) -> Duration

pub fn discard_overstep(&mut self, discard: Duration)

pub fn overstep_fraction(&self) -> f32

pub fn overstep_fraction_f64(&self) -> f64

impl Time<Real>

pub fn new(startup: Instant) -> Time<Real>

pub fn update(&mut self)

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

pub fn update_with_instant(&mut self, instant: Instant)

pub fn startup(&self) -> Instant

pub fn first_update(&self) -> Option<Instant>

pub fn last_update(&self) -> Option<Instant>

impl<T> Time<T>where T: Default,

pub fn new_with(context: T) -> Time<T>

pub fn advance_by(&mut self, delta: Duration)

pub fn advance_to(&mut self, elapsed: Duration)

§Panics

pub fn wrap_period(&self) -> Duration

pub fn set_wrap_period(&mut self, wrap_period: Duration)

§Panics

pub fn delta(&self) -> Duration

pub fn delta_secs(&self) -> f32

pub fn delta_secs_f64(&self) -> f64

pub fn elapsed(&self) -> Duration

pub fn elapsed_secs(&self) -> f32

pub fn elapsed_secs_f64(&self) -> f64

pub fn elapsed_wrapped(&self) -> Duration

pub fn elapsed_secs_wrapped(&self) -> f32

pub fn elapsed_secs_wrapped_f64(&self) -> f64

pub fn context(&self) -> &T

pub fn context_mut(&mut self) -> &mut T

pub fn as_generic(&self) -> Time

impl Time<Virtual>

pub fn from_max_delta(max_delta: Duration) -> Time<Virtual>

§Panics

pub fn max_delta(&self) -> Duration

pub fn set_max_delta(&mut self, max_delta: Duration)

§Panics

pub fn relative_speed(&self) -> f32

pub fn relative_speed_f64(&self) -> f64

pub fn effective_speed(&self) -> f32

pub fn effective_speed_f64(&self) -> f64

pub fn set_relative_speed(&mut self, ratio: f32)

§Panics

pub fn set_relative_speed_f64(&mut self, ratio: f64)

§Panics

pub fn pause(&mut self)

pub fn unpause(&mut self)

pub fn is_paused(&self) -> bool

pub fn was_paused(&self) -> bool

Trait Implementations§

impl<T> Clone for Time<T>where T: Clone + Default,

fn clone(&self) -> Time<T>

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

impl<T> Debug for Time<T>where T: Debug + Default,

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

impl<T> Default for Time<T>where T: Default,

fn default() -> Time<T>

type This<'from_arg> = &'from_arg Time<T>

fn from_arg( arg: Arg<'_>, ) -> Result<<&'static Time<T> as FromArg>::This<'_>, ArgError>

type This<'from_arg> = &'from_arg mut Time<T>

fn from_arg( arg: Arg<'_>, ) -> Result<<&'static mut Time<T> as FromArg>::This<'_>, ArgError>

Struct Time

impl<T> Time<T>
where T: Default,

impl<T> Clone for Time<T>
where T: Clone + Default,

impl<T> Debug for Time<T>
where T: Debug + Default,

impl<T> Default for Time<T>
where T: Default,

fn into_return<'into_return>(self) -> Return<'into_return>
where &Time<T>: 'into_return,

fn into_return<'into_return>(self) -> Return<'into_return>
where &mut Time<T>: 'into_return,

fn into_return<'into_return>(self) -> Return<'into_return>
where Time<T>: 'into_return,