Struct Time

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

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_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 elapsed_seconds_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;
    }
}

Implementations

impl Time<Fixed>

pub fn from_duration(timestep: Duration) -> Self

Return new fixed time clock with given timestep as Duration

Panics

Panics if timestep is zero.

pub fn from_seconds(seconds: f64) -> Self

Return new fixed time clock with given timestep seconds as f64

Panics

Panics if seconds is zero, negative or not finite.

pub fn from_hz(hz: f64) -> Self

Return new fixed time clock with given timestep frequency in Hertz (1/seconds)

Panics

Panics if hz is zero, negative or not finite.

pub fn timestep(&self) -> Duration

Returns the amount of virtual time that must pass before the fixed timestep schedule is run again.

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

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 Self::overstep.

Panics

Panics if timestep is zero.

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

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 Self::overstep.

Panics

Panics if seconds is zero, negative or not finite.

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

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 Self::overstep.

Panics

Panics if hz is zero, negative or not finite.

pub fn overstep(&self) -> Duration

Returns the amount of overstep time accumulated toward new steps, as Duration.

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

Discard a part of the overstep amount.

If discard is higher than overstep, the overstep becomes zero.

pub fn overstep_fraction(&self) -> f32

Returns the amount of overstep time accumulated toward new steps, as an f32 fraction of the timestep.

pub fn overstep_fraction_f64(&self) -> f64

Returns the amount of overstep time accumulated toward new steps, as an f64 fraction of the timestep.

impl Time<Real>

pub fn new(startup: Instant) -> Self

Constructs a new Time<Real> instance with a specific startup Instant.

pub fn update(&mut self)

Updates the internal time measurements.

Calling this method as part of your app will most likely result in inaccurate timekeeping, as the Time resource is ordinarily managed by the TimePlugin.

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

Updates time with a specified Duration.

This method is provided for use in tests.

Calling this method as part of your app will most likely result in inaccurate timekeeping, as the Time resource is ordinarily managed by the TimePlugin.

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

Updates time with a specified Instant.

This method is provided for use in tests.

Calling this method as part of your app will most likely result in inaccurate timekeeping, as the Time resource is ordinarily managed by the TimePlugin.

pub fn startup(&self) -> Instant

Returns the Instant the clock was created.

This usually represents when the app was started.

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

Returns the Instant when Self::update was first called, if it exists.

This usually represents when the first app update started.

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

Returns the Instant when Self::update was last called, if it exists.

This usually represents when the current app update started.

impl<T: Default> Time<T>

pub fn new_with(context: T) -> Self

Create a new clock from context with Self::delta and Self::elapsed starting from zero.

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

Advance this clock by adding a delta duration to it.

The added duration will be returned by Self::delta and Self::elapsed will be increased by the duration. Adding Duration::ZERO is allowed and will set Self::delta to zero.

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

Advance this clock to a specific elapsed time.

Self::delta() will return the amount of time the clock was advanced and Self::elapsed() will be the elapsed value passed in. Cannot be used to move time backwards.

Panics

Panics if elapsed is less than Self::elapsed().

pub fn wrap_period(&self) -> Duration

Returns the modulus used to calculate elapsed_wrapped.

Note: The default modulus is one hour.

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

Sets the modulus used to calculate elapsed_wrapped.

Note: This will not take effect until the next update.

Panics

Panics if wrap_period is a zero-length duration.

pub fn delta(&self) -> Duration

Returns how much time has advanced since the last update, as a Duration.

pub fn delta_seconds(&self) -> f32

Returns how much time has advanced since the last update, as f32 seconds.

pub fn delta_seconds_f64(&self) -> f64

Returns how much time has advanced since the last update, as f64 seconds.

pub fn elapsed(&self) -> Duration

Returns how much time has advanced since startup, as Duration.

pub fn elapsed_seconds(&self) -> f32

Returns how much time has advanced since startup, as f32 seconds.

Note: This is a monotonically increasing value. Its precision will degrade over time. If you need an f32 but that precision loss is unacceptable, use elapsed_seconds_wrapped.

pub fn elapsed_seconds_f64(&self) -> f64

Returns how much time has advanced since startup, as f64 seconds.

pub fn elapsed_wrapped(&self) -> Duration

Returns how much time has advanced since startup modulo the wrap_period, as Duration.

pub fn elapsed_seconds_wrapped(&self) -> f32

Returns how much time has advanced since startup modulo the wrap_period, as f32 seconds.

This method is intended for applications (e.g. shaders) that require an f32 value but suffer from the gradual precision loss of elapsed_seconds.

pub fn elapsed_seconds_wrapped_f64(&self) -> f64

Returns how much time has advanced since startup modulo the wrap_period, as f64 seconds.

pub fn context(&self) -> &T

Returns a reference to the context of this specific clock.

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

Returns a mutable reference to the context of this specific clock.

pub fn as_generic(&self) -> Time<()>

Returns a copy of this clock as fully generic clock without context.

impl Time<Virtual>

pub fn from_max_delta(max_delta: Duration) -> Self

Create new virtual clock with given maximum delta step Duration

Panics

Panics if max_delta is zero.

pub fn max_delta(&self) -> Duration

Returns the maximum amount of time that can be added to this clock by a single update, as 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.

This ensures that even if no updates happen for an extended amount of time, the clock will not have a sudden, huge advance all at once. This also indirectly limits the maximum number of fixed update steps that can run in a single update.

The default value is 250 milliseconds.

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

Sets the maximum amount of time that can be added to this clock by a single update, as 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.

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.

If no updates happen for an extended amount of time, this limit prevents having a sudden, huge advance all at once. This also indirectly limits the maximum number of fixed update steps that can run in a single update.

The default value is 250 milliseconds. If you want to disable this feature, set the value to Duration::MAX.

Panics

Panics if max_delta is zero.

pub fn relative_speed(&self) -> f32

Returns the speed the clock advances relative to your system clock, as f32. This is known as “time scaling” or “time dilation” in other engines.

pub fn relative_speed_f64(&self) -> f64

Returns the speed the clock advances relative to your system clock, as f64. This is known as “time scaling” or “time dilation” in other engines.

pub fn effective_speed(&self) -> f32

Returns the speed the clock advanced relative to your system clock in this update, as f32.

Returns 0.0 if the game was paused or what the relative_speed value was at the start of this update.

pub fn effective_speed_f64(&self) -> f64

Returns the speed the clock advanced relative to your system clock in this update, as f64.

Returns 0.0 if the game was paused or what the relative_speed value was at the start of this update.

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

Sets the speed the clock advances relative to your system clock, given as an f32.

For example, setting this to 2.0 will make the clock advance twice as fast as your system clock.

Panics

Panics if ratio is negative or not finite.

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

Sets the speed the clock advances relative to your system clock, given as an f64.

For example, setting this to 2.0 will make the clock advance twice as fast as your system clock.

Panics

Panics if ratio is negative or not finite.

pub fn pause(&mut self)

Stops the clock, preventing it from advancing until resumed.

pub fn unpause(&mut self)

Resumes the clock if paused.

pub fn is_paused(&self) -> bool

Returns true if the clock is currently paused.

pub fn was_paused(&self) -> bool

Returns true if the clock was paused at the start of this update.

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

impl<T> FromReflect for Time<T>

where Self: Any + Send + Sync, T: TypePath + FromReflect + RegisterForReflection + Default, Duration: FromReflect + TypePath + RegisterForReflection, f32: FromReflect + TypePath + RegisterForReflection, f64: FromReflect + TypePath + RegisterForReflection,

fn from_reflect(reflect: &dyn Reflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn Reflect>, ) -> Result<Self, Box<dyn Reflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl<T> GetTypeRegistration for Time<T>

where Self: Any + Send + Sync, T: TypePath + FromReflect + RegisterForReflection + Default, Duration: FromReflect + TypePath + RegisterForReflection, f32: FromReflect + TypePath + RegisterForReflection, f64: FromReflect + TypePath + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl<T> Reflect for Time<T>

where Self: Any + Send + Sync, T: TypePath + FromReflect + RegisterForReflection + Default, Duration: FromReflect + TypePath + RegisterForReflection, f32: FromReflect + TypePath + RegisterForReflection, f64: FromReflect + TypePath + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable reflected value.

fn clone_value(&self) -> Box<dyn Reflect>

Clones the value as a Reflect trait object.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

fn try_apply(&mut self, value: &dyn Reflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn apply(&mut self, value: &(dyn Reflect + 'static))

Applies a reflected value to this value.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

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

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<T> Struct for Time<T>

where Self: Any + Send + Sync, T: TypePath + FromReflect + RegisterForReflection + Default, Duration: FromReflect + TypePath + RegisterForReflection, f32: FromReflect + TypePath + RegisterForReflection, f64: FromReflect + TypePath + RegisterForReflection,

fn field(&self, name: &str) -> Option<&dyn Reflect>

Returns a reference to the value of the field named name as a &dyn Reflect.

fn field_mut(&mut self, name: &str) -> Option<&mut dyn Reflect>

Returns a mutable reference to the value of the field named name as a &mut dyn Reflect.

fn field_at(&self, index: usize) -> Option<&dyn Reflect>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn Reflect>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

fn iter_fields(&self) -> FieldIter<'_>

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

impl<T> TypePath for Time<T>

where Self: Any + Send + Sync, T: TypePath + Default,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl<T> Typed for Time<T>

where Self: Any + Send + Sync, T: TypePath + FromReflect + RegisterForReflection + Default, Duration: FromReflect + TypePath + RegisterForReflection, f32: FromReflect + TypePath + RegisterForReflection, f64: FromReflect + TypePath + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<T: Copy + Default> Copy for Time<T>

impl<T: Default> Resource for Time<T>

where Self: Send + Sync + 'static,