Time
Read frame time with Time, pause and slow down the game with virtual time, and count down with Timer, Stopwatch, time-based run conditions and delayed commands.
On this page
The Time resource tells a system how much time passed since the last update and since the app started. Multiply movement by it and your game runs at the same speed at any frame rate. NEO keeps three clocks, and the virtual one can be paused and slowed down.
Reading time#
fn fall(time: Res<Time>, mut q: Query<&mut Transform, With<Falling>>) {
for mut transform in &mut q {
transform.translation.y -= 9.8 * time.delta_secs();
}
}| Method | Returns |
|---|---|
delta(), delta_secs(), delta_secs_f64() | Time since the last update, as a Duration, f32 or f64 of seconds. |
elapsed(), elapsed_secs(), elapsed_secs_f64() | Time since the clock started. |
elapsed_wrapped(), elapsed_secs_wrapped() | Elapsed time wrapped around a period (one hour by default), for shaders and effects that lose precision as f32 grows. |
The three clocks#
| Clock | What it measures |
|---|---|
Time<Real> | Wall-clock time. Never paused or scaled. Use it for UI animations that should run while the game is paused. |
Time<Virtual> | Game time. It follows real time, but you can pause it, change its speed, and it never jumps more than max_delta in one update. |
Time<Fixed> | The fixed timestep clock. It follows virtual time in steps of a fixed size. See Fixed timestep. |
Plain Time (that is, Time<()>) is the right one for where your system runs: virtual time in Update and the other main schedules, fixed time inside FixedUpdate. Most systems should just read Res<Time>.
Pause and slow motion#
Change the virtual clock to pause the game or play it faster or slower. Everything that reads Time follows, including FixedUpdate and animation.
fn pause_menu(keys: Res<ButtonInput<KeyCode>>, mut time: ResMut<Time<Virtual>>) {
if keys.just_pressed(KeyCode::KeyP) {
time.toggle(); // pause() / unpause()
}
if keys.just_pressed(KeyCode::KeyS) {
time.set_relative_speed(0.25); // slow motion
}
}Method on Time<Virtual> | What it does |
|---|---|
pause(), unpause(), toggle(), is_paused() | Stops and starts the game clock. While paused, delta() is zero. |
set_relative_speed(r), relative_speed() | Plays at r times real time. |
effective_speed() | The speed this update actually ran at: zero while paused. |
set_max_delta(d), max_delta() | The largest step in one update, 250 ms by default. A long hitch, such as dragging the window, doesn't make the game jump ahead. |
To run a system only while the game is paused, use the paused run condition from neo::time::common_conditions: .run_if(paused).
Example: cargo run --example virtual_time.
Timers#
A Timer counts down a duration. Tick it with the frame's delta and check whether it finished.
#[derive(Component)]
struct Fuse(Timer);
fn spawn_bomb(mut commands: Commands) {
commands.spawn(Fuse(Timer::from_seconds(3.0, TimerMode::Once)));
}
fn explode(mut commands: Commands, time: Res<Time>, mut q: Query<(Entity, &mut Fuse)>) {
for (entity, mut fuse) in &mut q {
if fuse.0.tick(time.delta()).just_finished() {
commands.entity(entity).despawn();
}
}
}| Method | What it does |
|---|---|
Timer::from_seconds(s, mode), Timer::new(duration, mode) | Makes a timer. TimerMode::Once stops when it finishes; TimerMode::Repeating starts again. |
tick(delta) | Advances the timer. Returns the timer, so you can chain a check. |
just_finished() | True on the tick it finished. |
is_finished() | True once finished (a once timer stays finished). |
times_finished_this_tick() | How many times a repeating timer finished in this tick, for short timers and long frames. |
fraction(), fraction_remaining(), remaining_secs(), elapsed_secs() | Progress. |
pause(), unpause(), reset(), finish(), set_duration(d) | Control. |
A Stopwatch counts up instead, with tick(delta), elapsed_secs(), pause() and reset().
Example: cargo run --example timers.
Time-based run conditions#
These run a system on a schedule without a timer of your own:
| Condition | Runs the system |
|---|---|
on_timer(duration) | Every duration of virtual time. |
on_real_timer(duration) | Every duration of real time. |
once_after_delay(duration) | Once, after duration. |
repeating_after_delay(duration) | Every update, once duration has passed. |
paused | While virtual time is paused. |
use neo::time::common_conditions::on_timer;
use std::time::Duration;
app.add_systems(Update, spawn_wave.run_if(on_timer(Duration::from_secs(10))));Delayed commands#
commands.delayed() queues commands to run after a delay, measured on the Time clock:
fn flash(mut commands: Commands) {
let flash = commands.spawn(Flash).id();
commands.delayed().secs(0.5).entity(flash).despawn();
}Example: cargo run --example delayed_commands.
Controlling the clock#
TimeUpdateStrategy decides how time advances. The default, Automatic, uses the system clock. ManualDuration(d) advances by exactly d every update, which makes runs repeatable across machines; NEO games use it for their --fixed-dt 1/60 option, for checks and recordings. ManualInstant and FixedTimesteps(n) are there for tests.
use neo::time::TimeUpdateStrategy;
use std::time::Duration;
app.insert_resource(TimeUpdateStrategy::ManualDuration(Duration::from_secs_f64(1.0 / 60.0)));